Activar un NIF del compte

Reactiva un NIF inactive del compte com a NIF ADDICIONAL, després de la porta de NIF addicional. - Porta: 403 forbidden_action, 403 additional_nif_not_in_plan, 402 additional_nif_plan_required. - Una plaça lliure el cobreix; si no n'hi ha cap, la plaça que falta es compra i es cobra a l'instant (402 payment_method_required); queda active només si es cobra. - Envia un Idempotency-Key.

Suspès pel sistema: 422 subcode nif_suspended_by_system.

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

company*string

Identificador públic (UUID v7) de l'empresa. Obtén-lo de GET /v1/me (data.scope[].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 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/companies/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/activate", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Idempotency-Key":"erp-2026-public-api-v1-companies-activate"} },});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Exemple de resposta

{
  "data": {
    "id": "01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c",
    "object": "company",
    "name": "Talleres García SL",
    "business_name": "Talleres García, Sociedad Limitada",
    "tax_id": "B12345674",
    "status": "active",
    "status_since": null,
    "address": "Calle Mayor 1",
    "city": "Madrid",
    "postal_code": "28013",
    "province": "Madrid",
    "country_aeat_zone": "peninsula",
    "country": "España",
    "email": "contacto@talleresgarcia.es",
    "phone": "+34911234567",
    "logo_url": "https://app.factuarea.com/storage/logos/abc.png",
    "paid_until": "2026-07-15T10:00:00+00:00",
    "suspension_reason": null,
    "created_at": "2026-01-15T09:30:00+00:00",
    "updated_at": "2026-05-25T18:00:00+00:00"
  }
}

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

POST /v1/accounts/{account}/companies/{company}/activate · 402 payment_method_required

{
  "error": {
    "type": "payment_required_error",
    "code": "payment_method_required",
    "message": "La cuenta no tiene un método de pago configurado para cobrar el NIF adicional: configúralo y vuelve a intentarlo.",
    "details": {
      "payment_setup_url": "https://billing.stripe.com/p/session/live_YWNjdF8xS2ZHM0RLb0h4RXBGV3lY"
    },
    "doc_url": "https://docs.factuarea.com/guides/errors#payment_method_required",
    "request_id": "req_a15e7a1c0d9b3f46a28c010000"
  }
}

POST /v1/accounts/{account}/companies/{company}/activate · 402 additional_nif_plan_required

{
  "error": {
    "type": "payment_required_error",
    "code": "additional_nif_plan_required",
    "message": "Tu cuenta no tiene un plan vigente: activa el plan Profesional o superior para añadir NIF.",
    "doc_url": "https://docs.factuarea.com/guides/errors#additional_nif_plan_required",
    "request_id": "req_a15e7a1c0d9b3f46a28c020000"
  }
}

POST /v1/accounts/{account}/companies/{company}/activate · 402 additional_nif_charge_failed

{
  "error": {
    "type": "payment_required_error",
    "code": "additional_nif_charge_failed",
    "subcode": "additional_nif_charge_failed",
    "message": "No se pudo cobrar el NIF adicional de la cuenta. Detalle: card_declined.",
    "doc_url": "https://docs.factuarea.com/guides/errors#additional_nif_charge_failed",
    "request_id": "req_a15e7a1c0d9b3f46a28c030000"
  }
}

POST /v1/accounts/{account}/companies/{company}/activate · 403 insufficient_scope

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

POST /v1/accounts/{account}/companies/{company}/activate · 403 additional_nif_not_in_plan

{
  "error": {
    "type": "authorization_error",
    "code": "additional_nif_not_in_plan",
    "message": "Tu plan no incluye NIF adicionales: pasa a Profesional o superior para añadir más NIF a tu cuenta.",
    "doc_url": "https://docs.factuarea.com/guides/errors#additional_nif_not_in_plan",
    "request_id": "req_a15e7a1c0d9b3f46a28c040000"
  }
}

POST /v1/accounts/{account}/companies/{company}/activate · 403 billing_managed_by_provider

{
  "error": {
    "type": "authorization_error",
    "code": "billing_managed_by_provider",
    "message": "La facturación de esta cuenta la gestiona otra cuenta: pide el cambio a quien la paga.",
    "doc_url": "https://docs.factuarea.com/guides/errors#billing_managed_by_provider",
    "request_id": "req_a15e7a1c0d9b3f46a28c050000"
  }
}

POST /v1/accounts/{account}/companies/{company}/activate · 403 company_read_only

{
  "error": {
    "type": "authorization_error",
    "code": "company_read_only",
    "message": "Tu acceso a esta empresa es de solo lectura.",
    "doc_url": "https://docs.factuarea.com/guides/errors#company_read_only",
    "request_id": "req_c0ae5d0b1e7a4f2c8d9e6b0001"
  }
}

POST /v1/accounts/{account}/companies/{company}/activate · 404 resource_not_found

{
  "error": {
    "type": "not_found_error",
    "code": "resource_not_found",
    "message": "El recurso solicitado no existe.",
    "doc_url": "https://docs.factuarea.com/guides/errors#resource_not_found",
    "request_id": "req_f321010f33f2fc90715c53dd35"
  }
}

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

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

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

POST /v1/accounts/{account}/companies/{company}/activate · 422 invalid_param_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_6b9d26c4c09e9ad8a49740076b"
  }
}

POST /v1/accounts/{account}/companies/{company}/activate · 422 business_rule_violation (additional_nif_limit_reached)

{
  "error": {
    "type": "invalid_request_error",
    "code": "business_rule_violation",
    "subcode": "additional_nif_limit_reached",
    "message": "Has alcanzado el máximo de NIF adicionales de tu contrato (5).",
    "doc_url": "https://docs.factuarea.com/guides/errors#business_rule_violation",
    "request_id": "req_a15e7a1c0d9b3f46a28c060000"
  }
}

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

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

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

{
  "error": {
    "type": "service_unavailable_error",
    "code": "gestoria_seat_preview_unavailable",
    "message": "No se puede calcular el cargo de la empresa gestionada. Revisa la configuración de facturación antes de continuar.",
    "doc_url": "https://docs.factuarea.com/guides/errors#gestoria_seat_preview_unavailable",
    "request_id": "req_managed_seat_terms_example"
  }
}

Activar un NIF del compte

Authorization

Paràmetres de ruta

Headers

Cos de la resposta

200application/json

400application/json

401application/json

402application/json

403application/json

404application/json

409application/json

422application/json

429application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`