Generar archivo ZIP trimestral

Genera y transmite un ZIP binario con todos los PDF de factura del trimestre solicitado.

Cuando la empresa tiene cargos fuera de facturación en ese trimestre y include_non_invoiced_charges no es false (por defecto true), incluye además el CSV trimestral de cargos y reembolsos y los totales por divisa; sin esos cargos se omite el archivo, y si el trimestre no tiene facturas, el ZIP contiene solo ese CSV.
La respuesta informa de los recuentos agregados en las cabeceras X-Quarterly-*; nunca devuelve una ruta de almacenamiento ni un payload de metadatos JSON.

Authorization

AuthorizationBearer <token>

Tu API key como token Bearer: fact_live_… en producción, fact_test_… en sandbox. Consulta la guía de autenticación.

En: header

Parámetros de ruta

company*string

Identificador público (UUID v7) de la empresa. Obtenlo de GET /v1/me (data.scope[].id).

Formatouuid

Clave opaca generada por el cliente (hasta 255 caracteres; se recomienda UUID v7) que permite reintentos seguros: la primera respuesta se almacena y se reproduce en las repeticiones sin volver a ejecutar la mutación. Reutilizar una clave con un cuerpo distinto devuelve 422 idempotency_key_reused; los valores de los campos secretos (password, secret…) cuentan como parte del cuerpo, así que reintentar con un secreto corregido bajo la misma clave es una petición distinta, nunca la repetición de la respuesta anterior. Consulta la guía de idempotencia. Obligatoria en esta operación: repetirla produce un efecto irreversible (un email enviado, un archivo generado, una llamada a un tercero o un cargo), por lo que una petición sin esta cabecera se rechaza con 422 idempotency_key_required antes de ejecutar lógica de negocio.

Longitud1 <= length <= 255

Factuarea-Version?string

Fija la versión de la API (YYYY-MM-DD, versionado por fecha estilo Stripe) para esta petición; omítelo para usar la versión fijada de la clave, o la última si no hay ninguna. Versión no soportada → 400 unsupported_api_version; malformada → 400 parameter_invalid_format. La versión efectiva se refleja en la cabecera de respuesta Factuarea-Version. Consulta la guía de Versioning.

Formatodate

Cuerpo de la petición

application/json

Definiciones de TypeScript

Usa el tipo request body en TypeScript.

year*integer

Rango2000 <= value <= 2027

quarter*integer

Rango1 <= value <= 4

include_index?boolean|null

include_non_invoiced_charges?boolean|null

email?|

Formatoemail

message?|

Longitudlength <= 5000

Cuerpo de la respuesta

`application/zip`

`application/json`

Ejemplo de petición

const apiKey = process.env.FACTUAREA_API_KEY;if (!apiKey) throw new Error("Set FACTUAREA_API_KEY");const response = await fetch("https://api.factuarea.com/v1/companies/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/invoices/quarterly/download-zip", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/zip","Content-Type":"application/json","Idempotency-Key":"erp-2026-public-api-v1-invoices-quarterly-download_zip"} },  body: JSON.stringify({  "year": 2026,  "quarter": 1,  "include_index": true}),});if (!response.ok) throw new Error(await response.text());await (await import("node:fs/promises")).writeFile("response.bin", new Uint8Array(await response.arrayBuffer()));

Ejemplo de respuesta

Descarga el archivo con las cabeceras de respuesta indicadas a continuación.

HTTP/1.1 200
Content-Type: application/zip
Content-Disposition: attachment; filename="FAC-2026-00042.zip"

Se envió la cabecera X-Active-Profile retirada

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_unknown",
    "subcode": "retired_active_profile_header",
    "message": "La cabecera 'X-Active-Profile' fue retirada de la API v1: la empresa efectiva se indica en el segmento de empresa de la ruta.",
    "param": "X-Active-Profile",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_unknown",
    "request_id": "req_01J8Y3M2Q40000000000000001"
  }
}

Cabecera Factuarea-Version malformada

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid_format",
    "message": "El header 'Factuarea-Version' debe tener formato YYYY-MM-DD.",
    "param": "Factuarea-Version",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_invalid_format",
    "request_id": "req_01J8Y3M2Q40000000000000002"
  }
}

Factuarea-Version no admitida

{
  "error": {
    "type": "invalid_request_error",
    "code": "unsupported_api_version",
    "message": "La versión de API '2020-01-01' no está soportada.",
    "param": "Factuarea-Version",
    "doc_url": "https://docs.factuarea.com/guides/errors#unsupported_api_version",
    "request_id": "req_01J8Y3M2Q40000000000000003"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "Falta header Authorization o X-API-Key.",
    "doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
    "request_id": "req_8f5afe0c17ee23e93008ebf014"
  }
}

POST /v1/companies/{company}/invoices/quarterly/download-zip · 403 insufficient_scope

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta operación requiere el scope 'pdfs:read'. Tu API key solo tiene los scopes: ninguno.",
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_16f50c47201469f89a8d316621"
  }
}

Empresa desactivada

