Documents

A document is an Invoice, a Proforma Invoice, a Credit Note or a Quote. On this page: the fields of a document, how to list and search a Business’s documents, how to create and change a Draft — held to the same rules as the document editor in Essentio — how to issue, send and cancel a document and convert a Proforma Invoice into its Invoice, and how to download a document’s PDF and its EN16931 XML.

Drafts and issued documents

A document starts as a Draft: it has no Document number and no issue date, it asks nobody for anything, and it can be changed freely. Issuing it takes the next number of the Business’s sequence, stamps the issue date and freezes its Lines and totals. The API creates, changes and deletes Drafts, and issues, sends and cancels documents as Essentio’s own buttons do.

A Draft can carry the number it should be issued as, document_number. It reserves nothing: the number is checked when the document is issued, and the issue is refused then if the number is taken, malformed or skips ahead. The document answers it as requested_document_number, and document_number stays null until the issue.
issue_date is never sent: a Draft has none, and one sent is refused.
Anything that would issue a document on saving is refused: money received with it (payments) and a Proforma Invoice it converts (proforma_invoice_id).
Only a Draft can be changed. An update of an issued document is refused with a 422 refusal, issued_not_changed.

Refusals

Issuing, sending, cancelling, converting and deleting a Draft are Actions, and each is open or refused for a document as it stands, exactly as in Essentio: an issued document is not issued again, a Draft is not cancelled. A refused Action answers 422 with the error type refusal, a message in Essentio’s words and a Refusal code your program can branch on. Nothing was written.

Cancelling a Draft: 422

{
  "error": {
    "type": "refusal",
    "code": "draft_not_cancelled",
    "message": "A draft is deleted, not cancelled — it is not a document yet."
  }
}

Some refusals carry a remedy: what the Business does in Essentio to open the Action. connect_mail_provider asks it to connect a mailbox of its own (or connect a lost account again) in Settings → Email — a Business with none sends through Essentio's own mail server, which needs the Business's email address and emails a limited number of recipients a day. Refusal codes are only ever added within v1: treat a code you do not know as a refusal you do not handle yet.

Name
already_issued
Refused by
Issue
Description
Only a Draft is issued; this document already has its number.
Name
number_taken
Refused by
Issue, Send
Description
The number the Draft asks for (requested_document_number) is taken by another document. So are number_skips_ahead, number_beyond_the_counter and number_malformed, each named in message. The Draft stays a Draft: change or clear its document_number and try again.
Name
numbering_at_its_end
Refused by
Issue, Send
Description
The next number of the document's type is the largest the numbering holds, which it never takes, because it cannot count past it; message names it. The Draft stays a Draft: send an unused earlier number as its document_number and try again.
Name
cancelled_not_sent
Refused by
Send
Description
A Cancelled document is not sent.
Name
no_client_address
Refused by
Send
Description
The Client has no email address. Nothing is issued.
Name
no_mail_provider
Refused by
Send
Description
The Business has nothing to send through: it sends through Essentio's own mail server unless it connected a mailbox, and it has no email address of its own for replies; remedy connect_mail_provider. Nothing is issued.
Name
mail_account_lost
Refused by
Send
Description
The Business’s connected mail account stopped renewing its access; remedy connect_mail_provider. When the Send met it after issuing a Draft, document_number names the number it took.
Name
sending_limit_reached
Refused by
Send
Description
The Business sends through Essentio's own mail server, which emails 20 recipients a day for it on the Free plan (and a Test or Paused Business), 100 on Pro and 200 on Pro Plus — To, Cc and Bcc each count — and this email does not fit what is left; remedy connect_mail_provider: its own mailbox has no such limit. Once none is left a Draft is not issued; when the Send met it after issuing a Draft, message names the number it took.
Name
draft_not_cancelled
Refused by
Cancel
Description
A Draft is not a document yet: it is deleted instead.
Name
paid_not_cancelled
Refused by
Cancel
Description
A Paid document is corrected with a Credit Note.
Name
already_cancelled
Refused by
Cancel
Description
The document is already Cancelled.
Name
holds_money
Refused by
Cancel
Description
The document holds Payments (or its Proforma’s): it is corrected with a Credit Note.
Name
not_a_proforma
Refused by
Convert
Description
Only a Proforma Invoice converts into an Invoice.
Name
draft_not_converted
Refused by
Convert
Description
A Draft Proforma Invoice is issued first.
Name
cancelled_not_converted
Refused by
Convert
Description
A Cancelled Proforma Invoice converts into nothing.
Name
already_converted
Refused by
Convert
Description
An Invoice was already made from this Proforma Invoice.
Name
issued_not_deleted
Refused by
Delete
Description
Only a Draft is deleted; an issued document is cancelled instead.
Name
draft_deleted
Refused by
Issue, Send, Update
Description
The Draft was deleted by another request while this one waited for it. Nothing is written and no number is taken.
Name
issued_not_changed
Refused by
Update
Description
Only a Draft is changed through the API; an issued document is changed in Essentio.
Name
proforma_deleted
Refused by
Update
Description
A Draft still linked to a Proforma Invoice is issued by its save, as that Proforma’s conversion. It is refused when the Proforma was deleted, and so are cancelled_not_converted (the Proforma was cancelled), only_into_an_invoice (the Draft is no longer an Invoice), proforma_other_currency and proforma_other_client, each named in message.
Name
not_exportable
Refused by
Download the XML
Description
The document is not exported as EN16931 XML: a Draft, a Proforma Invoice or a Quote, or one the EN16931 check does not pass. message says why.
Name
exports_not_in_a_test_business
Refused by
Download the XML
Description
The Business is a Test business, which keeps no real books and exports no XML. Its PDFs stay, marked SAMPLE.

