Ir para o conteúdo
Multipagamentos Consulta de Faturas

Sandbox

Crie sua conta de sandbox

Cadastro mínimo. Liberação automática, sem aprovação manual. Ambiente e documentação filtrados pelo seu perfil.

O ambiente de sandbox está no ar e atende chamada de fora, em https://sandbox.consultadefaturas.com.br, com limite de requisição na borda e aceite de termos guardado com data, hora e versão do texto. Este formulário chama a API real, e a credencial que você recebe é funcional na hora. Você recebe os dois papéis, emissor e banco, mais um bloco de documentos de pagador que é só seu: dá para ver a própria cobrança sair do outro lado sem depender de um segundo parceiro.

Este fluxo não passa por qualificação comercial. É separado do contato comercial da página inicial, de propósito: obrigar quem integra a passar por qualificação antes de testar quebra o pilar de onboarding rápido.

O critério é o escopo que a operação exige no contrato: emissor:* de um lado, banco:* do outro. Sem filtro, aparece tudo.

API Referências

URL base do sandbox: https://sandbox.consultadefaturas.com.br — no ar desde 24/09/2026. Toda operação abaixo pende dela, sem prefixo de versão: o caminho é o que está escrito, colado direto na URL base. O recorte abaixo dá a forma das operações; a referência completa traz corpo, respostas e esquemas de todas as catorze.

Caminho que a API não conhece devolve 404 com crf:9001, e método errado devolve 405. Esses códigos de protocolo, da família crf:90xx, não estão na tabela de erros de negócio abaixo.

  • POST /oauth/tokenA primeira chamada de qualquer integração. client_credentials no corpo, em formulário. O escopo do token vem do perfil da credencial, não é pedido pelo cliente: quem contratou um produto só recebe token sem o escopo do outro.
  • POST /faturasEnvia ou atualiza a cobrança. Reenvio da mesma cobrança atualiza a que existe em vez de criar outra.
  • GET /faturas/consultaLista as cobranças disponíveis para a instituição, paginadas por marcador de posição.
  • POST /faturas/{id}/pagamentoConfirma o pagamento, com verificação de que quem confirma recebeu aquela cobrança.
  • POST /opt-insCria e cancela o consentimento do pagador, individualmente ou em lote.
  • POST /distribuicaoO emissor decide para quais instituições distribui e por quais meios.
  • POST /webhookCadastra ou atualiza o endereço de notificação push do banco. Estado sempre completo.
  • GET /webhookDevolve o cadastro atual. Nunca devolve a chave de assinatura.
  • GET /faturas/{id}Uma cobrança pelo identificador. É a única operação que os dois perfis alcançam, cada um com o seu escopo.
  • POST /opt-ins/eliminacao-titularEliminação a pedido do titular. Anonimiza de forma irreversível e alcança todas as instituições.

Documentação de erros

Todo erro chega com código próprio e estável, pensado para ser tratado por programa. Recusa que só um humano entende obriga o integrador a interpretar texto, e texto muda.

Autenticação

  • crf:1001401 Credencial inválida. A resposta não diz qual dos dois campos está errado, de propósito.
  • crf:1002400 Requisição de token inválida. O detalhe diz qual campo.
  • crf:1003429 Muitas tentativas para este client_id. Aguarde antes de repetir.

Envio da cobrança

  • crf:1101400 Campo obrigatório ausente. Ao menos um dos dois códigos de pagamento é obrigatório.
  • crf:1102422 O valor declarado não bate com o valor contido no código. Recusa imediata.
  • crf:1104422 O código carrega valor de referência, não conferivel. Envie um com valor efetivo.
  • crf:1105400 Código de pagamento inválido. O detalhe diz o motivo.
  • crf:1106400 Documento inválido. O detalhe vem como campo: motivo.
  • crf:1107422 Competência fora do intervalo disponível. Confira a data.
  • crf:1108422 Documento do pagador válido, mas fora da lista sintética. Só ocorre em ambiente de sandbox.

