# BRV - Desenvolvimento de Sistemas LTDA — API de Integração (conteúdo completo para IA)

> API REST para emitir e consultar documentos fiscais eletrônicos (NF-e, NFC-e,
> NFS-e). Use este arquivo como contexto para implementar a integração.

Base URL: https://api.conttrole.io
Contrato OpenAPI (fonte da verdade dos endpoints): https://api.conttrole.io/openapi.json

## Autenticação
- Esquema: HTTP Bearer. Header: `Authorization: Bearer ck_live_<chave>`.
- A chave é por empresa. Toda requisição opera sobre a empresa dona da chave —
  nunca envie um identificador de empresa no corpo/query.
- Formato da chave: `ck_<ambiente>_<lookupId>_<secret>` (ambiente = live|test).
- A chave em texto puro é exibida UMA vez na criação (guardamos só o hash).
- Escopos (vazio = acesso total na empresa):
  - documents:read  — ler documentos fiscais
  - documents:write — emitir/alterar documentos
  - companies:read  — ler dados da empresa

## Formato de erro (todas as respostas de erro)
{
  "statusCode": <http>,
  "error": "<nome curto>",
  "message": "<mensagem legível pt-BR>",
  "code": "<código estável da aplicação>"
}
Códigos comuns:
- 400 validation_error      — parâmetros inválidos (campo "issues" detalha)
- 401 missing_api_key       — header Authorization ausente
- 401 invalid_api_key       — chave inválida/revogada/expirada
- 403 insufficient_scope    — escopo insuficiente
- 404 not_found             — recurso não encontrado
- 429                       — rate limit excedido (use backoff exponencial)
- 500                       — erro interno

## Paginação
Listagens aceitam page (>=1) e pageSize (1..100) e retornam:
{ "data": [ ... ], "meta": { "page", "pageSize", "total", "totalPages" } }

## Endpoints (resumo — detalhe completo no OpenAPI)
- GET  /health                       — liveness (sem auth)
- GET  /health/ready                 — readiness (checa o banco)
- GET  /v1/fiscal-documents          — lista documentos fiscais (auth: documents:read)
       query: page, pageSize, status, type
- GET  /v1/fiscal-documents/{id}     — detalha um documento (auth: documents:read)

## Exemplo (curl)
curl https://api.conttrole.io/v1/fiscal-documents \
  -H "Authorization: Bearer ck_live_sua_chave"

## Recomendações para implementação com IA
- Gere o client a partir de https://api.conttrole.io/openapi.json.
- Trate o campo "code" do erro para lógica de retry/feedback.
- Implemente backoff exponencial em 429 e em erros 5xx.
- Nunca exponha a chave no front-end; mantenha-a no servidor.