Developers · Quickstart
Copia cinc crides curl i acaba amb una factura emesa i el seu PDF. Tot passa al sandbox.
Integracions i formats compatibles
WhatsApp
La capçalera de cada petició
Authorization: Bearer fact_test_8KqW3pXnR2VbY7TcA9eFmN5zAquest tros decideix l'entorn.
fact_test_Sandboxfact_live_No hi ha cap paràmetre, capçalera ni camp del cos que ho canviï. Ho decideix la clau amb què signes la petició.
El camí
El recorregut real té cinc passos perquè sèrie, client i factura són recursos diferents. Cada resposta deixa preparat el següent; aquí només veus el codi que toca ara.
El recorregut complet
fact_test_ → factura.pdf
Pas 1 de 5
Una lectura que no crea res. Et diu quina empresa hi ha darrere de la clau, quin pla té i quins scopes porta.
T'emportes
La llista de scopes de la clau. Si li'n falta algun, el pas que el necessiti contestarà 403.
Canvia de pas des del mapa. Les crides completes i totes les respostes continuen disponibles a la guia tècnica.
1 crida en aquest pas
Pas 1 de 5
GET/v1/accountaccount:readexport FACTUAREA_API_KEY="fact_test_..."
curl https://api.factuarea.com/v1/account \
-H "Authorization: Bearer $FACTUAREA_API_KEY"El recorregut acaba amb una factura emesa i un PDF que ja conté la numeració definitiva.
Quan falla
Tots els errors mantenen un nucli estable (type, code i message) i afegeixen param, request_id o doc_url quan correspon.
invalid_api_keyLa clau no existeix, no coincideix amb el secret o ja no és vàlida.Comprova el prefix, que has copiat el secret complet i que la clau no està revocada ni caducada.insufficient_scopeLa clau és vàlida, però no porta el permís d'aquella operació.Els scopes de la clau surten a GET /v1/account. Compara'ls amb el que demana la crida.parameter_invalidUn camp no passa la validació.param porta el primer que falla. No reintentis amb el mateix cos: fallarà igual.rate_limit_exceededHas passat de la quota de la finestra.Espera el que digui Retry-After. X-RateLimit-Remaining et diu quant queda a la finestra.L'embolcall, sempre igual
{
"error": {
"type": "authorization_error",
"code": "insufficient_scope",
"message": "Esta API key no tiene el scope requerido para esta operación.",
"param": null,
"doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
"request_id": "req_01HKQS5NBC3P8M1KX4V7SLNHQD"
}
}Què es reintenta i què no
Un 4xx no: el mateix cos tornarà a fallar. El 429 sí, quan ho digui Retry-After. Un 5xx, amb espera creixent. Els SDK ja ho porten posat.
Catàleg d'errorsSi no faràs servir curl
curl va bé per a la primera vegada perquè no cal instal·lar res i no amaga res. Per al que ve després hi ha dos SDK oficials i un servidor MCP.
TypeScript@factuarea/sdk
PHPfactuarea/factuarea-phpPorten resolt allò que un acaba escrivint malament a mà:
391 eines
La mateixa API oberta a un agent, amb els mateixos scopes de sempre: l'agent no pot fer res que la clau no pugui.
La clau de prova també val aquí, i amb els mateixos efectes desconnectats.
El servidor MCPVagis per on vagis, l'entorn el segueix decidint el prefix de la clau.
Superfície publicada
El contracte OpenAPI, els SDK i el servidor MCP parteixen de la mateixa API. Les xifres es revisen contra la superfície publicada perquè puguis avaluar l'abast i el manteniment abans d'integrar.
Tecnologies i clients compatibles
TypeScriptPHP
OpenAPI
StripeEls logotips identifiquen tecnologies o clients compatibles; no impliquen una relació comercial ni un testimoni.
Dubtes
No. La clau de test es crea amb un compte normal, i l’empresa de proves s’aprovisiona en crear aquesta primera clau.
Crea el compte, treu una clau fact_test_ i segueix el flux. La factura es numera dins del sandbox i els seus efectes externs no en surten.