Authentication

Two supported methods: API Key (server-to-server) and JWT Bearer (browser/dashboard).

API Key (recommended for ERP integrations)

Send the API Key in the X-API-KEY header. Keys have format ecf_sk_<publicId>_<secret> and are hashed at rest using SHA-256 (Sprint 2 fix).

curl https://ecf.frandeone.com/TesteCF/documentos-ecf \
  -H "X-API-KEY: ecf_sk_abc123_def456..."

JWT Bearer (dashboard / interactive)

Obtain a token via login, then send it as Authorization: Bearer <token>.

# Login
curl -X POST https://ecf.frandeone.com/TesteCF/customer/authentication \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"..."}'

Idempotency

For POST /TesteCF/documentos-ecf, pass an Idempotency-Key header to safely retry. The server caches the response for 24 hours.

curl -X POST https://ecf.frandeone.com/TesteCF/documentos-ecf \
  -H "X-API-KEY: $KEY" \
  -H "Idempotency-Key: order-12345-retry-1" \
  -d @ecf.json

If the same key is reused with an identical body, the original response is returned with Idempotent-Replayed: true header. If the body differs, the server returns 409 IDEMPOTENCY_KEY_CONFLICT.

Rate limits (Sprint 4.8)

Endpoint group	Limit
Default API	120 req/min per tenant
POST /.../documentos-ecf (emit)	30 req/min per tenant
Sensitive ops (upload cert, change password, webhook test)	10 req/min per tenant
Public auth (login/register)	20 req/min per IP
/fe/* DGII receiver	600 req/min per tenant