Integrar com IA

Você é um engenheiro de software sênior. Implemente a integração de pagamentos Pix com a PhanterPay no meu projeto, seguindo exatamente o contrato abaixo.

CONTRATO DA API PHANTERPAY (v1)

Base URL (única, produção): https://api.phanterpay.com.br/v1
OpenAPI 3.1: https://api.phanterpay.com.br/openapi.json
Documentação: https://docs.phanterpay.com.br

AVISO CRÍTICO
- Não existe sandbox nem ambiente de teste. Toda chamada atinge a rede Pix real e movimenta dinheiro real.
- Valor mínimo por operação: R$ 2,00 (amount >= 2).
- Use apenas os endpoints listados abaixo. Não invente rotas, campos, filtros nem parâmetros.

AUTENTICAÇÃO
- Header: "Authorization: Bearer <chave>" (alternativa equivalente: "x-api-key: <chave>").
- Formato real da chave: bp_<8 hex>_<48 hex>. Exemplo: bp_a1b2c3d4_9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a3928
- Não existem chaves públicas (pk_) nem chaves de sandbox.
- Leia a credencial SEMPRE da variável de ambiente PHANTERPAY_API_KEY.
- NUNCA escreva a chave no código-fonte, em front-end, em app mobile ou em repositório.

ESCOPOS
- charges:read, charges:write, payouts:read, payouts:write, balance:read, med:read, med:write.
- Escopo ausente devolve 403 FORBIDDEN.

IDEMPOTÊNCIA
- Header "Idempotency-Key" (8 a 255 caracteres) é OBRIGATÓRIO em POST /charges e POST /payouts.
- Mesma chave + mesmo corpo já concluído -> devolve a resposta original com header "idempotent-replayed: true".
- Mesma chave + corpo diferente -> 409 IDEMPOTENCY_CONFLICT.
- Em timeout de rede, repita com a MESMA chave; nunca gere outra.

RATE LIMIT
- 600 requisições por minuto por chave. Headers x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset; retry-after em 429.

PAGINAÇÃO (cursor, único formato existente)
- Query: limit (1 a 200, padrão 50) e starting_after.
- Resposta: { "data": [...], "has_more": bool, "next_starting_after": string|null }.
- NÃO existe offset, page nem filtro de status em /charges e /payouts.

ENDPOINTS DISPONÍVEIS
1) POST https://api.phanterpay.com.br/v1/charges  (charges:write, Idempotency-Key obrigatório)
   body: { amount (>=2, obrigatório), description?, payer_name?, payer_document?, expires_in? (60-86400), external_id?, postback_url? }
   201: { id: "chg_...", txid, external_id, amount, test_mode, status, description,
          pix: { copy_paste, qr_code_image }, end_to_end_id, paid_at, expires_at, created_at }
   Atenção: o Pix copia e cola está em charge.pix.copy_paste e a imagem em charge.pix.qr_code_image.
2) GET  https://api.phanterpay.com.br/v1/charges          (charges:read) -> página com data/has_more/next_starting_after
3) GET  https://api.phanterpay.com.br/v1/charges/{id}     (charges:read) -> aceita chg_..., o txid do adquirente ou ext:<external_id>
4) POST https://api.phanterpay.com.br/v1/payouts  (payouts:write, Idempotency-Key obrigatório)
   body: { amount (>=2, obrigatório, LÍQUIDO ao destinatário), pix_key (obrigatório), pix_key_type? (cpf|cnpj|email|phone|random),
           recipient_name?, recipient_document?, description?, external_id?, postback_url? }
   201: { id: "pyt_...", external_id, amount, fee, net_amount, gross_amount, test_mode, status,
          pix: { key, recipient_name, recipient_document }, description, end_to_end_id, error_message, created_at, completed_at }
   Semântica: o destinatário recebe amount; gross_amount = amount + fee é debitado do saldo.
   A criação faz uma verificação rápida junto à adquirente e pode devolver "completed" (liquidação confirmada de imediato),
   "failed" (falha definitiva confirmada de imediato) ou "processing" (ainda sem confirmação final).
   Se vier "processing", aguarde payout.completed / payout.failed OU consulte GET /payouts/{id}.
5) GET  https://api.phanterpay.com.br/v1/payouts          (payouts:read)
6) GET  https://api.phanterpay.com.br/v1/payouts/{id}     (payouts:read)
7) GET  https://api.phanterpay.com.br/v1/balance          (balance:read)
   200: { available_balance, pending_balance, blocked_balance, total_balance, currency: "BRL" }