A key whose Role may not take the Action is answered 403 permission, never a refusal.

Money and decimals

Money is a string. Every amount the API answers is an exact decimal at its currency’s scale — "939.15" — never a floating-point number. Parse it with a decimal type.
Send decimals as strings too. A Line’s quantity, unit_price and vat_rate, and late_fee_rate, are sent as strings: "95.00", "19". A JSON number is refused, because it may be rounded before Essentio reads it.
Totals are Essentio’s. Each Line’s net amount is quantity × unit price, rounded to the currency’s minor unit. VAT is computed once per VAT group — the Lines sharing a VAT category, rate and exemption code — never per Line. subtotal + total_vat = total.
A Credit Note’s amounts are positive. Its type carries the sign: it reduces what the Client owes.

The document model

A document as the API answers it. A field that is null has not been filled in.

Properties

Name
id
Type
integer
Description
The document’s identifier.
Name
document_type
Type
string
Description
invoice, proforma (a Proforma Invoice), credit_note or quote. Another value may be added within v1: keep one you do not know.
Name
status
Type
string
Description
draft, issued, partially_paid, paid or cancelled. Whether the document reached its Client is not a state. Another value may be added within v1: keep one you do not know.
Name
is_test
Type
boolean
Description
Whether it is a Test business’s document: a sample, not real books. Its PDF prints SAMPLE and its number carries TEST-.
Name
document_number
Type
string or null
Description
The Document number, taken when the document is issued. null on a Draft. A Test business’s carries TEST- in front of what its number pattern makes, such as TEST-INV-2026-0007.
Name
requested_document_number
Type
string or null
Description
The number a Draft asks to be issued as. null when it asks for none, and once it is issued.
Name
client_id
Type
integer
Description
The Client the document is for: a Client’s id.
Name
client
Type
object
Description
That Client’s id and name, as it reads now, so the name needs no second request.
Name
currency
Type
string
Description
ISO 4217: EUR.
Name
issue_date
Type
date or null
Description
The day the document was issued. null on a Draft.
Name
due_date
Type
date
Description
The second date: an Invoice’s due date, a Proforma Invoice’s or a Quote’s valid-until date. A Credit Note shows none.
Name
payment_terms
Type
integer
Description
Days the due date is counted from.
Name
is_overdue
Type
boolean
Description
Whether the document is Overdue, as Essentio shows it: issued or partially paid, asking for payment — an Invoice, or a Proforma Invoice never converted — and its due_date before today. A Draft, a Paid or Cancelled document, a Credit Note, a Quote and a converted Proforma Invoice never are. Overdue is not a status: the document keeps its own.
Name
days_overdue
Type
integer or null
Description
How many days ago its due_date was, while is_overdue is true. null whenever it is not Overdue.
Name
client_reference, purchase_order_number, project_reference
Type
string or null
Description
The Client’s references, written into the EN16931 XML.
Name
notes
Type
string or null
Description
What the document says to its Client beside its Lines.
Name
footer_text
Type
string or null
Description
The line printed at the foot of the document.
Name
terms_and_conditions
Type
string or null
Description
The terms the document is issued under.
Name
late_fee_rate
Type
string or null
Description
A percentage with two decimals: "2.50". null on a Credit Note or a Quote, which state none.
Name
internal_notes
Type
string or null
Description
The Business’s own remark. Never shown to the Client.
Name
lines
Type
array
Description
The document’s Lines, in order: id, description, quantity ("3.000"), unit, unit_price ("95.0000", VAT excluded), vat_rate ("19.00"), vat_category, vat_exemption_code, product_code, notes (the note printed with the Line, or null) and net_amount. A Line’s id changes whenever the Lines are replaced.
Name
subtotal
Type
string
Description
The sum of the Lines’ net amounts.
Name
total_vat
Type
string
Description
The VAT of every VAT group.
Name
total
Type
string
Description
Subtotal + Total VAT.
Name
vat_groups
Type
array
Description
The Lines grouped by VAT category, rate and exemption code: category, rate, exemption_code, net and vat.
Name
bank_account_ids
Type
array of integers
Description
The Business’s bank accounts the Client pays into, by id, in the order the document shows them.
Name
proforma_id
Type
integer or null
Description
The Proforma Invoice this document was converted from, by id. null when it was made from none. That Proforma Invoice’s converted_into_id names this document.
Name
converted_into_id
Type
integer or null
Description
On a Proforma Invoice, the Invoice it was converted into, by id — a Draft included: a Draft made from it already converts it, so it takes no Payment of its own. null on a Proforma Invoice never converted, and on every other document. That Invoice’s proforma_id names this Proforma Invoice.
Name
last_sent
Type
object or null
Description
The newest time it was sent, while it is marked sent: at (when), recipients (the To list the email went to — a Test business’s goes to its Owner; empty when it was marked as sent by hand) and via — essentio (Essentio’s own mail server), gmail, microsoft (Outlook), smtp, or marked (marked as sent by hand in Essentio). null when it was never sent, once its sent mark is cleared in Essentio, whose History keeps every send it recorded, and on a document sent before Essentio recorded sends (October 2026): nobody knows to whom or how it went.
Name
public_url
Type
string or null
Description
The page in Essentio where the Client opens the document. null on a Draft, which has none.
Name
amount_due
Type
string or null
Description
Total − Prepaid − Payments: what the Client still owes. null where the document asks nobody for money — a Draft, a Cancelled document, a Credit Note, a Quote, and a Proforma Invoice converted into an Invoice, whose Invoice carries the debt. A Paid document still states it.
Name
prepaid
Type
string
Description
What the Proforma Invoice this Invoice was converted from was paid. "0.00" for any other document.
Name
payments_total
Type
string
Description
The sum of the document’s own Payments; a reversed Payment counts nowhere.
Name
shows_amount_due, shows_prepaid, shows_payments
Type
boolean
Description
Whether the document’s page, PDF and email state its Amount due, its Prepaid and its Payments.
Name
still_takes_payment
Type
boolean
Description
Whether a Payment can be recorded against it now.
Name
actions
Type
object
Description
What your key may do with the document now: issue, send, cancel, convert, record_payment and delete, each { "open": true, "code": null, "remedy": null } when taking it would be done, or with the Refusal code taking it would answer — role_forbidden when your key’s Role may not take it — and its remedy. With the remedy record_on_its_invoice, invoice_id names the Invoice to record the Payment on; with the remedy connect_mail_provider, remedy_url is the page in Essentio where the Business connects its mail account, and with choose_plan the page where its Owner chooses a plan, for a person signed in to Essentio who belongs to it.
Name
created_at
Type
timestamp
Description
When the document was created, in UTC.
Name
updated_at
Type
timestamp
Description
When the document last changed, in UTC.