Quem é quem na rede

  • crf:1203404 Banco não encontrado ou não credenciado.
  • crf:1204404 emissor_id não encontrado.

Consulta e autorização

  • crf:1202400 Cursor inválido. Use o proximo_cursor da página anterior.
  • crf:2001403 Cobrança não encontrada, ou não disponível para este token. Os dois casos dão a mesma resposta, de propósito.
  • crf:2002403 Token autenticado, mas sem o escopo que este recurso exige.

Consentimento

  • crf:1201404 Não há consentimento ativo deste pagador com esta instituição.
  • crf:3002409 Já existe consentimento ativo deste pagador com esta instituição.

Pagamento

  • crf:4001409 Pagamento já confirmado. Reenviar a mesma confirmação não duplica.
  • crf:4002422 valor_pago tem que ser exatamente o valor da cobrança.

Webhook

  • crf:1205400 webhook_url inválida. Host privado, de loopback ou link-local é recusado.

Autocadastro de sandbox

  • crf:5001400 email_corporativo inválido.
  • crf:5002400 O aceite explícito dos termos é obrigatório.
  • crf:5003429 Muitas tentativas de cadastro. Aguarde antes de repetir.

Falha da plataforma

  • crf:9999500 Erro não tratado do nosso lado. Vem com id_do_evento: é esse identificador que o suporte precisa, e nunca sai daqui detalhe de infraestrutura.

Documento repetido não é erro. Cadastrar de novo com um documento já usado devolve 201, igual a um cadastro novo — a credencial recebida, porém, não autentica. Achado de segurança: um 409 aqui revelaria, sem autenticação nenhuma, se um CNPJ/CPF (dado público) já é cliente da plataforma. Perdeu o client_secret do seu próprio cadastro? Fale com o suporte em rodrigo.melo@multipagamentos.tech — reenviar o formulário não recupera.

Os três do autocadastro só aparecem quando o cadastro self-service abrir; o código já existe no contrato. Esta é a tabela completa dos erros de negócio, não um recorte. Os de protocolo, da família crf:90xx, ficam fora dela e estão citados no começo da referência.

Notificação push

A plataforma empurra a cobrança para o banco. A consulta por marcador continua sendo a garantia, e é isso que permite ao push ser aditivo sem virar ponto único de falha.

O cadastro é estado completo, nunca remendo

Uma chamada com dois campos obrigatórios: o endereço e se está ativo. Omitir um campo é erro de contrato, nunca "mantenha o que estava". Para pausar a entrega sem perder o endereço, reenvie o mesmo endereço com o estado inativo.

O endereço é validado em toda chamada: HTTPS é obrigatório, e host privado, de loopback ou link-local é recusado. Toda alteração deixa trilha com o estado anterior e o novo.

Quando a notificação sai

  • O emissor envia uma cobrança elegível para você Vale a mesma regra de posse da consulta: você recebe o que lhe cabe.
  • A cobrança muda de forma material Reenvio idêntico do emissor não gera notificação nova.
  • O pagamento é confirmado Vai para todos os bancos elegíveis, e não só para quem confirmou, para que nenhum siga cobrando em duplicidade.

O corpo vem completo

A notificação carrega a mesma projeção da cobrança que a consulta por identificador devolveria a você. Não é um aviso que obriga a uma segunda chamada.

Como verificar a assinatura

HMAC-SHA256 sobre o timestamp, um ponto, e o corpo exato recebido. A chave é combinada fora de banda no cadastro: nunca trafega pela API, e a API não tem caminho para devolvê-la.

  • X-CRF-TimestampEpoch em segundos no instante do envio. Entra na assinatura.
  • X-CRF-Signaturesha256= seguido do hex.
  • X-CRF-Delivery-IdIdentificador da entrega, para conciliar tentativas da mesma notificação.

