Raising an invoice using the Okappy API
Okappy is a B2B workforce management platform consisting of companies, employees and devices. Companies can connect to customers, subcontractors and employees. Add jobs and then assign those jobs to an employee or subcontractor. You can also raise invoices to your customers or receive invoices from your subcontractors.
To raise an invoice using the Okappy API, follow the instructions below.
Authentication
First you will need to get an up to date authentication token. For further information see authenticating with Okappy.
Raising an invoice
Raise an invoice using the following endpoint.
POST /invoices
Headers
| Header | Content |
|---|---|
| Authorize | Bearer token |
The token should be a string taken from the “access_token” field of a response to an authorise request.
Parameters
No parameters
Body data
The following table lists the fields that may be present in the body data:
| Name | Content | Required |
|---|---|---|
| connectTo | The customer ID of the invoicee | Yes |
| customerReference | No | |
| materialsCostDescription | No | |
| labourCostDescription | No | |
| otherCostDescription | No | |
| taxDate | The date of the invoice, in the format yyyy-mm-dd h:mm | Yes |
| materialsCost | No | |
| labourCost | No | |
| otherCost | No | |
| netAmountCustomer | The total net amount of the invoice | Yes |
| invoiceType | “raised” or “draft” | Yes |
| companyName | The name of the company being invoiced | No |
| invoiceAddress | The address of the invoicee | No |
| vatAmount | The VAT amount of the invoice | Yes |
| deduction | Any deduction for CIS | No |
| invoiceItems | An array of items.
See table below for item fields |
No |
Invoice items
If an array of invoice items is included in the body data, these are the fields may be included in each item.
| Name | Content | Required |
|---|---|---|
| item | Item name | Yes |
| description | A description of the item | Yes |
| quantity | The number of items | Yes |
| unitPrice | The net price per item | Yes |
| discount | Amount discounted (Usually CIS) | No |
| vat | VAT amount | Yes |
| netAmount | net amount | Yes |
| vatReverse | True if the item may be considered DRC | No |
| itemCode | A short code | No |
Response
| Code | Description |
|---|---|
| 200 | Operation successful |
| 204 | No data returned |
| 400 | Bad request |
| 401 | Unauthorised |
| 415 | Data sent in wrong format (should be JSON) |
| 429 | Too many requests in a short period of time (please try again later) |