GET/v1/documents

List documents

Lists the Business’s documents of every type, Drafts included, a page at a time, oldest first — paged as every list is (Pagination). Send the same filters with every page. Every Role may read them, a Viewer’s key included.

Query parameters

Name
limit
Type
integer
Description
How many documents a page holds: 1 to 100. Not sent: 25.
Name
cursor
Type
string
Description
The next_cursor of the page before. Not sent: the first page.
Name
document_type
Type
string
Description
Only documents of this type: invoice, proforma, credit_note or quote.
Name
status
Type
string
Description
Only documents in this state: draft, issued, partially_paid, paid, cancelled, or overdue — issued Invoices and Proforma Invoices never converted, past their due date, neither paid nor cancelled — or awaiting_payment: every document that still takes a Payment, those whose still_takes_payment is true. That is the issued and partially paid Invoices and Proforma Invoices never converted with an amount due, overdue ones included, in one list; never a Draft, a Credit Note, a Quote, a converted Proforma Invoice, a paid or a cancelled document.
Name
client_id
Type
integer
Description
Only the documents of this Client.
Name
issued_from
Type
date
Description
Only documents issued on or after this day, YYYY-MM-DD. A Draft has no issue date, so a period leaves every Draft out.
Name
issued_to
Type
date
Description
Only documents issued on or before this day, YYYY-MM-DD, not before issued_from.
Name
search
Type
string
Description
Only the documents whose number or notes, or whose Client’s name, legal name or email, contains this text, in any case.

