Skip to content

Document types, series and sequential numbers ​

Configuration of a company's commercial document types: invoice, credit note, proforma, quote or custom ones, each with at least one series and a monotonic integer sequential number.

Key concepts ​

  • Seeds: when a company is created, or the first time types are listed, these are inserted idempotently: factura, nota_credito, proforma, presupuesto, each with a default series (F, NC, PR, PRE) and nextNumber = 1.
  • Fiscal vs non-fiscal: isFiscal marks whether the type consumes Verifactu/Facturae rules on issuance (the documents module covers this). Proforma and quote are born non-fiscal.
  • Credit note: requiresOriginDocument = true on nota_credito (and equivalent rectification types). Issuance then requires the origin invoice id (assertOriginLinkRequired in the service).
  • Sequential number: the number is assigned only when a document is issued, inside the same transaction; a failed issuance consumes no number.
  • Issued documents: if issued documents are linked to a type or series, DELETE on that type or series answers 409 (you cannot delete it, nor reset the counter by recreating the series). isFiscal cannot be changed either while issued documents exist; the rule includes the seeds. An unchanged value and name edits are still allowed. Additional defence: a partial unique index on (company_id, series_code, number) in commercial_documents.
  • RBAC: MEMBER/VIEWER read only; OWNER/ADMIN (and the platform super admin) configure.
  • Isolation: types and series are per companyId; cross-company access → 404.

Endpoints ​

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

MethodRouteRolesNotes
GET/document-typesAny tenant roleSeeds when missing
POST/document-typesOWNER, ADMINCreates the type + initial series
GET/document-types/:idAny roleIncludes series[]
PATCH/document-types/:idOWNER, ADMINName / flags; 409 when changing isFiscal with issued docs
DELETE/document-types/:idOWNER, ADMIN204; cascades series; 409 when issued docs exist
POST/document-types/:id/seriesOWNER, ADMINNew series
PATCH/document-types/:id/series/:seriesIdOWNER, ADMINCode/name (not the counter)
DELETE/document-types/:id/series/:seriesIdOWNER, ADMIN400 when it is the last one; 409 when issued docs exist

Example — create a type ​

http
POST /document-types
Content-Type: application/json

{
  "code": "albaran_fiscal",
  "name": "Albarán fiscal",
  "isFiscal": true,
  "requiresOriginDocument": false,
  "seriesCode": "ALB",
  "seriesName": "Serie ALB"
}