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, DeCA — más el modelo de cuentas: NIF adicionales, acceso cedido, cuentas gestionadas y traspasos de NIF.
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.
Nombres de producto
| Nombre de producto | Interfaz estable | Significado |
|---|---|---|
| Gastos (antes facturas de compra) | purchase_invoices | Registros de compra con sus documentos del proveedor, líneas y pagos. |
| Facturas (antes facturas de venta) | invoices | Facturas emitidas a clientes. |
Los nombres son Expenses / Invoices en inglés y Despeses / Factures en catalán. Los nombres de recursos, scopes, eventos, tools MCP, métodos SDK, comandos CLI y URLs publicadas no cambian. Usa las interfaces existentes; no hay un recurso nuevo llamado expenses.
El gasto se distingue de su justificante fiscal. Factura del proveedor, número de factura, factura simplificada y factura rectificativa conservan su significado fiscal. Los nombres nuevos no cambian los tipos documentales admitidos, los campos obligatorios ni el tratamiento fiscal.
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 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/companies/{company}/verifactu/aeat-access/* se relacionan con ella. |
Cuentas y NIF
El cliente de Factuarea es una cuenta, y los NIF que facturan pertenecen a ella. Estos términos aparecen en rutas como /v1/accounts/{account}/…, en nombres de campos como origin y account_relationship, en scopes y en códigos de error. Los valores de código (owner, admin, member, view, operate, granted, provisioned) son los que envías y recibes y nunca se traducen; los nombres en prosa son los que muestra la aplicación web. Cuentas y NIF es la guía por la que empezar.
| Término | Definición |
|---|---|
| Cuenta (account) | El cliente de Factuarea. Guarda el plan, las claves de API, el equipo, los NIF que facturan y lo que se cobra por ellos. Una credencial pertenece a una cuenta, y {account} en /v1/accounts/{account}/… es el id de esa cuenta, un UUID v7 que GET /v1/me devuelve como account.id. Las capacidades de la cuenta (equipo, invitaciones, titularidad, claves de API, cartera de NIF, traspasos, webhooks y registros de peticiones) son siempre las de tu propia cuenta: cualquier otro {account} responde 404 account_not_found, salvo las cuentas que gestionas, que una lista cerrada de rutas sí acepta. Consulta Cuentas y NIF. |
| NIF de la cuenta (account tax ID) | Un NIF registrado en una cuenta. En la API es una empresa: /v1/companies/{company}/… lo nombra con su id, un UUID v7, nunca con su tax_id. Conserva sus propias facturas, contactos, series y registros VeriFactu, y pertenece como máximo a una cuenta. Su status es active, inactive o archived. El primer NIF de una cuenta es su NIF titular, la empresa con la que se abrió la cuenta: no es un NIF adicional y no se puede traspasar. Consulta el estado de un NIF. |
| Cartera de NIF (tax ID portfolio) | Los NIF de una cuenta: el NIF titular y cada NIF adicional, que lista GET /v1/accounts/{account}/companies. Los NIF que solo alcanzas por un acceso cedido o una cuenta gestionada pertenecen a otra cuenta, así que no forman parte de tu cartera. El alcance cartera de una regla de automatización es más amplio: consulta Automatizaciones. Consulta Cartera de NIF. |
| NIF adicional (additional tax ID) | Todo NIF de una cuenta además del titular. Ocupa una de las plazas contratadas additional-nifs de la cuenta: añadirlo ocupa una plaza libre sin cobro, y solo comprar plazas cobra. Necesita el plan empresario o enterprise, es gratis durante el trial, y el tope de contrato max_additional_nifs puede limitar cuántos tiene la cuenta. El bloque de facturación que describe esa suscripción conserva su nombre anterior, gestoria_seats. Consulta NIF adicionales. |
| Titular (account holder) | La persona propietaria de la cuenta: el rol owner. Hay exactamente una, y solo el titular traspasa la titularidad, con PATCH /v1/accounts/{account}/owner y el scope account:owner. No confundas a la persona con el NIF titular, que es una empresa. Consulta Titularidad de la cuenta. |
| Rol de cuenta (account role) | Lo que es una persona dentro de una cuenta: owner, admin o member. En prosa los nombres son titular, administrador y miembro; los valores de código se quedan tal cual. Un titular y un administrador alcanzan todos los NIF sin grants y administran la cuenta: equipo, NIF y facturación. Un miembro solo alcanza los NIF sobre los que tiene un grant. Consulta Roles y grants. |
| Grant (permiso por NIF) | El acceso de un miembro a un NIF, con el nivel view u operate. Solo un miembro tiene grants: pasar a un miembro a admin los revoca, porque un administrador ya alcanza todo. Se fija con PUT /v1/accounts/{account}/members/{member}/grants/{company}. Consulta Miembros. |
| Nivel de acceso (access level) | Lo que puede hacer una persona, una clave u otra cuenta sobre un NIF: view, operate o none. view lee; operate lee y escribe. Una escritura con view responde 403 company_read_only. none no alcanza nada, y existe solo en una cuenta gestionada, donde el proveedor sigue pagando sin alcanzar ningún NIF: no es un nivel que puedas conceder. En un NIF alcanzado por una relación entre cuentas, el nivel de una clave se fija al emitirla y solo baja. |
| Acceso cedido (granted access) | El acceso que una cuenta da a otra a sus NIF, con el nivel view u operate, a todos (all, incluidos los que añada después) o a una lista. Es una relación entre cuentas con origin granted. Se gestiona solo en la aplicación web, no necesita plan ni módulo, no ocupa plaza de usuario en ninguna de las dos cuentas y la cuenta cedente sigue pagando sus NIF. La cuenta receptora alcanza los NIF por el segmento {company}. Consulta Acceso cedido entre cuentas. |
| Cuenta cedente y cuenta receptora (granting and receiving account) | En un acceso cedido, la cuenta cedente (grantor) lo da y la cuenta receptora (grantee) lo recibe. Un titular o administrador de cada lado opera su mitad en la aplicación web. Las capacidades de la cuenta cedente nunca pasan a la receptora: las de cuenta responden 404 account_not_found, y las de empresa, como GET …/billing o los webhooks de empresa, responden 403 forbidden_action. |
| Cuenta gestionada (managed account) | Una cuenta normal, separada de la del proveedor, que un proveedor de cuentas gestionadas aprovisiona para un cliente con POST /v1/accounts: tiene su propio NIF, su propio perfil fiscal, su propio plan y, una vez reclamada, su propio titular. Nace sin una persona titular y pasa por provisioned y claimed hasta active. El proveedor la opera por una relación con origin provisioned y el nivel none, view u operate, y la paga hasta que el cliente asume el pago. Consulta Cuentas gestionadas. |
| Proveedor de cuentas gestionadas (managed-account provider) | La cuenta que aprovisiona y opera cuentas gestionadas para sus clientes: una gestoría que trabaja en la aplicación web, que necesita el módulo gestoria y un titular o administrador, o una plataforma por la API con los scopes privilegiados accounts:* que concedemos a la cuenta. Paga el plan de cada cuenta gestionada live que aprovisiona, más sus NIF adicionales y plazas de empleado, en una única suscripción mensual managed-accounts, salvo las cuentas con contrato enterprise. GET /v1/me lo marca con account.is_provider. No lo confundas con un proveedor (supplier), la contraparte que emite facturas de compra a una empresa. |
| Pagador (payer) | Quién paga una cuenta. Cada cuenta se paga a sí misma, salvo una cuenta gestionada mientras su proveedor la paga: entonces su titular no puede comprar un plan, plazas de empleado ni NIF adicionales y recibe 403 billing_managed_by_provider. El pagador cambia cuando el titular asume el pago: el cliente conserva el mismo plan y precio y la relación pasa a ser un acceso cedido con el mismo nivel (con none no queda nada que ceder, y la gestión termina). Cuando la gestión termina tras la reclamación, el pago también pasa al titular, pero el proveedor pierde todo el acceso. Consulta Cambio de pagador. |
| Reclamación (claim) | Lo que hace el cliente para hacer suya una cuenta gestionada, en la aplicación web: con el vale, una persona nueva o una que ya tiene cuenta en Factuarea pasa a ser el owner. El proveedor conserva su nivel y sigue pagando hasta que el cliente asume el pago. Una cuenta de pruebas no se puede reclamar. La palabra es solo de las cuentas gestionadas: un NIF que cambia de cuenta se traspasa. Consulta La reclamación. |
| Vale de reclamación (claim voucher) | El secreto de un solo uso que abre la reclamación, en los campos claim_token y claim_url de la respuesta de aprovisionamiento. Caduca a los 14 días, se devuelve una sola vez y reemitirlo invalida los pendientes. Con send_email: true viaja solo en el correo y los dos campos valen null. Consulta El vale de reclamación. |
| Traspaso de NIF (tax ID transfer) | Cómo pasa un NIF de una cuenta a otra. La cuenta que lo entrega lo emite con POST /v1/accounts/{account}/nif-transfers, que devuelve el secret una sola vez, y la cuenta receptora lo acepta con POST /v1/accounts/{account}/nif-transfers/accept. Dura 24 horas salvo que expires_at fije otro instante, como máximo dentro de 7 días, y la cuenta que lo entrega puede revocarlo hasta que alguien lo acepte. El NIF que llega es un NIF adicional de la cuenta receptora, salvo que esa cuenta se registrara sin NIF. Consulta Traspasos de NIF. |
| Asesor externo (external advisor) | La única persona externa a la que una cuenta puede dar acceso, por ejemplo su gestor: siempre un member, uno por cuenta, en cualquier plan, con grants como cualquier otro miembro y sin ocupar plaza. Un titular o administrador lo marca con external_advisor en PATCH /v1/accounts/{account}/members/{member}; un segundo responde 422 external_advisor_already_assigned. Consulta Asesor externo. |
| Importación masiva (bulk import) | La forma de dar de alta NIF y aprovisionar cuentas gestionadas de una vez a partir de ficheros: POST /v1/accounts/imports/preview, POST /v1/accounts/imports y GET /v1/accounts/imports/template. Cada fila elige su mode, own_nif o managed_account, y se aplica por su cuenta, así que la importación no es atómica, y importar el mismo fichero otra vez reconcilia lo que ya existe en lugar de duplicarlo. No tiene herramienta MCP. Consulta Importación masiva de cuentas gestionadas. |
| Webhook de cuenta (account webhook) | Un endpoint de webhook de una cuenta, bajo /v1/accounts/{account}/webhooks, frente a uno de empresa. Escucha los eventos de los NIF de la cuenta, de las cuentas que gestiona y los eventos account.* de la propia cuenta, en un entorno, live o test. Sus eventos llevan el mismo id que sus gemelos de empresa. Consulta Webhooks de cuenta. |
| Registro de peticiones de la cuenta (account request log) | El registro de las peticiones hechas con las credenciales de una cuenta, que se lee con GET /v1/accounts/{account}/request-logs y el scope developers:read. Suma todas las credenciales de la cuenta, en el entorno de la credencial que pregunta, y nunca las de otra cuenta. Consulta Registros de peticiones de la cuenta. |
account_relationship | El filtro de un endpoint de webhook de cuenta, own, managed o all (el valor por defecto): los NIF de tu cuenta, las cuentas que gestionas, o ambos. Cada entrega lleva además su propio account_relationship, own o managed, que dice cómo se relaciona ese evento con tu cuenta. Los valores se quedan tal cual. Consulta el filtro. |
| Cuenta de pruebas (test account) | Una cuenta gestionada creada con una clave fact_test_: vive solo en el entorno de pruebas y su única empresa es un sandbox. Nunca se cobra, nunca se reclama ni se promueve a live, no cuenta para max_managed_accounts, y solo la alcanza una clave de pruebas o la aplicación web en modo pruebas. Consulta Probar cuentas gestionadas con clave fact_test_. |
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). Cada serie de facturas tiene un propósito fijo (invoice_kind: completas, simplificadas, rectificativas o rectificativas de simplificadas) y un documento solo se numera en una serie de su propio propósito; la serie que falta se crea sola en el primer uso. Una serie nunca se elimina y su numeración está protegida: PATCH /v1/companies/{company}/series/{id} la edita (name, code, counter_reset, number_format, initial_number, invoice_kind) bajo las guardas fiscales — el código, la máscara y el propósito quedan fijos cuando existen documentos, y nada de la numeración cambia cuando la AEAT acepta un registro de sus facturas. PUT y DELETE devuelven 405; archiva la serie en su lugar. 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. |
| Emitida (issued invoice) | Una factura que ya se ha emitido: tiene su número definitivo de serie, su registro VeriFactu y sus movimientos de stock, y ya no se puede editar. Estado issued desde la versión de la API 2026-10-01; las versiones anteriores la publican como sent. Emite un borrador con POST /v1/companies/{company}/invoices/{id}/issue. Emitir nunca envía la factura por correo. |
| Enviada (sent invoice) | Una factura emitida que ha llegado al cliente: el servidor de correo aceptó su email de entrega o registraste la entrega con POST /v1/companies/{company}/invoices/{id}/mark-sent (versión 2026-10-01). Es una marca independiente del estado y del cobro, expuesta como is_sent, sent_at (primera entrega) y sent_via (email o manual), y se borra con POST /v1/companies/{company}/invoices/{id}/unsend. Consulta Trabajar con facturas. |
| Modo de generación (generation mode) | Qué hace cada ejecución de una factura recurrente con la factura que genera (generation_mode): draft deja un borrador, issue la emite sin enviarla por correo e issue_and_send la emite y la envía por correo. Consulta Facturas recurrentes. |
| 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/companies/{company}/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/companies/{company}/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/companies/{company}/invoices/simplified-eligibility; agrupa varias en una sola factura sustitutiva completa (tipo F3) con POST /v1/companies/{company}/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/companies/{company}/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/companies/{company}/{resource}/find-by-external-id (body { "external_id": "..." }). Ideal como clave de mapeo al migrar desde otra plataforma — consulta Migración desde Holded. |
Catálogo de productos y precios
| Término | Definición |
|---|---|
| Unidad base | Unidad UNECE canónica que mide producto y stock (C62, KGM, GRM, LTR, MLT, MTR, MTK, HUR o DAY). |
| Presentación | Envase o medida comercial. fixed multiplica por un factor; variable_measure exige la cantidad base real en cada línea. Nunca tiene stock. |
| Variante | Identidad de producto con SKU/código de barras y overrides de precio/coste opcionales. Puede tener stock o delegar movimientos al producto. |
| Oferta de proveedor | Condiciones de compra para producto/variante: proveedor, unidad, conversión, disponibilidad, coste y plazo. Nunca cambia el precio de venta. |
| Tarifa | Conjunto tenant-scoped de precios EUR explícitos para destinos producto/variante/presentación, asignable a clientes y borradores. |
| Snapshot de catálogo | Contexto inmutable de producto, cantidad y precio copiado a una línea para que editar el catálogo no reescriba el histórico. |
Consulta Catálogo de productos y Tarifas.
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/companies/{company}/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/companies/{company}/verifactu/records/find-by-huella, y verifica la integridad de toda la cadena con GET /v1/companies/{company}/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/companies/{company}/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/companies/{company}/invoices/{id}/facturae (firmado XAdES-EPES con certificado activo) y envíalo a FACe vía POST /v1/companies/{company}/invoices/{id}/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/companies/{company}/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/companies/{company}/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/companies/{company}/tax-reports/347; es anual y no acepta un trimestre (enviar uno devuelve un error de validación). |
Control horario
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/companies/{company}/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. |
| Plaza de empleado (employee seat) | La unidad de facturación del control horario. Se contratan plazas en el add-on mensual dedicado employee-seats y crear un empleado ocupa una; un empleado nunca cuenta contra el límite users del plan. Consulta Facturación de plazas de empleado. |
| Plaza contratada (contracted seat) | Una plaza que la cuenta paga, por producto: employee-seats para empleados y additional-nifs para NIF adicionales. La cantidad de la suscripción mensual es la contratada, y nunca baja de la ocupada. Consulta Plazas contratadas. |
| Plaza ocupada (occupied seat) | Una plaza contratada que usa una entidad activa: un empleado activo o un NIF adicional activo de la cuenta. Se calcula en cada lectura y nunca se guarda. Consulta Plazas contratadas. |
| Plaza libre (free seat) | Una plaza contratada que nadie ocupa. Crear o reactivar un empleado o un NIF ocupa una libre sin cobro, y desactivar la libera sin tocar la factura. Sin ninguna libre, la aplicación web responde 422 contracted_seats_exhausted, mientras que la API v1 y el MCP compran las que faltan. Consulta Comprar plazas. |
| Mínimo pactado (agreed minimum) | El número de plazas del que depende el precio pactado de una línea de un paquete de oferta. No impide reducir: bajar de él exige aceptar la pérdida del paquete, y la reducción que llega a efecto termina el paquete entero. Consulta Mínimo pactado. |
| Paquete de oferta (offer package) | De una a tres líneas (plan, plazas de empleado, NIF adicionales) que se canjean con un solo código y se aplican una vez a la cuenta. Termina entero, con todas sus líneas de vuelta al precio de catálogo, si se rompe una de sus condiciones. Solo se canjea en la aplicación web, nunca por la API v1 ni el MCP. Consulta Paquetes de oferta. |
| Reducción pendiente (pending reduction) | Una reducción de plazas contratadas guardada para que surta efecto en la renovación, sin cobro ni abono. Lleva lo que se desactivará en ese momento, y una compra o pedir la cantidad actual la anula. Consulta Reducir plazas. |
| 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. |
Automatizaciones
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/companies/{company}/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/companies/{company}/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é NIF 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 la cartera de la cuenta que la posee: los otros NIF reales de esa cuenta, más los NIF que otra cuenta pone a su alcance por una relación vigente con nivel operate, un acceso cedido o una cuenta gestionada. Nunca vigila la empresa que posee la regla, y entrega el aviso a esa empresa, el NIF titular de la cuenta. No se puede cambiar una vez existe la regla. |
| Gestoría (accounting firm) | El despacho español que lleva la contabilidad de otras empresas. Factuarea no tiene un tipo de cuenta especial para ella: una gestoría es una cuenta como cualquier otra, y su cartera se compone de los NIF que tiene y alcanza —los NIF adicionales de su cuenta, los que otras cuentas le ceden y las cuentas gestionadas que aprovisiona—. El módulo gestoria (planes empresario y enterprise) le da las operaciones de proveedor de la aplicación web y las reglas de cartera, que solo puede crear la empresa titular de la cuenta. Esas reglas solo admiten cinco de los doce tipos de acción —los que avisan, más create_task— porque los otros siete tendrían por sujeto un documento o una tarea de otra empresa 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. |
Documentos de control (DeCA)
El documento de control es obligatorio en formato
digital en el transporte público de mercancías por carretera. Sus términos aparecen en
el recurso transport_documents y en los campos de peso del catálogo.
| Término | Definición |
|---|---|
| DeCA (documento de control) | El documento electrónico de control administrativo del transporte de mercancías por carretera (Orden FOM/2861/2012). Identifica las partes, los envíos, la mercancía, el vehículo y las fechas, y viaja con el conductor como un PDF cuyo código QR abre una URL pública permanente. No es una factura ni un registro VeriFactu. En la API es el recurso transport_documents. |
| Cargador contractual | Quien contrata el transporte en nombre propio. Tu empresa declara su papel en cada documento con company_role: "shipper". |
| Transportista efectivo | Quien realiza materialmente el transporte, incluido el transportista que lo subcontrata. company_role: "carrier". Un transportista extranjero (cabotaje) se identifica con tax_id_country. |
| Envío | Un tramo origen-destino de un documento, con sus líneas de mercancía, su fecha y su magnitud declarada (shipments[]). Un documento puede agrupar varios envíos que comparten cargador y transportista, y cada uno puede salir de un albarán. |
| Magnitud declarada | El peso en kg u otra magnitud (un valor y una unidad libre, como palets) declarada para un envío (declared_measure). Es obligatoria para emitir; el peso del catálogo solo ayuda a rellenarla. |
| Peso bruto de transporte | Lo que pesa en kg una unidad tal como se carga, embalaje incluido (gross_weight_kg): por unidad base en productos y variantes y por unidad comercial en presentaciones fijas. Las líneas de albarán lo congelan al crearse o editarse en borrador. |
| Modificación | Un cambio sobre un documento emitido durante el servicio: mismo número, URL y QR, una versión nueva del PDF con el motivo, quién comunicó el dato (data_origin) y los datos anteriores marcados como ya no válidos. |
| Registro de emisión | El registro de versiones, envíos por email y descargas públicas de un documento, que se exporta bajo demanda como justificante de emisión en PDF. Es la prueba que exime al cargador que demuestra haberlo emitido (art. 7.1 de la Orden). |
| Lugar de carga | Una dirección de la empresa de la que salen los envíos, gestionada en la app. Un envío sin origen toma el lugar de carga por defecto o, si no hay, el domicilio fiscal. |
| Transporte privado complementario | El transporte que una empresa hace con vehículos y conductores propios para su propia mercancía. No necesita DeCA. |
Tareas y proyectos
El módulo de tareas habla el vocabulario de la app. Tres pares se confunden fácilmente con conceptos anteriores y se mantienen separados a propósito: una etiqueta de tarea no es una etiqueta de documento, un campo personalizado de tarea no es un campo personalizado de documento, y el tiempo imputado a una tarea no es un fichaje de jornada.
| Término | Definición |
|---|---|
| Tarea (task) | Una unidad de trabajo de un proyecto, con una clave (DEV-12), un status de tablero (planned, active o archived), una prioridad, fechas opcionales, una persona asignada, etiquetas y valores de campos personalizados. Recurso tasks, scopes tasks:*. Consulta Proyectos y tareas. |
| Proyecto (project) | Agrupa tareas y es dueño de su tablero. Su clave (DEV) prefija las claves de sus tareas y es única en la empresa (recurso projects, scopes projects:*). Lleva los valores de facturación por defecto para facturar el tiempo imputado. |
| Columna (column) | Un paso del tablero de un proyecto. Una columna final (is_final) completa las tareas que entran en ella. planned (el backlog) y archived son estados virtuales, no columnas. |
| Etiqueta de tarea (task label) | Una entrada del catálogo de etiquetas de tarea de la empresa (/v1/companies/{company}/task-labels), con un nombre, un color y tasks_count. No es una etiqueta de documento: las etiquetas de documento clasifican facturas, presupuestos y otros documentos y tienen sus propias reglas. Consulta Etiquetas y campos personalizados. |
| Campo personalizado de tarea (task custom field) | Un campo definido por proyecto —text, number, date, dropdown, boolean o multiselect— cuyos valores viven en las tareas de ese proyecto. No es un campo personalizado de documento, que amplía facturas y otros documentos. |
| Imputación de tiempo de tarea (task time entry) | Tiempo imputado a una tarea, a mano o con un temporizador (/v1/companies/{company}/tasks/{task}/time-entries), facturable por defecto y susceptible de facturarse. No es un fichaje: los fichajes de jornada del control horario son el registro legal de /v1/companies/{company}/time-entries, con sus propios scopes y eventos. Consulta Tiempo imputado a tareas. |
| Temporizador (timer) | Una imputación de tiempo de tarea en marcha —ended_at es null— de la que cada usuario puede tener una por empresa. Detenerlo cierra la imputación. |
| Agenda | El calendario combinado de una ventana de fechas (GET /v1/companies/{company}/agenda): tareas con vencimiento y, en cada capa que la credencial también puede leer, vencimientos de documentos, plazos fiscales, ausencias y festivos. |
| Feed iCal (iCal feed) | Una suscripción de calendario de solo lectura, tras una URL secreta, que publica las tareas con fecha de un proyecto o de una persona. Solo en la app. Consulta Feed iCal. |
| Tablero público (public board) | Una vista de solo lectura del tablero de un proyecto que se puede compartir sin iniciar sesión. Solo en la app: no tiene operación en la API. |
| Enlace de subida (upload link) | Un enlace de un solo uso, válido 30 minutos, con el que alguien sin cuenta sube ficheros a una tarea (POST /v1/companies/{company}/tasks/{task}/upload-links). |
Identificadores de tienda y pedido
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.