Exportació i importació

L'API pública mou dades dins i fora de Factuarea amb dues operacions basades en fitxer: exportar factures a un full de càlcul i importar clients des d'un CSV. Totes dues reutilitzen els mateixos motors que el tauler, i la importació segueix el contracte partial-success: una fila errònia mai enfonsa el fitxer sencer.

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: no crea ni modifica res.

Dos eixos ortogonals controlen la sortida:

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

Importar clients des d'un CSV

POST /v1/clients/import (scope clients:write) llegeix un fitxer delimitat i crea un client per cada fila vàlida. La petició és multipart/form-data —porta un fitxer, no un cos JSON— amb tres camps:

El mapping indica a l'importador quina columna del full alimenta cada camp del client. El conjunt de destí ha d'incloure name i tax_id: sense ells no es pot crear un client i la petició es rebutja amb 422 abans de processar cap fila.

Descarregar la plantilla

GET /v1/clients/import/template retorna un CSV a punt per omplir (UTF-8 amb BOM perquè Excel l'obri bé) la fila de capçalera del qual llista totes les columnes que entén l'importador: Nombre, NIF/CIF, Razón social, Email, Teléfono, camps d'adreça, IVA/retenció per defecte, IBAN i més. Dues files d'exemple mostren el format esperat.

curl -s https://api.factuarea.com/v1/clients/import/template \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -o plantilla-clients.csv

Primer dry run, després importar

Valida sempre amb dry_run=true abans de confirmar. La previsualització retorna un informe per fila i no escriu res:

curl -s -X POST https://api.factuarea.com/v1/clients/import \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -F "file=@clients.csv" \
  -F 'mapping={"Nombre":"name","NIF/CIF":"tax_id","Email":"email"};type=application/json' \
  -F "dry_run=true"

{
  "data": {
    "object": "client_import_preview",
    "total_rows": 3,
    "rows": [
      { "row": 2, "status": "valid", "errors": [], "warnings": [] },
      {
        "row": 3,
        "status": "error",
        "errors": [{ "param": "tax_id", "code": "invalid_tax_id", "message": "El NIF no es válido." }],
        "warnings": []
      },
      { "row": 4, "status": "valid", "errors": [], "warnings": [] }
    ]
  }
}

row és el número de línia (en base 1) al fitxer (la capçalera és la fila 1, així que la primera fila de dades és la 2). status és valid o error; cada ítem de errors[] porta el param afectat, un code estable i un message en castellà.

Quan la previsualització està neta, reenvia el mateix fitxer i mapatge amb dry_run=false (o omet-lo). Només es creen les files vàlides; les rebutjades tornen a failures[], i la resposta segueix la forma partial-success amb un results[] per fila:

{
  "data": {
    "total": 3,
    "successful": 2,
    "failed": 1,
    "failures": [
      {
        "index": 1,
        "error_code": "invalid_tax_id",
        "error_message": "El NIF no es válido.",
        "errors": [{ "param": "tax_id", "code": "invalid_tax_id", "message": "El NIF no es válido." }],
        "warnings": []
      }
    ],
    "results": [
      { "row": 3, "status": "error", "errors": [{ "param": "tax_id", "code": "invalid_tax_id", "message": "El NIF no es válido." }], "warnings": [] }
    ]
  }
}

Sempre es compleix total === successful + failed. Una fila duplicada (un client ja existent, segons la regla de deduplicació) s'omet (skipped), no falla: compta com a successful i no es torna a crear, així que reexecutar el mateix fitxer és segur.

Límit de mida de fitxer

La importació v1 és síncrona per poder retornar el resultat per fila en la mateixa resposta. Els fitxers tenen un límit de menys de 200 files; un fitxer més gran es rebutja amb 422 i el codi client_import_too_large. Divideix una llista gran en lots per sota del límit i importa'ls en seqüència.