Skip to content

Document model

A document in xTool is the core entity for an invoice or credit note. It has a direction, format, status, and optional metadata and content. For more on related concepts: Formats, Transactions, and Status lifecycle.

Direction

  • Inbound — the document was received (e.g. via Peppol).
  • Outbound — the document was created or uploaded by you and can be sent.

Direction is set when the document is created and does not change. In the web app, inbound and outbound documents are shown in Documents → Inbound and Documents → Outbound. In the API you can filter the document list by direction (the direction parameter). See Receive by Peppol and Create documents.

Format

Each document has a format (e.g. Peppol BIS invoice UBL, XRechnung, Factur-X, SAP IDoc). The format determines which validation and conversion rules apply. The full list of formats is in Formats. How to validate and convert documents: Validate and convert.

Status

The document status reflects the current step in its lifecycle. Each step can be in one of three states: processing, completed, or failed. Steps include:

  • create — Document created (e.g. from form or model).
  • upload — Document uploaded (e.g. XML file).
  • import — Document imported (e.g. from an integration).
  • receive — Document received (e.g. via Peppol).
  • send — Document sent (Peppol or email).
  • delete — Document deleted.

Example codes: upload.completed, send.processing, send.failed. The status log is a list of entries (code, details, time) showing the history of status changes. You can view it in the document card in the web app and in API responses. For more on steps and transitions: Status lifecycle.

Metadata

When available, the document includes metadata such as:

  • number, issue_date
  • sender_name, sender_email, sender_id
  • receiver_name, receiver_email, receiver_id

Metadata is filled from the XML or model when the document is created or updated. It is shown in the document card in the web app and returned by the API when you get a document.

Duplicates

If the system detects that a document may be a duplicate (e.g. same business key as another document), it can return related document IDs (e.g. the duplicate_ids field in the API). This helps avoid sending the same invoice twice. In the web app, duplicate information may be shown in a notification or on the document card.

Creating, updating, deleting

  • Create — Upload a model or XML via the API or the web app (Create form or Upload). See Create documents.
  • Update — Replace the content via the API (update model or XML) or by editing in the web app. Validation applies to the new content.
  • Delete — Delete the document via the API or the web app.

Relation to transactions

Each send or receive operation creates a transaction (e.g. send.peppol, send.email, receive.peppol). The document status and the transaction status are related: when a send completes or fails, the document status moves to send.completed or send.failed. A document can have multiple transactions (e.g. multiple send attempts). See Transactions.