Exportación e importación

Exporta facturas a una hoja de cálculo e importa contactos con roles acumulables de cliente, proveedor y lead. Cada operación de archivos usa su propio contrato de respuesta; revisa la previsualización antes de escribir.

Exportar facturas a una hoja de cálculo

POST /v1/invoices/export/excel (scope invoices:read) genera una hoja XLSX o CSV de tus facturas y devuelve el fichero binario. Es una operación de lectura en el dominio: no crea ni modifica nada. El POST exige Idempotency-Key porque sí consume recursos de generación de ficheros.

Dos ejes ortogonales controlan la salida:

Elige las facturas a exportar de dos maneras:

• Por id — pasa invoice_ids con los ids UUID v7 de facturas concretas.
• Por filtro — omite invoice_ids y acota el conjunto con status, date_from, date_to, client_id, series_id y search. date_from y date_to filtran por fecha de emisión (ambas incluidas); client_id y series_id toman el UUID v7 público del cliente/serie.

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 facturas-t1.xlsx

El tope de 5000 facturas

El conjunto seleccionado tiene un tope de 5000 facturas. Si tus filtros casan con más, la API no trunca de forma silenciosa: devuelve 422 con el código de 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 rango de fechas, el estado o el cliente, o divide la exportación en varias llamadas, para que cada petición quede por debajo del tope.

Topes y presupuesto de empaquetado

Una exportación también puede fallar antes de servir el fichero:

Un rechazo por tope, un periodo vacío y un empaquetado abortado no consumen presupuesto de exportación. Volver a descargar un artefacto ya materializado tampoco.

Importar contactos desde un archivo

Usa POST /v1/contacts/import/preview antes de POST /v1/contacts/import. Ambos requieren contacts:write, Idempotency-Key y multipart/form-data. El importador admite archivos CSV, TXT, XLSX o XLS de hasta 10 MB.

Mapeo y roles

mapping asocia campo destino → cabecera de la columna de origen, por ejemplo mapping[name]=Name. Omítelo si las cabeceras ya usan los nombres canónicos. Los destinos desconocidos se rechazan; no se descartan en silencio. Incluye name, una identidad fiscal válida y al menos un rol, indicado en el archivo o mediante target_roles.

La vista previa también devuelve source_headers, los nombres originales de las columnas leídas del CSV, TXT, XLSX o XLS. Para descubrir las columnas antes de preparar el mapeo, envía el archivo al mismo endpoint de vista previa omitiendo mapping. Usa source_headers para asociar cada campo de destino con su columna y vuelve a previsualizar. Las filas pueden aparecer como invalid hasta mapear los campos obligatorios; descubrir columnas nunca escribe contactos.

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"

Previsualiza y después importa

La previsualización clasifica cada fila como create, update, add_role, merge_candidate, conflict o invalid. Revisa errors, warnings y target_uuid; resuelve las identidades ambiguas antes de importar. La respuesta incluye total, recuentos por acción, dry_run y queued, en lugar del envoltorio del importador antiguo de clientes.

Envía el archivo revisado y el mismo mapeo a /v1/contacts/import, con una idempotency key nueva. dry_run=true también valida sin escribir. El valor predeterminado conflict_strategy=reject protege los datos existentes; elige update o merge deliberadamente tras revisar la previsualización. Las importaciones grandes pueden devolver 202 con queued=true: la aceptación no demuestra que todas las filas hayan terminado.

Datos de contacto admitidos

El importador canónico admite external_id, kind, roles, tags, dirección (address_line_1, country_code), identidad fiscal alternativa, billing_emails, bank_accounts, metadata, códigos DIR3 y valores por rol (customer_*, supplier_*). Mapea solo las columnas que quieras escribir. Conserva ambos roles si un contacto compra y vende; nunca dividas su identidad fiscal en registros duplicados.

Formatos de descarga y alcance público

Descarga la plantilla CSV canónica con GET /v1/contacts/import/template y mapea sus columnas de forma explícita al previsualizar e importar. Esta descarga binaria está disponible por REST y no tiene tool MCP. FacturaE devuelve XML; las descargas CSV/PDF/XLSX/ZIP devuelven bytes. Las respuestas 204 y 304 no tienen body. Usa solo las operaciones de la Referencia API vigente.