API REST

• Base: https://app.fiscal.protoncode.com.br/api/v1
• Autenticação: Authorization: Bearer pk_live_... (criar chave)
• Formato: JSON (UTF-8). Datas em milissegundos desde 1970 (UTC).
• Referência completa: Referência da API

Exemplo

curl https://app.fiscal.protoncode.com.br/api/v1/invoices \
  -H "Authorization: Bearer pk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-123" \
  -d '{
    "external_ref": "pedido-123",
    "taker": { "document": "52998224725", "name": "Ana Souza", "email": "ana@exemplo.com" },
    "service": { "description": "Troca de óleo e revisão", "amount_cents": 25050 }
  }'

Resposta 202 com a nota em processing. O envio ao Sistema Nacional NFS-e é assíncrono: acompanhe por GET /invoices/{id} ou pelo webhook invoice.authorized / invoice.rejected. Antes de emitir, GET /issuer/status diz se a empresa está pronta (dados fiscais e certificado A1 válido).

• Idempotency-Key é obrigatório: repetir a chamada com a mesma chave e o mesmo corpo devolve a mesma nota.
• external_ref (opcional) identifica o pedido no seu sistema: nunca existem duas notas em andamento ou autorizadas com a mesma referência (a segunda chamada recebe 409 com o id da existente).
• Cancelar: POST /invoices/{id}/cancel com {"reason_code": 1, "reason": "..."} (1 erro na emissão, 2 serviço não prestado, 9 outros; justificativa de 15 a 255 caracteres). XML da nota: GET /invoices/{id}/xml.

Paginação

Listas devolvem { "data": [...], "next_cursor": "..." }. Para a próxima página, envie ?cursor=<next_cursor>. limit vai de 1 a 100 (padrão 50).

Erros

Erros seguem a RFC 9457 (application/problem+json):

{ "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "name é obrigatório", "request_id": "3f9c2a..." }

Status	Significado
400	Dados inválidos — veja detail
401	Chave ausente, inválida ou revogada
403	A chave não tem a permissão necessária
404	Não encontrado (ou pertence a outra conta)
429	Muitas requisições — aguarde Retry-After segundos

Repetir com segurança (idempotência)

Envie Idempotency-Key nos POST. Repetir a mesma chamada com a mesma chave em até 24 h devolve a resposta original, sem duplicar.

Rastreamento

Envie o header traceparent se o seu sistema já usa tracing; nós continuamos o mesmo trace e devolvemos X-Trace-Id. Os webhooks gerados pela sua chamada levam o mesmo trace.