Boas práticas

Segurança

• Sempre HTTPS. Nunca trafegue credenciais ou payloads em texto claro.
• Chave privada só no backend. A private-key.pem nunca deve aparecer no front-end, em logs ou em repositório. O kid (fingerprint) não é segredo e pode ser versionado à vontade.
• Rotação e revogação. Gere um novo certificado periodicamente (rotação) e revogue imediatamente qualquer chave sob suspeita de vazamento — assinaturas com um cert revogado passam a receber 401.
• Guarde a API key. Ela identifica a sua operação; gire-a em caso de suspeita.

Assinatura

• Relógio sincronizado (NTP). O t da assinatura é aceito dentro de ±5 min do relógio do servidor. Um relógio muito fora gera 401.
• Assine os bytes exatos do corpo. A assinatura é sobre t.corpo — não reserialize o JSON depois de assinar (espaços/ordem de campos mudam os bytes e invalidam a sig).
• Uma assinatura por requisição. Recalcule t e sig a cada chamada; não reaproveite.

Confiabilidade

• Idempotência. Onde houver um id de operação (ex.: event_id no envio de transações), use um valor estável e único; reenviar o mesmo id é seguro (é deduplicado).
• Retry com backoff. Em 5xx ou timeout, tente de novo com exponential backoff — confie na idempotência para não duplicar efeitos.
• Não derrube o lote por um item. No envio em lote, um evento inválido entra como skipped e os demais seguem; confira o resumo da resposta.

Dados

• Valores em centavos. Todo valor monetário é inteiro em minor units (centavos) — R$100,00 = 10000. Nunca envie decimal.
• CPF/CNPJ com ou sem pontuação. A formatação é removida no servidor; o importante é a quantidade de dígitos (CPF 11, CNPJ 14).
• Telefone com DDI. O celular precisa incluir o código do país 55 (12–13 dígitos no total); o + e a pontuação são opcionais (ex.: +5511998877665 ou 5511998877665).
• Registre as respostas. Guarde o corpo de resposta (status por item, contadores) para conciliação e suporte.