Skip to content

Update dd api docs to include response and custom data #22

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update dd api docs to include response and custom data #22

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 0 additions & 17 deletions source/includes/_authentication.md
View file
Open in desktop

This file was deleted.

24 changes: 24 additions & 0 deletions source/includes/_dynamic_discounting_authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
45 changes: 30 additions & 15 deletions source/includes/_dynamic_discounting_invoices.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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: "..." }
}
]
}' \
Expand Down Expand Up @@ -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" }
}
}
}
Expand All @@ -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
Expand All @@ -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

Expand All @@ -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.

Expand All @@ -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

Expand Down Expand Up @@ -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

Expand Down
41 changes: 32 additions & 9 deletions source/includes/_dynamic_discounting_payment_instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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`
Expand All @@ -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

Expand Down
37 changes: 28 additions & 9 deletions source/includes/_dynamic_discounting_suppliers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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: "..." }
}
]
}' \
Expand Down Expand Up @@ -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"}
}
}
}
Expand All @@ -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
Expand All @@ -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

Expand All @@ -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.

Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion source/index.html.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down