Skip to content

Commercial documents ​

Lifecycle of commercial billing documents per company: draft → issuance, credit notes, proforma or quote → invoice conversion, automatic generation from payments, ES preparatory Verifactu and Facturae XML export.

Key concepts ​

  • Draft / issued: a document is created as draft; issuing freezes the type's code and fiscal classification (documentTypeSnapshot), issuer, recipient, lines, taxes (snapshot), totals, series/number and date. Issued fiscal documents are immutable; corrections → credit note. Old issued documents without a snapshot keep documentTypeSnapshot: null; the system does not infer their classification from the current type.
  • Sequential number: the number is assigned only in the successful issuance transaction (allocateNextNumberInManager), not when creating the draft nor on auto-gen failures.
  • Fiscal identity: issuing a fiscal type requires the company's complete fiscal identity (fiscalName, taxId, fiscalAddress, fiscalCountryCode).
  • Origin document: nota_credito (and types with requiresOriginDocument) require an originDocumentId pointing at an issued fiscal invoice.
  • Origin line: each credit note line is linked to an invoice line through originLineIndex (zero-based). It is inferred only when productId or the normalized description yields a single match; if it is missing or duplicated, the API requires the index. On issuance it keeps the rate, percentage, version and origin of the invoice's fiscal snapshot and recomputes base and tax on the refunded amount, including for manual US rates.
  • Conversion: converting a proforma or quote creates an invoice linked to the origin (draft or issued depending on emit).
  • Nimobase→tenant: recipientMode=company + recipientCompanyId (tenant). Only the platform issuer (isDefault) or a super admin actor; any other OWNER/ADMIN → 403 before resolving the UUID (no 404/201 oracle). Issuer = the document's companyId (platform); recipient = the tenant company's fiscal fields; no Client required. Issuer must ≠ recipient (no self-invoice). Series and sequential numbers stay on the issuer company — never shared with tenant→client.
  • Auto-generation: from billing.invoice-paid / billing.payment-succeeded; configurable type (default factura); the tenant→client path requires clientId in the event or autoGenDefaultClientId (never a self-invoice); the Nimobase→tenant path passes recipientMode=company + recipientCompanyId; actionable failures appear at /documents/auto-gen-failures without inventing data or marking the payment as legally invoiced.
  • RBAC: MEMBER reads only; OWNER/ADMIN write and issue.
  • Preparatory Verifactu: when issuing a fiscal type with an issuer whose fiscalCountryCode=ES, the same transaction creates a chained record (SHA-256 hash + link to the issuer's previous record), a qrPayload (AEAT ValidarQR URL) and aeatStatus=pending_remission. The chain is per issuing company (not per series): concurrent issuances in different series are serialized so they cannot collide in the sequence. There is no remission to AEAT in v1. Non-fiscal types or a non-ES issuer → no record.
  • Facturae export: for documents with documentTypeSnapshot.isFiscal = true and a snapshot code of factura / nota_credito, issued with an ES issuer: generate unsigned Facturae 3.2.2 XML. The XML is validated against the unsigned product profile (assets/facturae/Facturae_v3_2_2_unsigned.xsd) — it is not the Ministry's official XSD nor a FACe homologation: no address pieces are invented; if fiscalPostCode / fiscalTown / fiscalProvince / personTypeCode / residenceTypeCode are missing from the snapshots (captured from company/client), the export is rejected with an actionable error. Old issued documents without documentTypeSnapshot are not reclassified using the current type. Credit notes include Corrective. No XAdES signature and no FACe in v1.
  • Isolation: everything by companyId; cross-company access → 404.

Endpoints ​

All require Authorization: Bearer <token> and a company context (X-Company-Id or a JWT).

MethodRouteRolesNotes
GET/documents/settingsAny roleAuto-gen mapping
PATCH/documents/settingsOWNER, ADMINautoGenEnabled, autoGenDocumentTypeCode, autoGenDefaultClientId
GET/documents/auto-gen-failuresAny roleActionable failures (paginated)
POST/documentsOWNER, ADMINCreate a draft
GET/documentsAny roleList (?status=draft|issued)
GET/documents/:idAny roleDetail
PATCH/documents/:idOWNER, ADMINDrafts only
DELETE/documents/:idOWNER, ADMINDrafts only — 204
POST/documents/:id/emitOWNER, ADMINIssue + snapshots + sequential number (+ Verifactu if fiscal ES)
POST/documents/:id/convertOWNER, ADMINProforma/quote → invoice ({ emit?: boolean })
GET/documents/:id/verifactuAny roleVerifactu record + QR; 404 when not applicable
POST/documents/:id/facturae/exportOWNER, ADMINGenerate XML from the fiscal snapshot; no snapshot → 400
GET/documents/:id/facturaeAny roleDownload the XML; legacy without snapshot requires a persisted artifact
GET/documents/productsAny roleList the active company's reusable products
GET/documents/products/tax-optionsAny roleRates available for the issuing company's fiscal country
POST/documents/productsOWNER, ADMINCreate a product (name, optional description, price, currency, rate)
PATCH/documents/products/:idOWNER, ADMINEdit a product and its fiscal rate
GET/documents/products/searchAny roleSearch by name, currency and limit (maximum 50)
POST/documents/products/quick-createOWNER, ADMINCreate from a line and return a temporary capability if new
PATCH/documents/products/:id/quick-priceOWNER, ADMINUpdate the price of a product created by a write in that session

Billing product catalogue ​

Products belong to the active company and never accept a companyId from the body. GET /documents/products/search searches by name and currency and caps the response at 50 products. POST /documents/products/quick-create returns { product, created, priceEditToken }; the token is only issued when a new product is created (an exact normalized match returns created: false with no token). PATCH /documents/products/:id/quick-price requires that token and updates only the authorized product, actor and company; the token is stored as a hash and expires.

Lines keep an optional productId. When sent, the API looks the product up inside the active company, derives its description (name · description when both values exist) and ignores any description sent by the client. Without productId, description stays mandatory for manual lines and older clients. Description, price and taxes are frozen as line snapshots; changing the catalogue does not modify an already saved invoice. A line with a token updates the master price when leaving the price field only if the value changed; when the document is saved, the last price is applied inside the same transaction and the token is consumed. Products picked from the catalogue do not modify their master price.

The product stores the chosen fiscal rate code. GET /documents/products/tax-options derives the jurisdiction from the active company's fiscalCountryCode and returns the current rates (or the company's own rates under OTROS); in the US it returns an empty list and MANUAL with an explicit percentage is accepted. With no fiscal country configured, no rates are offered. For catalogue rates the API takes the percentage and rateType from the published rate, and when a line is created or edited it resolves the current rate for the issuing company. Changing the product's rate does not rewrite existing lines or issued documents; historical drafts without the new configuration keep the tax they already had. The backend does not infer the rate by name: the fiscal catalogue offers no product classifier.

