Do Sandbox para a Produção

Depois dos testes, configure a integração para emitir boletos reais pela API, usando a conta de produção que já existe ou preparando uma nova. Enquanto desenvolve, fique no sandbox.

Atenção

Enquanto sua aplicação estiver em desenvolvimento, use somente o endpoint Sandbox, em https://sandbox.boletocloud.com. Isso evita problemas como bloqueio de chamadas, inconsistência de dados e até o bloqueio total da conta na plataforma.

Confira no sandbox

Antes de apontar o sistema para produção, confira na conta de testes:

• POST /boletos responde 201, com o PDF no corpo e o header X-BoletoCloud-Token. Guarde o token do boleto.
• Cada cobrança leva um boleto.tokenControleUsuario diferente; no reenvio da mesma cobrança, mantenha o valor. Repetir o mesmo valor responde 409 com o boleto já criado. Confira o uso responsável da API e a orientação para o erro 500 em Criar boleto.
• Pagador, valor e vencimento saem certos no PDF.

No sandbox, registro online, VAN e envio automático de remessa não funcionam: nada vai ao banco automaticamente. Dá para exportar o arquivo CNAB de remessa e importá-lo no banco para validar o arquivo.

Prepare a conta de produção

Os ambientes são independentes: cadastros, API Key, token da conta e boletos de um não existem no outro. A API Key do sandbox não autentica em produção, e o token da conta de testes não aponta para a conta de produção.

Já emite em produção

Use a conta que já existe. Passar a emitir pela API não pede outra conta de usuário, outro beneficiário nem outra conta bancária. O painel continua disponível.

Começa do zero

Crie o acesso em produção e cadastre o beneficiário e a conta bancária que ainda não existem. Veja os passos em Acesso.

Beneficiário, conta bancária e as configurações de multa, juros e instruções continuam no cadastro da conta. A requisição envia o token dessa conta. Os boletos emitidos pela API aparecem no painel, em Boletos → Consultar.

Troque os três valores

Endereço, API Key e token da conta mudam juntos para os valores de produção. A API Key autentica o usuário; o token da conta escolhe a conta bancária. Ambos começam com api-key_, por isso o prefixo não distingue um do outro.

1. Endereço da API

   Troque https://sandbox.boletocloud.com/api/v1 por https://app.boletocloud.com/api/v1, o host de produção com /api/v1.

2. API Key no Authorization

   Entre em produção e consulte a API Key na área de dados do usuário, seguindo os passos de Acesso. Use a que já existe; se ainda não houver uma, gere a API Key ali.

   No HTTP Basic do header Authorization, use essa API Key como usuário. A senha continua sendo a palavra literal token.

3. Token da conta em boleto.conta.token

   No painel de produção, abra Conta → Consultar → conta → Editar dados e copie o campo do token para boleto.conta.token. Se já houver token, não gere outro: o anterior deixa de valer. Se ainda não houver, use Gerar Token uma vez.

Reutilize as credenciais existentes

Gerar outro token da conta invalida o anterior. Gerar outra API Key também invalida a anterior. Se já existirem em produção, use esses valores.

Primeiros boletos reais

Se você também emite pelo painel, combine quando as novas cobranças passam a sair pela API e emita cada cobrança por um caminho só, painel ou API.

Em produção, o boleto é cobrança real. Comece por poucos boletos, de um pagador, e confira o PDF da resposta 201 antes de seguir.

Se um boleto sair errado, baixe-o antes de enviá-lo ao pagador. Na API, a baixa (PUT /boletos/{token}/baixa) é do plano Personalizado. O 201 confirma o estado Baixado da Cobrança no Boleto Cloud. No banco, a baixa segue o canal da conta. A operação é irreversível.

No plano Personalizado, confira o registro em GET /boletos/{token}/registro antes de enviar o boleto ao pagador. Depois do 201, a comunicação com o banco segue o tipo já configurado na conta: registro online, VAN ou arquivo CNAB.

O sandbox depois da troca

O sandbox continua para testar uma mudança no sistema antes de levá-la à produção. Os dados gerados pela API podem ser vistos no painel de lá e são apagados de tempos em tempos; use-o para testes, não como armazenamento permanente. Os dados de acesso da conta do usuário permanecem.

Veja Também

Criar boletoO POST /boletos, o PDF da resposta 201 e o token do boleto.

Conta bancáriaO token da conta, a API Key e o que cada um identifica.

IdempotênciaUm token de controle por boleto e o que o 409 devolve.

Baixar boletoComo baixar um boleto emitido por engano, no plano Personalizado.