Exportaciones

Además de la respuesta JSON, Constaia genera ficheros listos para usar con los datos extraídos y el veredicto. Las exportaciones están incluidas en el precio del análisis: no gastan créditos.

FormatosCopy Anchor Link

En csv y xlsx, cada fila empieza por unas columnas comunes (id, fichero, tipo, veredicto, motivos, avisos, fecha), sigue con los campos extraídos y termina con una columna metadata.<clave> por cada clave de metadata. Los campos anidados (por ejemplo lines de una factura) van como JSON en su celda. El CSV usa ; como separador, coma decimal y UTF-8 con BOM, para que Excel en español lo abra bien a la primera.

Las columnas de campos dependen del tipo de documento. La forma más rápida de verlas es generar una exportación en modo test, que es gratis.

Hay dos formas de obtenerlasCopy Anchor Link

1. Al analizar: options.exportCopy Anchor Link

Pide los formatos en la misma petición. Cuando el análisis termina, exports trae una URL firmada por formato:

curl https://api.constaia.com/v1/analyze \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -F file=@invoice.pdf \
  -F 'options={"expect":"invoice","export":["xlsx","json"]}'

"exports": {
  "xlsx": "https://api.constaia.com/v1/files/exp_01J9Z…?expires=1790244002&sig=…",
  "json": "https://api.constaia.com/v1/files/exp_01J9Z…?expires=1790244002&sig=…"
}

• Las URL no necesitan clave de API: la firma es la autorización. Trátalas como un secreto y no las publiques.
• Caducan a las 24 horas. Después devuelven 404.
• GET /v1/analyses/{id} devuelve en exports los enlaces que siguen vigentes.
• Si el análisis es asíncrono, las URL llegan en el webhook analysis.completed.

2. Bajo demanda: GET /v1/analyses/{id}/exportCopy Anchor Link

Genera el fichero en el momento, con tu clave de API, para cualquier análisis terminado cuyos resultados sigan guardados:

curl -OJ "https://api.constaia.com/v1/analyses/an_01J9Z8Q3K4M5N6P7Q8R9S0T1V2/export?format=xlsx" \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"

• format admite json (por defecto), csv, xlsx, xml, vcard o pdf.
• La respuesta es el fichero con Content-Disposition: attachment; filename="an_….xlsx" (por eso curl -OJ lo guarda con su nombre).
• Si el análisis no ha terminado: 409 analysis_not_completed. Espera a completed.
• Si se borró o se creó con keep_results: false: 404 resource_missing.

Descargar desde tu códigoCopy Anchor Link

import { writeFile } from "node:fs/promises";
import { Constaia, InvalidRequestError } from "@constaia/sdk";

const constaia = new Constaia();
const id = process.argv[2]!;

try {
  const res = await constaia.analyses.export(id, "xlsx");
  await writeFile(`${id}.xlsx`, Buffer.from(await res.arrayBuffer()));
  console.log(`Guardado ${id}.xlsx`);
} catch (err) {
  if (err instanceof InvalidRequestError && err.code === "analysis_not_completed") {
    console.error("El análisis aún no ha terminado.");
  } else {
    throw err;
  }
}

Para descargar una URL firmada de exports no hace falta el SDK ni la clave: basta un GET.

curl -o factura.xlsx "https://api.constaia.com/v1/files/exp_01J9Z…?expires=1790244002&sig=…"

Exportación combinada de un loteCopy Anchor Link

En un lote, options.export se aplica al lote: cuando terminan todos los documentos, Constaia genera un único fichero por formato con una fila por documento (campos extraídos y veredicto). Las URL llegan en exports del objeto lote y en el webhook batch.completed:

curl https://api.constaia.com/v1/batches \
  -H "Authorization: Bearer $CONSTAIA_API_KEY" \
  -F "files[]=@factura-1.pdf" \
  -F "files[]=@factura-2.pdf" \
  -F 'options={"expect":"invoice","export":["xlsx"]}'

{
  "id": "bat_01J9Z…",
  "object": "batch",
  "status": "completed",
  "total": 2,
  "exports": { "xlsx": "https://api.constaia.com/v1/files/exp_01J9Z…?expires=…&sig=…" }
}

Es la forma más cómoda de pasar un montón de facturas a Excel. Guía completa: facturas a Excel.

PrivacidadCopy Anchor Link

Los ficheros exportados se guardan cifrados, como los documentos, y se borran al borrar el análisis (DELETE /v1/analyses/{id}). Los enlaces firmados caducan a las 24 horas. Más en almacenamiento y privacidad.

Siguientes pasosCopy Anchor Link