Canviar en bloc l'estat de factures

Passa fins a 50 factures a issued, sent (àlies d'issued) o paid en una sola crida, amb èxit parcial. - paid requereix payment_date (no futura), que s'aplica a totes les factures. - Els errors són resource_not_found o invalid_status_transition, en un BulkPartialSuccessResult.

Authorization

AuthorizationBearer <token>

La teva API key com a token Bearer: fact_live_… en producció, fact_test_… en sandbox. Consulta la guia d'autenticació.

A: header

Paràmetres de ruta

company*string

Identificador públic (UUID v7) de l'empresa. Obtén-lo de GET /v1/me (data.scope[].id).

Formatuuid

Headers

Idempotency-Key*string

Clau opaca generada pel client (fins a 255 caràcters; es recomana UUID v7) que permet reintents segurs: la primera resposta s'emmagatzema i es reprodueix en les repeticions sense tornar a executar la mutació. Reutilitzar una clau amb un cos diferent retorna 422 idempotency_key_reused; els valors dels camps secrets (password, secret…) compten com a part del cos, així que reintentar amb un secret corregit sota la mateixa clau és una petició diferent, mai la repetició de la resposta anterior. Consulta la guia d'idempotència. Obligatòria en aquesta operació: repetir-la produeix un efecte irreversible (un correu enviat, un fitxer generat, una crida a un tercer o un càrrec), per la qual cosa una petició sense aquesta capçalera es rebutja amb 422 idempotency_key_required abans d'executar lògica de negoci.

Longitud1 <= length <= 255

Factuarea-Version?string

Fixa la versió de l'API (YYYY-MM-DD, versionat per data estil Stripe) per a aquesta petició; omet-lo per usar la versió fixada de la clau, o l'última si no n'hi ha cap. Versió no suportada → 400 unsupported_api_version; mal formada → 400 parameter_invalid_format. La versió efectiva es reflecteix a la capçalera de resposta Factuarea-Version. Consulta la guia de Versioning.

Formatdate

Cos de la petició

application/json

Els canvis d'estat massius de factures accepten un mapa opcional, amb UUID com a claus, de precondicions de presentació completes de set camps. Quan la presentació amb revisions està activada per a l'empresa i el canvi emet factures (issued o l'heretat sent), cada fila en esborrany ha de portar la seva precondició: una fila en esborrany sense precondició no s'emet i es notifica a failures[] amb 428 pdf_presentation_precondition_required, mentre les altres files continuen. Amb la presentació amb revisions desactivada, els camps de precondició s'ignoren.

Definicions de TypeScript

Usa el tipus request body a TypeScript.

ids*array<>

Elements1 <= items <= 50

new_status*string

Estat de destinació: issued emet cada esborrany (número definitiu, registre VeriFactu) sense enviar cap email; paid registra un cobrament per l'import pendent de cada factura emesa. sent s'accepta com a àlies d'issued a totes les versions de l'API i mai no posa la marca d'enviament (is_sent).

Valor a"issued" | "sent" | "paid"

payment_date?|

Formatdate-time

presentation_preconditions?

Mapa opcional de l'UUID de cada factura afectada a la seva precondició de presentació completa de set camps. Les claus han d'identificar documents d'aquest lot; no reutilitzis el token d'origen d'un altre document. Només té efecte quan la presentació amb revisions està activada per a l'empresa; en cas contrari s'ignora.

Cos de la resposta

`application/json`

Exemple de petició

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/bulk-status", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Content-Type":"application/json","Idempotency-Key":"erp-2026-public-api-v1-invoices-bulk_status"} },  body: JSON.stringify({  "ids": [    "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01"  ],  "new_status": "issued"}),});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Exemple de resposta

POST /v1/companies/{company}/invoices/bulk-status · 200

{
  "data": {
    "total": 3,
    "successful": 2,
    "failed": 1,
    "failures": [
      {
        "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff",
        "error_code": "resource_not_found",
        "error_message": "El recurso no existe o no pertenece a tu empresa."
      }
    ]
  }
}

POST /v1/companies/{company}/invoices/bulk-status · 200 (a row stopped by an unreachable PDF engine)

{
  "data": {
    "total": 2,
    "successful": 1,
    "failed": 1,
    "failures": [
      {
        "id": "019e0000-0000-7000-8000-00000000000b",
        "error_code": "pdf_engine_unreachable",
        "error_message": "El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes."
      }
    ]
  }
}

S'ha enviat la capçalera 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"
  }
}

Capçalera 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 admesa

{
  "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_3551e3d53dcd01c9e9da920c04"
  }
}

POST /v1/companies/{company}/invoices/bulk-status · 403 insufficient_scope

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

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

Recurs no trobat

{
  "error": {
    "type": "not_found_error",
    "code": "resource_not_found",
    "message": "El recurso solicitado no existe o pertenece a otra empresa.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#resource_not_found",
    "request_id": "req_01HKQS5NEQ6X1R4N9B0C5DWTPG"
  }
}

Empresa no trobada o fora de l'abast de l'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"
  }
}

{
  "error": {
    "type": "conflict_error",
    "code": "resource_conflict",
    "message": "Hay otra operación reservando identificadores sobre 'series' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.",
    "doc_url": "https://docs.factuarea.com/guides/errors#resource_conflict",
    "request_id": "req_01J8Y3M2Q4CF0000000000IDR1"
  }
}

POST /v1/companies/{company}/invoices/bulk-status · 422 invalid_param_value

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

Idempotency key reutilitzada amb un payload diferent

{
  "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"
  }
}

Format d'Idempotency-Key no vàlid

{
  "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 escriptura amb efecte extern

{
  "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_0bc0f4c736c2f672262bb5b036"
  }
}

{
  "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_fc03640ff0f15c772ed1723169"
  }
}

Canviar en bloc l'estat de factures

Authorization

Paràmetres de ruta

Headers

Cos de la petició

Cos de la resposta

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`