Crear una identidad comercial de PDF

Crea una identidad de marca con su primera revisión: name más una configuration con el nombre comercial, los identificadores de los recursos de logotipo y de imagen de marca, el modo de marca y el email, el teléfono y la dirección de contacto.

Los recursos deben pertenecer a tu empresa y ser del tipo adecuado.
Envía id y revision_id (UUID v7) para elegir tú los identificadores.
Devuelve 201. Solo los administradores de la empresa pueden crearla.
Requiere pdf_templates:write y admite Idempotency-Key.

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

Headers

Idempotency-Key?string

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

Escritura interna reversible: la idempotencia sigue la política vigente; la repetición con una clave enviada ocurre antes del CAS. Los campos desconocidos se rechazan. Hasta que la empresa esté preparada para las plantillas con revisiones (inicialización de la empresa pendiente o generación con revisiones desactivada), toda escritura en la biblioteca devuelve 422 pdf_presentation_not_ready antes de cualquier precondición o efecto; las lecturas siguen disponibles y no se aplica ningún Retry-After.

Definiciones de TypeScript

Usa el tipo request body en TypeScript.

id?string

Coincidencia^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$

Formatouuid

revision_id?string

Coincidencia^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$

Formatouuid

name*string

Longitud1 <= length <= 120

description?|null

configuration?

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/pdf-commercial-identities", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Content-Type":"application/json","Idempotency-Key":"erp-2026-public-api-v1-pdf_commercial_identities-create"} },  body: JSON.stringify({  "name": "Tienda principal"}),});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Ejemplo de respuesta

{
  "availability": {
    "reason": null,
    "selectable": true
  },
  "created_at": "2026-03-02T09:15:00.000000Z",
  "current_revision": {
    "brand_image_asset_id": null,
    "brand_image_dark_asset_id": null,
    "brand_mode": "none",
    "brand_size": "medium",
    "dark_background_fallback": "silhouette",
    "commercial_name": "Servicios Ejemplo",
    "contact_email": "contacto@serviciosejemplo.example",
    "contact_phone": null,
    "created_at": "2026-03-02T09:15:00.000000Z",
    "id": "019e1a2b-3c4d-7e5f-8a6b-1c2d3e4f5a02",
    "identity_id": "019e1a2b-3c4d-7e5f-8a6b-1c2d3e4f5a01",
    "identity_version": 1,
    "logo_asset_id": null,
    "logo_dark_asset_id": null,
    "number": 1,
    "state": "active"
  },
  "description": null,
  "id": "019e1a2b-3c4d-7e5f-8a6b-1c2d3e4f5a01",
  "name": "Servicios Ejemplo",
  "state": "active",
  "updated_at": "2026-03-02T09:15:00.000000Z",
  "version": 1
}

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

Falta la API key

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "No se ha proporcionado una API key válida en el header Authorization.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
    "request_id": "req_01HKQS5N8VR7QXJ9K3T6BWPMZA"
  }
}

Formato de API key no válido

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "La API key no tiene el formato esperado (debe empezar por fact_live_ o fact_test_).",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_api_key",
    "request_id": "req_01HKQS5N9JTQM7HVTQP3FBN5XB"
  }
}

API key revocada

{
  "error": {
    "type": "authentication_error",
    "code": "api_key_revoked",
    "message": "Esta API key ha sido revocada y ya no es válida.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#api_key_revoked",
    "request_id": "req_01HKQS5NA8K7E2V9YDZWMT6RJC"
  }
}

API key caducada

{
  "error": {
    "type": "authentication_error",
    "code": "api_key_expired",
    "message": "Esta API key ha caducado.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#api_key_expired",
    "request_id": "req_01HKQS5NAPIKEYEXPIRED00008"
  }
}

IP de la petición fuera de la lista de acceso de la API key

{
  "error": {
    "type": "authentication_error",
    "code": "ip_not_allowed",
    "message": "La IP 203.0.113.10 no está autorizada para esta API key.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#ip_not_allowed",
    "request_id": "req_01HKQS5NIPNOTALLOWED000009"
  }
}

La API key carece del scope requerido

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta API key no tiene el scope requerido para esta operación.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_01HKQS5NBC3P8M1KX4V7SLNHQD"
  }
}

Se requiere mejorar el plan

{
  "error": {
    "type": "authorization_error",
    "code": "feature_not_available_in_plan",
    "message": "Esta funcionalidad requiere el plan empresario o superior. Actualiza tu suscripción para acceder.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#feature_not_available_in_plan",
    "request_id": "req_01HKQS5NCK4V9N2L7Y8X3WPMRE"
  }
}

Plan sin acceso a la API pública

{
  "error": {
    "type": "authorization_error",
    "code": "addon_not_active",
    "message": "Tu plan actual no incluye acceso a la API pública. Contrata o renueva un plan de Factuarea para usar la API.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#addon_not_active",
    "request_id": "req_01HKQS5NDP5W0Q3M8Z9A4BVSNF"
  }
}

Módulo no disponible con una clave de prueba

{
  "error": {
    "type": "authorization_error",
    "code": "module_not_available_in_sandbox",
    "message": "El módulo \"verifactu\" no está disponible en modo de pruebas. Usa una clave fact_live_ para operar sobre este recurso.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#module_not_available_in_sandbox",
    "request_id": "req_01HKQS5NMODULESANDBOX00010"
  }
}

Privilegio de proveedor de cuentas no concedido

