Fijar las plazas de NIF adicional contratadas

Fija las plazas de NIF adicional contratadas de la cuenta en un contracted_seats absoluto. - Un valor mayor compra ahora las plazas que faltan (402 payment_method_required o additional_nif_charge_failed no compra nada); uno menor es una reducción que se aplica en la renovación, sin reembolso. - Bajar de las plazas ocupadas requiere deactivate con exactamente el excedente (422 contracted_seats_selection_required); romper un paquete de oferta requiere accept_offer_package_loss. - Idempotency-Key es obligatorio.

Por encima del tope: 422 additional_nif_limit_reached.

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

account*string

Identificador público (UUID v7) de tu cuenta. Obtenlo de GET /v1/me (data.account.id).

Formatouuid

Headers

Idempotency-Key*string

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.

contracted_seats*integer

Plazas contratadas deseadas (valor absoluto, 0 o más).

Rango0 <= value <= 1000

deactivate?array<>|

IDs (UUID v7) de los empleados o NIF que se desactivarán en la renovación al bajar de las plazas ocupadas. Exactamente las ocupadas menos el nuevo total, todos ocupando una plaza de la cuenta; si no, 422 contracted_seats_selection_required.

Elementositems <= 1000

accept_offer_package_loss?|

Confirma que se pierde el paquete de oferta aplicado que rompe la reducción (por defecto false). Sin ello, la reducción se rechaza con 422 offer_package_loss_unconfirmed.

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/accounts/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/additional-nif-seats", {  method: "PATCH",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Content-Type":"application/json","Idempotency-Key":"erp-2026-public-api-v1-additional-nif-seats-update"} },  body: JSON.stringify({  "contracted_seats": 5}),});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Ejemplo de respuesta

PATCH /v1/accounts/{account}/additional-nif-seats · 200

{
  "data": {
    "object": "additional_nif_seats",
    "subscribed": true,
    "quantity": 3,
    "seats_billable": true,
    "max_additional_nifs": null,
    "seats": {
      "contracted": 3,
      "occupied": 2,
      "free": 1,
      "agreed_minimum": 0,
      "agreed_minimum_ends_at": null,
      "reducible_to": 0,
      "pending_reduction": null,
      "enforced": true
    }
  }
}

PATCH /v1/accounts/{account}/additional-nif-seats · 200 reduction scheduled at renewal

{
  "data": {
    "object": "additional_nif_seats",
    "subscribed": true,
    "quantity": 3,
    "seats_billable": true,
    "max_additional_nifs": null,
    "seats": {
      "contracted": 3,
      "occupied": 2,
      "free": 1,
      "agreed_minimum": 0,
      "agreed_minimum_ends_at": null,
      "reducible_to": 0,
      "pending_reduction": {
        "contracted": 1,
        "effective_at": "2026-12-01T00:00:00+00:00",
        "deactivations": [
          {
            "id": "0198f2d4-1b7e-7c3a-9d41-6a5e8b2c4f21",
            "name": "Taller Norte, S.L."
          }
        ],
        "offer_package_loss": null
      },
      "enforced": true
    }
  }
}

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

{
  "error": {
    "type": "payment_required_error",
    "code": "payment_method_required",
    "message": "Comprar plazas de NIF adicional cobra de inmediato y la cuenta opera en modo real sin método de pago configurado.",
    "doc_url": "https://docs.factuarea.com/guides/errors#payment_method_required",
    "request_id": "req_e29418f073ad1bf48eb57c62bd"
  }
}

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

Recurso no encontrado

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

Cuenta no encontrada o no es la cuenta de la API key

{
  "error": {
    "type": "not_found_error",
    "code": "account_not_found",
    "message": "La cuenta indicada no existe o no es la de tu credencial.",
    "param": "account",
    "doc_url": "https://docs.factuarea.com/guides/errors#account_not_found",
    "request_id": "req_01J8Y3M2Q40000000000000006"
  }
}

Resultado de la operación de empleado desconocido

