Invoices
- Kristjan Vaga
Invoicing endpoints enables access to invoices created in Order module.
Invoice statuses
draft | Invoice is created but not registered in accounting yet. At this stage invoice details can still be changed or it can be removed altogether. Many otherwise mandatory fields might not be filled (which will be set automatically at the time of posting). |
|---|---|
posted | Invoice is registered in accounting and its details cannot be changed. This is final state of “non-tax“ invoices, such as pro-forma. |
paid | Tax invoice is fully paid. |
partly-paid | Tax invoice is partly paid. |
past-due | Tax invoice is unpaid and has became overdue. |
credited | Tax invoice is fully credited. |
When invoice status changes then updatedAt timestamp is updated.
Examples
Retrieve posted invoices of a single day:
curl -X GET \
-G 'https://salesfront.url/api/v3/invoices' \
-d invoiceDate[after]=2022-02-20 \
-d invoiceDate[before]=2022-02-20 \
-d status=posted \
-H 'Content-Type: application/json' \
-H 'X-API-Key: XXX'Create new advance (tax) invoice:
curl -X POST https://salesfront.url/api/v3/invoices \
-H 'Content-Type: application/json' \
-H 'X-API-Key: XXX' \
-d '{ "order": "/api/v3/orders/138", "type": "/api/v3/invoice-types/2", "description": "TEST", "amount": 1000 }'Note there are not many required fields to create an invoice draft. Response is created invoice:
{
"id": 1,
"order": {
"id": 3,
"iri": "/api/v3/orders/3",
"number": "O303"
},
"type": {
"id": 2,
"iri": "/api/v3/invoice-types/2",
"name": "ADVANCE"
},
"number": "N303/1",
"description": "TEST",
"status": "draft",
"amount": 1000,
"netAmount": 0,
"vatAmount": 0,
"issuedBy": {
"id": 5,
"name": "apiuser",
"iri": "/api/v3/users/5"
},
"createdAt": "2022-02-20T22:22:22+03:00"
}Note few missing details:
missing invoiceDate - as it was not saved in initial request it will automatically set as posting date.
zero netAmount and vatAmount - since taxes are not accounted both values are calculated at the time of posting.
missing duePaymentDate - as it was not provided it will be calculated automatically from invoiceDate at the time of posting.
missing recipient - as it was not provided it will be set to order customer automatically at the time of posting.
In draft status the various details about the invoice can be adjusted:
curl -X PATCH https://salesfront.url/api/v3/invoices/1 \
-H 'Content-Type: application/json' \
-H 'X-API-Key: XXX' \
-d '{ "recipient": { name": "Jane Doe" }, "paymentType": "/api/v3/payment-types/4", "duePaymentDate": "2022-02-28" }'Note paymentType that defines the expected payment method for the invoice.
Available payment types can be retrieved from dedicated endpoint:
curl -X GET \
-G 'https://salesfront.url/api/v3/payment-types' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: XXX'In order to make the invoice permanent, it need to be “posted“:
curl -X POST https://salesfront.url/api/v3/invoices/1/post \
-H 'Content-Type: application/json' \
-H 'X-API-Key: XXX'When successful the request returns final posted invoice.