Personalización de la cuenta

La personalización controla el aspecto y la lectura de tus facturas: el idioma en que se genera el PDF, la plantilla PDF que lo enmarca y el color de acento que lo identifica. Los tres viven en la empresa autenticada y se aplican a todos los documentos que la API genera para ti.

La personalización pertenece a la empresa, así que las dos operaciones cuelgan del eje de empresa: cambias los tres ajustes con una única actualización parcial en PATCH /v1/companies/{company}/personalization, que responde con el recurso Account actualizado y su bloque personalization refrescado, y descubres el catálogo que tu plan permite con GET /v1/companies/{company}/personalization/templates. Los dos funcionan igual en modo de prueba (claves fact_test_) y en producción (claves fact_live_).

{company} es el id (UUID v7) del NIF con el que operas, y en los ejemplos curl es $COMPANY_ID. Alcanzar un NIF explica cómo resolverlo.

Los tres ajustes

Idioma de emisión de facturas

language es el locale en que se genera el PDF. Ponlo a en y los títulos, etiquetas y fechas de cada PDF que generes pasan a inglés; ca los muestra en catalán; es (por defecto) en castellano. No cambia el texto message de los errores de la API — esos siguen en castellano, como documenta el modelo de errores.

Plantilla PDF

pdf_template es un slug del catálogo cerrado PdfTemplate . Las cinco plantillas de sistema son classic , modern (por defecto), minimal , corporative y premium . Cuáles puede seleccionar tu cuenta depende de tu plan — descubre el conjunto permitido con el endpoint de plantillas en lugar de fijarlo a mano.

Color de acento

accent_color es el color hexadecimal #RRGGBB con que se identifica el PDF (cabeceras, totales, acentos). Envía null para limpiarlo y volver al valor por defecto de la plantilla.

Personalización y biblioteca de plantillas

Estos tres ajustes son el nivel de toda la cuenta del aspecto del PDF. Para algo más fino — varios diseños, una marca con su propio logotipo, una plantilla por tipo de documento, por serie o por contacto— usa la biblioteca de plantillas PDF. Las dos conviven:

• Último nivel. Cuando un documento no tiene selección manual ni una plantilla por defecto de serie, de contacto o de empresa que esté disponible, se genera a partir de estos ajustes (pdf_template, accent_color, el logotipo y los datos de la empresa), exactamente como antes. Un valor por defecto de la empresa definido en la biblioteca tiene prioridad sobre ellos. El orden completo está en qué plantilla usa un documento.
• Importación única. Cuando se inicializa la salida revisionada para tu empresa, los ajustes que tiene hoy (plantilla, personalización, logotipo, imagen de marca y datos de contacto comercial) se copian en una plantilla importada y una marca importada, con el nombre en tu language de emisión. Son un punto de partida corriente en la biblioteca. A partir de ahí los dos lados no se sincronizan mientras la empresa no haya pasado a la biblioteca: un PATCH posterior de pdf_template no edita esas revisiones, y editarlas no cambia estos ajustes. Cuando la empresa ya trabaja con la biblioteca, ese PATCH aplica el diseño y el color a su plantilla principal (una revisión nueva) y la lectura devuelve los valores de esa plantilla; sin plantilla principal responde 409 pdf_main_template_required.
• Documentos ya emitidos. Un documento conserva el PDF con el que se capturó. Cambiar cualquiera de estos ajustes solo afecta a los documentos que crees o revises después.
• Mismas reglas de plan. pdf_capabilities sigue describiendo lo que permite tu plan, y los cinco slugs de pdf_template son los mismos preajustes (base_preset) desde los que parten las plantillas de la biblioteca. El render_activation de solo lectura de GET /v1/companies/{company}/pdf-templates/defaults indica si la biblioteca está efectivamente activa para la empresa.

language y accent_color conservan su significado: language es el idioma de emisión de la cuenta, mientras que una plantilla de la biblioteca también lleva sus propios títulos y etiquetas en es, en y ca.

Leer la personalización actual