{
  "error": {
    "type": "conflict_error",
    "code": "employee_seat_mutation_outcome_unknown",
    "subcode": "employee_seat_mutation_outcome_unknown",
    "message": "La operación de empleados sigue pendiente de comprobación. No repitas el cargo; contacta con soporte indicando la referencia de la operación.",
    "details": {
      "operation_id": "01990c3a-5b2e-7c41-9d3f-2a6b8e1f4c13",
      "operation_kind": "legacy_employee"
    },
    "doc_url": "https://docs.factuarea.com/guides/errors#employee_seat_mutation_outcome_unknown",
    "request_id": "req_01J8Y3M2Q4CF0000000000ESM1"
  }
}

Operación de empleado en curso

{
  "error": {
    "type": "conflict_error",
    "code": "employee_seat_operation_in_progress",
    "subcode": "employee_seat_operation_in_progress",
    "message": "Hay una operación de empleados pendiente. Consulta su estado antes de iniciar otra.",
    "details": {
      "operation_id": "01990c3a-5b2e-7c41-9d3f-2a6b8e1f4c14"
    },
    "doc_url": "https://docs.factuarea.com/guides/errors#employee_seat_operation_in_progress",
    "request_id": "req_01J8Y3M2Q4CF0000000000ESO1"
  }
}

Las condiciones programadas bloquean el cambio de puestos

{
  "error": {
    "type": "conflict_error",
    "code": "employee_seat_phase_incompatible",
    "subcode": "employee_seat_phase_incompatible",
    "message": "La suscripción tiene condiciones programadas que requieren revisión antes de cambiar sus plazas.",
    "param": "quantity",
    "details": {
      "reason": "phase_incompatible"
    },
    "doc_url": "https://docs.factuarea.com/guides/errors#employee_seat_phase_incompatible",
    "request_id": "req_01J8Y3M2Q4CF0000000000ESP1"
  }
}

Operación de facturación todavía en verificación

{
  "error": {
    "type": "conflict_error",
    "code": "customer_offer_legacy_outcome_unknown",
    "message": "Estamos confirmando con el procesador de pagos el resultado de una operación anterior. Espera unos minutos y vuelve a intentarlo; si el aviso continúa, contacta con soporte.",
    "details": {
      "operation_id": "01990c3a-5b2e-7c41-9d3f-2a6b8e1f4c11"
    },
    "doc_url": "https://docs.factuarea.com/guides/errors#customer_offer_legacy_outcome_unknown",
    "request_id": "req_01J8Y3M2Q4CF0000000000COL1"
  }
}

Hay otra operación en curso

{
  "error": {
    "type": "conflict_error",
    "code": "customer_offer_operation_in_progress",
    "subcode": "customer_offer_operation_in_progress",
    "message": "Hay otra operación de facturación en curso para tu empresa. Espera unos minutos y vuelve a intentarlo; si el aviso continúa, contacta con soporte.",
    "doc_url": "https://docs.factuarea.com/guides/errors#customer_offer_operation_in_progress",
    "request_id": "req_01J8Y3M2Q4CF0000000000COP1"
  }
}

No se puede verificar el precio privado

{
  "error": {
    "type": "conflict_error",
    "code": "customer_offer_price_mapping_conflict",
    "subcode": "customer_offer_price_mapping_conflict",
    "message": "No se puede acreditar el precio particular de esta compra.",
    "doc_url": "https://docs.factuarea.com/guides/errors#customer_offer_price_mapping_conflict",
    "request_id": "req_01J8Y3M2Q4CF0000000000COM1"
  }
}

El estado de la operación no permite la acción

{
  "error": {
    "type": "conflict_error",
    "code": "customer_offer_state_conflict",
    "subcode": "customer_offer_state_conflict",
    "message": "La operación no admite esta acción. Consulta su estado actual.",
    "doc_url": "https://docs.factuarea.com/guides/errors#customer_offer_state_conflict",
    "request_id": "req_01J8Y3M2Q4CF0000000000COS1"
  }
}

Clave de idempotencia vinculada a otro lote