In credit notes, each line is linked to the corrected invoice line. The API accepts originLineIndex inside lines[]; it may be omitted when the product or the description identifies a single origin line. If several matches exist, the API returns 400 and requires the index. Issuance copies the rate, percentage, type, catalogue version and origin from the original snapshot; it only recomputes base and tax amount for the refunded quantity. Later changes to the product or the catalogue do not change the credit note's fiscal treatment.

Example — Verifactu after issuing ​

http
POST /documents/:id/emit
http
GET /documents/:id/verifactu

Response (excerpt): { "chainSequence": 1, "recordHash": "...", "qrPayload": "https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR?...", "aeatStatus": "pending_remission" }.

Example — Facturae ​

http
POST /documents/:id/facturae/export
GET /documents/:id/facturae

Frontend / SDK contract ​

The catalogue is exposed in the browser and Node SDKs through listProducts(), searchProducts(), getProductTaxOptions(), createProduct() and updateProduct(). Writes require OWNER/ADMIN. The frontend copies the chosen product into an editable line; it does not keep a live relationship with the catalogue.

Documents HTTP contract:

  • Resources under /documents (+ settings / auto-gen-failures / verifactu / facturae).
  • Issuance: POST /documents/:id/emit → body with number, seriesCode, documentTypeSnapshot (code, isFiscal) and the remaining snapshots; if fiscal ES, query GET .../verifactu for the QR (qrPayload string — the frontend renders the QR).
  • Facturae: POST .../facturae/export (metadata) or GET .../facturae (XML download). Generation requires an issued fiscal snapshot with code factura/nota_credito and an ES issuer; 400 when the snapshot is missing or Facturae data (structured address) is incomplete. Old issued documents without evidence are not reclassified; GET may return an already persisted artifact.
  • Verifactu/Facturae: no AEAT/FACe homologation claim; the XSD is the unsigned 3.2.x product profile (not the "official XSD"); no remission and no signature in v1.
  • RBAC: MEMBER reads (including verifactu/facturae GET); OWNER/ADMIN write, issue and export.