Integration Topologies

​

Overview

• Server-side — your backend calls the API on behalf of all registers.
• Device-direct — each register calls the API itself, with no backend in between.

​

Server-side

1. Your backend includes the platform API key in the Authorization: Bearer header on every request.
2. When a register reports a sale, your backend calls POST /registers/:id/sales with the API key and the OpenFiskal-Organization header.
3. OpenFiskal returns the fiscal document. Your backend passes the receipt data back to the register.

• Traditional POS systems with a backend (restaurant, retail, hospitality)
• Cloud-based POS where the server already manages register state
• Any setup where devices have reliable connectivity to your own infrastructure

• One API key to manage — no per-device key distribution.
• The API key stays on your server, never on hardware that could be physically compromised.
• Single key works across all organizations and registers.
• Backend can add business logic (validation, enrichment) before calling OpenFiskal.

• Extra dependency — fiscal calls go register → backend → OpenFiskal. If the backend is down, registers must queue locally until it recovers (see Offline Guidance).
• Adds latency — every fiscal call round-trips through your server.
• You must build and operate the backend.

​

Device-direct

1. During provisioning, your backend creates the register and fiscal unit with issue_register_credential: true. This returns a one-time register API key.
2. You securely push the API key to the device (over a provisioning channel, device management platform, or at manufacturing time).
3. The device includes the key in the X-Register-Api-Key header for all API calls.

• Unattended hardware — EV chargers, fuel pumps, vending machines, self-service kiosks.
• Devices that operate without reliable connectivity to your own backend.
• Edge deployments where a central server is impractical.

• No backend dependency for fiscal operations — the device talks directly to OpenFiskal.
• Simpler architecture for autonomous hardware.
• Each device is independent — one going offline does not affect the others.

• One API key per register. At 500 devices, that is 500 keys to distribute and track.
• Keys are long-lived and stored on physical hardware — a stolen device means a compromised key. Rotate immediately via POST /registers/:id/credentials/rotate.
• The device firmware must handle retries and offline queuing directly (see Offline Guidance).

​

Choosing a topology

​

Hybrid approach

​

Provisioning device-direct registers

curl -X POST https://api.openfiskal.com/v1/locations/loc_01HXYZ/registers \
  -H "Authorization: Bearer $API_KEY" \
  -H "OpenFiskal-Organization: org_01HXYZ" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Charger A-042",
    "jurisdiction": "DE"
  }'

curl -X POST https://api.openfiskal.com/v1/registers/reg_01HXYZ/fiscal-units \
  -H "Authorization: Bearer $API_KEY" \
  -H "OpenFiskal-Organization: org_01HXYZ" \
  -H "Content-Type: application/json" \
  -d '{ "issue_register_credential": true }'

{
  "object": "fiscal_unit_response",
  "fiscal_unit": { "id": "fu_01HXYZ", "state": "active" },
  "register_api_key": "ofk_reg_live_...",
  "credential_issued": true
}

​

Key rotation

curl -X POST https://api.openfiskal.com/v1/registers/reg_01HXYZ/credentials/rotate \
  -H "Authorization: Bearer $API_KEY" \
  -H "OpenFiskal-Organization: org_01HXYZ"

​

Next steps