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.

Lees los valores actuales desde el bloque personalization de GET /v1/account, y los cambias con una única actualización parcial en PATCH /v1/account/personalization. Ambos endpoints funcionan igual en modo de prueba (claves fact_test_) y en producción (claves fact_live_).

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.

Leer la personalización actual

El bloque personalization forma parte del recurso Account:

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

{
  "language": "es",
  "pdf_template": "modern",
  "accent_color": "#1a73e8"
}

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

Actualizar la personalización

PATCH /v1/account/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 — con la misma forma que GET /v1/account, incluido el bloque personalization recién refrescado. Requiere el scope account:write.

curl -s -X PATCH https://api.factuarea.com/v1/account/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/account/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/account/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"]
  }
}

Descubrir las plantillas disponibles

GET /v1/account/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/account/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"
  }
}

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