{
  "error": {
    "type": "idempotency_error",
    "code": "employee_batch_idempotency_conflict",
    "subcode": "employee_batch_idempotency_conflict",
    "message": "La clave ya corresponde a otra intención. Conserva la operación actual o prepara una intención nueva.",
    "doc_url": "https://docs.factuarea.com/guides/errors#employee_batch_idempotency_conflict",
    "request_id": "req_01J8Y3M2Q4CF0000000000EBI1"
  }
}

Acción no compatible con el estado del lote

{
  "error": {
    "type": "conflict_error",
    "code": "employee_batch_state_conflict",
    "subcode": "employee_batch_state_conflict",
    "message": "Esta acción no es compatible con el estado del lote. Consulta su estado actual.",
    "doc_url": "https://docs.factuarea.com/guides/errors#employee_batch_state_conflict",
    "request_id": "req_01J8Y3M2Q4CF0000000000EBS1"
  }
}

No se pueden conservar las condiciones adquiridas del puesto

{
  "error": {
    "type": "conflict_error",
    "code": "customer_offer_phase_incompatible",
    "subcode": "customer_offer_phase_incompatible",
    "message": "Las condiciones adquiridas del asiento requieren revisión antes de añadir empresas gestionadas.",
    "param": "quantity",
    "details": {
      "reason": "phase_incompatible"
    },
    "doc_url": "https://docs.factuarea.com/guides/errors#customer_offer_phase_incompatible",
    "request_id": "req_01J8Y3M2Q4CF0000000000CSI1"
  }
}

PATCH /v1/accounts/{account}/additional-nif-seats · 422 contracted_seats_selection_required

{
  "error": {
    "type": "invalid_request_error",
    "code": "business_rule_violation",
    "message": "Elige exactamente 1 empresas para desactivar en la renovación.",
    "subcode": "contracted_seats_selection_required",
    "param": "deactivate",
    "details": {
      "product": "additional-nifs",
      "requested": 1,
      "occupied": 2,
      "required": 1,
      "selected": 0,
      "invalid": 0
    },
    "doc_url": "https://docs.factuarea.com/guides/errors#business_rule_violation",
    "request_id": "req_f3a529f184be2c059fc68d73ce"
  }
}

PATCH /v1/accounts/{account}/additional-nif-seats · 422 offer_package_loss_unconfirmed

{
  "error": {
    "type": "invalid_request_error",
    "code": "business_rule_violation",
    "message": "Reducir las plazas hará que termine el paquete de oferta «Paquete de lanzamiento»: todos sus precios volverán al de catálogo. Confirma la pérdida para continuar.",
    "subcode": "offer_package_loss_unconfirmed",
    "param": "accept_offer_package_loss",
    "details": {
      "product": "additional-nifs",
      "package_id": "0198f2d4-1b7e-7c3a-9d41-6a5e8b2c4f10",
      "name": "Paquete de lanzamiento",
      "effective_at": "2026-12-01T00:00:00+00:00",
      "lines": [
        {
          "from_price": 200,
          "to_price": 250,
          "interval": "month",
          "concept": "gestoria-seats"
        }
      ]
    },
    "doc_url": "https://docs.factuarea.com/guides/errors#business_rule_violation",
    "request_id": "req_04b63aa295cf3d16a0d79e84df"
  }
}

PATCH /v1/accounts/{account}/additional-nif-seats · 422 additional_nif_limit_reached

{
  "error": {
    "type": "invalid_request_error",
    "code": "business_rule_violation",
    "message": "La cuenta ha alcanzado su límite de NIF adicionales.",
    "subcode": "additional_nif_limit_reached",
    "doc_url": "https://docs.factuarea.com/guides/errors#business_rule_violation",
    "request_id": "req_15c74bb3a6d04e27b1e8af95e0"
  }
}

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

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

Fijar las plazas de NIF adicional contratadas

Authorization

Parámetros de ruta

Headers

Cuerpo de la petición

Cuerpo de la respuesta

200application/json

400application/json

401application/json

402application/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`

`application/json`