Skip to content

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 conservan documentTypeSnapshot: 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 con requiresOriginDocument) exigen originDocumentId de 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 si productId o 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 = document companyId (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 (default factura); path tenant→cliente requiere clientId en el evento o autoGenDefaultClientId (nunca autofactura); path pasa recipientMode=company + recipientCompanyId; fallos accionables en /documents/auto-gen-failures sin 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) y aeatStatus=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 = true y código snapshot factura / 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 faltan fiscalPostCode / fiscalTown / fiscalProvince / personTypeCode / residenceTypeCode en los snapshots (capturados desde company/client), el export se rechaza con error accionable. Los emitidos antiguos sin documentTypeSnapshot no se reclasifican usando el tipo actual. NC incluye Corrective. 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étodoRutaRolesNotas
GET/documents/settingsCualquier rolMapeo auto-gen
PATCH/documents/settingsOWNER, ADMINautoGenEnabled, autoGenDocumentTypeCode, autoGenDefaultClientId
GET/documents/auto-gen-failuresCualquier rolFallos accionables (paginado)
POST/documentsOWNER, ADMINCrear borrador
GET/documentsCualquier rolListar (?status=draft|issued)
GET/documents/:idCualquier rolDetalle
PATCH/documents/:idOWNER, ADMINSolo borradores
DELETE/documents/:idOWNER, ADMINSolo borradores — 204
POST/documents/:id/emitOWNER, ADMINEmitir + snapshots + correlativo (+ Verifactu si fiscal ES)
POST/documents/:id/convertOWNER, ADMINProforma/presupuesto → factura ({ emit?: boolean })
GET/documents/:id/verifactuCualquier rolRegistro Verifactu + QR; 404 si no aplica
POST/documents/:id/facturae/exportOWNER, ADMINGenerar XML con snapshot fiscal; sin snapshot → 400
GET/documents/:id/facturaeCualquier rolDescargar XML; legado sin snapshot requiere artefacto persistido
GET/documents/productsCualquier rolListar productos reutilizables de la empresa activa
GET/documents/products/tax-optionsCualquier rolTasas aplicables según el país fiscal de la empresa emisora
POST/documents/productsOWNER, ADMINCrear producto (nombre, descripción opcional, precio, moneda y tasa)
PATCH/documents/products/:idOWNER, ADMINEditar producto y su tasa fiscal
GET/documents/products/searchCualquier rolBuscar por nombre, moneda y límite (máximo 50)
POST/documents/products/quick-createOWNER, ADMINCrear desde una línea y devolver capacidad temporal si es nuevo
PATCH/documents/products/:id/quick-priceOWNER, ADMINActualizar 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 ​

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

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

Ejemplo — Facturae ​

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

Contrato 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 con number, seriesCode, documentTypeSnapshot (code, isFiscal) y demás snapshots; si fiscal ES, consultar GET .../verifactu para QR (qrPayload string — el FE renderiza el QR).
  • Facturae: POST .../facturae/export (meta) o GET .../facturae (XML download). La generación exige snapshot fiscal emitido con código factura/nota_credito y emisor ES; 400 si falta el snapshot o faltan datos Facturae (dirección estructurada). Los emitidos antiguos sin evidencia no se reclasifican; GET puede 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 ​