Personalització del compte

La personalització controla l'aspecte i la lectura de les teves factures: l'idioma en què es genera el PDF, la plantilla PDF que l'emmarca i el color d'accent que l'identifica. Tots tres viuen a l'empresa autenticada i s'apliquen a tots els documents que l'API genera per a tu.

Llegeixes els valors actuals des del bloc personalization de GET /v1/account, i els canvies amb una única actualització parcial a PATCH /v1/account/personalization. Tots dos endpoints funcionen igual en mode de prova (claus fact_test_) i en producció (claus fact_live_).

Els tres ajustos

Idioma d'emissió de factures

language és el locale en què es genera el PDF. Posa'l a en i els títols, etiquetes i dates de cada PDF que generis passen a anglès; ca els mostra en català; es (per defecte) en castellà. No canvia el text message dels errors de l'API — aquests continuen en castellà, tal com documenta el model d'errors.

Plantilla PDF

pdf_template és un slug del catàleg tancat PdfTemplate. Les cinc plantilles de sistema són classic, modern (per defecte), minimal, corporative i premium. Quines pot seleccionar el teu compte depèn del teu pla — descobreix el conjunt permès amb l'endpoint de plantilles en lloc de fixar-lo a mà.

Color d'accent

accent_color és el color hexadecimal #RRGGBB amb què s'identifica el PDF (capçaleres, totals, accents). Envia null per netejar-lo i tornar al valor per defecte de la plantilla.

Llegir la personalització actual

El bloc personalization forma part del recurs 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",
  "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 i pdf_template sempre hi són presents. accent_color és null quan no hi ha cap color configurat.

pdf_capabilities és només de lectura i descriu el que el pla del compte permet als documents generats. Llegeix-lo per activar o desactivar els controls de marca abans de cridar el PATCH:

Actualitzar la personalització

PATCH /v1/account/personalization és una actualització parcial: només s'apliquen els camps que envies, i qualsevol camp que ometis manté el seu valor actual. La resposta és el recurs Account actualitzat — amb la mateixa forma que GET /v1/account, inclòs el bloc personalization tot just refrescat. Requereix 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'

Canvia un únic ajust enviant només aquest camp:

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

Neteja el color d'accent enviant 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 }'

Errors de validació

Cada ajust es valida contra el seu catàleg tancat. Un valor fora del catàleg retorna 422 amb els allowed_values del camp erroni — language i pdf_template contra el seu enum, accent_color contra el patró #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 fora de available_templates en un compte sense l'editor PDF retorna 403 amb code: feature_not_available_in_plan i no aplica cap camp. pdf_capabilities.upgrade_plan indica el pla que el desbloqueja.

Descobrir les plantilles disponibles

GET /v1/account/personalization/templates llista les plantilles PDF disponibles per al pla del teu compte (segons el pla) juntament amb el format acceptat per a accent_color. Fes-lo servir per omplir un selector en lloc de fixar el catàleg a mà. Requereix 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"
  },
  "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 repeteix el bloc de GET /v1/account, de manera que un selector es pot construir amb aquesta única crida. L'indicador available reflecteix el teu pla actual: un slug en false existeix al catàleg però no es pot fixar fins que milloris de pla. Ofereix només les plantilles disponibles, i llegeix accent_color.format per validar el color al client abans del PATCH.

Scopes