Documentos comerciales
Ciclo de vida de documentos de facturación comercial por empresa: borrador → emisión, notas de crédito, conversión proforma/presupuesto → factura, generación automática desde cobros, Verifactu preparatorio ES y export Facturae XML.
Conceptos clave
- Borrador / emitido: se crea en
draft; al emitir se congela código/clasificación fiscal del tipo (documentTypeSnapshot), emisor, receptor, líneas, impuestos (snapshot), totales, serie/número y fecha. Los fiscales emitidos son inmutables; correcciones → nota de crédito. Los emitidos antiguos sin snapshot conservandocumentTypeSnapshot: null; el sistema no deduce su clasificación del tipo actual. - Correlativo: el número se asigna solo en la transacción de emisión exitosa (
allocateNextNumberInManager), no al crear el borrador ni en fallos de auto-gen. - Identidad fiscal: emitir un tipo fiscal exige identidad fiscal completa de la empresa (
fiscalName,taxId,fiscalAddress,fiscalCountryCode). - Documento de origen:
nota_credito(y tipos conrequiresOriginDocument) exigenoriginDocumentIdde una factura fiscal emitida. - Línea de origen: cada línea de una nota de crédito se asocia a una línea de factura con
originLineIndex(base cero). Se infiere solo siproductIdo descripción normalizada da una coincidencia única; si falta o hay duplicados, el API exige el índice. Al emitir conserva tasa, porcentaje, versión y origen del snapshot fiscal de la factura y recalcula base/impuesto sobre el importe abonado, incluso para tasas manuales US. - Conversión: convertir proforma/presupuesto crea una factura enlazada al origen (borrador o emisión según
emit). - Nimobase→tenant:
recipientMode=company+recipientCompanyId(tenant). Solo emisor plataforma (isDefault) o actor super admin; otro OWNER/ADMIN → 403 antes de resolver el UUID (sin oracle 404/201). Issuer = documentcompanyId(platform); receptor = tenant company fiscal fields; no Client required. Issuer must ≠ recipient (no self-invoice). Series/correlativos stay on the issuer company — never shared with tenant→cliente. - Auto-generación: auto-gen desde
billing.invoice-paid/billing.payment-succeeded; tipo configurable (defaultfactura); path tenant→cliente requiereclientIden el evento oautoGenDefaultClientId(nunca autofactura); path pasarecipientMode=company+recipientCompanyId; fallos accionables en/documents/auto-gen-failuressin inventar datos ni marcar el cobro como facturado legalmente. - RBAC: MEMBER solo lectura; OWNER/ADMIN escriben y emiten.
- Verifactu preparatorio: al emitir un tipo fiscal con emisor
fiscalCountryCode=ES, dentro de la misma transacción se crea un registro encadenado (huella SHA-256 + enlace al registro anterior del emisor),qrPayload(URL AEAT ValidarQR) yaeatStatus=pending_remission. La cadena es por empresa emisora (no por serie): emisiones concurrentes en series distintas se serializan para no chocar en la secuencia. No hay remisión a la AEAT en v1. Tipos no fiscales o emisor no ES → sin registro. - Facturae export: para documentos con
documentTypeSnapshot.isFiscal = truey código snapshotfactura/nota_credito, emitidos con emisor ES: generar XML Facturae 3.2.2 unsigned. El XML se valida contra el perfil de producto unsigned (assets/facturae/Facturae_v3_2_2_unsigned.xsd) — no es el XSD oficial del Ministerio ni homologación FACe.: no se inventan piezas de dirección; si faltanfiscalPostCode/fiscalTown/fiscalProvince/personTypeCode/residenceTypeCodeen los snapshots (capturados desde company/client), el export se rechaza con error accionable. Los emitidos antiguos sindocumentTypeSnapshotno se reclasifican usando el tipo actual. NC incluyeCorrective. Sin firma XAdES ni FACe en v1. - Aislamiento: todo 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 | /documents/settings | Cualquier rol | Mapeo auto-gen |
PATCH | /documents/settings | OWNER, ADMIN | autoGenEnabled, autoGenDocumentTypeCode, autoGenDefaultClientId |
GET | /documents/auto-gen-failures | Cualquier rol | Fallos accionables (paginado) |
POST | /documents | OWNER, ADMIN | Crear borrador |
GET | /documents | Cualquier rol | Listar (?status=draft|issued) |
GET | /documents/:id | Cualquier rol | Detalle |
PATCH | /documents/:id | OWNER, ADMIN | Solo borradores |
DELETE | /documents/:id | OWNER, ADMIN | Solo borradores — 204 |
POST | /documents/:id/emit | OWNER, ADMIN | Emitir + snapshots + correlativo (+ Verifactu si fiscal ES) |
POST | /documents/:id/convert | OWNER, ADMIN | Proforma/presupuesto → factura ({ emit?: boolean }) |
GET | /documents/:id/verifactu | Cualquier rol | Registro Verifactu + QR; 404 si no aplica |
POST | /documents/:id/facturae/export | OWNER, ADMIN | Generar XML con snapshot fiscal; sin snapshot → 400 |
GET | /documents/:id/facturae | Cualquier rol | Descargar XML; legado sin snapshot requiere artefacto persistido |
GET | /documents/products | Cualquier rol | Listar productos reutilizables de la empresa activa |
GET | /documents/products/tax-options | Cualquier rol | Tasas aplicables según el país fiscal de la empresa emisora |
POST | /documents/products | OWNER, ADMIN | Crear producto (nombre, descripción opcional, precio, moneda y tasa) |
PATCH | /documents/products/:id | OWNER, ADMIN | Editar producto y su tasa fiscal |
GET | /documents/products/search | Cualquier rol | Buscar por nombre, moneda y límite (máximo 50) |
POST | /documents/products/quick-create | OWNER, ADMIN | Crear desde una línea y devolver capacidad temporal si es nuevo |
PATCH | /documents/products/:id/quick-price | OWNER, ADMIN | Actualizar precio de un producto creado por escritura en esa sesión |
Catálogo de productos de facturación
Los productos pertenecen a la empresa activa y nunca aceptan companyId desde el cuerpo. GET /documents/products/search busca por nombre y moneda y limita la respuesta a 50 productos. POST /documents/products/quick-create devuelve { product, created, priceEditToken }; el token solo se entrega al crear un producto nuevo (una coincidencia exacta normalizada devuelve created: false y sin token). PATCH /documents/products/:id/quick-price requiere ese token y actualiza solo el producto, actor y empresa autorizados; el token se almacena como hash y expira.
Las líneas guardan productId opcional. Cuando se envía, el API busca el producto dentro de la empresa activa, deriva su descripción (nombre · descripción cuando existen ambos valores) e ignora cualquier descripción del cliente. Sin productId, description sigue siendo obligatoria para líneas manuales y clientes antiguos. La descripción, el precio y los impuestos quedan congelados como snapshots de la línea; cambiar el catálogo no modifica una factura ya guardada. Una línea con token actualiza el precio maestro al salir del campo de precio solo cuando el valor cambió; al guardar documento, el último precio se aplica dentro de la misma transacción y consume el token. Productos elegidos del catálogo no modifican su precio maestro.
El producto almacena el código de tasa fiscal elegido. GET /documents/products/tax-options deriva la jurisdicción del fiscalCountryCode de la empresa activa y devuelve las tasas vigentes (o las tasas propias en OTROS); en US devuelve una lista vacía y se admite MANUAL con un porcentaje explícito. Sin país fiscal configurado no se ofrecen tasas. Para tasas de catálogo el API obtiene porcentaje y rateType de la tasa publicada, y al crear o editar una línea resuelve la tasa vigente según la empresa emisora. Cambiar la tasa del producto no reescribe líneas existentes ni documentos emitidos; los borradores históricos sin configuración nueva conservan el impuesto que ya tenían. El backend no deduce la tasa por nombre: el catálogo fiscal no ofrece un clasificador de producto.
En notas de crédito, cada línea se vincula a la línea de factura corregida. El API acepta originLineIndex dentro de lines[]; puede omitirlo si el producto o la descripción identifican una sola línea de origen. Si existen varias coincidencias, el API devuelve 400 y requiere el índice. La emisión copia la tasa, porcentaje, tipo, versión de catálogo y origen del snapshot original; solo recalcula base e importe de impuesto según la cantidad abonada. Cambios posteriores al producto o al catálogo no cambian el tratamiento fiscal de la nota.
Ejemplo — Verifactu tras emitir
POST /documents/:id/emitGET /documents/:id/verifactuRespuesta (extracto): { "chainSequence": 1, "recordHash": "...", "qrPayload": "https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR?...", "aeatStatus": "pending_remission" }.
Ejemplo — Facturae
POST /documents/:id/facturae/export
GET /documents/:id/facturaeContrato FE / SDK
El catálogo está expuesto en los SDK de navegador y Node mediante listProducts(), searchProducts(), getProductTaxOptions(), createProduct() y updateProduct(). Las escrituras requieren OWNER/ADMIN. El frontend copia el producto elegido a una línea editable; no mantiene una relación viva con el catálogo.
Contrato HTTP de documentos:
- Recursos bajo
/documents(+ settings / auto-gen-failures / verifactu / facturae). - Emisión:
POST /documents/:id/emit→ cuerpo connumber,seriesCode,documentTypeSnapshot(code,isFiscal) y demás snapshots; si fiscal ES, consultarGET .../verifactupara QR (qrPayloadstring — el FE renderiza el QR). - Facturae:
POST .../facturae/export(meta) oGET .../facturae(XML download). La generación exige snapshot fiscal emitido con códigofactura/nota_creditoy emisor ES; 400 si falta el snapshot o faltan datos Facturae (dirección estructurada). Los emitidos antiguos sin evidencia no se reclasifican;GETpuede devolver un artefacto ya persistido. - Verifactu/Facturae: no claim de homologación AEAT/FACe; XSD = perfil de producto unsigned 3.2.x (no “XSD oficial”); sin remisión ni firma en v1.
- RBAC: MEMBER lectura (incl. verifactu/facturae GET); OWNER/ADMIN escritura/emisión/export.
Relacionado
- Clientes — destinatarios
- Tipos / series — correlativos y tipos
- Catálogo fiscal — snapshots
- Empresas — identidad fiscal