Tipos de documento, series y correlativos
Configuración de tipos de documento comerciales por empresa: factura, nota de crédito, proforma, presupuesto u otros personalizados, cada uno con al menos una serie y un correlativo entero monótono.
Conceptos clave
- Semillas: al crear una empresa o al listar tipos por primera vez se insertan de forma idempotente:
factura,nota_credito,proforma,presupuesto, cada uno con una serie por defecto (F,NC,PR,PRE) ynextNumber = 1. - Fiscal vs no fiscal:
isFiscalmarca si el tipo consume reglas Verifactu/Facturae en emisión (módulo de documentos posterior). Proforma/presupuesto nacen no fiscales. - Nota de crédito:
requiresOriginDocument = trueennota_credito(y tipos de rectificación equivalentes). La emisión exigirá el id de la factura origen (assertOriginLinkRequireden el servicio). - Correlativo: el número se asigna solo al emitir un documento, dentro de la misma transacción; una emisión fallida no consume correlativo.
- Emitidos: si hay documentos
issuedligados a un tipo o serie,DELETEde ese tipo/serie responde 409 (no se puede borrar ni reiniciar el correlativo recreando la serie). Tampoco se puede cambiarisFiscalmientras existan emitidos; la regla incluye las semillas. Un valor sin cambios y las ediciones de nombre siguen permitidos. Defensa adicional: índice único parcial(company_id, series_code, number)encommercial_documents. - RBAC: MEMBER/VIEWER solo leen; OWNER/ADMIN (y super admin de plataforma) configuran.
- Aislamiento: tipos y series son por
companyId; acceso cruzado → 404.
Endpoints
Todos requieren Authorization: Bearer <token> y contexto de empresa (X-Company-Id o JWT).
| Método | Ruta | Roles | Notas |
|---|---|---|---|
GET | /document-types | Cualquier rol del tenant | Semillas si faltan |
POST | /document-types | OWNER, ADMIN | Crea tipo + serie inicial |
GET | /document-types/:id | Cualquier rol | Incluye series[] |
PATCH | /document-types/:id | OWNER, ADMIN | Nombre / flags; 409 al cambiar isFiscal si hay emitidos |
DELETE | /document-types/:id | OWNER, ADMIN | 204; cascade series; 409 si hay emitidos |
POST | /document-types/:id/series | OWNER, ADMIN | Nueva serie |
PATCH | /document-types/:id/series/:seriesId | OWNER, ADMIN | Código/nombre (no correlativo) |
DELETE | /document-types/:id/series/:seriesId | OWNER, ADMIN | 400 si es la última; 409 si hay emitidos |
Ejemplo — crear tipo
http
POST /document-types
Content-Type: application/json
{
"code": "albaran_fiscal",
"name": "Albarán fiscal",
"isFiscal": true,
"requiresOriginDocument": false,
"seriesCode": "ALB",
"seriesName": "Serie ALB"
}