Create Document

Issue a document: a sale/purchase invoice, a credit note or a proforma.

Only what identifies the document and what it bills is provided. Everything else is derived and refused if sent: the number comes from the journal’s numbering sequence, the payment communication is a structured one built from the document itself, and all the amounts are computed from the lines (subtotal = quantity x unit price, then the VAT of each rate, then the totals). payment_status follows from paid_amount, and the document starts waiting on the accounting side.

The third party is given by relation_id alone: the same identifier space covers business relations and contacts, so which of the two it is never has to be declared — the response says it in relation_type.

payment_terms drives the due date, which is always derived from it and from the issue date — due_date is accepted but ignored. The terms themselves default to the ones set on the third party, and to 30-df when it has none — which is always the case for a contact.

The journal must match the document type (a sale invoice goes in a sales_invoice journal, a purchase credit note in a purchases_credit one); omit journal_id to use the company’s default journal for that category. purchase_invoice and purchase_credit_note are self-billing documents and require self-billing to be enabled on the company.

The PDF and, when the type allows it, the Peppol XML are rendered asynchronously: they are false on the freshly created document and become available shortly after — poll GET /documents/{id} to follow it. In sandbox mode the body is validated exactly as in live mode but nothing is stored, so the returned id is not resolvable.

By default nothing leaves: the document is written and rendered, and that is all. Add ?send_peppol=true to have it put on the network as soon as its files exist — which requires the u permission on top of the c, and a type Peppol carries (not a proforma). One flag per channel, because the channels are independent: mail will join as send_mail, and a document may need one, the other, or both. The send stays asynchronous: the 201 says the document exists, not that it was delivered.

When the send was asked for but could not be started, the answer is 422 send_failed instead of the 201: the error names the document, which was created and numbered. Do not create it again — retry the send with POST /documents/{id}/send.

POST /documents

Create Document

cURL

curl --request POST \
  --url https://api.fidly.be/documents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "<string>",
  "relation_id": "<string>",
  "lines": [
    {
      "item_name": "<string>",
      "quantity": 0,
      "unit_price": 499999999.5,
      "vat_code": "<string>",
      "vat_rate": 50,
      "sequence": 123,
      "subtotal": 123,
      "total": 123,
      "tax_amount": 123,
      "item_description": "<string>",
      "section_name": "<string>",
      "unit_code": "C62",
      "item_properties": {},
      "item_identification": "<string>",
      "product_code": "<string>",
      "allowance_charges": [
        {
          "type": "<string>",
          "amount": 499999999.5,
          "rate": 50,
          "code": "<string>",
          "reason": "<string>"
        }
      ]
    }
  ],
  "relation_type": "<string>",
  "attachments": [
    "<unknown>"
  ],
  "journal_id": "<string>",
  "delivery_location_id": "<string>",
  "issue_date": "2023-12-25",
  "due_date": "2023-12-25",
  "payment_terms": "<string>",
  "tax_point_date": "2023-12-25",
  "delivery_date": "2023-12-25",
  "period_start": "2023-12-25",
  "period_end": "2023-12-25",
  "order_number": "<string>",
  "despatch_reference": "<string>",
  "buyer_reference": "<string>",
  "legal_notice": "<string>",
  "currency": "EUR",
  "paid_amount": 0,
  "allowance_charges": [
    {
      "type": "<string>",
      "amount": 499999999.5,
      "rate": 50,
      "code": "<string>",
      "reason": "<string>"
    }
  ]
}
'

201