{
  "error": {
    "type": "authorization_error",
    "code": "company_inactive",
    "message": "Esta empresa está desactivada. Actívala para operar.",
    "param": "company",
    "doc_url": "https://docs.factuarea.com/guides/errors#company_inactive",
    "request_id": "req_01J8Y3M2Q40000000000000005"
  }
}

POST /v1/companies/{company}/invoices/quarterly/download-zip · 404 invoice_not_found

{
  "error": {
    "type": "not_found_error",
    "code": "invoice_not_found",
    "message": "Factura no encontrada.",
    "param": "invoice_uuid",
    "subcode": "invoice_not_found",
    "doc_url": "https://docs.factuarea.com/guides/errors#invoice_not_found",
    "request_id": "req_2a30f19df41108310a96e00d5f"
  }
}

Empresa no encontrada o fuera del alcance de la API key

{
  "error": {
    "type": "not_found_error",
    "code": "profile_not_found",
    "message": "La empresa indicada no existe o no está en el ámbito de tu credencial.",
    "param": "company",
    "doc_url": "https://docs.factuarea.com/guides/errors#profile_not_found",
    "request_id": "req_01J8Y3M2Q40000000000000004"
  }
}

La presentación del documento ha cambiado

{
  "error": {
    "type": "conflict_error",
    "code": "pdf_presentation_conflict",
    "message": "La presentación documental ha cambiado. Actualiza los datos antes de volver a guardar.",
    "param": "expected_version",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_presentation_conflict",
    "request_id": "req_01J8Y3M2Q4CF0000000000PPC1"
  }
}

El contexto de presentación revisado ha cambiado

{
  "error": {
    "type": "conflict_error",
    "code": "pdf_presentation_context_changed",
    "message": "El contexto de presentación ha cambiado. Actualiza la vista previa antes de continuar.",
    "param": "expected_preview_context_fingerprint",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_presentation_context_changed",
    "request_id": "req_01J8Y3M2Q4CF0000000000PCC1"
  }
}

Los datos legales de la factura han cambiado

{
  "error": {
    "type": "conflict_error",
    "code": "pdf_legal_source_changed",
    "message": "Los datos jurídicos de la factura han cambiado. Crea una revisión antes de entregar esta presentación.",
    "param": "presentation_id",
    "doc_url": "https://docs.factuarea.com/guides/errors#pdf_legal_source_changed",
    "request_id": "req_01J8Y3M2Q4CF0000000000PLS1"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "export_document_cap_exceeded",
    "message": "La descarga empaquetada pide MÁS DOCUMENTOS de los que admite ese tipo de artefacto. No es un límite de peticiones ni un problema de permisos: es el tamaño de lo que se pide en una sola llamada, y el mismo tope rige en la aplicación web y en la API, de modo que partir el trabajo entre superficies no lo esquiva.",
    "doc_url": "https://docs.factuarea.com/guides/errors#export_document_cap_exceeded",
    "request_id": "req_9f3cbe4154ae8e146bf38909ea"
  }
}

POST /v1/companies/{company}/invoices/quarterly/download-zip · 422 invalid_param_value

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param_value",
    "message": "El campo year es obligatorio.",
    "param": "year",
    "errors": [
      {
        "param": "year",
        "code": "parameter_missing",
        "message": "El campo year es obligatorio."
      }
    ],
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_param_value",
    "request_id": "req_20f3f8654a68e60cae94241e2f"
  }
}

Idempotency key reutilizada con un payload distinto

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reused",
    "message": "La Idempotency-Key 'order-2026-0001' ya se usó con un payload distinto.",
    "param": "Idempotency-Key",
    "doc_url": "https://docs.factuarea.com/guides/errors#idempotency_key_reused",
    "request_id": "req_01J8Y3M2Q40000000000000007"
  }
}

Formato de Idempotency-Key no válido

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param_format",
    "message": "La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.",
    "param": "Idempotency-Key",
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_param_format",
    "request_id": "req_01J8Y3M2Q40000000000000008"
  }
}

Falta la Idempotency-Key en una escritura con efecto externo

{
  "error": {
    "type": "invalid_request_error",
    "code": "idempotency_key_required",
    "message": "La operación «public-api.v1.invoices.send» exige la cabecera Idempotency-Key desde el 2026-10-01. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.",
    "param": "Idempotency-Key",
    "doc_url": "https://docs.factuarea.com/guides/errors#idempotency_key_required",
    "request_id": "req_01J8Y3M2Q40000000000000009"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has excedido el límite de requests permitido. Reintenta más tarde.",
    "doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
    "request_id": "req_cb538d459feb305afbaaad5d0e"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.",
    "doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
    "request_id": "req_ede5a293b39d7235ef4b9782fe"
  }
}

Generar archivo ZIP trimestral

Authorization

Parámetros de ruta

Headers

Cuerpo de la petición

Cuerpo de la respuesta

200application/zip

400application/json

401application/json

403application/json

404application/json

409application/json

413application/json

422application/json

429application/json

500application/json

`application/zip`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`