Pular para o conteúdo

Comece aqui

Como a integração funciona, ambientes, autenticação e formato.

3 min de leitura

Nesta página

A API de PDV da Moeda Nobre liga o sistema de caixa de uma loja credenciada ao app do cliente. O caixa cria a cobrança com o valor da venda, mostra o QR Code, o cliente paga com o saldo do benefício pelo app, e o seu sistema fica sabendo na hora.

Você não mexe com dinheiro, cartão nem dado pessoal: a Moeda Nobre confirma o pagamento e o valor entra na loja pelo caminho de sempre.

Como uma venda acontece

  1. O operador fecha a venda no caixa.
  2. O seu servidor chama POST /cobrancas com o valor e recebe a cobrança com o QR Code.
  3. O caixa mostra o QR (na tela ou no cupom).
  4. O cliente lê o QR com o app da Moeda Nobre e confirma com o PIN.
  5. O seu sistema descobre que foi paga, do jeito recomendado, segurando uma consulta aberta (GET /cobrancas/{id}?aguardar=25), ou recebendo o webhook cobranca.paga.
  6. O caixa imprime o comprovante e segue.

Dois ambientes, o mesmo contrato

Testes Produção
Chave mn_test_… mn_live_…
Lojas e clientes fictícios, criados por você no portal lojas reais credenciadas
Dinheiro nenhum real
Liberação na hora, ao entrar no portal pela TribeX, depois da homologação

É a chave que decide o ambiente: a URL é a mesma. Um QR de teste nunca é pago pelo app real, e uma chave de teste nunca enxerga uma loja real.

Endereço

https://moedanobre.com/api/v1

Todas as rotas deste guia são relativas a esse endereço (ex.: https://moedanobre.com/api/v1/ping).

Autenticação

Toda chamada leva a chave no cabeçalho:

Authorization: Bearer mn_test_a8Kq2x9LmP0Z_…
  • A chave fica no seu servidor. Nunca no navegador, no aplicativo do caixa distribuído para as lojas ou em código-fonte público. Uma chamada vinda de navegador é recusada (403 CHAVE_EM_NAVEGADOR) e avisa a TribeX.
  • A chave completa aparece uma única vez, quando você a cria no portal. Guarde-a num cofre de segredos.
  • Mantenha duas chaves ativas para trocar sem parar o caixa: crie a nova, publique no servidor, revogue a antiga.

Formato

  • JSON em UTF-8, nomes em português, camelCase.
  • Dinheiro sempre em centavos inteiros (valorCentavos: 4590 = R$ 45,90).
  • Datas em ISO-8601 com o fuso de Brasília (2026-09-25T14:03:11-03:00).
  • Campos novos podem aparecer nas respostas sem aviso: ignore o que você não conhece. Campos desconhecidos no que você envia são recusados (400 CAMPO_DESCONHECIDO).

Cabeçalhos de toda resposta

Cabeçalho Para quê
Moeda-Nobre-Request-Id Identifica a chamada. Guarde nos seus logs e mande ao suporte quando algo der errado.
RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset Seu limite por minuto e quanto falta. Vêm em toda resposta com chave válida, inclusive no 429; não vêm quando a chave é recusada (401/403), porque aí ainda não se sabe de quem é o limite, nem no 405 (método não aceito) e no 404 RECURSO_NAO_ENCONTRADO (rota que não existe), que respondem antes de olhar a chave.
Idempotent-Replayed: true A resposta é a repetição de um POST /cobrancas que já tinha dado certo.

Próximo passo

Siga o primeiro teste em 10 minutos. Tudo o que ele usa você cria sozinho no portal, sem falar com ninguém.