Answers

Name
200
Type
DocumentList
Description
data: the page’s documents. next_cursor: where the next page starts, or null on the last.
Name
401
Type
Error
Description
No API key, an unknown one or a revoked one.
Name
422
Type
Error
Description
A filter the list cannot read — an unknown type or state, a day not written YYYY-MM-DD, a period ending before it starts — a limit out of range, or a cursor this API did not give. A filter is refused, never ignored.

Request

GET/v1/documents

curl -G https://api.essentio.pro/v1/documents \
  -H "Authorization: Bearer ess_your_api_key" \
  -d document_type=invoice \
  -d status=overdue

POST/v1/documents

Create a Draft

Creates a Draft of any of the four types, held to the same rules as the document editor in Essentio, in its words. An Admin’s or Member’s key may create; a Viewer’s may not. Send an Idempotency-Key to retry safely (see Idempotency).

Body

Name
document_type
Type
string
Description
Required. invoice, proforma, credit_note or quote.
Name
client_id
Type
integer
Description
Required. One of the Business’s Clients.
Name
currency
Type
string
Description
Required. ISO 4217, one Essentio computes documents in.
Name
due_date
Type
date
Description
Required. The second date, YYYY-MM-DD. A Draft still waiting past it is given a fresh one when it is issued.
Name
lines
Type
array
Description
Required, at least one. Each Line: description, quantity, unit_price (VAT excluded) and vat_rate, required; vat_category (not sent: S; only S carries a rate above 0), vat_exemption_code (required for a category other than S and Z), unit (not sent: pcs), product_code and notes (at most 500 characters, printed with the Line). Decimals as strings. An error in a Line is keyed by its index, lines.0.quantity, and its words name the Line by its place, counted from 1: “Line 1: Quantity must be greater than 0.” A Line’s Net amount (quantity × unit price) and the document’s Total stay below 1,000,000,000,000,000, which is the most an amount is stored to: past it, the Line is refused under its unit_price, the Total under lines.
Name
document_number
Type
string
Description
The number the Draft asks to be issued as, instead of the next one. It reserves nothing.
Name
payment_terms
Type
integer
Description
Days the due date is counted from, at most 999999. Not sent: the Client’s.
Name
terms_and_conditions, footer_text, late_fee_rate
Type
string
Description
Not sent: the Business’s defaults. Sent as null: none. A Credit Note or a Quote stores no late_fee_rate.
Name
notes, internal_notes, client_reference, purchase_order_number, project_reference
Type
string
Description
Optional, as in the editor.
Name
bank_account_ids
Type
array of integers
Description
The Business’s bank accounts the Client pays into, by id, in the order to show them. Another Business’s is refused at its index (bank_account_ids.0).

