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/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.

Factures de compra — impost per línia

Una factura de compra 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 factura de compra 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/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}'

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.

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 de venda i rectificatives, pressupostos, proformes, albarans, factures de compra 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.