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.

La personalització pertany a l'empresa, així que les dues operacions pengen de l'eix d'empresa: canvies els tres ajustos amb una única actualització parcial a PATCH /v1/companies/{company}/personalization, que respon amb el recurs Account actualitzat i el seu bloc personalization refrescat, i descobreixes el catàleg que el teu pla permet amb GET /v1/companies/{company}/personalization/templates. Tots dos funcionen igual en mode de prova (claus fact_test_) i en producció (claus fact_live_).

{company} és l'id (UUID v7) del NIF amb què operes, i als exemples curl és $COMPANY_ID. Arribar a un NIF explica com resoldre'l.

Els tres ajustos

Ajust	Camp	Valors acceptats
Idioma d'emissió de factures	`language`	`es`, `en`, `ca`
Plantilla PDF	`pdf_template`	`classic`, `modern`, `minimal`, `corporative`, `premium`
Color d'accent	`accent_color`	hexadecimal `#RRGGBB`, o `null` per netejar-lo

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.

Personalització i biblioteca de plantilles

Aquests tres ajustos són el nivell de tot el compte de l'aspecte del PDF. Per a alguna cosa més fina — diversos dissenys, una marca amb el seu propi logotip, una plantilla per tipus de document, per sèrie o per contacte — fes servir la biblioteca de plantilles PDF. Les dues conviuen:

Últim nivell. Quan un document no té selecció manual ni cap plantilla per defecte de sèrie, de contacte o d'empresa que estigui disponible, es genera a partir d'aquests ajustos (pdf_template, accent_color, el logotip i les dades de l'empresa), exactament com abans. Un valor per defecte de l'empresa definit a la biblioteca té prioritat sobre ells. L'ordre complet és a quina plantilla fa servir un document.
Importació única. Quan s'inicialitza la sortida revisionada per a la teva empresa, els ajustos que té avui (plantilla, personalització, logotip, imatge de marca i dades de contacte comercial) es copien en una plantilla importada i una marca importada, amb el nom en el teu language d'emissió. Són un punt de partida corrent a la biblioteca. A partir d'aquí els dos costats no se sincronitzen mentre l'empresa no hagi passat a la biblioteca: un PATCH posterior de pdf_template no edita aquestes revisions, i editar-les no canvia aquests ajustos. Quan l'empresa ja treballa amb la biblioteca, aquest PATCH aplica el disseny i el color a la seva plantilla principal (una revisió nova) i la lectura retorna els valors d'aquesta plantilla; sense plantilla principal respon 409 pdf_main_template_required.
Documents ja emesos. Un document conserva el PDF amb què es va capturar. Canviar qualsevol d'aquests ajustos només afecta els documents que creïs o revisis després.
Mateixes regles de pla. pdf_capabilities continua descrivint el que permet el teu pla, i els cinc slugs de pdf_template són els mateixos preajusts (base_preset) dels quals parteixen les plantilles de la biblioteca. El render_activation de només lectura de GET /v1/companies/{company}/pdf-templates/defaults indica si la biblioteca està efectivament activa per a l'empresa.

language i accent_color conserven el seu significat: language és l'idioma d'emissió del compte, mentre que una plantilla de la biblioteca també porta els seus propis títols i etiquetes en es, en i ca.

Llegir la personalització actual

El bloc personalization viatja al recurs Account que retorna l'actualització — la v1 no publica cap endpoint de només lectura per a ell, així que llegeix-lo a la resposta del PATCH que acabes de fer, o a la del que fas amb el cos buit per no canviar res:

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 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:

Camp	Significat
`can_upload_logo`	El compte pot pujar un logotip. `can_upload_brand_image` el replica.
`can_customize`	L'editor PDF avançat està disponible: color d'accent, plantilles avançades i opcions de maquetació.
`requires_attribution`	Els documents generats conserven l'atribució de Factuarea. `true` sempre que `can_customize` sigui `false`.
`available_templates`	Slugs que el compte pot fixar: les cinc amb l'editor; si no, `classic`, `modern` i `minimal`.
`upgrade_plan`	Pla que desbloqueja l'editor per a un compte `emprendedor` (`empresario`), o `null`.

Actualitzar la personalització

PATCH /v1/companies/{company}/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, inclòs el bloc personalization tot just refrescat. Requereix 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'

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

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

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

Cada ajust és independent: language, pdf_template i accent_color no es trepitgen entre si. Enviar-ne un mai reinicia els altres dos.

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/companies/{company}/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/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 repeteix el bloc de GET /v1/accounts/{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

Operació	Endpoint	Scope
Llistar plantilles	`GET /v1/companies/{company}/personalization/templates`	`account:read`
Actualitzar la personalització	`PATCH /v1/companies/{company}/personalization`	`account:write`

Personalització del compte

En aquesta pàgina