Conceptos clave
Glosario
Términos fiscales y de dominio españoles usados en toda la API de Factuarea — NIF, VeriFactu, AEAT, FacturaE, Modelo 303/347, series, rectificativa, huella, CSV y más.
La API de Factuarea modela conceptos de facturación y cumplimiento fiscal españoles. Si integras desde fuera de España — o simplemente quieres una referencia precisa — este glosario explica los términos del dominio que aparecen en nombres de campos, valores de enum y mensajes de error, y cómo se corresponde cada uno con la API.
Los mensajes de error de la API (error.message) se devuelven en español
porque reflejan la respuesta real de la API. Los campos type, code y
subcode son identificadores estables en inglés — haz match sobre esos, no
sobre el texto del mensaje. Consulta Errors.
Identificadores fiscales
| Término | Definición |
|---|---|
| NIF / CIF / NIE | El número fiscal tributario español. El NIF (Número de Identificación Fiscal) identifica a residentes y empresas, el CIF era el código heredado para personas jurídicas, y el NIE (Número de Identidad de Extranjero) identifica a residentes extranjeros. En la API todos residen en el único campo tax_id de clients, suppliers y tu cuenta. Para contrapartes no españolas usa alternative_id en su lugar — es mutuamente excluyente con tax_id. |
| VAT ID (NIF intracomunitario) | Un número de IVA intracomunitario de la UE, expuesto como el campo vat_id en clients y suppliers. Distinto de tax_id: identifica a la parte para operaciones intracomunitarias exentas de IVA, no para fines fiscales domésticos. |
| AEAT | Agencia Estatal de Administración Tributaria — la agencia tributaria española. Es la receptora de los registros VeriFactu, la autoridad detrás de las declaraciones Modelo y la emisora del CSV. Todos los campos aeat_* y los endpoints /v1/verifactu/aeat-access/* se relacionan con ella. |
Impuestos
| Término | Definición |
|---|---|
| IVA (VAT) | Impuesto sobre el Valor Añadido — el impuesto sobre el valor añadido español. En la API es un impuesto de type: "vat" en el catálogo de impuestos. Aplícalo por línea mediante tax_rate_id; los totales los calcula la API (subtotal + total_vat + total_surcharge − total_retention). Consulta la sección Taxes en la API Reference. |
| Retención (IRPF withholding) | Una retención deducida de una línea y remitida a la AEAT en nombre del destinatario, normalmente IRPF (Impuesto sobre la Renta de las Personas Físicas) para autónomos. Se modela como un impuesto de type: "retention". Resta del total del documento, a diferencia del IVA y el recargo. |
| Recargo de equivalencia (equivalence surcharge) | Un régimen especial de IVA para minoristas: un recargo adicional sumado sobre el IVA para que el minorista no presente declaraciones de IVA por separado. Se modela como un impuesto de type: "surcharge"; una contraparte sujeta a él lleva is_surcharge_subject: true. Suma al total del documento. |
Documentos
| Término | Definición |
|---|---|
| Serie (numbering series) | La secuencia de numeración correlativa y sin huecos a la que pertenece una factura (series_id). Una serie es inmutable por cumplimiento de la AEAT — una vez creada no se puede editar (el método PUT devuelve 405). El modo de prueba usa las propias series de la empresa sandbox y nunca toca tu numeración de producción. Consulta la sección Series en la API Reference y Test mode. |
| Rectificativa (corrective invoice) | Una factura rectificativa que corrige una emitida previamente — la forma legal de arreglar una factura, ya que las facturas emitidas no se pueden editar ni eliminar. Se crea mediante POST /v1/invoices/{id}/corrective; el resultado es una factura nueva con is_corrective: true y un objeto corrective, mapeada a un código de tipo R1–R5 de la AEAT. Compárala con anular (POST /v1/invoices/{id}/annul), que anula sin corregir. |
| Factura simplificada (simplified invoice) | Una factura con datos reducidos (tipo F2 de la AEAT) permitida para importes pequeños bajo el Real Decreto 1619/2012 art. 4, sin los datos completos del destinatario. Comprueba la elegibilidad con POST /v1/invoices/simplified-eligibility; agrupa varias en una sola factura sustitutiva completa (tipo F3) con POST /v1/invoices/substitute-simplified. Una factura ordinaria completa es de tipo F1. |
| Proforma | Una factura proforma de previsualización no fiscal usada para presupuestar o solicitar el pago antes de emitir la factura real (fiscal). No lleva numeración legal y puede convertirse en factura mediante POST /v1/proformas/{id}/convert. Ciclo de vida: draft, accepted, rejected, cancelled, expired, converted. |
| Albarán (delivery note) | Un documento que registra las mercancías entregadas a un cliente (el recurso delivery_notes), que más tarde puede convertirse en factura. Admite una firma manuscrita del destinatario (PNG en base64). Ciclo de vida público: draft, sent, signed, invoiced, cancelled. |
external_id (clave de integración) | Un identificador de negocio externo — el ID del registro en tu propio ERP/CRM/e-commerce — guardado en un recurso para mapearlo y deduplicarlo entre integraciones. De formato libre (≤ 100 caracteres), único por empresa y ortogonal a los identificadores propios de Factuarea (id, number, sku). Busca un registro por él con POST /v1/{recurso}/find-by-external-id (body { "external_id": "..." }). Ideal como clave de mapeo al migrar desde otra plataforma — consulta Migración desde Holded. |
Cumplimiento VeriFactu y AEAT
| Término | Definición |
|---|---|
| VeriFactu | El sistema español de facturación antifraude (SIF) bajo el cual cada factura emitida genera un registro "Alta" a prueba de manipulaciones enviado a la AEAT. En live el registro se transmite a la AEAT; en test se crea localmente pero nunca se transmite. Se gestiona bajo los endpoints /v1/verifactu/*. Consulta Test mode. |
| Huella (hash chain) | La huella encadenada SHA-256 de un registro VeriFactu (campo huella) que enlaza cada registro con el anterior, haciendo la secuencia a prueba de manipulaciones. Busca un registro por ella con POST /v1/verifactu/records/find-by-huella, y verifica la integridad de toda la cadena con GET /v1/verifactu/chain/validate. |
| CSV (Código Seguro de Verificación) | El Código Seguro de Verificación que la AEAT devuelve cuando acepta un registro VeriFactu (el campo aeat_csv; null hasta que se asigna). Es un código de recibo de la AEAT — no un fichero de valores separados por comas. Busca un registro por él con POST /v1/verifactu/records/find-by-csv. |
| FacturaE | El formato XML español de factura electrónica (FacturaE 3.2.2) requerido para facturación B2G a la administración pública. Descárgalo para una factura con GET /v1/invoices/{id}/facturae (firmado XAdES-EPES con certificado activo) y envíalo a FACe vía /v1/face-submissions. Consulta Facturación FACe. |
| FACe | El punto general de entrada de facturas electrónicas de la administración pública española (Ley 25/2013). Factuarea presenta el XML FacturaE firmado al web service de FACe y sigue el estado de tramitación (submitted → registered_rcf → accounted → paid). Consulta Facturación FACe. |
| DIR3 | El directorio español de unidades de la administración pública. Todo cliente B2G lleva tres códigos DIR3 — oficina contable (01), órgano gestor (02) y unidad tramitadora (03) — requeridos por FACe, con formato ^[A-Z][A-Z0-9]{8,9}$. |
| Declaración responsable | Una declaración formal de cumplimiento (declaración responsable) que el productor del software SIF — Factuarea — emite para acreditar la conformidad con VeriFactu. Es a nivel de productor y de solo lectura (no por empresa): recupera la actual con GET /v1/verifactu/declaracion-responsable. |
Declaraciones tributarias
| Término | Definición |
|---|---|
| Modelo 303 | La autoliquidación trimestral española del IVA presentada ante la AEAT. Genérala con POST /v1/tax_reports/303, indicando el trimestre (1–4). La respuesta incluye un desglose por tipo de IVA ({base, cuota} en céntimos). Consulta la sección Tax reports en la API Reference. |
| Modelo 347 | La declaración informativa anual que declara a terceros con quienes las operaciones anuales superaron el umbral legal. Genérala con POST /v1/tax_reports/347; es anual y no acepta un trimestre (enviar uno devuelve un error de validación). |
Eventos
Objetos event de solo lectura con un id opaco. Consulta histórica vía la API y entrega por webhook.
Verificación censal AEAT
Contrasta el par razón social + NIF de tu empresa — y el de tus clientes — contra el censo de la AEAT antes de emitir facturas VeriFactu — estados deterministas, NIFs mágicos del sandbox y comportamiento fail-open.