{
  "error": {
    "type": "authorization_error",
    "code": "privileged_scope_required",
    "message": "Esta operación exige el privilegio de proveedor de cuentas (accounts:*) y la persona que emitió la clave debe ser propietaria o administradora de la cuenta",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#privileged_scope_required",
    "request_id": "req_01HKQS5NPRIVILEGEDSCOPE001"
  }
}

Operación de la cuenta propietaria sobre un NIF al que se llega por una relación

{
  "error": {
    "type": "authorization_error",
    "code": "forbidden_action",
    "message": "Esta operación solo la puede hacer la cuenta dueña del NIF: con un acceso por relación entre cuentas no está disponible.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#forbidden_action",
    "request_id": "req_01HKQS5NRELATIONNIFOWNER01"
  }
}

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

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

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

El parámetro no superó la validación

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "El campo `name` es obligatorio y no puede estar vacío.",
    "param": "name",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_invalid",
    "request_id": "req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"
  }
}

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

Idempotency key reutilizada con un body 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_01HKQS5NHT9A4U7R2E3F8GZWTJ"
  }
}

Límite de peticiones superado

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has excedido el rate limit de 60 peticiones por minuto. Reintenta tras 30 segundos.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
    "request_id": "req_01HKQS5NKW1C6W9T4G5H0JBZVL"
  }
}

Demasiados fallos de autenticación (bloqueo temporal)

{
  "error": {
    "type": "authentication_error",
    "code": "too_many_auth_failures",
    "message": "Has alcanzado el número máximo de intentos de autenticación fallidos. La API key queda bloqueada temporalmente. Reintenta tras el tiempo indicado en `Retry-After`.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#too_many_auth_failures",
    "request_id": "req_01HKQS5NKW1C6W9T4G5H0JBZVM"
  }
}

Demasiadas subidas simultáneas en curso

{
  "error": {
    "type": "rate_limit_error",
    "code": "upload_in_flight_budget_exceeded",
    "message": "Tu empresa tiene demasiadas subidas en curso a la vez: este archivo ocupa 10 MB y el margen simultáneo es de 120 MB. Espera a que terminen las subidas en marcha y vuelve a intentarlo dentro de 45 segundos.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#upload_in_flight_budget_exceeded",
    "request_id": "req_01HKQS5NUPLOADINFLIGHT005"
  }
}

Límite de peticiones de toda la empresa superado (todas las claves combinadas)

{
  "error": {
    "type": "rate_limit_error",
    "code": "company_rate_limit_exceeded",
    "message": "Tu empresa ha superado su límite conjunto de 900 peticiones por minuto, contando a la vez todas sus credenciales. Es un techo de la empresa, así que repartir el tráfico no lo eleva. Reintenta en 12 segundos, o solicita una ampliación de plan si necesitas más capacidad.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#company_rate_limit_exceeded",
    "request_id": "req_01HKQS5NCOMPANYRATELIMIT06"
  }
}

Cuota mensual de toda la empresa agotada (todas las claves combinadas)

{
  "error": {
    "type": "rate_limit_error",
    "code": "company_monthly_quota_exceeded",
    "message": "Tu empresa ha agotado su cuota conjunta de 150000 peticiones de este mes, contando a la vez todas sus credenciales. Es un techo de la empresa, así que repartir el tráfico no lo eleva. El contador se reinicia el día 1 del mes siguiente; solicita una ampliación de plan si necesitas más volumen antes.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#company_monthly_quota_exceeded",
    "request_id": "req_01HKQS5NCOMPANYMONTHLY0007"
  }
}

Cuota mensual de la API key agotada

{
  "error": {
    "type": "rate_limit_error",
    "code": "monthly_quota_exceeded",
    "message": "Has agotado tu cuota mensual de 100000 requests. Mejora tu plan para obtener una cuota superior.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#monthly_quota_exceeded",
    "request_id": "req_01HKQS5NMONTHLYQUOTA000011"
  }
}

Límite de peticiones de la cartera superado (todos los NIF de la cuenta juntos)

{
  "error": {
    "type": "rate_limit_error",
    "code": "portfolio_rate_limit_exceeded",
    "message": "La cartera de tu cuenta ha superado su límite conjunto de 1800 peticiones por minuto, contando a la vez todos sus NIF. Es un techo de la cartera, así que repartir el tráfico entre NIF no lo eleva. Reintenta en 12 segundos, o solicita una ampliación de plan si necesitas más capacidad.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#portfolio_rate_limit_exceeded",
    "request_id": "req_01HKQS5NPORTFOLIORATE00012"
  }
}

Cuota mensual de la cartera agotada (todos los NIF de la cuenta juntos)

{
  "error": {
    "type": "rate_limit_error",
    "code": "portfolio_monthly_quota_exceeded",
    "message": "La cartera de tu cuenta ha agotado su cuota conjunta de 300000 peticiones de este mes, contando a la vez todos sus NIF. Es un techo de la cartera, así que repartir el tráfico entre NIF no lo eleva. El contador se reinicia el día 1 del mes siguiente; solicita una ampliación de plan si necesitas más volumen antes.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#portfolio_monthly_quota_exceeded",
    "request_id": "req_01HKQS5NPORTFOLIOMONTH0013"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Ha ocurrido un error inesperado. Si persiste, contacta con soporte adjuntando el request_id.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
    "request_id": "req_01HKQS5NLX2D7X0U5H6J1KCAWM"
  }
}

Crear una identidad comercial de PDF

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

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`