Gerar documentos por API com idempotência

Sistemas que geram documentos transacionais têm um inimigo clássico: o retry. A rede falha depois do pedido chegar, o cliente repete, e nascem dois contratos. A API da DOPTIZER elimina esta classe de bugs com idempotência nativa.

Autenticação

curl -X POST https://api.doptizer.pavulla.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "integracao@empresa.pt", "password": "•••"}'
# → { "token": "eyJ…", "expires_at": "…" }

Use o token em todas as chamadas: Authorization: Bearer {token}. Cada resposta traz um correlation id — inclua-o quando reportar problemas.

O render idempotente

curl -X POST https://api.doptizer.pavulla.com/v1/render \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: pedido-8842" \
  -H "Content-Type: application/json" \
  -d '{
    "templateVersionId": "9d2f…",
    "format": "pdf",
    "data": { "cliente": { "nome": "Ana Silva" }, "valor": 1250.5 }
  }'

• Primeira chamada: gera o documento, devolve documentId e checksum.
• Chamadas repetidas com a MESMA chave: devolvem o MESMO documento com replayed: true — sem gerar de novo, sem consumir quota.
• Use uma chave estável derivada do vosso domínio (ex.: o id do pedido no vosso sistema).

Erros que se corrigem sozinhos

Todos os erros seguem RFC 9457 (problem+json): um type estável para programar contra, um detail legível para humanos e, quando aplicável, a lista de campos inválidos.

{
  "type": "https://errors.doptizer.com/render/template_not_published",
  "title": "Template rule violated",
  "status": 409,
  "detail": "A versão indicada não está publicada — só versões publicadas geram documentos.",
  "correlationId": "01J…"
}

Preview sem custo

POST /v1/render/preview corre o mesmo pipeline mas não persiste nem consome quota, e devolve HTML com watermark — perfeito para mostrar o documento na vossa UI antes de gerar a sério.