Versioning

The current public API version is v1.

https://api.factulit.es/api/v1
https://api.sandbox-factulit.es/api/v1

Versioning is shared by both environments: each serves the same v1 version and the same order payload contract.

Factulit keeps v1 compatible for existing server-side integrations. Additive fields may be introduced when they do not break existing payloads.

Order Payload Contract

Order payloads support contract_version.

• Missing contract_version is treated as 1.0.
• 1.1 adds optional fiscal and reconciliation fields.
• 1.3 adds explicit correction_events[].
• 1.4 adds optional order tags[] as source facts for account-configured rules.
• 1.5 adds optional timing metadata and the payment date paid_at.
• 1.6 adds optional buyer_role as a declared fact about the buyer.
• 1.7 adds optional id_external_variation to identify the exact variation sold on a line.
• 1.8 adds optional kind on discounts[] and unmapped_totals[].
• Existing v1.0 integrations do not need to send v1.1 fields.

Breaking API changes will be published as a new public version.

v1.4 (additive, backward-compatible)

• Orders may send up to 100 tags, with 255 characters per value.
• Omitting tags on update preserves the stored list; tags: [] clears it.
• Tags never instruct Factulit to invoice or cancel. The account owner defines ordered rules in Factulit, and explicit refunds/corrections retain priority.

v1.8 (additive, backward-compatible)

• discounts[] and unmapped_totals[] accept kind, one of promotional, customer_credit, gift_card, loyalty or unknown. Any other value is discarded.
• kind is a convenience, not the only route: a rule the account owner defines on the row's code takes precedence over the connector's label.
• unmapped_totals[] requires a stable lowercase code; rows without one are discarded.

v1.7 (additive, backward-compatible)

• Lines in breakdown[] and correction_events[].lines[] accept id_external_variation, the exact variation sold. Leave it empty for simple products.
• The variation takes part in version and fiscal-decision fingerprints: changing it invalidates an earlier decision even when the total is unchanged.

v1.6 (additive, backward-compatible)

• buyer_role (consumer, business or unknown) declares the role the recipient acts in for that purchase. It is a neutral fact, not a fiscal instruction: absence means unknown and never on its own widens the simplified-invoice threshold.

v1.5 (additive, backward-compatible)

• Optional timing metadata (source_updated_at, source_event_id, source_event_occurred_at, mapper_version, sync_scope) to order the history. Their absence never blocks syncing.
• paid_at declares the payment date.

Changelog

v1 direct invoice issuance (additive, backward-compatible)

• API connections with explicit VeriFactu invoicing consent can use POST /invoice to atomically issue a numbered invoice and its ALTA record.
• external_id provides connection-scoped idempotency; GET /invoice/{external_id} retrieves the result and PUT is rejected because issued invoices are immutable.
• Existing client, status, order, and key operations are unchanged.

v1.1 (additive, backward-compatible)

• invoice_action gained the exchange_to_full value, requesting the exchange of an already-issued simplified invoice (F2) for a full invoice (F3) once the customer provides their tax ID. See Fiscal Lifecycle.
• original_order_reference (optional, up to 64 characters) was added at the order level to reference the original order when the F3 exchange arrives as a separate order rather than an update.
• breakdown[].regime is now documented against the full VeriFactu regime key list (ClaveRegimen). The core always honors an explicit regime; it only derives a value automatically when the line omits it or sends the generic 01.

These fields are optional and do not change the behavior of existing v1.0 or v1.1 integrations that omit them.