Revisar el enrutamiento administrativo de la factura

Añade una revisión del enrutamiento administrativo a una factura emitida o vencida.

Envía en el cuerpo administrative_centres (incluido [] para no seleccionar ninguno), un motivo no vacío de como máximo 500 caracteres y el expected_version actual.
Si falta la versión, devuelve 428; una versión obsoleta devuelve 409 con current_version solo tras autorizar.
Una adición correcta devuelve 201 y su administrative_version confirmada.
El If-Match de la factura padre no sustituye a la precondición del cuerpo.
Los datos fiscales, la emisión, las condiciones de pago y la entrega no cambian; esta operación no envía ni presenta ninguna factura por correo.

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

invoice*string

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

Formatouuid

Clave opaca generada por el cliente (hasta 255 caracteres; se recomienda UUID v7) que hace seguros los reintentos: la primera respuesta se cachea 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.

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.

administrative_centres*array<>

Como máximo una entrada por rol, devuelta ordenada por role_code. [] selecciona explícitamente ningún centro administrativo; nunca recurre a los valores por defecto actuales del contacto.

Elementositems <= 4

reason*string

Coincidencia\S

Longitud1 <= length <= 500

expected_version*integer

Versión administrativa obligatoria del historial o de la respuesta de la factura. Si falta, 428; si está obsoleta, 409 con current_version tras autorizar. Solo se acepta esta precondición del cuerpo; el If-Match de la factura padre no la sustituye.

Rango1 <= value

Cuerpo de la respuesta

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

Ejemplo de respuesta

Revisión y versión confirmadas

{
  "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ícitamente ningún centro administrativo

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

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

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

{
  "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 el enrutamiento administrativo de la factura

Authorization

Parámetros de ruta

Headers

Cuerpo de la petición

Cuerpo de la respuesta

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`