Sessions & Billing

Endereco supports two billing models. Sessions enable the success-based model: you pay only when a user confirms and saves their data.

How Sessions Work

1. User opens form           → Generate UUID v4 session ID
2. User types / autocompletes → Send validation requests with X-Transaction-Id header
3. User saves the form       → Call doAccounting with the session ID → billed
4. User abandons the form    → No doAccounting call → auto-abandoned after 1 hour, not billed

Step 1: Generate a Session ID

Use UUID v4 (random). Each address/contact entry gets its own ID.

const sessionId = crypto.randomUUID()
// e.g. "c07968ba-ec38-4cf2-8819-5b9c70b78a72"

Step 2: Include in Every Request Header

X-Transaction-Id: c07968ba-ec38-4cf2-8819-5b9c70b78a72

Step 3: Finalize on Save

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "doAccounting",
  "params": {
    "sessionsId": "c07968ba-ec38-4cf2-8819-5b9c70b78a72"
  }
}

Rules

Rule	Detail
Uniqueness	Session IDs must be unique within one calendar month
UUID version	Must be v4 (random)
Abandonment	Sessions without doAccounting are auto-abandoned after 1 hour
Per record	Each address/contact gets its own session ID, not per page load

Client Identification

Always identify your integration:

X-Agent: MyShop v2.1.0

Format: [CLIENT_NAME] [SEMVER_VERSION]

Referrer

Optionally pass the page URL where data was entered:

X-Transaction-Referer: www.example.de/checkout

Readiness Check

Before making API calls you can verify the service is reachable with readinessCheck. It takes no parameters and simply returns "ready" when the service is up.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "readinessCheck",
  "params": {}
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "status": "ready"
  }
}

Use this as a lightweight health-check ping during integration setup or monitoring.