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) andnextNumber = 1. - Fiscal vs non-fiscal:
isFiscalmarks whether the type consumes Verifactu/Facturae rules on issuance (the documents module covers this). Proforma and quote are born non-fiscal. - Credit note:
requiresOriginDocument = trueonnota_credito(and equivalent rectification types). Issuance then requires the origin invoice id (assertOriginLinkRequiredin 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
issueddocuments are linked to a type or series,DELETEon that type or series answers 409 (you cannot delete it, nor reset the counter by recreating the series).isFiscalcannot 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)incommercial_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).
| Method | Route | Roles | Notes |
|---|---|---|---|
GET | /document-types | Any tenant role | Seeds when missing |
POST | /document-types | OWNER, ADMIN | Creates the type + initial series |
GET | /document-types/:id | Any role | Includes series[] |
PATCH | /document-types/:id | OWNER, ADMIN | Name / flags; 409 when changing isFiscal with issued docs |
DELETE | /document-types/:id | OWNER, ADMIN | 204; cascades series; 409 when issued docs exist |
POST | /document-types/:id/series | OWNER, ADMIN | New series |
PATCH | /document-types/:id/series/:seriesId | OWNER, ADMIN | Code/name (not the counter) |
DELETE | /document-types/:id/series/:seriesId | OWNER, ADMIN | 400 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"
}