Revisar l'encaminament administratiu de la factura

Afegeix una revisió d'encaminament administratiu a una factura emesa o vençuda.

Envia al body administrative_centres (inclòs [] per no seleccionar-ne cap), un motiu no buit de com a màxim 500 caràcters i l'expected_version actual.
Si falta la versió, retorna 428; una versió obsoleta retorna 409 amb current_version només després d'autoritzar.
Una addició correcta retorna 201 i la seva administrative_version confirmada.
L'If-Match de la factura pare no substitueix la precondició del body.
Les dades fiscals, l'emissió, els termes de pagament i el lliurament no canvien; aquesta operació no envia ni presenta cap factura per correu.

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

invoice*string

Identificador públic (UUID v7) de la factura.

Formatuuid

Clau opaca generada pel client (fins a 255 caràcters; es recomana UUID v7) que fa segurs els reintents: la primera resposta es cacheja i es reprodueix a 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.

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

Definicions de TypeScript

Usa el tipus request body a TypeScript.

administrative_centres*array<>

Com a màxim una entrada per rol, retornada ordenada per role_code. [] no selecciona explícitament cap centre administratiu; mai recorre als valors per defecte actuals del contacte.

Elementsitems <= 4

reason*string

Coincidència\S

Longitud1 <= length <= 500

expected_version*integer

Versió administrativa obligatòria de l'historial o de la resposta de la factura. Si falta, 428; si és obsoleta, 409 amb current_version després d'autoritzar. Només s'accepta aquesta precondició del body; l'If-Match de la factura pare no la substitueix.

Rang1 <= value

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/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/administrative-revisions", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Content-Type":"application/json","Idempotency-Key":"erp-2026-public-api-v1-invoices-administrative_revisions-store"} },  body: JSON.stringify({  "administrative_centres": [    {      "role_code": "01",      "code": "L01000001",      "name": "Oficina contable"    },    {      "role_code": "02",      "code": "L01000002",      "name": "Órgano gestor"    },    {      "role_code": "03",      "code": "L01000003",      "name": "Unidad tramitadora"    },    {      "role_code": "04",      "code": "L01000004",      "name": "Órgano proponente"    }  ],  "reason": "Actualizar unidad tramitadora",  "expected_version": 1}),});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Exemple de resposta

Revisió i versió confirmades

{
  "data": {
    "id": "019e0000-0000-7000-8000-0000000000c1",
    "version": 2,
    "administrative_centres": [
      {
        "role_code": "01",
        "code": "L01000001",
        "name": "Oficina contable"
      },
      {
        "role_code": "02",
        "code": "L01000002",
        "name": "Órgano gestor"
      },
      {
        "role_code": "03",
        "code": "L01000003",
        "name": "Unidad tramitadora"
      },
      {
        "role_code": "04",
        "code": "L01000004",
        "name": "Órgano proponente"
      }
    ],
    "reason": "Actualizar unidad tramitadora",
    "created_at": "2026-01-15T10:00:00+00:00",
    "actor_id": "019e0000-0000-7000-8000-0000000000d1",
    "correlation_id": "019e0000-0000-7000-8000-0000000000e1"
  },
  "administrative_version": 2
}

Seleccionar explícitament cap centre administratiu

{
  "data": {
    "id": "019e0000-0000-7000-8000-0000000000c1",
    "version": 2,
    "administrative_centres": [],
    "reason": "Actualizar unidad tramitadora",
    "created_at": "2026-01-15T10:00:00+00:00",
    "actor_id": "019e0000-0000-7000-8000-0000000000d1",
    "correlation_id": "019e0000-0000-7000-8000-0000000000e1"
  },
  "administrative_version": 2
}

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

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

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

invoice_not_found

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

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": "invoice_administrative_version_conflict",
    "message": "El routing administrativo ha cambiado. Recarga la factura.",
    "param": "expected_version",
    "details": {
      "current_version": 2,
      "recovery": "reload_or_keep_local"
    },
    "doc_url": "https://docs.factuarea.com/guides/errors#invoice_administrative_version_conflict",
    "request_id": "req_01J8Y3M2Q4CF0000000000IAV1"
  }
}

invalid_invoice_business_data

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_invoice_business_data",
    "message": "Los datos comerciales de la factura no son válidos.",
    "param": "administrative_centres.0.role_code",
    "details": {
      "field_errors": {
        "administrative_centres.0.role_code": [
          "Los datos comerciales de la factura no son válidos."
        ]
      }
    },
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_invoice_business_data",
    "request_id": "req_01KFST3RC7D9E1F3G5H7J9KMNP"
  }
}

business_rule_violation

{
  "error": {
    "type": "invalid_request_error",
    "code": "business_rule_violation",
    "subcode": "invoice_not_editable_in_current_state",
    "message": "La factura F-BORRADOR no puede ser editada en estado 'draft'",
    "doc_url": "https://docs.factuarea.com/guides/errors#business_rule_violation",
    "request_id": "req_01KFST3RC7D9E1F3G5H7J9KMNP"
  }
}

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

{
  "error": {
    "type": "invalid_request_error",
    "code": "invoice_administrative_precondition_required",
    "message": "Indica la versión administrativa actual.",
    "param": "expected_version",
    "doc_url": "https://docs.factuarea.com/guides/errors#invoice_administrative_precondition_required",
    "request_id": "req_01KFST3RC7D9E1F3G5H7J9KMNP"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has excedido el límite de 60 requests por minuto. Reintenta en 30 segundos.",
    "doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
    "request_id": "req_01KFST3RC7D9E1F3G5H7J9KMNP"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Ha ocurrido un error interno. Contacta soporte indicando el request_id.",
    "doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
    "request_id": "req_01KFST3RC7D9E1F3G5H7J9KMNP"
  }
}

Revisar l'encaminament administratiu de la factura

Authorization

Paràmetres de ruta

Headers

Cos de la petició

Cos de la resposta

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

428application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`