Answers

Name
201
Type
Document
Description
The Draft created — or, for a retry under the same Idempotency-Key, the one the first request created.
Name
401
Type
Error
Description
No API key, an unknown one or a revoked one.
Name
403
Type
Error
Description
A Viewer’s key.
Name
422
Type
Error
Description
A field the rules refused (invalid_request, each field in errors), or an Idempotency-Key sent with another body (idempotency).

Request

POST/v1/documents

curl https://api.essentio.pro/v1/documents \
  -H "Authorization: Bearer ess_your_api_key" \
  -H "Idempotency-Key: order-10427" \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "invoice",
    "client_id": 42,
    "currency": "EUR",
    "due_date": "2026-10-27",
    "bank_account_ids": [3],
    "lines": [
      {"description": "Design", "quantity": "3", "unit": "hour", "unit_price": "95.00", "vat_rate": "19"},
      {"description": "Print", "quantity": "500", "unit_price": "1.20", "vat_rate": "0", "vat_category": "Z"}
    ]
  }'

Response: 201

{
  "id": 118,
  "document_type": "invoice",
  "status": "draft",
  "is_test": false,
  "document_number": null,
  "requested_document_number": null,
  "client_id": 42,
  "client": {"id": 42, "name": "Acme Trading"},
  "currency": "EUR",
  "issue_date": null,
  "due_date": "2026-10-27",
  "is_overdue": false,
  "days_overdue": null,
  "payment_terms": 30,
  "client_reference": null,
  "purchase_order_number": null,
  "project_reference": null,
  "notes": null,
  "footer_text": "Registered in Cyprus, HE 123456",
  "terms_and_conditions": "Payment within 30 days.",
  "late_fee_rate": "1.00",
  "internal_notes": null,
  "lines": [
    {
      "id": 301,
      "description": "Design",
      "quantity": "3.000",
      "unit": "hour",
      "unit_price": "95.0000",
      "vat_rate": "19.00",
      "vat_category": "S",
      "vat_exemption_code": null,
      "product_code": null,
      "notes": "Two rounds of revisions",
      "net_amount": "285.00"
    },
    {
      "id": 302,
      "description": "Print",
      "quantity": "500.000",
      "unit": "pcs",
      "unit_price": "1.2000",
      "vat_rate": "0.00",
      "vat_category": "Z",
      "vat_exemption_code": null,
      "product_code": null,
      "notes": null,
      "net_amount": "600.00"
    }
  ],
  "subtotal": "885.00",
  "total_vat": "54.15",
  "total": "939.15",
  "vat_groups": [
    {"category": "S", "rate": "19.00", "exemption_code": null, "net": "285.00", "vat": "54.15"},
    {"category": "Z", "rate": "0.00", "exemption_code": null, "net": "600.00", "vat": "0.00"}
  ],
  "bank_account_ids": [3],
  "proforma_id": null,
  "converted_into_id": null,
  "last_sent": null,
  "public_url": null,
  "amount_due": null,
  "prepaid": "0.00",
  "payments_total": "0.00",
  "shows_amount_due": false,
  "shows_prepaid": false,
  "shows_payments": false,
  "still_takes_payment": false,
  "actions": {
    "issue": {"open": true, "code": null, "remedy": null},
    "send": {"open": true, "code": null, "remedy": null},
    "cancel": {"open": false, "code": "draft_not_cancelled", "remedy": null},
    "convert": {"open": false, "code": "not_a_proforma", "remedy": null},
    "record_payment": {"open": false, "code": "draft_takes_no_payments", "remedy": null},
    "delete": {"open": true, "code": null, "remedy": null}
  },
  "created_at": "2026-09-27T10:15:00+00:00",
  "updated_at": "2026-09-27T10:15:00+00:00"
}

