Exportació i importació

Exporta factures a un full de càlcul i importa contactes amb rols acumulables de client, proveïdor i lead. Cada operació de fitxers fa servir el seu propi contracte de resposta; revisa la previsualització abans d’escriure.

Exportar factures a un full de càlcul

POST /v1/invoices/export/excel (scope invoices:read) genera un full XLSX o CSV de les teves factures i retorna el fitxer binari. És una operació de lectura al domini: no crea ni modifica res. El POST exigeix Idempotency-Key perquè sí que consumeix recursos de generació de fitxers.

Dos eixos ortogonals controlen la sortida:

Paràmetre	Valors	Significat
`format`	`SUMMARY` (per defecte) · `ITEMS`	Disposició del contingut. `SUMMARY` és una fila per factura; `ITEMS` és una fila per línia de factura (les columnes de capçalera es repeteixen a cada línia).
`file_format`	`xlsx` (per defecte) · `csv`	Format de fitxer.

Tria les factures a exportar de dues maneres:

Per id — passa invoice_ids amb els ids UUID v7 de factures concretes.
Per filtre — omet invoice_ids i acota el conjunt amb status, date_from, date_to, client_id, series_id i search. date_from i date_to filtren per data d'emissió (totes dues incloses); client_id i series_id prenen l'UUID v7 públic del client/sèrie.

curl -s -X POST https://api.factuarea.com/v1/invoices/export/excel \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "ITEMS",
    "file_format": "xlsx",
    "status": "paid",
    "date_from": "2026-01-01",
    "date_to": "2026-03-31"
  }' \
  -o factures-t1.xlsx

El límit de 5000 factures

El conjunt seleccionat té un límit de 5000 factures. Si els teus filtres coincideixen amb més, l'API no trunca de manera silenciosa: retorna 422 amb el codi d'error export_limit_exceeded:

{
  "error": {
    "type": "invalid_request_error",
    "code": "export_limit_exceeded",
    "message": "La exportación supera el máximo de 5000 facturas."
  }
}

Acota el rang de dates, l'estat o el client, o divideix l'exportació en diverses crides, perquè cada petició quedi per sota del límit.

Sostres i pressupost d'empaquetat

Una exportació també pot fallar abans de servir el fitxer:

Estat / code	Significat	Què cal fer
`413 export_document_cap_exceeded`	L'artefacte sol·licitat abasta massa documents.	Divideix per dates, sèrie o lots d'ids.
`413 export_byte_cap_exceeded`	L'arxiu estimat o real supera el sostre de bytes. `subcode` val `before_writing` o `while_writing`; mai no se serveix un fitxer parcial.	Demana menys documents per crida.
`429 export_budget_exceeded`	S'ha exhaurit el pressupost horari d'empaquetat de l'empresa. `subcode` identifica l'eix de documents o artefactes.	Respecta `Retry-After`; canviar d'API key no esquiva un pressupost d'empresa.

Un rebuig per sostre, un període buit i un empaquetat avortat no consumeixen pressupost d'exportació. Tornar a descarregar un artefacte ja materialitzat tampoc.

client_id, series_id i les entrades de invoice_ids es resolen dins de la teva empresa. Un UUID inexistent o d'una altra empresa simplement es descarta de la selecció: mai filtra dades entre empreses ni retorna un 404 global.

Importar contactes des d’un fitxer

Fes servir POST /v1/contacts/import/preview abans de POST /v1/contacts/import. Tots dos requereixen contacts:write, Idempotency-Key i multipart/form-data. L’importador admet fitxers CSV, TXT, XLSX o XLS de fins a 10 MB.

Mapeig i rols

mapping associa camp destí → capçalera de la columna d’origen, per exemple mapping[name]=Name. Omet-lo si les capçaleres ja fan servir els noms canònics. Els destins desconeguts es rebutgen; no es descarten en silenci. Inclou name, una identitat fiscal vàlida i almenys un rol, indicat al fitxer o mitjançant target_roles.

La vista prèvia també retorna source_headers, els noms originals de les columnes llegides del CSV, TXT, XLSX o XLS. Per descobrir les columnes abans de preparar el mapatge, envia el fitxer al mateix endpoint de vista prèvia ometent mapping. Fes servir source_headers per associar cada camp de destinació amb la seva columna i torna a previsualitzar. Les files poden aparèixer com a invalid fins que es mapin els camps obligatoris; descobrir columnes no escriu mai contactes.

curl -X POST https://api.factuarea.com/v1/contacts/import/preview \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@contacts.csv" \
  -F "mapping[name]=Name" \
  -F "mapping[tax_id]=VAT number" \
  -F "mapping[external_id]=Id" \
  -F "target_roles[]=customer" \
  -F "conflict_strategy=reject"

Previsualitza i després importa

La previsualització classifica cada fila com a create, update, add_role, merge_candidate, conflict o invalid. Revisa errors, warnings i target_uuid; resol les identitats ambigües abans d’importar. La resposta inclou total, recomptes per acció, dry_run i queued, en lloc de l’embolcall de l’importador antic de clients.

Envia el fitxer revisat i el mateix mapeig a /v1/contacts/import, amb una idempotency key nova. dry_run=true també valida sense escriure. El valor predeterminat conflict_strategy=reject protegeix les dades existents; tria update o merge deliberadament després de revisar la previsualització. Les importacions grans poden retornar 202 amb queued=true: l’acceptació no demostra que totes les files hagin acabat.

Dades de contacte admeses

L’importador canònic admet external_id, kind, roles, tags, adreça (address_line_1, country_code), identitat fiscal alternativa, billing_emails, bank_accounts, metadata, codis DIR3 i valors per rol (customer_*, supplier_*). Mapeja només les columnes que vulguis escriure. Conserva tots dos rols si un contacte compra i ven; no divideixis mai la seva identitat fiscal en registres duplicats.

Formats de descàrrega i abast públic

Descarrega la plantilla CSV canònica amb GET /v1/contacts/import/template i mapeja’n les columnes explícitament en previsualitzar i importar. Aquesta descàrrega binària està disponible per REST i no té cap tool MCP. FacturaE retorna XML; les descàrregues CSV/PDF/XLSX/ZIP retornen bytes. Les respostes 204 i 304 no tenen body. Fes servir només les operacions de la Referència API vigent.

En aquesta pàgina