# Integrar a API BORA

Você vai integrar a API BORA no meu sistema. Siga estas instruções.

## O que é a BORA

A BORA faz autenticação pela palma da mão em catracas de transporte. O aparelho BORA ACCESS fica na catraca e reconhece a palma offline. Ele manda um veredito assinado pelo cabo USB ao validador da operadora, o DBD. O DBD decide e abre a catraca. A API BORA é a parte na nuvem: cadastra pessoas, abre o cadastro da palma, guarda as passagens para conciliação e serve de carteiro entre a BORA e os aparelhos.

## Leia antes de escrever código

1. https://docs.bora.id/llms-full.txt: a referência completa em Markdown.
2. https://docs.bora.id/openapi.json: o contrato OpenAPI 3.1 com as 16 operações da prova de conceito.

Siga o contrato. Não invente rota, campo nem código de erro.

## Conexão

- Base URL do sandbox: https://sandbox.api.bora.id (em breve). Até lá, use a URL que a equipe BORA passar.
- Produção: https://api.bora.id (em breve).
- Toda chamada de parceiro leva o header `Authorization: Bearer <API key>`.
- Leia a key da variável de ambiente `BORA_API_KEY`. Nunca escreva a key no código.
- No sandbox, use a key de teste (`bora_test_...`).

## Fluxo para implementar

1. Criar a pessoa com o `external_ref` da conta do cliente: `POST /v1/subjects`. O `external_ref` é o ID da conta no meu sistema, nunca o CPF. O CPF é opcional e vai só no corpo.
2. Registrar o consentimento da finalidade de acesso: `POST /v1/subjects/{subject_id}/consents` com `purpose` igual a `identification` e a evidência do aceite (`method`, `terms_version`, `accepted_at`, `evidence_sha256`).
3. Abrir a sessão de cadastro: `POST /v1/enrollment-sessions`. Mostrar o `qr_payload` como QR code para o totem ler, ou o `short_code` para digitar no totem. O `token` só aparece nessa resposta. Não guarde o token em log.
4. Acompanhar o estado do cadastro: `GET /v1/enrollment-sessions/{session_id}` até `completed`. Trate também `expired`, `cancelled`, `failed` e `review`.
5. Consultar as passagens para conciliação: `GET /v1/verdicts`, com filtros (`gate_id`, `device_id`, `from`, `to`, `reconciliation`) e paginação por cursor. A prova assinada de uma passagem está em `GET /v1/verdicts/{verdict_id}`.
6. Carteiro: para cada aparelho (`GET /v1/devices`), buscar `GET /v1/devices/{device_id}/inbox?after_seq=<último seq entregue>` e entregar os registros ao DBD do jeito que vieram. O que o DBD puxar do aparelho, devolver em `POST /v1/devices/{device_id}/outbox`, sem abrir nem alterar. Guarde o último `seq` entregue de cada aparelho.
7. Apagar a pessoa a pedido (LGPD): `DELETE /v1/subjects/{subject_id}`. Guarde o recibo assinado que volta na resposta.

## Regras

- Nunca ponha CPF em URL, query string ou log.
- Mande `Idempotency-Key` (um UUID v4 novo) em todo POST. Ao repetir a mesma operação, repita a mesma chave.
- Se vier `429`, espere os segundos do header `Retry-After` antes de tentar de novo. Em `5xx`, tente de novo com espera crescente e a mesma `Idempotency-Key`.
- Os erros vêm em `application/problem+json` com um `code` estável. Trate pelo `code`, nunca pelo texto do `detail`.
- No sandbox, use só a key de teste. Nunca use uma key `bora_live_` em teste.
- Ignore campos desconhecidos nas respostas. A API só cresce com campos novos.
- Não chame rotas internas do aparelho (registro, galeria, envio de vereditos). Elas não são do parceiro.

## Entrega

- Um cliente da API com as operações do fluxo, com timeout e tratamento de erro pelo `code`.
- Testes do fluxo de ponta a ponta com respostas simuladas a partir dos exemplos do `openapi.json`.
- Um resumo curto do que foi feito e de como rodar.