Compare em tempo constante e recuse timestamp fora de uma janela curta de tolerância. Sem as duas coisas, uma requisição capturada pode ser reenviada por terceiro.

Retentativa, e o que acontece quando ela esgota

A entrega tem fila própria, com recuo exponencial que se estende por cerca de 33 horas. O trabalhador roda em várias instâncias ao mesmo tempo sem entregar a mesma linha duas vezes, e uma instância que caia no meio do envio devolve aquela entrega para outra em dois minutos.

Quando as tentativas esgotam, a cobrança continua disponível na consulta e o seu marcador não retrocede. Perder uma notificação atrasa, não perde.

Guia de integração

Orientado a caso de uso, não a endpoint.

A credencial determina o que você alcança

A autenticação é por credencial de cliente: você troca o par de credenciais por um token de vida curta e o apresenta em cada chamada. Não há chave estática no código nem segredo compartilhado por canal.

Cada credencial carrega um conjunto declarado de capacidades: enviar cobrança, decidir a distribuição, consultar, gerir consentimento e envio, confirmar pagamento. Uma credencial recebe apenas as que lhe couberem, e o que ela recebe é teto: a limitação está em restrição de banco de dados, não em uma checagem que alguém pode esquecer de fazer. Uma credencial feita para enviar cobrança não alcança a distribuição. Não por convenção, por impossibilidade.

Quem você é vem do canal, nunca do conteúdo

Sua identidade é lida da credencial que autenticou a chamada. Se o corpo da requisição trouxer o identificador de outro participante, o campo é ignorado. Não existe caminho para enviar cobrança em nome de terceiro.

Na confirmação de pagamento vale o inverso da mesma regra: a plataforma verifica se quem confirma é a instituição que de fato recebeu aquela cobrança.

Reenviar é seguro, e é assim que se corrige

A mesma cobrança enviada duas vezes não se torna duas. A unicidade é uma restrição do banco de dados, e não uma verificação feita antes de gravar: a diferença aparece exatamente quando duas chamadas chegam ao mesmo tempo, que é quando a verificação prévia falha.

O reenvio enriquece, nunca sobrescreve: campo que estava vazio é preenchido, campo que já tinha valor permanece. E a resposta diz qual dos dois aconteceu.

A recusa é imediata e explicada

O valor que você declara é comparado com o valor contido no próprio código de pagamento, no momento do envio. Divergência é recusada na hora. Não existe aceitar agora e conferir depois, nem cobrança em estado pendente de conserto.

No sandbox, o documento do pagador vem de uma lista fechada

Um emissor ou banco de sandbox só consegue gravar documento que esteja numa lista sintética fechada. Não é faixa numérica: CPF não tem bloco reservado para teste, então a lista é explícita e um gatilho no banco recusa qualquer documento fora dela. Vale para o envio da cobrança e para o consentimento.

O seu cadastro devolve dez documentos que são só seus, no campo documentos_de_teste, junto com a credencial. Use esses. Só o seu emissor e o seu banco gravam neles, e a checagem é do próprio banco de dados: um documento do bloco de outro parceiro é recusado com crf:1108. Isso é controle, não recomendação.

A faixa original de 999 documentos, por índice de 0 a 998, continua existindo como demonstração compartilhada. A regra dela é a base índice + 1 em nove dígitos, mais os dois dígitos verificadores por módulo 11:

  • 000.000.001-91Índice 0, o primeiro da faixa de demonstração.
  • 000.000.002-72Índice 1.
  • 000.000.999-70Índice 998, o último da faixa.

Nesta faixa os integradores se veem. O consentimento é banco × pagador, e não existe uma terceira chave por integrador: uma cobrança criada com um destes documentos pode ser vista por outro integrador que tenha dado opt-in no mesmo pagador. É exatamente por isso que o bloco do seu cadastro existe, e é ele que você deve usar.

