Actuar en nom d'una filla
Maneja qualsevol empresa filla des d'una sola master key amb el header X-Active-Profile — resolució del perfil, el guard de propietat i com els scopes es mantenen fixos.
Un cop tens empreses gestionades sota el teu tenant mestre,
hi ha dues maneres d'actuar sobre una d'elles. Pots emetre una API key
filla lligada a ella — útil quan vols una credencial
acotada a una sola empresa. O pots seguir fent servir la teva master key i
triar l'empresa objectiu per petició amb el header X-Active-Profile. Així, una
sola master key opera sobre qualsevol empresa del teu arbre, sense reautenticar-te
ni gestionar una key per NIF. Aquesta pàgina cobreix el header.
Posa al header l'id públic (UUID v7) de l'empresa filla sobre la qual vols
actuar. Funciona sobre qualsevol endpoint — factures, clients, sèries i la
resta:
curl https://api.factuarea.com/v1/invoices \
-H "Authorization: Bearer fact_live_8KqW3pXnR2VbY7TcA9eFmN5z" \
-H "X-Active-Profile: 01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c"Quan el header és present i l'empresa és teva, tota la petició s'executa sobre
les dades d'aquesta empresa filla: cada lectura es filtra a ella i cada escriptura
hi cau. La petició es resol al company_id de l'empresa filla abans del rate
limit i la idempotència, de manera que cada empresa té els seus propis buckets.
El header és opcional i additiu. Omet-lo i la petició opera sobre l'empresa a la qual pertany la teva key — exactament com abans. Les integracions existents continuen funcionant sense canvis.
El header mai amplia la teva key. Els seus scopes, tier i environment
es conserven intactes: una master key amb només invoices:read que apunta a una
empresa filla segueix sense poder fer POST /v1/invoices allà (403 insufficient_scope), i una key fact_test_ es manté al sandbox sigui quin
sigui el perfil actiu. Canviar de perfil canvia sobre quina empresa actues,
mai què tens permès fer. L'empresa filla hereta el pla i els add-ons del
mestre.
Resolució i errors
X-Active-Profile resol l'empresa activa abans que s'executi cap handler:
| Header | Resultat |
|---|---|
| Absent o buit | La petició opera sobre l'empresa a la qual pertany la key (no-op). |
L'id de la teva pròpia empresa mestra | Permès — equival a ometre el header. |
Una empresa filla que posseeixes, active | La petició opera sobre aquesta empresa filla. |
Una empresa filla que posseeixes, però inactive | 403 company_inactive — reactiva-la primer. |
| No és un UUID v7 vàlid | 400 parameter_invalid_uuid, amb param: "X-Active-Profile". |
| Una empresa que no posseeixes (un altre arbre, o inexistent) | 404 profile_not_found. |
El 404 és indistingible tant si l'empresa pertany a un altre mestre com si
no existeix — l'API mai revela que una empresa fora del teu arbre existeix:
{
"error": {
"type": "not_found_error",
"code": "profile_not_found",
"message": "El perfil de empresa indicado no existe o no pertenece a tu cuenta.",
"param": "X-Active-Profile"
}
}El 403 és diferent: l'empresa sí és teva, així que revelar que està
desactivada és legítim — és el senyal per
reactivar-la abans d'operar:
{
"error": {
"type": "authorization_error",
"code": "company_inactive",
"message": "Esta empresa está desactivada. Actívala para operar.",
"param": "X-Active-Profile"
}
}Quina hauries de fer servir?
X-Active-Profile i les API keys filles resolen
necessitats diferents i coexisteixen:
- Fes servir una key filla per lliurar una credencial acotada a una integració lligada a una empresa — la credencial en si queda lligada a aquesta empresa.
- Fes servir el header per gestionar moltes empreses des d'una sola master key — una credencial, empresa objectiu triada per petició.
El header només canvia l'empresa activa. Mai canvia els scopes de la key, i
l'aïllament entre mestres s'aplica igual que en gestionar les
empreses: una empresa fora del teu arbre mai és
observable, retornant 404 en comptes de 403.