Getting Started

Factulit API v1 is designed for server-side integrations that sync commerce data into Factulit.

Base URL and environments

Factulit exposes two independent environments. They do not share data, and a key issued for one is not valid in the other.

Environment	Base URL	Key prefix	Records are filed with
Test	https://api.sandbox-factulit.es/api/v1	factulit_test_	AEAT pre-production (Preportal). No fiscal effect.
Production	https://api.factulit.es/api/v1	factulit_live_	The live AEAT service. Records have fiscal effect.

Build and test against the test environment. The prefix of your key determines which environment it belongs to: sending a factulit_test_ key to the production base URL returns 401, and the reverse is also true. Production is not open to new sign-ups yet, so today the test environment is the starting point for every integration.

First Request

Use a placeholder key in examples and store real keys only in your server-side configuration.

curl https://api.sandbox-factulit.es/api/v1/status/paid \
  -H "Accept: application/json" \
  -H "X-API-KEY: factulit_test_example_key"

Main Resources

Resource	Purpose
client	Create or update customers associated with the authenticated integration.
status	Create or update external order statuses and mark which ones are final.
order	Sync orders, line breakdowns, customer data, and fiscal lifecycle intent.
key	Validate, rotate, or update API credentials owned by the authenticated business.

Integration Flow

1. Configure the API key in your server-side integration.
2. Sync the order statuses your platform uses.
3. Sync clients when they are created or updated.
4. Sync orders whenever fiscal state changes, including paid orders, cancellations, and refunds.
5. Handle 422 validation or quota responses as final business errors, not transient transport failures.