From 04795b23f377ea93cef17c039b2ac5c2de2b27ca Mon Sep 17 00:00:00 2001 From: Abhay Kumar Date: Wed, 20 Oct 2021 15:57:49 +0200 Subject: [PATCH] Update dd api docs to include response and custom data --- source/includes/_authentication.md | 17 ------- .../_dynamic_discounting_authentication.md | 24 ++++++++++ .../includes/_dynamic_discounting_invoices.md | 45 ++++++++++++------- ...ynamic_discounting_payment_instructions.md | 41 +++++++++++++---- .../_dynamic_discounting_suppliers.md | 37 +++++++++++---- source/index.html.md | 2 +- 6 files changed, 115 insertions(+), 51 deletions(-) delete mode 100644 source/includes/_authentication.md create mode 100644 source/includes/_dynamic_discounting_authentication.md diff --git a/source/includes/_authentication.md b/source/includes/_authentication.md deleted file mode 100644 index f1f2460..0000000 --- a/source/includes/_authentication.md +++ /dev/null @@ -1,17 +0,0 @@ -# Authentication - -> To authorize while using the endpoint `dynamic_discounting/suppliers`, there are two ways: - -```shell -curl "https://api.novicap.com/v1/dynamic_discounting/suppliers" --data api_key=abcd - -curl -H "Authorization: Bearer abcd" "https://api.novicap.com/v1/dynamic_discounting/suppliers" -``` - -> where `abcd` should be replaced with your API key. Note that this particular endpoint also requires a valid product_id in the request (see [/v1/dynamic_discounting/suppliers](#add-suppliers)). - -We use an API key to authenticate which can be found by logging into your account at [novicap.com](https://www.novicap.com) and generating it under your user profile. All API hits will be associated with your user and an indefinite audit log is accessible from your account. - -The API key should be included in all requests to the server either as a HTTP request parameter named `api_key` or inside an `Authorization: Bearer` HTTP request header. - -OAuth 2.0 authentication is available on request. The exact implementation will depend on your authentication provider and workflow. diff --git a/source/includes/_dynamic_discounting_authentication.md b/source/includes/_dynamic_discounting_authentication.md new file mode 100644 index 0000000..cc39879 --- /dev/null +++ b/source/includes/_dynamic_discounting_authentication.md @@ -0,0 +1,24 @@ +## Authentication + +> To authorize while using the endpoints, there are two ways: + +```shell +curl "https://api.novicap.com/v1/dynamic_discounting/suppliers" --data api_key=abcd + +curl -H "Authorization: Bearer abcd" "https://api.novicap.com/v1/dynamic_discounting/suppliers" +``` + +> where `abcd` should be replaced with your API key. Note that all the endpoints also require a valid `product_id` in the request (see [/v1/dynamic_discounting/suppliers](#add-suppliers)). + +We use an API key to authenticate which can be found by logging into your account at [novicap.com](https://www.novicap.com) and generating it under your user profile. All API hits will be associated with your user and an indefinite audit log is accessible from your account. + +The API key should be included in all requests to the server either as a HTTP request parameter named `api_key` or inside an `Authorization: Bearer` HTTP request header. + +OAuth 2.0 authentication is available on request. The exact implementation will depend on your authentication provider and workflow. + +| Parameter | Type | Required | Format | Description | +|------------+--------+----------+--------+-------------------------------------------------------------------------| +| api_key | String | | | Your API key for authentication | +| product_id | Number | ✓ | | The ID of the product, visible in the Novicap platform near the API key | + +All the endpoints also require a valid `product_id` in the request. diff --git a/source/includes/_dynamic_discounting_invoices.md b/source/includes/_dynamic_discounting_invoices.md index 362ad71..5f62756 100644 --- a/source/includes/_dynamic_discounting_invoices.md +++ b/source/includes/_dynamic_discounting_invoices.md @@ -9,7 +9,8 @@ curl -i -H "Content-Type: application/json" -X POST -i -d '{ "company_id": "00445790", "reference": "A1234", "amount": 1000, - "due_at": "2021/10/30" + "due_at": "2021/10/30", + "custom_invoice_data": { system_reference: "1234", generated_by: "..." } } ] }' \ @@ -52,7 +53,8 @@ If your account has more than one legal entity, you must include a `debtor_id` a "company_id": { "type": "string" }, "reference": { "type": "string" }, "amount": { "type": "number" }, - "due_at": { "type": "string" } + "due_at": { "type": "string" }, + "custom_invoice_data": { "type": "object" } } } } @@ -62,8 +64,6 @@ If your account has more than one legal entity, you must include a `debtor_id` a | Parameter | Type | Required | Format | Description | |------------+--------+----------+--------+-------------------------------------------------------------------------| -| api_key | String | | | Your API key for authentication | -| product_id | Number | ✓ | | The ID of the product, visible in the Novicap platform near the API key | | invoices | Array | ✓ | | An array of objects matching the invoice schema below | #### Invoices @@ -75,6 +75,7 @@ If your account has more than one legal entity, you must include a `debtor_id` a | reference | String | ✓ | | | The reference of the invoice | | | amount | String | | | | The amount of the invoice | | | due_at | String | | | | The date on which the invoice is due | | +| custom_invoice_data | Object | | | | Any custom data you want to save for the invoice | | ### Response @@ -91,7 +92,6 @@ curl -i -H "Content-Type: application/json" -X GET -i -d '{ "https://api.novicap.com/v1/dynamic_discounting/invoices" ``` -> The above command returns an array of Invoice objects in the JSON payload with the 200 OK status. This endpoint returns all the invoices registered in your product. @@ -116,11 +116,31 @@ This endpoint returns all the invoices registered in your product. } ``` -| Parameter | Type | Required | Format | Description | -|------------+--------+----------+--------+-------------------------------------------------------------------------| -| api_key | String | | | Your API key for authentication | -| product_id | Number | ✓ | | The ID of the product, visible in the Novicap platform near the API key | +> The above command returns an array of Invoice objects in the JSON payload with the 200 OK status. +```shell +{ + "invoices": [ + { + "company_id": "00445790", + "company_id": "A61866125", + "reference": "A1234", + "transaction_id": "DDI-7SNOF", + "amount": 1000, + "discount": 100.0, + "facilitator_fee": 20.0, + "accepted_at": "2021-09-30T00:00:00.437Z", + "due_at": "2021-09-30T00:00:00.437Z", + "management_status": "", + "payment_instruction_id": "TQEZHG", + "custom_company_data": { status: "active", addresses: "..." }, + "custom_invoice_data": { system_reference: "1234", generated_by: "..." } + }, + {...}, + {...} + ] +} +``` ### Response @@ -161,16 +181,11 @@ We may have already notified the supplier of the invoice, and they may have alre "required": ["product_id"], "properties": { "api_key": { "type": "string" }, - "product_id": { "type": "number" }, + "product_id": { "type": "number" } } } ``` -| Parameter | Type | Required | Format | Description | -|------------+--------+----------+--------+-------------------------------------------------------------------------| -| api_key | String | | | Your API key for authentication | -| product_id | Number | ✓ | | The ID of the product, visible in the Novicap platform near the API key | - ### Response diff --git a/source/includes/_dynamic_discounting_payment_instructions.md b/source/includes/_dynamic_discounting_payment_instructions.md index 6297930..ce1c6dd 100644 --- a/source/includes/_dynamic_discounting_payment_instructions.md +++ b/source/includes/_dynamic_discounting_payment_instructions.md @@ -39,8 +39,6 @@ If your account has more than one legal entity, you must include a `company_id`, | Parameter | Type | Required | Format | Description | |------------+--------+----------+--------+-------------------------------------------------------------------------| -| api_key | String | | | Your API key for authentication | -| product_id | Number | ✓ | | The ID of the product, visible in the Novicap platform near the API key | | debtor_id | Number | | | The ID of the entity, if your account has more then one legal entity | ### Response @@ -58,11 +56,8 @@ curl -H "Content-Type: application/json" -X GET -i -d '{ "https://api.novicap.com/v1/dynamic_discounting/payment_instructions" ``` -> The above command returns a JSON payload with the 200 OK status. - This endpoint returns all the payments instructions with an array of invoices included with every instruction. - ### HTTP Request `GET https://api.novicap.com/v1/dynamic_discounting/payment_instructions` @@ -84,10 +79,38 @@ This endpoint returns all the payments instructions with an array of invoices in } ``` -| Parameter | Type | Required | Format | Description | -|------------+--------+----------+--------+-------------------------------------------------------------------------| -| api_key | String | | | Your API key for authentication | -| product_id | Number | ✓ | | The ID of the product, visible in the Novicap platform near the API key | +> The above command returns the following JSON payload with the 200 OK status. + +```shell +{ + "payment_instructions": [ + { + "payment_instruction_id": "TQEZHG", + "invoices": [ + { + "company_id": "00445790", + "reference": "A1234", + "transaction_id": "DDI-7SNOF", + "amount": 1000, + "discount": 100.0, + "facilitator_fee": 20.0, + "accepted_at": "2021-09-30T00:00:00.437Z", + "due_at": "2021-09-30T00:00:00.437Z", + "management_status": "", + "supplier_registration_number": "A12345679", + "debtor_registration_number": "A12345678", + "payment_instruction_id": "TQEZHG", + "rectified_invoice_url": "" + }, + {...}, + {...} + ] + }, + {...}, + {...} + ] +} +``` ### Response diff --git a/source/includes/_dynamic_discounting_suppliers.md b/source/includes/_dynamic_discounting_suppliers.md index 0e99b86..4c2fb74 100644 --- a/source/includes/_dynamic_discounting_suppliers.md +++ b/source/includes/_dynamic_discounting_suppliers.md @@ -15,7 +15,8 @@ curl -i -H "Content-Type: application/json" -X POST -i -d '{ "contact_phone": "+44724565898", "apr": 10, "fixed_fee_percentage": 0.5, - "early_payment_cutoff_in_days": 5 + "early_payment_cutoff_in_days": 5, + "custom_company_data": { status: "active", addresses: "..." } } ] }' \ @@ -65,7 +66,8 @@ If your account has more than one legal entity, you must include a `debtor_id` a "apr": {"type": "number"}, "fixed_fee_percentage": {"type": "number"}, "early_payment_cutoff_in_days": {"type": "integer"}, - "iban": {"type": "string"} + "iban": {"type": "string"}, + "custom_company_data": {"type": "object"} } } } @@ -75,8 +77,6 @@ If your account has more than one legal entity, you must include a `debtor_id` a | Parameter | Type | Required | Format | Description | |------------+--------+----------+--------+-------------------------------------------------------------------------| -| api_key | String | | | Your API key for authentication | -| product_id | Number | ✓ | | The ID of the product, visible in the Novicap platform near the API key | | suppliers | Array | ✓ | | An array of objects matching the supplier schema below | #### Suppliers @@ -95,6 +95,7 @@ If your account has more than one legal entity, you must include a `debtor_id` a | fixed_fee_percentage | Number | Percentage points | ✓ | | The fixed fee, as a percentage of the face value of the invoice, you want the supplier to pay, in percentage points e.g. 0.5% -> 0.5 | | | early_payment_cutoff_in_days | Number | | | 10 | This number of days before the due date, we stop allowing the supplier to accept financing | | | iban | String | IBAN | | | The IBAN code of the bank account you pay to when making payments to the supplier | | +| custom_company_data | Object | | | | Any custom data you want to save for the supplier | | ### Response @@ -110,7 +111,6 @@ curl -i -H "Content-Type: application/json" -X GET -i -d '{ "https://api.novicap.com/v1/dynamic_discounting/suppliers" ``` -> The above command returns an array of Supplier objects in the JSON payload with the 200 OK status. This endpoint returns all the suppliers in your dynamic discounting product. @@ -136,10 +136,29 @@ This endpoint returns all the suppliers in your dynamic discounting product. } ``` -| Parameter | Type | Required | Format | Description | -|------------+--------+----------+--------+-------------------------------------------------------------------------| -| api_key | String | | | Your API key for authentication | -| product_id | Number | ✓ | | The ID of the product, visible in the Novicap platform near the API key | +> The above command returns an array of Supplier objects in the JSON payload with the 200 OK status. + +```shell +{ + "suppliers": [ + { + "country_code": "GB", + "company_id": "00445790", + "company_name": "Tesco PLC", + "contact_first_name": "John", + "contact_last_name": "Smith", + "contact_email": "john.smith@company.com", + "contact_phone": "+44724565898", + "apr": 10, + "fixed_fee_percentage": 0.5, + "early_payment_cutoff_in_days": 5, + "custom_company_data": { status: "active", addresses: "..." } + }, + {...}, + {...} + ] +} +``` ### Response diff --git a/source/index.html.md b/source/index.html.md index 45a0b85..8d20952 100644 --- a/source/index.html.md +++ b/source/index.html.md @@ -6,10 +6,10 @@ language_tabs: includes: - introduction - - authentication - permissions - identifying_companies - dynamic_discounting_header + - dynamic_discounting_authentication - dynamic_discounting_suppliers - dynamic_discounting_invoices - dynamic_discounting_payment_instructions