El bloque personalization viaja en el recurso Account que devuelve la actualización — la v1 no publica ningún endpoint de solo lectura para él, así que léelo en la respuesta del PATCH que acabas de hacer, o en la del que haces con el cuerpo vacío para no cambiar nada:

curl -s -X PATCH https://api.factuarea.com/v1/companies/$COMPANY_ID/personalization \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  | jq '.data.personalization'

{
  "language": "es",
  "pdf_template": "modern",
  "accent_color": "#1a73e8",
  "pdf_capabilities": {
    "can_upload_logo": true,
    "can_customize": true,
    "can_upload_brand_image": true,
    "requires_attribution": false,
    "available_templates": ["classic", "modern", "minimal", "corporative", "premium"],
    "upgrade_plan": null
  }
}

language y pdf_template siempre están presentes. accent_color es null cuando no hay ningún color configurado.

pdf_capabilities es de solo lectura y describe lo que el plan de la cuenta permite en los documentos generados. Léelo para activar o desactivar los controles de marca antes de llamar al PATCH:

Actualizar la personalización

PATCH /v1/companies/{company}/personalization es una actualización parcial: solo se aplican los campos que envías, y cualquier campo que omitas mantiene su valor actual. La respuesta es el recurso Account actualizado, incluido el bloque personalization recién refrescado. Requiere el scope account:write.

curl -s -X PATCH https://api.factuarea.com/v1/companies/$COMPANY_ID/personalization \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "en", "pdf_template": "premium", "accent_color": "#0F766E" }' \
  | jq '.data.personalization'

Cambia un único ajuste enviando solo ese campo:

curl -s -X PATCH https://api.factuarea.com/v1/companies/$COMPANY_ID/personalization \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "ca" }'

Limpia el color de acento enviando null:

curl -s -X PATCH https://api.factuarea.com/v1/companies/$COMPANY_ID/personalization \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "accent_color": null }'

Errores de validación

Cada ajuste se valida contra su catálogo cerrado. Un valor fuera del catálogo devuelve 422 con los allowed_values del campo erróneo — language y pdf_template contra su enum, accent_color contra el patrón #RRGGBB:

{
  "error": {
    "type": "validation_error",
    "code": "validation_failed",
    "message": "El idioma indicado no es válido.",
    "param": "language",
    "allowed_values": ["es", "en", "ca"]
  }
}

Un accent_color o una plantilla fuera de available_templates en una cuenta sin el editor PDF devuelve 403 con code: feature_not_available_in_plan y no aplica ningún campo. pdf_capabilities.upgrade_plan indica el plan que lo desbloquea.

Descubrir las plantillas disponibles

GET /v1/companies/{company}/personalization/templates lista las plantillas PDF disponibles para el plan de tu cuenta (según el plan) junto con el formato aceptado para accent_color . Úsalo para poblar un selector en vez de fijar el catálogo a mano. Requiere el scope account:read .

curl -s https://api.factuarea.com/v1/companies/$COMPANY_ID/personalization/templates \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  | jq '.data'

{
  "object": "personalization_templates",
  "templates": [
    { "slug": "classic", "label": "Clásica", "available": true },
    { "slug": "modern", "label": "Moderna", "available": true },
    { "slug": "minimal", "label": "Minimalista", "available": true },
    { "slug": "corporative", "label": "Corporativa", "available": false },
    { "slug": "premium", "label": "Premium", "available": false }
  ],
  "accent_color": {
    "format": "#RRGGBB",
    "example": "#1a73e8"
  },
  "pdf_capabilities": {
    "can_upload_logo": true,
    "can_customize": false,
    "can_upload_brand_image": true,
    "requires_attribution": true,
    "available_templates": ["classic", "modern", "minimal"],
    "upgrade_plan": "empresario"
  }
}

pdf_capabilities repite el bloque de GET /v1/accounts/{account}, así que un selector puede construirse con esta única llamada. El indicador available refleja tu plan actual: un slug en false existe en el catálogo pero no se puede fijar hasta que mejores de plan. Ofrece solo las plantillas disponibles, y lee accent_color.format para validar el color en cliente antes del PATCH.

Scopes