Revise invoice administrative routing

Append an administrative routing revision to an issued or overdue invoice.

Supply administrative_centres (including [] to select none), a nonblank reason of at most 500 characters and the current expected_version in the body.
Missing version returns 428; a stale version returns 409 with current_version only after authorization.
A successful append returns 201 and its committed administrative_version.
Parent invoice If-Match does not replace the body precondition.
Fiscal data, issuance, payment terms and delivery are unchanged; no invoice is emailed or submitted by this operation.

Authorization

AuthorizationBearer <token>

Your API key as a bearer token: fact_live_… in production, fact_test_… in sandbox. See the authentication guide.

In: header

Path Parameters

company*string

Public identifier (UUID v7) of the company. Get it from GET /v1/me (data.scope[].id).

Formatuuid

invoice*string

Public identifier (UUID v7) of the invoice.

Formatuuid

Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns 422 idempotency_key_reused; the values of secret fields (password, secret…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the Idempotency guide.

Length1 <= length <= 255

Factuarea-Version?string

Pin the API version (YYYY-MM-DD, Stripe-style date versioning) for this request; omit to use the key's pinned version, or the latest if none. Unsupported version → 400 unsupported_api_version; malformed → 400 parameter_invalid_format. The effective version is echoed in the Factuarea-Version response header. See the Versioning guide.

Formatdate

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

administrative_centres*array<>

At most one entry per role, returned sorted by role_code. [] explicitly selects no administrative centres; it never falls back to current contact defaults.

Itemsitems <= 4

reason*string

Match\S

Length1 <= length <= 500

expected_version*integer

Required administrative version from history or the invoice response. Missing means 428, stale means 409 with current_version after authorization. Only this body precondition is accepted; parent invoice If-Match does not replace it.

Range1 <= value

Response Body

`application/json`

Request example

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());

Response example

Committed revision and version

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

Explicitly select no administrative centres

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

Retired X-Active-Profile header sent

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

Malformed Factuarea-Version header

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

Unsupported Factuarea-Version

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

Company deactivated

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

Company not found or outside the API key scope

{
  "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 reused with a different payload

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

Invalid Idempotency-Key format

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

Revise invoice administrative routing

Authorization

Path Parameters

Headers

Request Body

Response Body

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`