8) GET  https://api.phanterpay.com.br/v1/med              (med:read) -> query: limit (1-100, padrão 20), starting_after, status
9) GET  https://api.phanterpay.com.br/v1/med/{id}         (med:read)
10) POST https://api.phanterpay.com.br/v1/med/{id}        (med:write) -> body { defense_text (obrigatório), defense_evidence_url? }

ROTAS RESERVADAS (hoje respondem HTTP 501 FEATURE_NOT_AVAILABLE — não implemente fluxo de pagamento nelas)
- POST/GET https://api.phanterpay.com.br/v1/boletos, GET https://api.phanterpay.com.br/v1/boletos/{id}
- POST/GET https://api.phanterpay.com.br/v1/card/charges, GET https://api.phanterpay.com.br/v1/card/charges/{id}

WEBHOOKS
- Webhooks são OPCIONAIS. É possível integrar somente com a API REST, criando a operação via POST e consultando o status pelos endpoints GET.
  Para atualizações automáticas em tempo real e menor uso de polling, recomendamos o uso de webhooks.
- Cadastre a URL no painel (API & Integrações) ou envie postback_url na criação da transação.
- Eventos entregues hoje: charge.created, charge.paid, payout.created, payout.completed, payout.failed.
- Header de assinatura: "x-phanterpay-signature: t=<unix>,v1=<hex>".
- HMAC-SHA256 sobre a string "<t>.<corpo cru>" com o secret do endpoint (whsec_...).
- Valide SEMPRE o corpo cru (sem reserializar), rejeite t com mais de 5 minutos e compare em tempo constante.
- Responda 2xx rapidamente e processe de forma assíncrona; entregas são "pelo menos uma vez" — deduplique pelo campo id do evento.

ERROS (envelope único)
{ "success": false, "error": { "code", "message", "retryable", "issues"? }, "request_id" }
Códigos: VALIDATION_ERROR(400), UNAUTHORIZED(401), INSUFFICIENT_BALANCE(402), FORBIDDEN(403), NOT_FOUND(404),
IDEMPOTENCY_CONFLICT(409), AMOUNT_LIMIT_EXCEEDED(422), RATE_LIMIT_EXCEEDED(429), INTERNAL_ERROR(500),
FEATURE_NOT_AVAILABLE(501), PROVIDER_UNAVAILABLE(502), SERVICE_UNAVAILABLE(503).
Decida retentar pelo campo booleano "retryable", nunca pelo texto de "message".

VARIÁVEIS DE AMBIENTE ESPERADAS
PHANTERPAY_API_KEY=bp_a1b2c3d4_9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a3928
PHANTERPAY_API_BASE_URL=https://api.phanterpay.com.br/v1
PHANTERPAY_WEBHOOK_SECRET=whsec_troque_pelo_secret_do_endpoint

O QUE EU PRECISO
1. Um cliente HTTP tipado para os endpoints acima, lendo a credencial de process.env.PHANTERPAY_API_KEY (ou equivalente na linguagem).
2. Autenticação por header "Authorization: Bearer <PHANTERPAY_API_KEY>".
3. Criação de cobrança Pix (POST /charges) com Idempotency-Key gerado por operação e persistido junto do pedido.
4. Consulta de cobrança (GET /charges/{id}) para acompanhar o status até atingir um estado final.
5. Criação de saque Pix (POST /payouts) com tratamento explícito de 402 INSUFFICIENT_BALANCE e exibição de fee/gross_amount ao usuário.
6. Consulta de saque (GET /payouts/{id}) para acompanhar o status até atingir um estado final.
7. Tratamento de erros pelo envelope real e retentativa com backoff apenas quando retryable=true.

WEBHOOK (OPCIONAL)
- A integração deve funcionar completamente sem webhook.
- Para acompanhar status sem webhook, utilize GET /charges/{id} e GET /payouts/{id}.
- Ao final da implementação, apenas informe que webhooks estão disponíveis como opção recomendada para confirmação automática em tempo real.
- NÃO implemente webhook a menos que o usuário solicite. Se ele solicitar, use assinatura HMAC-SHA256 sobre o corpo cru, janela de 5 minutos, deduplicação por event id e resposta 2xx rápida.

REGRAS OBRIGATÓRIAS
- Use somente os endpoints e campos documentados acima; se algo não estiver no contrato, pergunte em vez de inventar.
- Além da PHANTERPAY_API_KEY, POST /charges e POST /payouts exigem também o header Idempotency-Key.
- Não coloque a chave no código, em variáveis de front-end, em logs ou em commits.
- Lembre-se: não há sandbox; qualquer chamada gerada pelo código pode movimentar dinheiro real.