GET/v1/documents/{document}

Retrieve a document

One document of the Business, of any type and state, by its id. Every Role may read it. A document of another Business, or one that was deleted, is not found.

Answers

Name
200
Type
Document
Description
The document.
Name
401
Type
Error
Description
No API key, an unknown one or a revoked one.
Name
404
Type
Error
Description
The Business has no document with this id.

Request

GET/v1/documents/118

curl https://api.essentio.pro/v1/documents/118 \
  -H "Authorization: Bearer ess_your_api_key"

PATCH/v1/documents/{document}

Update a Draft

Changes the fields sent of a Draft and nothing else, held to the same rules as a create. An Admin’s or Member’s key may update; a Viewer’s may not.

lines, when sent, replaces every Line. Not sent, the Lines stay.
due_date and payment_terms sent as null keep their values.
document_number sent as null clears the number the Draft asks for.
bank_account_ids: a list replaces them, in its order; [] clears them.
A document that is not a Draft is refused with a 422 refusal, issued_not_changed: an issued document is changed in Essentio.
A Draft still linked to a Proforma Invoice is issued by its save, and refused when the Proforma does not convert into it: proforma_deleted, cancelled_not_converted, only_into_an_invoice, proforma_other_currency or proforma_other_client.

Answers

Name
200
Type
Document
Description
The Draft as it now stands.
Name
401
Type
Error
Description
No API key, an unknown one or a revoked one.
Name
403
Type
Error
Description
A Viewer’s key.
Name
404
Type
Error
Description
The Business has no document with this id.
Name
422
Type
Error
Description
A field the rules refused, each named in errors (invalid_request); or a refusal: the document is not a Draft (issued_not_changed), the Draft was deleted meanwhile (draft_deleted), or the Proforma Invoice it is linked to does not convert into it.

Request

PATCH/v1/documents/118

curl -X PATCH https://api.essentio.pro/v1/documents/118 \
  -H "Authorization: Bearer ess_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"notes": "Thank you for your order.", "purchase_order_number": "PO-7731"}'

DELETE/v1/documents/{document}

Delete a Draft

Deletes a Draft, as Delete does in Essentio: it leaves the Business’s documents at once, and it took no Document number. Only a Draft is deleted: an issued document keeps its number for good and is cancelled instead. The document’s actions.delete says beforehand whether it would be done. An Admin’s or Member’s key may delete; a Viewer’s may not.

Answers

Name
204
Type
none
Description
The Draft was deleted. No body.
Name
401
Type
Error
Description
No API key, an unknown one or a revoked one.
Name
403
Type
Error
Description
A Viewer’s key.
Name
404
Type
Error
Description
The Business has no document with this id, or it was deleted already.
Name
422
Type
Error
Description
A refusal: issued_not_deleted.

Request

DELETE/v1/documents/118

curl -X DELETE https://api.essentio.pro/v1/documents/118 \
  -H "Authorization: Bearer ess_your_api_key"

POST/v1/documents/{document}/issue

Issue a Draft

Issues a Draft as Essentio’s Issue does: it takes its Document number — the one it asks for (requested_document_number), else the next of its type’s sequence — and today’s issue date, and its Lines and totals are frozen. A Draft whose due date has passed is issued due today plus its payment terms. Nothing is emailed: Send does that. An Admin’s or Member’s key may issue; a Viewer’s may not. Send an Idempotency-Key to retry safely.

Answers

Name
200
Type
Document
Description
The document as issued — or, for a retry under the same Idempotency-Key, what the first request answered.
Name
401
Type
Error
Description
No API key, an unknown one or a revoked one.
Name
403
Type
Error
Description
A Viewer’s key.
Name
404
Type
Error
Description
The Business has no document with this id.
Name
422
Type
Error
Description
A refusal: already_issued, draft_deleted (deleted meanwhile, no number taken), or a number_* code for the number the Draft asks for — it stays a Draft.

