Boas práticas

A chave fica no servidor

O caixa da loja fala com o seu servidor; o seu servidor fala com a Moeda Nobre. Nunca coloque a chave no aplicativo instalado nos caixas, num site ou num repositório. Mantenha duas chaves ativas para trocar sem parar a operação.

Uma Idempotency-Key por venda

Use um identificador da venda que você já tem (número do cupom, id do pedido) como Idempotency-Key. Se a rede cair no meio do POST /cobrancas, repita com a mesma chave e o mesmo corpo: você recebe a mesma cobrança (200 com Idempotent-Replayed: true), nunca duas. Chave igual com corpo diferente → 422 IDEMPOTENCY_CONFLITO.

Uma cobrança aberta por caixa

Cada caixa tem no máximo uma cobrança pendente. Se o operador desistir da venda, cancele (POST /cobrancas/{id}/cancelar) ou crie a próxima com cancelarPendenteAnterior: true. Se a resposta for 409 COBRANCA_NAO_PENDENTE com statusAtual: "PAGA", o cliente pagou a anterior — siga com aquela venda, não cobre de novo.

Saber se pagou: segure a consulta

GET /cobrancas/{id}?aguardar=25&semImagem=true

A resposta volta assim que o status muda (ou em 25 s, com o status atual). Em loop, enquanto PENDENTE e antes do expiraEm. É mais rápido e mais barato que consultar a cada segundo, e funciona atrás de qualquer internet de loja. O webhook é um complemento para o servidor.

Prazo da cobrança

expiraEmSegundos vai de 60 a 900 (padrão 300). Depois dele a cobrança vira EXPIRADA sozinha e o cliente não consegue mais pagar. Mostre ao operador um contador baseado no expiraEm.

Não entre em loop no erro

Um 4xx de regra de negócio (PDV_INATIVO, LOJA_INATIVA, VINCULO_REVOGADO, CHAVE_REVOGADA…) não vai mudar se você repetir. Mostre a mensagem ao operador e pare. Repita só 429, 5xx, 409 REQUISICAO_EM_ANDAMENTO e falhas de rede, com espera crescente.

Relógio certo

A assinatura dos webhooks recusa diferenças acima de 5 minutos. Mantenha o relógio do servidor sincronizado (NTP).

Sem dado pessoal

metadados e referenciaExterna servem para o seu controle (operador, número do cupom, mesa). Não coloque nome, CPF, telefone ou e-mail de cliente. A Moeda Nobre também não manda nenhum dado de cliente para você.

Guarde o requestId

Registre o Moeda-Nobre-Request-Id de cada chamada nos seus logs. Com ele o suporte (e você, em Monitoramento → Registros no portal) encontra a chamada exata.

Homologação

Antes de pedir a produção, o seu PDV prova no ambiente de testes, sozinho, estes 9 itens (a tela Homologação do portal acompanha ao vivo):

Conectou (GET /ping)
Ativou um caixa com código T-…
Criou cobrança com Idempotency-Key
Repetiu a criação sem duplicar (resposta com Idempotent-Replayed)
Detectou o pagamento (leu PAGA depois de pago, ou recebeu o webhook)
Cancelou uma cobrança
Leu uma cobrança EXPIRADA
Viu um estorno (leu ESTORNADA ou recebeu o webhook)
Depois de um 422 PDV_INATIVO, fez no máximo 3 chamadas iguais no minuto seguinte

Com os 9 verdes, um administrador da sua empresa pede a liberação. A TribeX também confere, numa conversa, onde a chave fica guardada e se a assinatura do webhook é verificada.