Imports i dates

Cada valor monetari, de data i d'hora de l'API pública segueix un petit conjunt de convencions fixes. Són les mateixes a tots els recursos, així que tan aviat com les gestiones en un lloc el teu client funciona a tot arreu.

Diners

Els imports sempre van en euros (EUR) — el camp currency és present a tots els documents i és "EUR" a v1 (ISO 4217). L’escriptura de documents públics continua limitada a EUR; els connectors de botigues poden convertir comandes entrants a EUR.

Els imports porten dos decimals (precisió de cèntims). La representació canònica és un string decimal amb exactament dos decimals, a l'estil Stripe:

{ "price": "1234.56" }

Deixa que l'API calculi els totals

El total d'un document segueix una sola fórmula a tota l'API:

total = subtotal + total_vat + total_surcharge − total_retention

Si necessites previsualitzar el desglossament abans de crear un document — per a un resum de comanda, un carretó o per conciliar les teves pròpies xifres — crida POST /v1/companies/{company}/taxes/calculate-totals amb les línies i llegeix el subtotal, el total_vat, el total_surcharge, el total_retention i el total calculats (imports en EUR), més un desglossament per línia en el mateix ordre:

{
  "subtotal": 250,
  "total_vat": 52.5,
  "total_surcharge": 0,
  "total_retention": 15,
  "total": 287.5,
  "lines": [
    { "subtotal": 100, "vat_amount": 21, "surcharge_amount": 0, "retention_amount": 0, "total": 121 }
  ]
}

El mateix desglossament d'impostos per línia aplica a tots els documents de venda: factures, pressupostos, proformes i albarans accepten tots un retention_rate i un surcharge_rate per línia (retenció d'IRPF i recàrrec d'equivalència, 0–100), i la seva capçalera porta els total_vat, total_surcharge i total_retention agregats. La mateixa fórmula es compleix a tot arreu. Cada línia a més retorna retention_rate i surcharge_rate a la resposta, perquè puguis reconciliar el desglossament línia a línia.

Despeses — impost per línia

Una despesa registra el que et va cobrar un proveïdor, així que cadascuna de les seves línies accepta uns qualificadors fiscals extra que el costat de venda cobreix a la seva manera. A CreatePurchaseInvoiceRequest.lines[] pots fixar:

Les línies de catàleg accepten a més discount_percent (0–100, aplicat abans d'impostos i ja descomptat a subtotal) i el bloc purchase_measurement, que separa embalums, quantitat facturada i cost unitari. En una línia mesurada l'API retorna quantity i unit_price com a strings de 4 decimals; una línia legacy conserva el número que sempre ha publicat, així que parseja tots dos. Consulta Línies de compra mesurades.

El total per línia segueix la mateixa forma que al costat de venda, restant la retenció i sumant el recàrrec:

total de línia = subtotal + impostos − retention_amount + surcharge_amount

El surcharge_rate d'una línia de compra segueix els mateixos parells legals IVA↔recàrrec que una línia de venda, validats al servidor: 21 → 5.2, 10 → 1.4, 4 → 0.5, 0 → 0. El parell 0 → 0 també és vàlid al costat de compra — una línia exempta o a tipus zero porta un recàrrec zero. Un parell il·legal es rebutja amb 422.

exemption_reason qualifica per què una línia queda fora de l'IVA ordinari. És un enum o null (o absent), cosa que significa que la línia hereta la qualificació de la capçalera de la factura, o no en declara cap:

Una línia de despesa que porta alhora un recàrrec i un motiu d'exempció:

{
  "description": "Wholesale goods",
  "quantity": 10,
  "unit_price": "50.00",
  "tax_rate": 21,
  "surcharge_rate": 5.2,
  "retention_rate": 0,
  "vat_deductible": true,
  "exemption_reason": null
}

curl -s -X POST https://api.factuarea.com/v1/companies/$COMPANY_ID/purchase-invoices \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "supplier_id": "01931b3e-...s01",
    "received_on": "2026-03-15",
    "lines": [
      { "description": "Exempt service", "quantity": 1, "unit_price": "200.00", "tax_rate": 0, "surcharge_rate": 0, "exemption_reason": "E1" }
    ]
  }' | jq '.data | {subtotal, total_vat, total_surcharge, total_retention, total}'