Request

POST/v1/documents/118/issue

curl -X POST https://api.essentio.pro/v1/documents/118/issue \
  -H "Authorization: Bearer ess_your_api_key" \
  -H "Idempotency-Key: issue-118"

POST/v1/documents/{document}/send

Send a document

Emails the document to its Client’s address, with its PDF, through the Business’s mailbox, or Essentio’s own mail server when it connected none — as Essentio’s Send does. Through Essentio the email is sent once it is accepted into Essentio’s queue; one Essentio then fails to deliver is listed on the document’s History in Essentio and told to the Business’s Owner. A Draft is issued first. Without a body the email takes the Business’s own subject and message for the type. An Admin’s or Member’s key may send; a Viewer’s may not.

subject (string, at most 255 characters) and message (string, at most 2000 characters) replace the Business’s.
A send that could never go out — no Client address, no mail provider, a Cancelled document — is refused before the Draft is issued, so no number is taken.
Send it with an Idempotency-Key. A retry of a Send that went out answers the first response and sends nothing again. A Send that did not go out keeps no key, so the retry sends.
A test business’s email goes to its Owner, never the Client.
A not_delivered is rarely final. When the connection to the mail provider failed — it did not answer in time, or dropped — the provider may have taken the email before the connection was lost. A retry then sends it a second time. Check the Client’s inbox, or your provider’s sent mail, before you send again.

Answers

Name
200
Type
Document
Description
The document as it now stands, issued if it was a Draft.
Name
401
Type
Error
Description
No API key, an unknown one or a revoked one.
Name
403
Type
Error
Description
A Viewer’s key.
Name
404
Type
Error
Description
The Business has no document with this id.
Name
422
Type
Error
Description
A refusal: cancelled_not_sent, no_client_address, no_mail_provider, mail_account_lost, sending_limit_reached, draft_deleted (a Draft deleted meanwhile, nothing sent), or a number_* code for a Draft. Or a subject or message the rules refused (invalid_request).
Name
409
Type
Error
Description
idempotency_in_flight: a Send under the same Idempotency-Key is still being performed.
Name
502
Type
Error
Description
not_delivered: the mail provider did not accept the email, or could not be reached. A Draft the Send issued first stays issued, and error.document_number names its number.

Request

POST/v1/documents/118/send

curl -X POST https://api.essentio.pro/v1/documents/118/send \
  -H "Authorization: Bearer ess_your_api_key" \
  -H "Idempotency-Key: send-118" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Invoice INV-0042", "message": "Thank you for your order."}'

POST/v1/documents/{document}/cancel

Cancel a document

Cancels an issued document as Essentio’s Cancel does: it keeps its Document number and leaves every figure. A Draft is deleted instead, and a document holding money is corrected with a Credit Note. An Admin’s or Member’s key may cancel; a Viewer’s may not.

Answers

Name
200
Type
Document
Description
The document as cancelled.
Name
401
Type
Error
Description
No API key, an unknown one or a revoked one.
Name
403
Type
Error
Description
A Viewer’s key.
Name
404
Type
Error
Description
The Business has no document with this id.
Name
422
Type
Error
Description
A refusal: draft_not_cancelled, paid_not_cancelled, already_cancelled or holds_money.

Request

POST/v1/documents/118/cancel

curl -X POST https://api.essentio.pro/v1/documents/118/cancel \
  -H "Authorization: Bearer ess_your_api_key" \
  -H "Idempotency-Key: cancel-118"

POST/v1/documents/{document}/convert

Convert a Proforma Invoice into its Invoice

Makes the Invoice an issued Proforma Invoice becomes — as Create Invoice from Proforma does in Essentio — and issues it. An Admin’s or Member’s key may convert; a Viewer’s may not.

The Invoice takes the Proforma’s Client, currency, Lines, notes, footer, Terms & Conditions, Late fee rate and bank accounts, and is due today plus the Client’s payment terms.
The Proforma’s Payments are the Invoice’s Prepaid: an Invoice they cover is paid the moment it is issued, one they cover in part partially_paid.
A Proforma converts once. Send an Idempotency-Key: a retry answers the Invoice the first request made.

