How do I move from testing to production?

Create a production key in your account and verify its access and permissions. Use identifiers from the real company: sandbox identifiers do not carry over. Editing a key’s prefix does not change its environment.

How do I avoid duplicates when retrying?

Keep the same Idempotency-Key and request body when repeating an operation. Reusing a key with a different body may return 409. Generate a new key for a new operation.

Does a test invoice spend a number from the series?

Not when you create it. Issuing assigns a number from the sandbox series; it never consumes or changes production numbering.

What if I lose the secret?

You cannot retrieve it again. Create or rotate the key in your account and update the secret on your server.

Developers · Quickstart

From your first API call to an invoice PDF.

Connect your test key, prepare your data and follow an invoice through its full lifecycle. Five steps, seven requests and the same contract you will use in production.

Create my test key Open the full guide

cURL or Node.js · REST API · Isolated sandbox

Before your first request

One key. Your testing environment.

Create an account and open Settings → Developers → API keys. Choose a test key and keep its secret on your server.

Create my test key

Permissions for this walkthrough

account:readseries:readtaxes:readcontacts:writeinvoices:writeinvoices:sendpdfs:read

Key prefixfact_test_••••••••

Test

Start in the sandbox

Your first test key provisions an isolated company. Issuing uses its own numbering; email and AEAT submissions do not leave the sandbox.

The same base URL in both environmentshttps://api.factuarea.com/v1

Prepare your terminal

Bash, cURL and uuidgen. For the JavaScript alternative, Node.js 20 or later. Replace TU_CLAVE and run this setup once in the same terminal.

Keep each REQUEST_ID when retrying the same operation with the same body. Generate another for a new operation. Never expose your API key in the browser.

export FACTUAREA_API_KEY="fact_test_TU_CLAVE"
export CONTACT_REQUEST_ID="$(uuidgen)"
export INVOICE_REQUEST_ID="$(uuidgen)"
export SEND_REQUEST_ID="$(uuidgen)"

The complete workflow

From connection to document.

Choose a step to inspect its request. Run the code in your terminal; you can explore this walkthrough here without sending requests.

Factuarea API / quickstart

Testapi.factuarea.com/v1

Step 1 / 5

Check your key and account

Your first call confirms which company the key belongs to and which permissions it has. It does not create documents.

GET/account

1: "${FACTUAREA_API_KEY:?FACTUAREA_API_KEY}"23curl --fail-with-body --silent --show-error \4  --request GET \5  "https://api.factuarea.com/v1/account" \6  --header "Authorization: Bearer $FACTUAREA_API_KEY"

cURL · Bash

Expected result

Your account, plan and key permissions.

HTTP 200JSON

Response fields

"company"
"plan"
"api_key"

Required permissionaccount:read

A 200 response confirms you can continue.

Check data.company and data.api_key.scopes before continuing.

The requests in this guide use your test key.

When something needs attention

Read the error. Keep going.

The HTTP status gives context; the response code and message tell you what to check.

Read about errors and responses

HTTP 401invalid_api_key

The key does not authenticate

Check the complete secret and the Authorization: Bearer header. If you lost the secret, create or rotate the key in your account.

What to check

Make sure FACTUAREA_API_KEY is exported in your terminal.

Where your integration goes next

Your first invoice is the beginning.

Bring it into your application

Official TypeScript and PHP SDKs: pagination, typed errors and retries.

Receive events as they happen

Connect webhooks and verify each notification’s signature before processing it.

Connect your assistant

Use the MCP server with compatible clients such as Claude and ChatGPT.

Questions

Before connecting your application

No. The test key is created from a normal account, and the sandbox company is provisioned when that first key is created.

A more connected business

The test invoice is five steps away

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.

Start free Developer portal