Conta Bancária na API

Conta Bancária

A conta bancária é o elemento central da integração com a API Boleto Cloud. Ela representa o vínculo entre sua aplicação e o banco onde os boletos serão registrados e liquidados.

O Papel da Conta Bancária

Quando você cadastra uma conta bancária no Boleto Cloud, ela armazena:

Informação	Descrição
Dados bancários	Banco, agência, número da conta, dígito verificador
Carteira de cobrança	Tipo de carteira e suas configurações específicas
Dados do beneficiário	Razão social, CNPJ/CPF, endereço completo
Configurações padrão	Multa, juros, instruções de cobrança, mensagens
Credenciais de registro	Certificados e chaves para comunicação com o banco

Benefício da centralização

Ao centralizar esses dados na conta, você não precisa informá-los em cada requisição. Basta enviar o token da conta e todos os dados são aplicados automaticamente ao boleto.

---

Token da Conta (boleto.conta.token)

O token é a credencial de acesso que identifica unicamente a conta bancária na API. Ele é o único campo obrigatório relacionado à conta na criação de boletos.

Campo	Tipo	Obrigatório	Exemplo
boleto.conta.token	string	Sim	"api-key_OmeuWUHYZTRIuo1MjFW3Xi7Ej88dF5TX5BRwP4iptRw="

Exemplo de Uso

curl -X POST "https://sandbox.boletocloud.com/api/v1/boletos" \
  -u "api-key_SUA-API-KEY:token" \
  -d "boleto.conta.token=api-key_OmeuWUHYZTRIuo1MjFW3Xi7Ej88dF5TX5BRwP4iptRw=" \
  -d "boleto.emissao=2024-01-15" \
  -d "boleto.vencimento=2024-02-15" \
  # ... demais campos do boleto

Token vs API Key

Não confunda o token da conta com a API Key:

• API Key: Autentica sua aplicação na API (usada no header Authorization)
• Token da Conta: Identifica qual conta bancária será usada para gerar o boleto

---

Como Gerar o Token da Conta

Para criar o token de uma conta bancária para acesso à API, siga o caminho no painel do Boleto Cloud:

1. Acesse Conta no menu principal
2. Clique em Consultar
3. Clique no nome da conta desejada
4. Clique em Editar dados
5. Clique no botão “Gerar Token”

Segurança do Token

O token da conta é uma credencial sensível. Nunca compartilhe ou exponha o token em código-fonte público, repositórios ou logs. Trate-o com o mesmo cuidado de uma senha.

---

Múltiplas Contas Bancárias

Você pode cadastrar múltiplas contas bancárias no Boleto Cloud e usar tokens diferentes conforme a necessidade:

Cenário	Uso
Filiais diferentes	Cada filial com sua própria conta e CNPJ
Bancos diferentes	Diversificar entre bancos para contingência
Carteiras diferentes	Separar cobrança simples de cobrança registrada
Produtos diferentes	Contas específicas para cada linha de produto
Multi-tenant (SaaS)	Cada cliente com suas próprias contas e personalizações

Múltiplos CNPJs e Beneficiários

A Boleto Cloud suporta cenários com múltiplos beneficiários e CNPJs diferentes em uma única conta de usuário:

• Sua empresa possui uma conta de login (usuário) na plataforma
• Dentro dessa conta, você cadastra seus clientes como Beneficiários
• Cada Beneficiário pode ter uma ou mais contas bancárias
• Cada conta bancária possui seu próprio token para uso via API
• Cada conta conta com personalização independente de mensagens, instruções e imagens

Arquitetura multi-tenant

Essa estrutura permite construir soluções multi-tenant onde cada cliente (beneficiário) tem suas próprias contas bancárias e personalizações, tudo gerenciado via API com tokens distintos.

Exemplo: Selecionando a Conta por Filial

# Tokens das contas por filial
CONTAS = {
    'matriz': 'api-key_TOKEN_MATRIZ...',
    'filial_sp': 'api-key_TOKEN_FILIAL_SP...',
    'filial_rj': 'api-key_TOKEN_FILIAL_RJ...',
}

def criar_boleto(filial, dados_boleto):
    dados_boleto['boleto.conta.token'] = CONTAS[filial]
    # ... enviar requisição

---

Dados Herdados da Conta

Quando você cria um boleto usando o token da conta, os seguintes dados são herdados automaticamente:

Dados do Beneficiário

O beneficiário (quem recebe o pagamento) é obtido do cadastro da conta:

• Razão social / Nome
• CNPJ / CPF
• Endereço completo

Nota

Esses dados aparecem impressos no boleto na seção “Beneficiário” e não podem ser alterados por requisição.

Configurações de Cobrança Padrão

Se não informados na requisição, são utilizados os valores cadastrados na conta:

Configuração	Campo que sobrescreve
Multa	boleto.multa
Juros	boleto.juros
Instruções	boleto.instrucao ou boleto.instrucao1 a boleto.instrucao5
Mensagens	boleto.informacao1 a boleto.informacao8

Flexibilidade

Você pode sobrescrever qualquer configuração padrão enviando o campo correspondente na requisição. Isso permite personalizar boletos específicos sem alterar o cadastro da conta.

---

Validação da Conta

Ao enviar uma requisição com boleto.conta.token, a API valida:

Validação	Erro se falhar
Token existe	404 Not Found
Token está ativo	403 Forbidden
Conta está configurada corretamente	400 Bad Request
Conta suporta o banco solicitado	400 Bad Request

---

Ambientes: Sandbox vs Produção

Os ambientes Sandbox e Produção são completamente independentes e não compartilham dados entre si:

Ambiente	URL Base	Finalidade
Sandbox	sandbox.boletocloud.com	Desenvolvimento e testes
Produção	app.boletocloud.com	Operação real com clientes

Independência Total dos Ambientes

Aspecto	Comportamento
Cadastros	Beneficiários, contas bancárias e pagadores de um ambiente não existem no outro
Tokens	Tokens do Sandbox não funcionam em Produção (e vice-versa)
API Keys	Cada ambiente possui suas próprias credenciais de acesso
Dados	Boletos criados no Sandbox não aparecem em Produção

Replicação manual necessária

Se você configurou uma conta bancária no Sandbox, após validar os testes, precisará replicar manualmente a configuração no ambiente de Produção.

Limitações do Sandbox

O ambiente Sandbox não suporta:

• Integração online via API/Webservices bancários
• Conexão via VAN (Value Added Network)
• Registro automático de boletos no banco

O que você pode fazer no Sandbox

Mesmo sem registro online, o Sandbox permite exportar arquivos CNAB de remessa manualmente. Você pode usar esse arquivo para validar no sistema do banco, se necessário. Alternativamente, pode deixar essa validação para a Produção, já que os ambientes são independentes.

Estratégia Recomendada

Para evitar retrabalho, siga esta sequência:

1. Desenvolva no Sandbox - Teste toda a lógica de integração
2. Valide os fluxos - Confirme que boletos, carnês e arquivos CNAB estão corretos
3. Replique em Produção - Cadastre beneficiários e contas bancárias
4. Faça a homologação - Execute o fluxo completo com dados reais

Dica

O registro online (API bancária) e integrações avançadas só estão disponíveis no plano personalizado em ambiente de Produção.

---

Veja Também

Bancos Suportados Lista de bancos disponíveis para registro

Criar Boleto Referência completa de criação de boletos

Campos do Boleto Todos os campos disponíveis na requisição

Autenticação Como autenticar requisições na API