Answers

Name
201
Type
Document
Description
The Invoice, issued.
Name
401
Type
Error
Description
No API key, an unknown one or a revoked one.
Name
403
Type
Error
Description
A Viewer’s key.
Name
404
Type
Error
Description
The Business has no document with this id.
Name
422
Type
Error
Description
A refusal: not_a_proforma, draft_not_converted, cancelled_not_converted or already_converted.

Request

POST/v1/documents/118/convert

curl -X POST https://api.essentio.pro/v1/documents/118/convert \
  -H "Authorization: Bearer ess_your_api_key" \
  -H "Idempotency-Key: convert-118"

GET/v1/documents/{document}/pdf

Download a document’s PDF

The document’s PDF — the same file the document page in Essentio downloads, in the Business’s template and with its Branding. A Draft’s PDF reads “No number yet” and “Not issued yet”. A Test business’s documents are marked SAMPLE. Every Role may download it.

Answers

Name
200
Type
application/pdf
Description
The PDF, as an attachment named after the document.
Name
401
Type
Error
Description
No API key, an unknown one or a revoked one.
Name
404
Type
Error
Description
The Business has no document with this id.

Request

GET/v1/documents/118/pdf

curl https://api.essentio.pro/v1/documents/118/pdf \
  -H "Authorization: Bearer ess_your_api_key" \
  -o invoice.pdf

GET/v1/documents/{document}/xml

Download a document’s EN16931 XML

The document as EN16931 UBL 2.1 XML — an Invoice as a UBL Invoice, a Credit Note as a UBL CreditNote — the same file the document page in Essentio exports. Only an issued Invoice or Credit Note that passes the EN16931 check is exported. Every Role may download it.

The file follows EN 16931 itself, and no CIUS or network profile: its cbc:CustomizationID is urn:cen.eu:en16931:2017, and it carries no cbc:ProfileID. What it writes follows the document’s VAT categories, as the standard asks:

The Business’s identifiers. A VAT payer’s VAT number as PartyTaxScheme VAT (BT-31). Where no VAT number is written — a Non-VAT Payer, or a document whose Lines are all not subject to VAT — its TAX ID, when it has one, as PartyIdentification (BT-29) and PartyTaxScheme TAX (BT-32). Its Registration Number, when it has one, as PartyLegalEntity/CompanyID (BT-30).
The Client’s VAT number. As PartyTaxScheme VAT (BT-48) on every document but one whose Lines are all O, when the Client has one. Essentio stores a Client’s VAT number without its country code, as the Client form takes it, so the file writes the Client’s country first, in capitals — EL for Greece — as in DE987654321. A number stored with two letters first, as an import may store it, is written as stored.
Not subject to VAT (O). When every Line is O, neither the Business’s nor the Client’s VAT number is written. An O Line and an O VAT breakdown carry no cbc:Percent; every other category carries its own.
Intra-community supply (K). A document with a K Line carries cac:Delivery: its issue date as the Actual delivery date (BT-72) and the Client’s country as the Deliver to country (BT-80), left out when the Client has no country.
Payment means. 30, credit transfer, with the Business’s bank account (BT-84); 1, not defined, when the Business has none.

Answers

Name
200
Type
application/xml
Description
The XML, as an attachment named after the document.
Name
401
Type
Error
Description
No API key, an unknown one or a revoked one.
Name
404
Type
Error
Description
The Business has no document with this id.
Name
422
Type
Error
Description
A refusal, not_exportable: the document is not exported — a Draft, a Proforma Invoice or a Quote, or an Invoice or Credit Note the EN16931 check does not pass — and error.message says why, in the words the document page shows. A Test business’s document is refused exports_not_in_a_test_business.

Request

GET/v1/documents/118/xml

curl https://api.essentio.pro/v1/documents/118/xml \
  -H "Authorization: Bearer ess_your_api_key" \
  -o invoice.xml