Venciments de pagament

El payment_terms d'una factura és el seu calendari contractual de venciments. A diferència dels totals anteriors, els seus imports mai no són nombres JSON i mai no s'infereixen.

Una factura de 121.00 repartida en tres venciments:

{
  "payment_terms": [
    { "due_date": "2026-02-15", "amount": "40.00", "payment_means": "01" },
    { "due_date": "2026-03-15", "amount": "30.00", "payment_means": "04",
      "account": { "iban": "ES9121000418450200051332", "bic": "CAIXESBBXXX" } },
    { "due_date": "2026-04-15", "amount": "51.00", "payment_means": "04",
      "account": { "iban": "ES9121000418450200051332", "bic": "CAIXESBBXXX" } }
  ]
}

40.00 + 30.00 + 51.00 suma 121.00. Una factura rectificativa de -50.00 porta "-20.00" i "-30.00". Un calendari que no suma, o amb un import que no és una cadena de dos decimals, respon 422 invalid_invoice_payment_terms i no escriu res: param anomena la fila (payment_terms.1.amount) o payment_terms per a l'ordre, el signe i el total. Ometre, null i [] signifiquen coses diferents (desconegut, treure, sense calendari de forma explícita); consulta Dades de negoci de la factura.

Amb terminis, la factura venç el dia del seu últim termini: a l'exemple anterior, due_on ha de ser 2026-04-15 per emetre-la. Un esborrany conserva una altra data, però emetre'l respon 422 invoice_due_date_not_last_instalment; consulta el calendari de pagaments.

Dates

Les dates de calendari (sense component horari) usen YYYY-MM-DD — la forma de data completa ISO-8601 / RFC 3339. Això cobreix camps com ara issued_on, due_on, paid_on, valid_until, delivery_date, received_on, start_on i end_on:

{
  "issued_on": "2026-03-15",
  "due_on": "2026-04-14",
  "paid_on": "2026-03-20"
}

Envia les dates en el mateix format. Una data no té hora ni zona horària — és el dia de calendari tal com queda registrat per al document.

Període de facturació i data de generació

invoicing_period és { "start_date", "end_date" }, dues dates reals amb start_date <= end_date (les dates iguals són vàlides). Un període que envies substitueix el període sencer i null l'esborra. Cap de les dues dates porta hora ni zona.

La data de generació d'una factura recurrent no és un camp que enviïs: el servidor la fixa com el dia de negoci de la petició que genera la factura, i repetir la mateixa petició retorna la factura ja creada. El calendari relatiu d'una recurrència (payment_terms_template) dona a cada factura nova les seves pròpies dates de venciment, comptades des d'aquell dia.

Timestamps

Els camps d'instant temporal (metadades d'auditoria i cicle de vida com ara created_at, updated_at, signed_at, last_delivery_at) usen strings de data-hora ISO-8601 / RFC 3339 complets. La majoria s'emeten en UTC amb un sufix Z:

{ "created_at": "2026-05-15T10:34:21Z" }

Alguns timestamps porten en el seu lloc un offset Europe/Madrid explícit (+01:00 a l'hivern, +02:00 a l'estiu):

{ "created_at": "2026-04-15T10:31:05+02:00" }

Zona horària per a les quotes

La quota mensual del rate limit es reinicia el dia 1 de cada mes natural a les 00:00 Europe/Madrid (CET/CEST), no en UTC. La quota per minut és una finestra lliscant i la capçalera X-RateLimit-Reset és un UNIX timestamp (segons des de l'epoch, independent de la zona horària). Consulta Rate limits per a la semàntica completa de les finestres.

Sempre que l'API necessita una única referència de calendari civil per a un límit de negoci — períodes fiscals, el reinici de la quota mensual — aquesta referència és Europe/Madrid.

Referència ràpida

Descripcions addicionals de línia

Les línies admeten additional_description nullable de fins a 5000 caràcters al costat de description. Està disponible en factures i rectificatives, pressupostos, proformes, albarans, despeses i plantilles recurrents. Mantén aquest detall separat de quantitats, preus, camps fiscals i identificadors del catàleg; afegir descripció no canvia el càlcul de l’import.