Fixar les places de NIF addicional contractades

Fixa les places de NIF addicional contractades del compte a un contracted_seats absolut. - Un valor més gran compra ara les places que falten (402 payment_method_required o additional_nif_charge_failed no compra res); un de més petit és una reducció que s'aplica a la renovació, sense reemborsament. - Baixar de les places ocupades requereix deactivate amb exactament l'excedent (422 contracted_seats_selection_required); trencar un paquet d'oferta requereix accept_offer_package_loss. - Idempotency-Key és obligatori.

Per sobre del topall: 422 additional_nif_limit_reached.

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

account*string

Identificador públic (UUID v7) del teu compte. Obtén-lo de GET /v1/me (data.account.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

Definicions de TypeScript

Usa el tipus request body a TypeScript.

contracted_seats*integer

Places contractades desitjades (valor absolut, 0 o més).

Rang0 <= value <= 1000

deactivate?array<>|

IDs (UUID v7) dels empleats o NIF que es desactivaran a la renovació en baixar de les places ocupades. Exactament les ocupades menys el nou total, tots ocupant una plaça del compte; si no, 422 contracted_seats_selection_required.

Elementsitems <= 1000

accept_offer_package_loss?|

Confirma que es perd el paquet d'oferta aplicat que trenca la reducció (per defecte false). Sense això, la reducció es rebutja amb 422 offer_package_loss_unconfirmed.

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

Exemple de resposta

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

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

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

Compte no trobat o no és el compte de l'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"
  }
}

Resultat de l'operació d'empleat desconegut

{
  "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ó d'empleat en curs

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

Les condicions programades bloquegen el canvi de llocs

{
  "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ó de facturació encara en verificació

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

Hi ha una altra operació en curs

{
  "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 es pot verificar el preu privat

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

L'estat de l'operació no permet l'acció

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

Clau d'idempotència vinculada a un altre lot

{
  "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ó no compatible amb l'estat del lot

{
  "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 es poden conservar les condicions adquirides del lloc

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

Fixar les places de NIF addicional contractades

Authorization

Paràmetres de ruta

Headers

Cos de la petició

Cos de la resposta

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`