Glossary
Spanish fiscal and domain terms used across the Factuarea API — NIF, VeriFactu, AEAT, FacturaE, Modelo 303/347, series, rectificativa, huella, CSV, DeCA — plus the account model: additional tax IDs, granted access, managed accounts and tax ID transfers.
The Factuarea API models Spanish invoicing and tax-compliance concepts. If you are integrating from outside Spain — or just want a precise reference — this glossary explains the domain terms that appear in field names, enum values and error messages, and how each maps to the API.
API error messages (error.message) are returned in Spanish because
they mirror the real API response. The type, code and subcode
fields are stable English identifiers — match on those, not on the
message text. See Errors.
Product names
| Product name | Stable interface | Meaning |
|---|---|---|
| Expenses (formerly purchase invoices) | purchase_invoices | Purchase records with their supplier documents, lines and payments. |
| Invoices (formerly sales invoices) | invoices | Invoices issued to customers. |
The names are Gastos / Facturas in Spanish and Despeses / Factures in Catalan. Resource names, scopes, events, MCP tools, SDK methods, CLI commands and published URLs stay unchanged. Use the existing interfaces; there is no new expenses resource.
An expense is distinct from its fiscal supporting document. Supplier invoice, invoice number, simplified invoice and corrective invoice retain their fiscal meaning. The new names do not change the accepted document types, required fields or tax treatment.
Fiscal identifiers
| Term | Definition |
|---|---|
| NIF / CIF / NIE | The Spanish fiscal tax number. NIF (Número de Identificación Fiscal) identifies residents and companies, CIF was the legacy code for legal entities, and NIE (Número de Identidad de Extranjero) identifies foreign residents. In the API they all live in the single tax_id field on contacts and your account. For non-Spanish counterparties use alternative_id instead — it is mutually exclusive with tax_id. |
| VAT ID (NIF intracomunitario) | An EU intra-community VAT number, exposed as the vat_id field on contacts. Distinct from tax_id: it identifies the party for VAT-exempt intra-EU operations, not for domestic fiscal purposes. |
| AEAT | Agencia Estatal de Administración Tributaria — the Spanish tax agency. It is the recipient of VeriFactu records, the authority behind Modelo declarations, and the issuer of the CSV. All aeat_* fields and the /v1/companies/{company}/verifactu/aeat-access/* endpoints relate to it. |
Accounts and NIFs
Factuarea's customer is an account, and the tax IDs (NIF) that invoice belong to it. These terms appear in paths such as /v1/accounts/{account}/…, in field names such as origin and account_relationship, in scopes and in error codes. The code values (owner, admin, member, view, operate, granted, provisioned) are what you send and receive and are never translated; the names in prose are the ones the web app shows. Accounts and tax IDs is the guide to start with.
| Term | Definition |
|---|---|
| Account | The customer of Factuarea. It holds the plan, the API keys, the team, the tax IDs that invoice and what is billed for them. A credential belongs to one account, and {account} in /v1/accounts/{account}/… is that account's id, a UUID v7 that GET /v1/me returns as account.id. The capabilities of the account (team, invitations, ownership, API keys, tax ID portfolio, transfers, webhooks and request logs) are always those of your own account: any other {account} answers 404 account_not_found, apart from the accounts you manage, which a closed list of routes accepts. See Accounts and tax IDs. |
| Tax ID of the account (NIF) | A tax ID registered in an account. In the API it is a company: /v1/companies/{company}/… names it with its id, a UUID v7, never with its tax_id. It keeps its own invoices, contacts, series and VeriFactu records, and it belongs to at most one account. Its status is active, inactive or archived. The first tax ID of an account is its titular NIF, the company the account was opened with: it is not an additional tax ID and it cannot be given away. See the state of a tax ID. |
| Tax ID portfolio | The tax IDs of an account: the titular NIF and every additional tax ID, which GET /v1/accounts/{account}/companies lists. The tax IDs that you only reach through a granted access or a managed account belong to another account, so they are not part of your portfolio. The cartera scope of an automation rule is wider: see Automations. See Tax ID portfolio. |
| Additional tax ID | Every tax ID of an account besides the titular one. It takes one of the account's contracted additional-nifs seats: adding it occupies a free seat without a charge, and only buying seats charges. It needs the empresario or enterprise plan, it is free during the trial, and the contract cap max_additional_nifs can limit how many the account holds. The billing block that describes that subscription keeps its older name, gestoria_seats. See Additional tax IDs. |
| Account holder (titular) | The person who owns the account: the role owner. There is exactly one, and only the holder hands the ownership over, with PATCH /v1/accounts/{account}/owner and the account:owner scope. Do not confuse the person with the titular NIF, which is a company. See Account ownership. |
| Account role | What a person is inside an account: owner, admin or member. In prose the names are holder (titular), administrator and member; the code values stay verbatim. An owner and an admin reach every tax ID without grants and administer the account: team, tax IDs and billing. A member reaches only the tax IDs on which it has a grant. See Roles and grants. |
| Grant | The access of one member to one tax ID, with the level view or operate. Only a member carries grants: moving a member to admin revokes them, because an administrator already reaches everything. You set one with PUT /v1/accounts/{account}/members/{member}/grants/{company}. See Members. |
| Access level | What a person, a key or another account can do on a tax ID: view, operate or none. view reads; operate reads and writes. A write with view answers 403 company_read_only. none reaches nothing, and it exists only on a managed account, where the provider keeps paying without reaching any tax ID: it is not a level you can grant. On a tax ID reached through a relation between accounts, the level of a key is set when the key is issued and it only goes down. |
| Granted access | The access that one account gives another to its tax IDs, at the level view or operate, for all of them (all, the ones it adds later included) or for a list. It is a relation between accounts with origin granted. It is managed in the web app only, it needs no plan and no module, it takes no user seat from either account and the granting account keeps paying for its tax IDs. The receiving account reaches the tax IDs through the {company} segment. See Granted access between accounts. |
| Granting account and receiving account | In a granted access, the granting account (grantor) gives it and the receiving account (grantee) receives it. An owner or admin of each side operates its half in the web app. The capabilities of the granting account never pass to the receiving one: the account-level ones answer 404 account_not_found, and the company-level ones, such as GET …/billing or the company webhooks, answer 403 forbidden_action. |
| Managed account | A normal account, separate from the provider's, that a provider provisions for a client with POST /v1/accounts: it has its own tax ID, its own fiscal profile, its own plan and, once claimed, its own owner. It is born without a person holding it and goes through provisioned and claimed to active. The provider operates it through a relation with origin provisioned and the level none, view or operate, and pays for it until the client takes over the payment. See Managed accounts. |
| Managed-account provider | The account that provisions and operates managed accounts for its clients: a firm working in the web app, which needs the gestoria module and an owner or admin, or a platform over the API with the privileged accounts:* scopes that we grant to the account. It pays the plan of each live managed account it provisions, plus their additional tax IDs and employee seats, in one monthly managed-accounts subscription, apart from the accounts under an enterprise contract. GET /v1/me marks it with account.is_provider. It is a provider of accounts, not a supplier: a supplier is a counterparty that issues purchase invoices to a company. |
| Payer | Who pays for an account. Every account pays for itself, except a managed account while its provider pays for it: then its holder cannot buy a plan, employee seats or additional tax IDs and gets 403 billing_managed_by_provider. The payer changes when the holder takes over the payment, and the client keeps the same plan and price and the relation becomes a granted access with the same level (at none there is nothing left to grant, and the management ends). When the management ends after the claim the payment also passes to the holder, but the provider loses all access. See Change of payer. |
| Claim | What the client does to make a managed account its own, in the web app: with the voucher, a new person or one who already has a Factuarea account becomes the owner. The provider keeps its level and keeps paying until the client takes over the payment. A test account cannot be claimed. The word belongs only to managed accounts: a tax ID that changes account is a transfer. See The claim. |
| Claim voucher | The single-use secret that opens the claim, in the fields claim_token and claim_url of the provisioning response. It expires after 14 days, it is returned once, and reissuing it invalidates the pending ones. With send_email: true it travels only in the email and both fields are null. See The claim voucher. |
| Tax ID transfer | How a tax ID moves from one account to another. The giving account issues it with POST /v1/accounts/{account}/nif-transfers, which returns the secret once, and the receiving account accepts it with POST /v1/accounts/{account}/nif-transfers/accept. It lasts 24 hours unless expires_at sets another instant, at most 7 days ahead, and the giving account can revoke it until somebody accepts it. The incoming tax ID is an additional one of the receiving account, unless that account was registered without a tax ID. See Tax ID transfers. |
| External advisor | The one outside person an account can give access to, such as its accountant: always a member, one per account, in any plan, with grants like any other member and without taking a seat. An owner or admin marks it with external_advisor in PATCH /v1/accounts/{account}/members/{member}; a second one answers 422 external_advisor_already_assigned. See External advisor. |
| Bulk import | The file-based way to register tax IDs and provision managed accounts in one go: POST /v1/accounts/imports/preview, POST /v1/accounts/imports and GET /v1/accounts/imports/template. Each row chooses its mode, own_nif or managed_account, and is applied on its own, so the import is not atomic, and importing the same file again reconciles what already exists instead of duplicating it. It has no MCP tool. See Bulk import of managed accounts. |
| Account webhook | A webhook endpoint of an account, under /v1/accounts/{account}/webhooks, as opposed to one of a company. It hears the events of the tax IDs of the account, of the accounts it manages and the account.* events of the account itself, in one environment, live or test. Its events carry the same id as their company twins. See Account webhooks. |
| Account request log | The record of the requests made with the credentials of an account, read with GET /v1/accounts/{account}/request-logs and the developers:read scope. It adds up all the credentials of the account, in the environment of the credential that asks, and never those of another account. See Account request logs. |
account_relationship | The filter of an account webhook endpoint, own, managed or all (the default): the tax IDs of your account, the accounts you manage, or both. Every delivery also carries its own account_relationship, own or managed, which says how that event relates to your account. The values stay verbatim. See the filter. |
| Test account | A managed account created with a fact_test_ key: it lives only in the test environment and its only company is a sandbox. It is never charged, it is never claimed or promoted to live, it does not count against max_managed_accounts, and only a test key, or the web app in test mode, reaches it. See Test managed accounts with fact_test_. |
Taxes
| Term | Definition |
|---|---|
| IVA (VAT) | Impuesto sobre el Valor Añadido — Spanish value-added tax. In the API it is a tax of type: "vat" in the tax catalog. Apply it per line via tax_rate_id; totals are computed by the API (subtotal + total_vat + total_surcharge − total_retention). See the Taxes section in the API Reference. |
| Retención (IRPF withholding) | A withholding deducted from a line and remitted to the AEAT on the recipient's behalf, typically IRPF (Impuesto sobre la Renta de las Personas Físicas) for freelancers. Modeled as a tax of type: "retention". It subtracts from the document total, unlike VAT and surcharge. |
| Recargo de equivalencia (equivalence surcharge) | A special VAT regime for retailers: an extra surcharge added on top of VAT so the retailer does not file VAT returns separately. Modeled as a tax of type: "surcharge"; a counterparty subject to it carries is_surcharge_subject: true. It adds to the document total. |
Documents
| Term | Definition |
|---|---|
| Serie (numbering series) | The sequential, gap-free numbering sequence an invoice belongs to (series_id). Every invoice series has a fixed purpose (invoice_kind: complete, simplified, corrective or simplified corrective) and a document is only numbered in a series of its own purpose; the series that is missing is created automatically on first use. A series is never deleted, and its numbering is protected: PATCH /v1/companies/{company}/series/{id} edits it (name, code, counter_reset, number_format, initial_number, invoice_kind) under the fiscal guards — the code, mask and purpose are fixed once documents exist, and nothing numbering-related changes after AEAT accepts a record of its invoices. PUT and DELETE return 405; archive a series instead. Test mode uses the sandbox company's own series and never touches your production numbering. See the Series section in the API Reference and Test mode. |
| Emitida (issued invoice) | An invoice that has been issued: it has its definitive series number, its VeriFactu record and its stock movements, and it can no longer be edited. Status issued from API version 2026-10-01; earlier versions publish it as sent. Issue a draft with POST /v1/companies/{company}/invoices/{id}/issue. Issuing never emails the invoice. |
| Enviada (sent invoice) | An issued invoice that has reached the customer: the mail server accepted its delivery email, or you recorded the delivery with POST /v1/companies/{company}/invoices/{id}/mark-sent (version 2026-10-01). It is a mark independent of the status and of payment, exposed as is_sent, sent_at (first delivery) and sent_via (email or manual), and cleared with POST /v1/companies/{company}/invoices/{id}/unsend. See Working with invoices. |
| Modo de generación (generation mode) | What each run of a recurring invoice does with the invoice it generates (generation_mode): draft leaves a draft, issue issues it without emailing it and issue_and_send issues and emails it. See Recurring invoices. |
| Rectificativa (corrective invoice) | A corrective invoice that amends a previously issued one — the legal way to fix an invoice, since issued invoices cannot be edited or deleted. Created via POST /v1/companies/{company}/invoices/{id}/corrective; the result is a new invoice with is_corrective: true and a corrective object, mapped to an AEAT R1–R5 type code. The code is derived from the correction_reason slug by default, but you can force it explicitly with correction_code (R1–R5): a simplified (F2) original admits only R5, a complete (F1/F3) original only R1–R4 — an incompatible code returns 422 with the legal codes in error.allowed_values. An optional justification (min:10) records the documentary trace the LIVA requires for some causes (insolvency, bad debt). Compare with annul (POST /v1/companies/{company}/invoices/{id}/annul), which voids without amending. |
| Factura simplificada (simplified invoice) | A reduced-data invoice (AEAT type F2) allowed for small amounts under Real Decreto 1619/2012 art. 4, with no full recipient details. Check eligibility with POST /v1/companies/{company}/invoices/simplified-eligibility; group several into one full substitutive invoice (type F3) with POST /v1/companies/{company}/invoices/substitute-simplified. A full ordinary invoice is type F1. |
| Proforma | A non-fiscal preview invoice used to quote or request payment before issuing the real (fiscal) invoice. It carries no legal numbering and can be converted to an invoice via POST /v1/companies/{company}/proformas/{id}/convert. Lifecycle: draft, accepted, rejected, cancelled, expired, converted. |
| Albarán (delivery note) | A document tracking goods delivered to a customer (the delivery-notes resource), which can later be converted to an invoice. Supports a handwritten recipient signature (base64 PNG). Public lifecycle: draft, sent, signed, invoiced, cancelled. |
external_id (integration key) | An external business identifier — the record's ID in your own ERP/CRM/e-commerce — stored on a resource to map and deduplicate it across integrations. Free-format (≤ 100 chars), unique per company, and orthogonal to Factuarea's own identifiers (id, number, sku). Look a record up by it with POST /v1/companies/{company}/{resource}/find-by-external-id (body { "external_id": "..." }). Ideal as the mapping key when migrating from another platform — see Migrate from Holded. |
Product catalog & pricing
| Term | Definition |
|---|---|
| Base unit | The canonical UNECE unit in which a product and its stock are measured (C62, KGM, GRM, LTR, MLT, MTR, MTK, HUR or DAY). |
| Presentation | A commercial package or measure. fixed multiplies by a conversion factor; variable_measure requires the real base quantity on each line. It never owns stock. |
| Variant | A product identity with optional SKU/barcode and price/cost overrides. It may own stock or delegate movements to the base product. |
| Supplier offer | Purchase conditions for a product/variant: supplier, purchase unit, conversion, availability, cost and lead time. It never changes the sales price. |
| Price list | A tenant-scoped set of explicit EUR prices for product/variant/presentation targets, assignable to clients and draft documents. |
| Catalog snapshot | The immutable product, quantity and price context copied onto a document line so later catalog edits cannot rewrite history. |
See Product catalog and Price lists.
VeriFactu & AEAT compliance
| Term | Definition |
|---|---|
| VeriFactu | The Spanish anti-fraud invoicing system (SIF) under which each issued invoice generates a tamper-evident "Alta" record submitted to the AEAT. In live the record is transmitted to the AEAT; in test it is created locally but never transmitted. Managed under the /v1/companies/{company}/verifactu/* endpoints. See Test mode. |
| Huella (hash chain) | The chained SHA-256 fingerprint of a VeriFactu record (huella field) that links each record to the previous one, making the sequence tamper-evident. Look up a record by it with POST /v1/companies/{company}/verifactu/records/find-by-huella, and verify the whole chain's integrity with GET /v1/companies/{company}/verifactu/chain/validate. |
| CSV (Código Seguro de Verificación) | The Secure Verification Code the AEAT returns when it accepts a VeriFactu record (the aeat_csv field; null until assigned). This is an AEAT receipt code — not a comma-separated-values file. Look up a record by it with POST /v1/companies/{company}/verifactu/records/find-by-csv. |
| FacturaE | The Spanish electronic-invoice XML format (FacturaE 3.2.2) required for B2G invoicing to public administration. Download it for an invoice with GET /v1/companies/{company}/invoices/{id}/facturae (signed XAdES-EPES when a certificate is active) and submit it to FACe via POST /v1/companies/{company}/invoices/{id}/face-submissions. See FACe invoicing. |
| FACe | The general entry point of the Spanish public administration for electronic invoices (Ley 25/2013). Factuarea presents the signed FacturaE XML to the FACe web service and tracks the processing status (submitted → registered_rcf → accounted → paid). See FACe invoicing. |
| DIR3 | The Spanish directory of public-administration units. Every B2G client carries three DIR3 codes — oficina contable (01), órgano gestor (02) and unidad tramitadora (03) — required by FACe, with format ^[A-Z][A-Z0-9]{8,9}$. |
| Declaración responsable | A formal compliance declaration (declaración responsable) that the SIF software producer — Factuarea — issues to attest VeriFactu conformity. It is producer-level and read-only (not per-company): retrieve the current one with GET /v1/companies/{company}/verifactu/declaracion-responsable. |
Tax declarations
| Term | Definition |
|---|---|
| Modelo 303 | The quarterly Spanish VAT (IVA) self-assessment return filed with the AEAT. Generate it with POST /v1/companies/{company}/tax-reports/303, indicating the quarter (1–4). The response includes a per-VAT-rate breakdown ({base, cuota} in cents). See the Tax reports section in the API Reference. |
| Modelo 347 | The yearly informational return declaring third parties with whom annual operations exceeded the legal threshold. Generate it with POST /v1/companies/{company}/tax-reports/347; it is annual and does not accept a quarter (sending one returns a validation error). |
Time tracking (control horario)
The time-tracking system covers the Spanish
working-time duty. Its terms appear in field names and enum values across the
workforce domains, all gated behind the control_horario module.
| Term | Definition |
|---|---|
| RD-ley 8/2019 | Royal Decree-law 8/2019 (art. 34.9 of the Workers' Statute), which obliges Spanish employers to keep an objective, reliable and unalterable daily record of every employee's working day and retain it for four years for the Labour Inspectorate (ITSS). Factuarea builds it as an append-only ledger sealed by a per-company SHA-256 hash chain — the VeriFactu tamper-evidence pattern applied to attendance. See Time tracking. |
| Fichaje (time entry) | Each clock event — clock in, pause, resume, clock out — appended to the immutable ledger (the time_entries resource) and never edited or deleted. The live session state (working, paused, finished) is derived from the ledger, not stored in a column. See Time clock. |
| Jornada (working day) | An employee's working day. It may split into several shifts (jornada partida) when the employee clocks out and back in on the same day; the expected weekly hours come from the assigned work schedule. |
| Registro inalterable (ledger) | The append-only, hash-chained time record. There is no update or delete: a mistake is fixed by a correction request that appends a new entry referencing the original, so both the error and its fix stay in the record. Verify its integrity with GET /v1/companies/{company}/time-entries/chain/validate. |
| Cierre mensual (monthly close) | A snapshot that freezes a finished month's balances and absence breakdown and locks the period against retroactive entries (the monthly-register-closes resource). It moves closed ⇄ reopened; reopening is an audited recovery. See Monthly close. |
| Sellado (seal) | The optional, irreversible signature of a monthly close: a canonical SHA-256 digest plus a detached RSA-SHA256 signature made with the company certificate, so an auditor can prove the snapshot has not changed since it was signed. One seal per close — re-sealing returns 409. |
| Employee seat | The billing unit for time tracking. You contract seats in the dedicated monthly employee-seats add-on, and creating an employee takes one of them; an employee never counts against the plan users limit. See Employee seat billing. |
| Contracted seat | A seat the account pays for, per product: employee-seats for employees and additional-nifs for additional tax IDs. The quantity of the monthly subscription is the contracted one, and it is always at least the occupied one. See Contracted seats. |
| Occupied seat | A contracted seat that an active entity uses: an active employee, or an active additional tax ID of the account. It is worked out on every read and never stored. See Contracted seats. |
| Free seat | A contracted seat nobody occupies. Creating or reactivating an employee or a tax ID takes a free one at no charge, and deactivating releases it without touching the invoice. With none free, the web app answers 422 contracted_seats_exhausted, while the v1 API and MCP buy the missing ones. See Buy seats. |
| Agreed minimum | The number of seats a line of an offer package depends on for its agreed price. It does not stop you from reducing: going below it needs you to accept losing the package, and the reduction that takes effect ends the whole package. See Agreed minimum. |
| Offer package | One to three lines (plan, employee seats, additional tax IDs) redeemed with a single code and applied once to the account. It ends entire, with all its lines back at the catalogue price, if one of its conditions breaks. It is redeemed in the web app only, never through the v1 API or MCP. See Offer packages. |
| Pending reduction | A reduction of contracted seats saved to take effect at renewal, with no charge and no credit. It carries what will be deactivated at that moment, and a purchase or asking for the current quantity cancels it. See Reduce seats. |
| Tipo de ausencia (absence type) | What an employee can request — holiday, sick leave, a personal day — carrying whether it is paid, whether it needs approval, and a measurement unit (days or hours). A default Spanish set is seeded into every new company. See Absences. |
| Política de ausencia (absence policy) | The rule that decides how much and for whom: an allowance (limited days or unlimited), an accrual method (annual or monthly), the types it covers and the employees it is assigned to. |
| Saldo (balance) | The remaining allowance per employee and absence type, derived from the policy accrual minus approved requests (the absence-balances resource). |
| Presencialidad (presence) | The read-only view of who is working right now and who is in office or remote today, derived from the ledger, the schedules and the roster — never persisted. There is no presence:write scope: declaring office/remote presence is a portal-only task. See Presence. |
Automations
The automation engine turns an event into work. Its
vocabulary is the one the rule editor shows in Spanish, and two of its enum
values are Spanish literals you meet in the API. Everything here is gated behind
the automations module.
| Term | Definition |
|---|---|
| Automatización (automation rule) | A rule with three moving pieces: the event it listens to (trigger_type), the condition that decides whether a given event is its case (conditions), and the ordered actions that run (actions). A new rule is born draft and hears nothing until you activate it. See Automations. |
| Disparador (trigger) | The event type a rule listens to, in resource.action form (invoice.paid). Ask GET /v1/companies/{company}/automations/catalog for the triggers your company can subscribe to — already filtered by the modules your plan includes — and a second call for the evaluable fields of the one you picked. |
| Ensayo (dry run) | What a rule would do against a sample event (POST /v1/companies/{company}/automations/rules/{rule}/dry-run). It materialises nothing: no e-mail, no webhook delivery, no mutation, no run row, and it consumes neither the monthly budget nor the engine's frequency limit. |
| Ejecución (run) | What an admitted event produces. It freezes the definition it executed (rule_version + rule_snapshot) and the payload of the triggering event, so a run stays readable after the rule has moved on. blocked — stopped by an engine limit before executing — is not failed. |
| Paso (step) | One action of the frozen definition, identified by its zero-based step_index. Steps always come back in execution order, each with its action_type, its frozen parameters, the result its adapter returned and a replayable flag. |
| Versión sellada (sealed version) | Editing a rule never rewrites its previous definition: it seals a new version and bumps current_version. Every run points at the exact version it executed, which can lag behind the current one — and that is the point. |
| Relanzamiento (replay) | Rearming parked work, a whole run or a single step. It executes for real — it sends e-mail, delivers webhooks and calls third parties — and it carries x-irreversible in the spec. Only steps parked with a replayable reason are rearmed. |
Alcance empresa / cartera (rule scope) | Which tax IDs a rule watches, in its optional scope field. The two values are Spanish literals: empresa (the default) watches the company that owns the rule; cartera watches the portfolio of the account that owns it: the other real tax IDs of that account, plus the tax IDs that another account puts within its reach through a relation in force at level operate, a granted access or a managed account. It never watches the company that owns the rule, and it delivers the notice to that company, the titular NIF of the account. It cannot be changed once the rule exists. |
| Gestoría (accounting firm) | The Spanish firm that keeps other companies' books. Factuarea has no special kind of account for it: a gestoría is an account like any other, and its portfolio is made of the tax IDs it holds and reaches — the additional tax IDs of its account, the ones other accounts grant it and the managed accounts it provisions. The gestoria module (plans empresario and enterprise) gives it the provider operations of the web app and the cartera rules, which only the titular company of the account can create. Those rules accept only five of the twelve action types — the ones that notify, plus create_task — because the other seven would take a document or a task of another company as their subject — and each run names the company it acted upon in subject_company. |
discard_reason_label | The human label of a typed discard_reason (condition_not_matched, rate_limit_exceeded…), always in Spanish: it belongs to the vocabulary of the engine and does not follow Accept-Language. Branch on discard_reason, which is a closed catalog, never on its label. |
Transport control documents (DeCA)
The transport control document is mandatory in digital
form for Spanish public road freight transport. Its terms appear in the
transport_documents resource and in the catalog weight fields.
| Term | Definition |
|---|---|
| DeCA (documento de control) | The electronic administrative control document of road freight transport (Orden FOM/2861/2012). It identifies the parties, the shipments, the goods, the vehicle and the dates, and travels with the driver as a PDF whose QR code opens a permanent public URL. It is not an invoice nor a VeriFactu record. In the API it is the transport_documents resource. |
| Cargador contractual (contractual shipper) | Whoever hires the transport in their own name. Your company declares its role in each document with company_role: "shipper". |
| Transportista efectivo (effective carrier) | Whoever actually performs the transport, including a carrier that subcontracts it. company_role: "carrier". A foreign carrier (cabotage) is identified with tax_id_country. |
| Envío (shipment) | One origin-destination leg of a document, with its goods lines, its date and its declared measure (shipments[]). A document can group several shipments that share shipper and carrier, and each one can come from a delivery note. |
| Magnitud declarada (declared measure) | The weight in kg or another measure (a value and a free unit such as palets) declared for a shipment (declared_measure). It is required to issue; the catalog weight only helps to fill it in. |
| Peso bruto de transporte (gross transport weight) | The weight in kg of one unit as it is loaded, packaging included (gross_weight_kg): per base unit on products and variants and per commercial unit on fixed presentations. Delivery note lines freeze it when they are created or edited in draft. |
| Modificación (modification) | A change made to an issued document during the service: same number, URL and QR, a new PDF version with the reason, who reported the data (data_origin) and the previous data marked as no longer valid. |
| Registro de emisión (issuance evidence) | The record of versions, email deliveries and public downloads of a document, exported on demand as a PDF proof of issuance. It is the proof that frees the shipper who can show it issued the document (art. 7.1 of the Orden). |
| Lugar de carga (loading place) | A company address from which shipments leave, managed in the app. A shipment without origin takes the default loading place or, without one, the registered address. |
| Transporte privado complementario (private complementary transport) | Transport a company does with its own vehicles and drivers for its own goods. It does not need a DeCA. |
Tasks & projects
The task module speaks the vocabulary of the app. Three pairs are easy to confuse with older concepts and are kept apart on purpose: a task label is not a document tag, a task custom field is not a document custom field, and time logged on a task is not a working-day clock-in.
| Term | Definition |
|---|---|
| Task | A unit of work in a project, with a key (DEV-12), a board status (planned, active or archived), a priority, optional dates, an assignee, labels and custom field values. Resource tasks, scopes tasks:*. See Projects and tasks. |
| Project | Groups tasks and owns their board. Its key (DEV) prefixes the keys of its tasks and is unique in the company (resource projects, scopes projects:*). It carries the billing defaults used to invoice logged time. |
| Column | A step of a project board. A final column (is_final) completes the tasks that enter it. planned (the backlog) and archived are virtual states, not columns. |
| Task label | An entry of the task label catalog of the company (/v1/companies/{company}/task-labels), with a name, a color and tasks_count. It is not a document tag: tags label invoices, quotes and other documents and have their own rules. See Tags & custom fields. |
| Task custom field | A field defined per project — text, number, date, dropdown, boolean or multiselect — whose values live on the tasks of that project. It is not a document custom field, which extends invoices and other documents. |
| Task time entry | Time logged on a task, by hand or with a timer (/v1/companies/{company}/tasks/{task}/time-entries), billable by default and possibly invoiced. It is not a clocking entry: the working-day clock-ins of Time tracking are the legal register under /v1/companies/{company}/time-entries, with their own scopes and events. See Time logged on tasks. |
| Timer | A running task time entry — ended_at is null — of which each user can have one per company. Stopping it closes the entry. |
| Agenda | The combined calendar of a date window (GET /v1/companies/{company}/agenda): due tasks and, for every layer the credential can also read, due dates of documents, tax deadlines, absences and holidays. |
| iCal feed | A read-only calendar subscription, behind a secret URL, that publishes the dated tasks of a project or of one person. App-only. See iCal feed. |
| Public board | A read-only view of a project board that can be shared without a login. App-only: it has no operation in the API. |
| Upload link | A single-use link, valid for 30 minutes, with which someone without an account uploads files to a task (POST /v1/companies/{company}/tasks/{task}/upload-links). |
Store and order identifiers
A store is a company’s configured ecommerce shop, identified by its public UUID. A provider connection is the authorization behind integration_id. An order has the provider’s opaque external_id. Invoice channel describes the origin and source_store_id points to the source store. In public order events, the store identifier is specifically data.store.uuid; keep that wire-format key unchanged.