# AGENTS.md — como um agente de código usa esta documentação

Você vai implementar um **conector** (o serviço do operador que fala com o Dracma): assinar chamadas, criar
depósitos e saques PIX, receber webhooks, fazer fetch-back, recuperar eventos e reconciliar. Este repositório
é só documentação e exemplos; o código do conector mora no repositório do operador.

## Ordem de leitura

1. [`developers/referencia-rapida.md`](https://developers.dracma.cfd/referencia-rapida/) — regras MUST/NEVER (`R01`…`R36`), endpoints,
   erros e estados. **Trate as regras como requisitos de aceite.**
2. [`developers/api/autenticacao.md`](https://developers.dracma.cfd/api/autenticacao/) e [`developers/webhooks/README.md`](https://developers.dracma.cfd/webhooks/) —
   assinatura nos dois sentidos, ordem de verificação, fetch-back.
3. [`developers/api/erros.md`](https://developers.dracma.cfd/api/erros/) e [`developers/api/idempotencia.md`](https://developers.dracma.cfd/api/idempotencia/) — erros,
   `Idempotency-Key`, repetição.
4. [`developers/referencia/README.md`](https://developers.dracma.cfd/referencia/) — endpoint por endpoint (depósitos, saques, saldos,
   regras, reconciliação) e os objetos em [`developers/referencia/schemas.md`](https://developers.dracma.cfd/referencia/schemas/).
5. [`docs/dinheiro/README.md`](https://docs.dracma.cfd/dinheiro/) e [`developers/conector/estados-no-produto.md`](https://developers.dracma.cfd/conector/estados-no-produto/) —
   o que cada estado significa para o seu livro.
6. [`developers/referencia/divergencias.md`](https://developers.dracma.cfd/referencia/divergencias/) — onde o código atual do Dracma difere
   do contrato. Siga a coluna "Seu código".
7. [`developers/sandbox/README.md`](https://developers.dracma.cfd/sandbox/) e [`developers/go-live/checklist.md`](https://developers.dracma.cfd/go-live/checklist/) —
   testar e entrar em produção.

Um operador concreto, só como exemplo de integração, está em [`developers/casos/README.md`](https://developers.dracma.cfd/casos/).

Tudo concatenado num arquivo só: [`llms-full.txt`](llms-full.txt). Índice curto: [`llms.txt`](llms.txt). Estes arquivos e este `AGENTS.md` ficam na raiz do portal de desenvolvedores (`developers.<domínio>`); o site de usuários (`docs.<domínio>`) só os redireciona para lá.
Precedência em conflito: Contrato de integração v1 (normativo) > `developers/referencia/openapi.yaml` > este guia.
O `developers/referencia/openapi.yaml` é o documento que a API serve (`GET /openapi.yaml`); o diff contra o contrato
1.1.0, item a item, está em [`developers/referencia/openapi.md`](https://developers.dracma.cfd/referencia/openapi/).

## Exemplos de referência

[`developers/exemplos/`](https://developers.dracma.cfd/exemplos/) tem clientes mínimos, só com biblioteca padrão, que assinam
chamadas, verificam webhooks e calculam o digest da reconciliação:

| Linguagem | Arquivos | Teste |
|---|---|---|
| Go | `developers/exemplos/go/dracma/*.go`, `cmd/ping` | `cd developers/exemplos/go && go test ./... && go vet ./...` |
| Node (TypeScript, Node ≥ 22.18) | `developers/exemplos/node/*.ts` | `cd developers/exemplos/node && node --test "*.test.ts"` |
| PHP ≥ 8.1 | `developers/exemplos/php/*.php` | `cd developers/exemplos/php && php vetores_test.php && php auxiliares_test.php` |
| Shell (só depuração) | `developers/exemplos/shell/*.sh` | `bash developers/exemplos/shell/vetores.sh && bash developers/exemplos/shell/helpers_test.sh` |

Porte a lógica desses arquivos; não invente outra forma de montar o pedido canônico.

## Vetores para testar a assinatura

[`developers/exemplos/vetores-assinatura.json`](https://developers.dracma.cfd/exemplos/vetores-assinatura.json) é **normativo**. O seu
conector só está certo quando o teste dele, no CI, reproduz byte a byte:

- os 3 vetores de chamada (`sha256_corpo`, `pedido_canonico`, `Dracma-Signature`);
- o webhook válido (aceita), o de rotação com dois `v1` (aceita com o segredo atual **e** só com o anterior,
  `whsec_test_vetor_ANTERIOR`) e o negativo (recusa: corpo alterado em 1 byte);
- janela: `t` a ±301 s de "agora" recusa, a 300 s aceita (fixe "agora" em `1790000300`);
- `Dracma-Timestamp` diferente de `t=` recusa; `v1` com hex inválido não lança exceção.

Os segredos dos vetores são **públicos e de teste**: nunca os use fora de teste. Antes de declarar pronto, veja
o teste falhar ao quebrar 1 byte (ex.: tirar o `.` de `"<t>."`) e voltar ao verde.

## Regras para o agente

- Nunca coloque segredo real em código, teste, fixture, log ou exemplo. Credenciais vêm de arquivo `0400`
  indicado por variável de ambiente (`DRACMA_KEY_SECRET_FILE`, `DRACMA_WEBHOOK_SECRETS_FILE`).
- Fixtures e testes só com domínios reservados (`.test`, `.invalid`, `.example`) e CPFs de teste gerados com
  dígito verificador válido. Nunca dados de pessoa real.
- Dinheiro é string de inteiro na menor unidade. Nunca float.
- Idempotência: `Idempotency-Key = external_id`, gravada antes da chamada; repetição usa a **mesma** chave.
- Estado desconhecido nunca move dinheiro; débito/recrédito fora do caminho feliz vai para decisão humana.
- Se mudar uma página deste repositório, rode `python3 scripts/gerar_llms_full.py` e
  `python3 scripts/verificar_docs.py` (links, tabelas, HTML, termos proibidos e `llms-full.txt` atualizado; `--estrito` é o modo do CI).

## Sites públicos (docs.<domínio> e developers.<domínio>)

- O repositório tem dois sites (ADR-0038): `docs/` (usuários do painel, `mkdocs.yml`) e `developers/` (integração da API,
  `mkdocs.developers.yml`). Esta documentação de integração é o site `developers`.
- Cada site é construído por `scripts/build_site.py --site {docs|developers} --out <dir>` (venv de `requirements.txt`, pinado por hash:
  `pip install --require-hashes`), tanto pelo `dracma_ops install` quanto pelo CI. Não use CDN: o mermaid está vendorizado em
  `docs/assets/vendor/` (o site developers o usa por `developers/assets`, um link simbólico para a mesma pasta).
- Link de uma página para o outro site usa o host-marcador `https://docs.dracma.cfd/…` ou `https://developers.dracma.cfd/…`
  (estilo de URL do mkdocs); o build troca por `--docs-url` / `--developers-url`.
- Atualizar dependência: editar `requirements.in` e regerar com `pip-compile --generate-hashes --allow-unsafe --strip-extras`.