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.
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 contacts 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 contacts. 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.
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.
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. El código se deriva del slug correction_reason por defecto, pero puedes forzarlo de forma explícita con correction_code (R1–R5): una original simplificada (F2) solo admite R5, y una original completa (F1/F3) solo R1–R4 — un código incompatible devuelve 422 con los códigos legales en error.allowed_values. Una justification opcional (min:10) registra la traza documental que la LIVA exige para algunas causas (concurso, incobrable). 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.
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.
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).
El sistema de control horario cubre el deber
español de registro de jornada. Sus términos aparecen en nombres de campo y
valores de enum de los dominios de control horario, todos tras el módulo
control_horario.
Término
Definición
RD-ley 8/2019
El Real Decreto-ley 8/2019 (art. 34.9 del Estatuto de los Trabajadores), que obliga a las empresas españolas a llevar un registro diario objetivo, fiable e inalterable de la jornada de cada empleado y conservarlo cuatro años para la Inspección de Trabajo (ITSS). Factuarea lo construye como un ledger inmutable (de sola adición) sellado por una cadena de hash SHA-256 por empresa — el patrón de inviolabilidad de VeriFactu aplicado a la jornada. Consulta Control horario.
Fichaje (time entry)
Cada evento de fichaje — entrada, pausa, reanudación, salida — añadido al ledger inmutable (el recurso time_entries) y nunca editado ni borrado. El estado de sesión en vivo (working, paused, finished) se deriva del ledger, no se guarda en una columna. Consulta Fichajes.
Jornada (working day)
La jornada laboral de un empleado. Puede partirse en varios turnos (jornada partida) cuando el empleado ficha salida y vuelve a fichar entrada el mismo día; las horas semanales esperadas vienen del horario de trabajo asignado.
Registro inalterable (ledger)
El registro horario inmutable y encadenado por hash. No se puede actualizar ni borrar: un error se corrige con una solicitud de corrección que añade un asiento nuevo referido al original, de modo que tanto el fallo como su arreglo quedan en el registro. Verifica su integridad con GET /v1/time-entries/chain/validate.
Cierre mensual (monthly close)
Una instantánea que congela los saldos y el desglose de ausencias de un mes finalizado y bloquea el periodo frente a fichajes retroactivos (el recurso monthly-register-closes). Va de closed ⇄ reopened; la reapertura es una recuperación auditada. Consulta Cierre mensual.
Sellado (seal)
La firma opcional e irreversible de un cierre mensual: un digest SHA-256 canónico más una firma RSA-SHA256 desacoplada hecha con el certificado de la empresa, para que un auditor pueda probar que la instantánea no ha cambiado desde su firma. Un sellado por cierre — volver a sellar devuelve 409.
Asiento de empleado (employee seat)
La unidad de facturación del control horario. Los empleados se facturan mediante un add-on mensual dedicado (employee-seats) cuya cantidad sigue el censo activo; un empleado nunca cuenta contra el límite users del plan. Consulta Facturación de asientos de empleado.
Tipo de ausencia (absence type)
Lo que un empleado puede solicitar — vacaciones, baja por enfermedad, un día personal — con si es retribuida, si requiere aprobación, y una unidad de medida (days u hours). Cada empresa nueva recibe un conjunto español por defecto. Consulta Ausencias.
Política de ausencia (absence policy)
La regla que decide cuánto y para quién: una dotación (limited días o unlimited), un método de devengo (annual o monthly), los tipos que cubre y los empleados a los que se asigna.
Saldo (balance)
La dotación restante por empleado y tipo de ausencia, derivada del devengo de la política menos las solicitudes aprobadas (el recurso absence-balances).
Presencialidad (presence)
La vista de solo lectura de quién está trabajando ahora mismo y quién está en oficina o en remoto hoy, derivada del ledger, los horarios y el censo — nunca persistida. No existe el scope presence:write: declarar presencia en oficina o remoto es una tarea solo del portal. Consulta Presencia.
El motor de automatizaciones convierte un evento en
trabajo. Su vocabulario es el que muestra el editor de reglas en español, y dos
de sus valores de enum son literales españoles que te encuentras en la API. Todo
lo de aquí está tras el módulo automations.
Término
Definición
Automatización (automation rule)
Una regla con tres piezas móviles: el evento que escucha (trigger_type), la condición que decide si un evento concreto es su caso (conditions) y las acciones ordenadas que se ejecutan (actions). Una regla nueva nace en draft y no escucha nada hasta que la activas. Consulta Automatizaciones.
Disparador (trigger)
El tipo de evento que escucha una regla, en forma resource.action (invoice.paid). Pide a GET /v1/automations/catalog los disparadores a los que tu empresa puede suscribirse —ya filtrados por los módulos que incluye tu plan— y haz una segunda llamada para los campos evaluables del que hayas elegido.
Ensayo (dry run)
Lo que una regla haría ante un evento de ejemplo (POST /v1/automations/rules/{rule}/dry_run). No materializa nada: ni correo, ni entrega de webhook, ni mutación, ni fila de ejecución, y no consume ni el presupuesto mensual ni el límite de frecuencia del motor.
Ejecución (run)
Lo que produce un evento admitido. Congela la definición que ejecutó (rule_version + rule_snapshot) y el payload del evento que la disparó, así que sigue siendo legible cuando la regla ya ha avanzado. blocked —detenida por un límite del motor antes de ejecutar— no es failed.
Paso (step)
Una acción de la definición congelada, identificada por su step_index empezando en cero. Los pasos vuelven siempre en orden de ejecución, cada uno con su action_type, sus parameters congelados, el result que devolvió su adaptador y una marca replayable.
Versión sellada (sealed version)
Editar una regla nunca reescribe su definición anterior: sella una versión nueva y sube current_version. Cada ejecución apunta a la versión exacta que ejecutó, que puede quedar por detrás de la actual — y esa es la gracia.
Relanzamiento (replay)
Rearmar trabajo aparcado, una ejecución entera o un solo paso. Ejecuta de verdad —manda correo, entrega webhooks y llama a terceros— y lleva x-irreversible en el spec. Solo se rearman los pasos aparcados con una razón relanzable.
Alcance empresa / cartera (rule scope)
Qué empresas vigila una regla, en su campo opcional scope. Los dos valores son literales españoles: empresa (el valor por defecto) vigila la empresa que posee la regla; cartera vigila todas las empresas gestionadas por una gestoría y le entrega el aviso a ella. No se puede cambiar una vez existe la regla.
Gestoría (accounting firm)
El despacho español que lleva la contabilidad de otras empresas. Sus reglas de cartera solo admiten los cuatro tipos de acción que avisan —los otros cuatro tendrían por sujeto un documento de la empresa gestionada— y cada ejecución nombra en subject_company la empresa sobre la que actuó.
discard_reason_label
La etiqueta humana de un discard_reason tipado (condition_not_matched, rate_limit_exceeded…), siempre en español: pertenece al vocabulario del motor y no sigue Accept-Language. Ramifica sobre discard_reason, que es un catálogo cerrado, nunca sobre su etiqueta.
Una tienda es el comercio electrónico configurado de una empresa, identificado por su UUID público. Una conexión del proveedor es la autorización detrás de integration_id. Un pedido tiene el external_id opaco del proveedor. channel describe el origen de la factura y source_store_id apunta a la tienda de origen. En los eventos públicos de pedido, el identificador de tienda es específicamente data.store.uuid; conserva esa clave del formato de intercambio.