Um CPF que você invente com dígito verificador válido vai ser recusado, mesmo sendo formalmente correto. A recusa chega como crf:1108, com status 422 e a lista citada na mensagem: o documento é válido, o que não vale é usá-lo aqui. Não é defeito da sua integração.

Dois códigos que funcionam, para a sua primeira chamada

O valor que você declara é conferido contra o valor contido no código, e divergência é recusada na hora com crf:1102. Por isso os dois exemplos abaixo vêm com o valor que cada um carrega: copie o par, não só o código.

  • codigo_barrasR$ 42,50 — arrecadação no padrão Febraban, 44 posições. É a conta de água do simulador do projeto, e o mesmo código que a suíte usa para afirmar que um leitor real ainda o aceita.
    81690000000425010010000000000000001809202601
  • codigo_pixR$ 42,50 — BR Code estático. O valor sai do campo 54, e os quatro dígitos do fim são o CRC16 sobre todo o resto: mexer em qualquer caractere sem recalcular o CRC invalida o código.
    00020126530014br.gov.bcb.pix0131consulta-faturas@exemplo.com.br520400005303986540542.505802BR5915EMISSOR EXEMPLO6009SAO PAULO62170513AGUA2026090016304FF90

Os dois descrevem a mesma cobrança de R$ 42,50, que é como um emissor manda os dois meios numa chamada só. Trocar o valor exige gerar o código de novo: no Febraban o dígito verificador cobre as outras 43 posições, e no BR Code o CRC cobre o payload inteiro.

A leitura é contínua, e o marcador é seu

A consulta é paginada por um marcador de posição que você guarda. Retoma de onde parou, sem janela de tempo e sem reprocessar o que já leu.

A plataforma deliberadamente não mantém o controle de até onde você leu. Avançar um marcador do nosso lado no momento de entregar o dado exigiria que você confirmasse o recebimento, e sem essa confirmação seria perda silenciosa apresentada como garantia.

Cobrança recém-enviada pode não aparecer ainda

Entre o envio e a cobrança aparecer nesta consulta há um horizonte de 15 segundos. Não é atraso de rede: o identificador de ordenação vem de uma sequência que não é transacional, e esse horizonte é o que impede a consulta de pular uma cobrança que ainda está sendo gravada.

Se você enviar e consultar logo em seguida, receber uma lista vazia por alguns segundos é esperado — não é falha do ambiente. Espere o horizonte passar antes de concluir que a cobrança não chegou.

O que ainda não existe, e você vai perguntar

  • Não há arquivo em lote nem canais legados A notificação push existe e está descrita acima. Arquivo em lote e canais legados seguem fora do escopo.
  • A credencial de sandbox não alcança webhook nem distribuição O formulário concede escopo mínimo: quem entra como banco recebe banco:consulta, banco:optin e banco:pagamento, e quem entra como emissor recebe emissor:ingestao. Ficam de fora banco:webhook, porque notificação push exige cadastro de URL e chave HMAC à parte, e emissor:distribuicao, porque distribuir é decisão comercial e não algo que um formulário público conceda sozinho. As duas operações estão descritas nesta página e no contrato: chamá-las com a credencial do formulário devolve crf:2002. Para testá-las, fale com o suporte.
  • Nada disso opera com dado de pessoa real A plataforma opera exclusivamente com dado sintético, e no sandbox isso deixou de ser combinação verbal: um gatilho no banco recusa documento que não esteja na lista sintética fechada, e a recusa chega com código próprio: crf:1108, status 422.

Depois do sandbox

Pronto para produção? O acesso é liberado com atendimento.

Credencial de produção, certificado e liberação de acesso passam por identificação formal e contrato. Não são autoatendimento.

  1. 01Emissão de credencial de produção
  2. 02Certificado e homologação de assinatura
  3. 03Liberação de acesso ao ambiente

Fale conosco para liberar produção