{
  "id": "<string>",
  "type": "<string>",
  "origin": "<string>",
  "document_number": "<string>",
  "order_number": "<string>",
  "despatch_reference": "<string>",
  "buyer_reference": "<string>",
  "issue_date": "2023-12-25",
  "due_date": "2023-12-25",
  "tax_point_date": "2023-12-25",
  "delivery_date": "2023-12-25",
  "period_start": "2023-12-25",
  "period_end": "2023-12-25",
  "payment_remittance": "<string>",
  "is_remittance_structured": true,
  "create_date": "2023-11-07T05:31:56Z",
  "currency": "<string>",
  "tax_exclusive_amount": 123,
  "tax_amount": 123,
  "total_amount": 123,
  "paid_amount": 123,
  "remaining_amount": 123,
  "payment_status": "<string>",
  "accounting_status": "<string>",
  "pdf_available": true,
  "xml_available": true,
  "relation_type": "<string>",
  "relation_id": "<string>",
  "journal_id": "<string>",
  "delivery_location_id": "<string>",
  "payment_terms": "<string>",
  "legal_notice": "<string>",
  "peppol_status": "<string>",
  "mail_status": "<string>",
  "attachments": [
    {
      "filename": "<string>",
      "mimetype": "<string>"
    }
  ],
  "allowance_charges": [
    {
      "code": "<string>",
      "type": "<string>",
      "amount": 123,
      "reason": "<string>",
      "rate": 123
    }
  ],
  "lines": [
    {
      "sequence": 123,
      "quantity": 123,
      "vat_rate": 123,
      "item_name": "<string>",
      "item_description": "<string>",
      "unit_price": 123,
      "unit_code": "<string>",
      "vat_code": "<string>",
      "subtotal": 123,
      "total": 123,
      "tax_amount": 123,
      "section_name": "<string>",
      "item_properties": {},
      "item_identification": "<string>",
      "product_code": "<string>",
      "allowance_charges": [
        {
          "code": "<string>",
          "type": "<string>",
          "amount": 123,
          "reason": "<string>",
          "rate": 123
        }
      ]
    }
  ]
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

send_peppol · boolean · default: false

Put the document on the Peppol network as soon as it is written. Requires the u permission in addition to c, and a type Peppol carries. A query parameter, not a body field: it drives what the call does, it is not part of the document. One flag per channel — mail will join as send_mail, the two being independent. Omit it and nothing leaves.

Body

application/json

A document to issue: an invoice, a credit note or a proforma.

Only what identifies the document and what it bills is provided here. Its number, its payment communication and every amount are computed from the lines and the journal.

type · string · required

Kind of document to issue. One of ['sale_invoice', 'sale_credit_note', 'purchase_invoice', 'purchase_credit_note', 'proforma_invoice'].

relation_id · string · required

Opaque identifier of the third party the document is issued to. It says by itself whether it is a company or a contact — nothing else has to be declared.

lines · LineIn · object[] · required

The lines to invoice. At least one is required, 500 at most.

Required array length: 1 - 500 elements

Show child attributes

relation_type · string | null

Ignored: the nature of the third party is read from relation_id, and the relation_type of the response is what it really is. Accepted rather than refused so a document that was read can be posted back unchanged.

attachments · any[] | null

Ignored: files are attached with POST /documents/{id}/attachments, never through this body. Accepted so a document that was read can be sent back unchanged.

journal_id · string | null

Opaque identifier of the journal to book the document in. Defaults to the company's default journal for the category the type requires.

delivery_location_id · string | null

Opaque identifier of one of the third party's saved delivery addresses (GET /delivery-locations?relation_id=…), to record where the goods go. It must belong to the same third party as the document.

issue_date · string<date> | null

Date the document is issued. Defaults to today, and cannot be in the future — a document dated ahead falls outside the window its number is drawn from, and that number would be handed out again to the next document.

due_date · string<date> | null

Ignored: always derived from payment_terms, counted from the issue date — the terms are the only thing a caller drives. Accepted rather than refused so a document that was read can be sent back unchanged.

payment_terms · string | null

Payment terms, as <days>-<basis> where days is 0 or more and the basis is df (from the document's date), fm (from the first day of the following month) or mf (end of the month the delay lands in) — for example 30-df, 0-df for immediate payment. Defaults to the terms set on the third party, and to 30-df when it has none (a contact never has any).

Pattern: ^\d{1,4}-(df|fm|mf)$

tax_point_date · string<date> | null

Date the VAT becomes chargeable, when it differs from the issue date.

delivery_date · string<date> | null

Date the goods/services were actually delivered — a fact, not a plan: today or earlier, never a future date.

period_start · string<date> | null

First day of the billed period.

period_end · string<date> | null

Last day of the billed period.

order_number · string | null

Purchase/sales order number referenced by the document.

Maximum string length: 255

despatch_reference · string | null

Reference of the despatch advice (delivery note).

Maximum string length: 50

buyer_reference · string | null

Reference given by the buyer (e.g. a cost centre).

Maximum string length: 50

legal_notice · string | null

Legal mention printed at the bottom of the document. On a sale invoice it defaults to the one configured on the company, as in the interface. Independently of it, every exempt VAT group (exempted, intra_community, export, reverse_charge, not_subject) carries its own exemption mention on the PDF and in the Peppol XML — the company's configured text for that code, else a standard wording.

Maximum string length: 10000

currency · string · default: EUR

ISO 4217 currency code of every amount, among those Fidly supports (EUR, USD, GBP…). Defaults to EUR.

Maximum string length: 20

paid_amount · number · default: 0

Amount already paid, tax included. Drives payment_status; defaults to 0 (unpaid).

Required range: 0 <= x <= 999999999

allowance_charges · AllowanceChargeIn · object[]

Discounts and surcharges on the document as a whole, applied after the lines and their own. A rate is a percentage of the document's line total; a fixed amount is taken off in full. Each one is spread over the VAT rates of the document in proportion to what they weigh, because the tax it saves belongs to each of them. That spread needs every rate to total a positive amount: if the lines of one rate add up to a negative amount, put the discount on the lines instead.

Maximum array length: 50

Show child attributes

Response

201

application/json

Successful Response

A document of the company: an invoice/credit note it issued or a document it received (purchase invoice, credit note, other). The source table is hidden — the client sees a single unified document identified by an opaque id.

Monetary amounts are decimal numbers in the document's currency. They may be null when the document could not be parsed automatically, or for other_document types that have no financial breakdown.

Both sources are normalised to this shape by the repository adapters; the validators below map the internal codes to their public values.

id · string · required

Opaque unique identifier of the document.

type · string · required

Document type. One of: sale_invoice, sale_credit_note, purchase_invoice, purchase_credit_note, other_document, unknown.

origin · string · required

Channel the document came in through. One of: fidly (generated in Fidly), manual, peppol, mail, odoo, billit, api (or unknown).

document_number · string | null · required

The document's own number (e.g. invoice number).

order_number · string | null · required

Purchase/sales order number referenced by the document.

despatch_reference · string | null · required

Reference of the despatch advice (delivery note) related to the document.

buyer_reference · string | null · required

Reference given by the buyer, to be quoted back on the document (e.g. a cost centre).

issue_date · string<date> | null · required

Date the document was issued (ISO YYYY-MM-DD).

due_date · string<date> | null · required

Payment due date (ISO YYYY-MM-DD).

tax_point_date · string<date> | null · required

Date the VAT becomes chargeable, when it differs from the issue date (ISO YYYY-MM-DD).

delivery_date · string<date> | null · required

Date the goods/services were actually delivered (ISO YYYY-MM-DD).

period_start · string<date> | null · required

First day of the period the document bills (ISO YYYY-MM-DD).

period_end · string<date> | null · required

Last day of the period the document bills (ISO YYYY-MM-DD).

payment_remittance · string | null · required

Communication to quote when paying the document. null when the document carries none.

is_remittance_structured · boolean · required

true when payment_remittance is a structured communication (a bank-checked reference such as a Belgian OGM/VCS) rather than free text. Always true for documents issued by Fidly.

create_date · string<date-time> | null · required

Timestamp the document was created in Fidly (ISO 8601). May be null on rare legacy rows where it was never set.

currency · string | null · required

ISO 4217 currency code of all amounts (e.g. EUR).

tax_exclusive_amount · number | null · required

Total amount excluding tax.

tax_amount · number | null · required

Total tax (VAT) amount.

total_amount · number | null · required

Total amount payable, tax included.

paid_amount · number | null · required

Amount already paid.

remaining_amount · number | null · required

Amount still to be paid (total_amount minus paid_amount).

payment_status · string · required

Payment state. One of: unpaid, partial, paid (or unknown).

accounting_status · string · required

Accounting workflow state. One of: waiting, accepted, transfered, exported, export_error, imported, validated, hidden, exporting, posting, posting_error, deleted (or unknown).

pdf_available · boolean · required

true if a PDF is stored for this document (retrievable via the file endpoint).

xml_available · boolean · required

true if a structured XML version (e.g. Peppol/UBL) is stored for this document.

relation_type · string | null

Nature of relation_id: company (a registered business relation) or contact (an individual contact). null when there is no linked third party.

relation_id · string | null

Opaque identifier of the third party the document is linked to (resolvable via GET /relations/{id}). Its nature is given by relation_type. null when the document has no linked third party.

journal_id · string | null

Opaque identifier of the journal the document is booked in (resolvable via GET /journals/{id}). null when the document has no linked journal.

delivery_location_id · string | null

Opaque identifier of the saved delivery address the document is delivered to (resolvable via GET /delivery-locations/{id}). null when none is set.

payment_terms · string | null

Payment terms the due_date follows from, as <days>-<basis> (e.g. 30-df). Always null on a received document: only documents Fidly issues carry them.

legal_notice · string | null

Legal mention printed at the bottom of the document (e.g. a VAT exemption wording). Always null on received documents.

peppol_status · string | null

Peppol send state of an issued document. One of: not_sent, sending, sent (delivered to the network), accepted (acknowledged by the recipient), rejected (refused by the recipient), failed (or unknown). rejected and failed can be sent again. Always null on a received document.

mail_status · string | null

E-mail send state of an issued document. One of: not_sent, sent, failed (or unknown). Always null on a received document.

attachments · AttachmentOut · object[]

Files attached to the document, in the order they were added. Attach one with POST /documents/{id}/attachments; the API offers no way to remove one. A received document never carries any.

Show child attributes

allowance_charges · AllowanceChargeOut · object[]

Discounts/surcharges applied to the document as a whole, after the lines and their own. tax_exclusive_amount is already net of them.

Show child attributes

lines · LineOut · object[]

Detailed lines of the document (invoiced items/services). Empty when none are stored.

Show child attributes