Developers · Quickstart
Copy five curl calls and finish with an issued invoice and its PDF. Everything runs in the sandbox.
Compatible integrations and formats
WhatsApp
The header on every request
Authorization: Bearer fact_test_8KqW3pXnR2VbY7TcA9eFmN5zThis part decides the environment.
fact_test_Sandboxfact_live_No parameter, header or body field changes this. It is decided by the key you sign the request with.
The path
The real flow has five steps because series, clients and invoices are separate resources. Each response prepares the next one; only the code you need now is shown.
The complete flow
fact_test_ → invoice.pdf
Step 1 of 5
A read that creates nothing. It tells you which company is behind the key, which plan it is on and which scopes it carries.
You walk away with
The list of scopes on the key. If one is missing, the step that needs it will answer 403.
Switch steps from the map. The full calls and every response remain available in the technical guide.
1 call in this step
Step 1 of 5
GET/v1/accountaccount:readexport FACTUAREA_API_KEY="fact_test_..."
curl https://api.factuarea.com/v1/account \
-H "Authorization: Bearer $FACTUAREA_API_KEY"The flow ends with an issued invoice and a PDF that already contains its final number.
When it fails
Every error keeps a stable core (type, code and message) and adds param, request_id or doc_url when relevant.
invalid_api_keyThe key does not exist, does not match the secret, or is no longer valid.Check the prefix, that you copied the full secret, and that the key has not been revoked or expired.insufficient_scopeThe key is valid, but it does not carry the permission for that operation.The scopes on the key come back from GET /v1/account. Compare them with the one the call asks for.parameter_invalidA field failed validation.param names the first one that failed. Do not retry the same body: it will fail again.rate_limit_exceededYou went past the quota for the window.Wait as long as Retry-After says. X-RateLimit-Remaining tells you what remains in the window.The envelope, always the same
{
"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"
}
}What to retry and what not to
Not a 4xx: the same body will fail again. A 429 yes, when Retry-After says so. A 5xx with growing backoff. The SDKs ship with all of that in place.
Error catalogueIf curl is not your plan
curl is right for the first run because there is nothing to install and nothing hidden. For what comes after there are two official SDKs and an MCP server.
TypeScript@factuarea/sdk
PHPfactuarea/factuarea-phpThey ship with the things everyone ends up writing badly by hand:
391 tools
The same API opened up to an agent, with the same scopes as always: the agent cannot do anything the key cannot.
The test key works here too, with the same effects switched off.
The MCP serverWhichever way you go, the environment is still decided by the prefix on the key.
Published surface
The OpenAPI contract, SDKs and MCP server share the same API. These figures are checked against the published surface so you can assess scope and maintenance before integrating.
Compatible technologies and clients
TypeScriptPHP
OpenAPI
StripeLogos identify compatible technologies or clients; they do not imply a commercial relationship or endorsement.
Questions
No. The test key is created from a normal account, and the sandbox company is provisioned when that first key is created.
Create the account, get a fact_test_ key and follow the flow. The invoice is numbered inside the sandbox and its external effects stay there.