Developers · Quickstart
Copia cinco llamadas curl y termina con una factura emitida y su PDF. Todo ocurre en el sandbox.
Integraciones y formatos compatibles
WhatsApp
La cabecera de cada petición
Authorization: Bearer fact_test_8KqW3pXnR2VbY7TcA9eFmN5zEste trozo decide el entorno.
fact_test_Sandboxfact_live_No hay parámetro, cabecera ni campo del cuerpo que cambie esto. Lo decide la clave con la que firmas la petición.
El camino
El recorrido real tiene cinco pasos porque serie, cliente y factura son recursos distintos. Cada respuesta deja preparado el siguiente; aquí solo ves el código que toca ahora.
El recorrido completo
fact_test_ → factura.pdf
Paso 1 de 5
Una lectura que no crea nada. Te dice qué empresa hay detrás de la clave, qué plan tiene y qué scopes lleva.
Te llevas
La lista de scopes de la clave. Si le falta alguno, el paso que lo necesite contestará 403.
Cambia de paso desde el mapa. Las llamadas completas y todas sus respuestas siguen en la guía técnica.
1 llamada en este paso
Paso 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 recorrido termina con una factura emitida y un PDF que ya contiene su numeración definitiva.
Cuando falla
Todos los errores mantienen un núcleo estable (type, code y message) y añaden param, request_id o doc_url cuando corresponde.
invalid_api_keyLa clave no existe, no coincide con el secreto o ya no es válida.Comprueba el prefijo, que copiaste el secreto completo y que la clave no está revocada ni caducada.insufficient_scopeLa clave es válida, pero no lleva el permiso de esa operación.Los scopes de la clave salen en GET /v1/account. Compáralos con el que pide la llamada.parameter_invalidUn campo no pasa la validación.param trae el primero que falla. No reintentes con el mismo cuerpo: va a fallar igual.rate_limit_exceededHas pasado del cupo de la ventana.Espera lo que diga Retry-After. X-RateLimit-Remaining te dice cuánto queda en la ventana.La envoltura, siempre 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é se reintenta y qué no
Un 4xx no: el mismo cuerpo va a fallar otra vez. El 429 sí, cuando lo diga Retry-After. Un 5xx, con espera creciente. Los SDK ya lo traen puesto.
Catálogo de erroresSi no vas a usar curl
curl vale para la primera vez porque no hay que instalar nada y no esconde nada. Para lo que viene después hay dos SDK oficiales y un servidor MCP.
TypeScript@factuarea/sdk
PHPfactuarea/factuarea-phpTraen resuelto lo que uno acaba escribiendo mal a mano:
391 herramientas
La misma API abierta a un agente, con los mismos scopes de siempre: el agente no puede hacer nada que la clave no pueda.
La clave de prueba también vale aquí, y con los mismos efectos desconectados.
El servidor MCPVayas por donde vayas, el entorno lo sigue decidiendo el prefijo de la clave.
Superficie publicada
El contrato OpenAPI, los SDK y el servidor MCP parten de la misma API. Las cifras se revisan contra la superficie publicada para que puedas evaluar alcance y mantenimiento antes de integrar.
Tecnologías y clientes compatibles
TypeScriptPHP
OpenAPI
StripeLos logotipos identifican tecnologías o clientes compatibles; no implican una relación comercial ni un testimonio.
Dudas
No. La clave de test se crea con una cuenta normal, y la empresa de pruebas se aprovisiona al crear esa primera clave.
Crea la cuenta, saca una clave fact_test_ y sigue el flujo. La factura se numera dentro del sandbox y sus efectos externos no salen de él.