Invoice Drafts
A draft is an invoice held in GoRoute that has not been sent. You create it, read it, change it and validate it as often as you like, and nothing leaves GoRoute until you explicitly send it. Drafts are what you build an approval step out of: a document can sit in front of a human for as long as that takes, and the Peppol network never sees it.
Every draft belongs to one organisation. A draft you did not create, in an organisation you are
not authenticated against, does not exist as far as the API is concerned — the read answers 404,
not 403.
Nothing in GoRoute puts an invoice into an approval queue by itself, and no send path consults your approval rules. If you need a sign-off before a document goes out, hold it as a draft and send it after the sign-off. See an approval step you can build today.
Reading a draft
GET /api/v1/drafts/{draft_id}
Returns the draft's stored invoice data together with the validation state recorded the last time it was validated:
| Field | What it is |
|---|---|
id | The draft's identifier |
name | The name you gave the draft, if any |
invoice_number | Extracted from the invoice data for display |
status | Where the draft is in its life — see below |
invoice_data | The whole invoice, in the same shape you would send to POST /api/v1/invoices |
is_valid | The result of the last validation, not a fresh one |
validation_errors | The errors from that same last validation |
validation_score | A completeness score from 0 to 100, from that same validation |
transaction_id | The transaction the draft became, once it has been sent |
error_message | Why the last send or import failed, when one did |
buyer_name, buyer_peppol_id, currency, total_amount, issue_date, due_date | Extracted from the invoice data for lists and search |
created_at, updated_at | Timestamps |
is_valid, validation_errors and validation_score are stored, not computed on read. They
tell you what validation said when it last ran. If you have changed the draft since, they are
stale — validate again before you trust them.
A draft that is not yours, or an identifier that does not exist, is refused with
404 "Draft not found". Both reads are scoped to the organisation your credential belongs to.
Validating a draft — this changes the draft
POST /api/v1/drafts/{draft_id}/validate
The answer is the validation result:
{
"is_valid": false,
"score": 85,
"errors": [
{
"code": "BUS_014",
"message": "Net amount is required in totals",
"field": "totals.net_amount"
}
],
"warnings": []
}
Each entry in errors and warnings carries a code, a message and the field it is about.
score is a completeness score from 0 to 100. It starts at 100 and loses 15 points for every
error and 3 for every warning, never going below 0 — which is why the single error above scores
85. A draft whose data cannot be parsed at all scores 0.
This call has a persist query parameter and it defaults to true. On the default, the
result is written back onto the draft — is_valid, validation_errors and validation_score are
replaced, and the draft's status moves:
- A draft that passes becomes
ready. - A draft that fails becomes
draftagain — unless it is in theexceptionstate, which is left alone, so an imported invoice stays in the exception list until it genuinely passes or is sent.
Send persist=false for a read-only preview. Use that whenever you are only inspecting a draft,
for example when opening a correction screen: with the default, merely looking at an imported
invoice can move it out of the exception list.
Before validating, the call prepares the stored data: it fills the seller in from your saved
company settings if the draft has none, and normalises the payload so it parses into the canonical
invoice model. That is why an imported draft usually comes back with business-rule errors you can
act on, naming the field, rather than one unhelpful parse error. If the data cannot be parsed at
all you get a single error with code PARSE_ERROR.
See Validation for what the rules are and what the error codes mean.
Draft status values
The values you will see in status are draft, ready, sending, sent, error and
exception. This page describes only the moves it has traced: validation setting ready or
draft, and leaving exception alone. Do not treat the list as a state machine — read the
status you are given rather than predicting it.
The rest of the drafts API
These calls exist and are listed in the API reference with their parameters and response shapes.
Related pages
- Validation — the rules a draft is checked against
- Sender domains — what a draft's email send needs
- Delivery and formats — what happens when a draft is sent
- Webhooks — building an approval step out of drafts