Documentação
API de boleto
Basehttps://api.apisimples.com/v1
Visão geral
A API de boleto cadastra carteiras bancárias do emitente com as credenciais e os dados de conta/convênio exigidos por cada banco. PIX e boleto compartilham a tabela carteiras, separados pelo campo tipo.
/boleto/bancosLista os bancos com integração de boleto e os campos exigidos./boleto/carteirasLista as carteiras de boleto do emitente./boleto/carteirasCadastra uma carteira de boleto./boleto/carteiras/{id}Consulta uma carteira pelo id./boleto/carteiras/{id}Atualiza nome, banco, autenticação ou conta./boleto/carteiras/{id}/ativarAtiva a carteira./boleto/carteiras/{id}/inativarInativa a carteira./boleto/carteiras/{id}/excluirExclui a carteira.As rotas de emissão de boleto entram na sequência. Nesta etapa a API organiza o cadastro e a validação das carteiras por banco.
Testar
Cole a chave do emitente e envie a requisição nesta página. A chave fica neste navegador e segue somente para a API, no header Authorization.
Autenticação
Todas as rotas exigem a chave do emitente no header Authorization: Bearer …. A chave fica em Emitentes no painel.
Habilitação
O emitente precisa ter doc_boleto = 1. Sem isso a API responde HTTP 403 com boleto_desabilitado.
Listar bancos
https://api.apisimples.com/v1/boleto/bancosDevolve os bancos com integração de boleto, os campos de autenticacao e, quando houver, o schema de conta.
curl https://api.apisimples.com/v1/boleto/bancos \
-H "Authorization: Bearer apse_sua_chave_do_emitente" \
-H "Accept: application/json"{
"bancos": [
{
"codigo": "001",
"nome": "Banco do Brasil",
"campos": [
"client_id",
"client_secret",
"id_aplicacao"
],
"opcionais": [],
"rotulos": {
"client_id": "Client ID",
"client_secret": "Client secret",
"id_aplicacao": "ID da aplicação",
"convenio": "Convênio",
"carteira": "Carteira de cobrança",
"variacao_carteira": "Variação da carteira",
"codigo_modalidade": "Código da modalidade"
},
"conta": {
"obrigatorios": [
"convenio",
"carteira",
"variacao_carteira"
],
"opcionais": [
"codigo_modalidade"
],
"campos": [
"convenio",
"carteira",
"variacao_carteira",
"codigo_modalidade"
]
}
},
{
"codigo": "033",
"nome": "Santander",
"campos": [
"client_id",
"client_secret",
"certificado_chave_publica",
"certificado_chave_privada"
],
"opcionais": [],
"rotulos": {
"client_id": "Client ID",
"client_secret": "Client secret",
"certificado_chave_publica": "Certificado (.pem / .cer)",
"certificado_chave_privada": "Chave privada (.key)",
"convenio": "Convênio"
},
"conta": {
"obrigatorios": [
"convenio"
],
"opcionais": [],
"campos": [
"convenio"
]
}
},
{
"codigo": "077",
"nome": "Inter",
"campos": [
"client_id",
"client_secret",
"certificado_chave_publica",
"certificado_chave_privada"
],
"opcionais": [],
"rotulos": {
"client_id": "Client ID",
"client_secret": "Client secret",
"certificado_chave_publica": "Certificado (.pem / .cer)",
"certificado_chave_privada": "Chave privada (.key)"
},
"conta": null
},
{
"codigo": "341",
"nome": "Itaú",
"campos": [
"client_id",
"client_secret",
"certificado_chave_publica",
"certificado_chave_privada"
],
"opcionais": [],
"rotulos": {
"client_id": "Client ID",
"client_secret": "Client secret",
"certificado_chave_publica": "Certificado (.pem / .cer)",
"certificado_chave_privada": "Chave privada (.key)",
"carteira": "Carteira de cobrança",
"numero_agencia": "Número da agência",
"numero_conta_corrente": "Número da conta corrente"
},
"conta": {
"obrigatorios": [
"numero_agencia",
"numero_conta_corrente",
"carteira"
],
"opcionais": [],
"campos": [
"numero_agencia",
"numero_conta_corrente",
"carteira"
]
}
},
{
"codigo": "364",
"nome": "Efí",
"campos": [
"client_id",
"client_secret"
],
"opcionais": [],
"rotulos": {
"client_id": "Client ID",
"client_secret": "Client secret"
},
"conta": null
},
{
"codigo": "461",
"nome": "Asaas",
"campos": [
"client_secret"
],
"opcionais": [],
"rotulos": {
"client_secret": "Client secret"
},
"conta": null
},
{
"codigo": "748",
"nome": "Sicredi",
"campos": [
"client_id",
"client_secret"
],
"opcionais": [],
"rotulos": {
"client_id": "Client ID",
"client_secret": "Client secret",
"numero_agencia": "Número da agência",
"codigo_beneficiario": "Código do beneficiário",
"numero_posto": "Número do posto"
},
"conta": {
"obrigatorios": [
"numero_agencia",
"codigo_beneficiario",
"numero_posto"
],
"opcionais": [],
"campos": [
"numero_agencia",
"codigo_beneficiario",
"numero_posto"
]
}
},
{
"codigo": "756",
"nome": "Sicoob",
"campos": [
"client_id",
"certificado_chave_publica",
"certificado_chave_privada"
],
"opcionais": [],
"rotulos": {
"client_id": "Client ID",
"certificado_chave_publica": "Certificado (.pem / .cer)",
"certificado_chave_privada": "Chave privada (.key)",
"codigo_modalidade": "Código da modalidade",
"numero_conta_corrente": "Número da conta corrente",
"numero_cliente": "Número do cliente / beneficiário",
"numero_contrato_cobranca": "Número do contrato de cobrança"
},
"conta": {
"obrigatorios": [
"numero_cliente",
"numero_conta_corrente",
"codigo_modalidade"
],
"opcionais": [
"numero_contrato_cobranca"
],
"campos": [
"numero_cliente",
"numero_conta_corrente",
"codigo_modalidade",
"numero_contrato_cobranca"
]
}
}
]
}Listar carteiras
https://api.apisimples.com/v1/boleto/carteirasLista só as carteiras com tipo = boleto do emitente autenticado.
Criar
https://api.apisimples.com/v1/boleto/carteirasHTTP 201 devolve a carteira criada. Certificados em base64. Segredos voltam mascarados. O objeto conta fica em autenticacao_extra e reaparece na resposta quando completo.
{
"nome": "Cobrança BB",
"codigo_banco": "001",
"autenticacao": {
"client_id": "seu-client-id",
"client_secret": "seu-client-secret",
"id_aplicacao": "d27b477108ffabf2136be18d80050f56b9a1a5b6"
},
"conta": {
"convenio": "1234567",
"carteira": "17",
"variacao_carteira": "19",
"codigo_modalidade": "1"
}
}{
"nome": "Cobrança Sicoob",
"codigo_banco": "756",
"autenticacao": {
"client_id": "seu-client-id",
"certificado_chave_publica": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tXG5NSUlCXG4tLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0t",
"certificado_chave_privada": "LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tXG5NSUlFXG4tLS0tLUVORCBQUklWQVRFIEtFWS0tLS0t"
},
"conta": {
"numero_cliente": "123456",
"numero_conta_corrente": "12345678",
"codigo_modalidade": "1"
}
}{
"nome": "Cobrança Asaas",
"codigo_banco": "461",
"autenticacao": {
"client_secret": "seu-client-secret"
}
}curl -X POST https://api.apisimples.com/v1/boleto/carteiras \
-H "Authorization: Bearer apse_sua_chave_do_emitente" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"nome": "Cobrança BB",
"codigo_banco": "001",
"autenticacao": {
"client_id": "seu-client-id",
"client_secret": "seu-client-secret",
"id_aplicacao": "d27b477108ffabf2136be18d80050f56b9a1a5b6"
},
"conta": {
"convenio": "1234567",
"carteira": "17",
"variacao_carteira": "19",
"codigo_modalidade": "1"
}
}'Consultar
https://api.apisimples.com/v1/boleto/carteiras/{id}Consulta uma carteira de boleto pelo UUID. Se não for deste emitente ou for PIX, a resposta é HTTP 404.
Atualizar
https://api.apisimples.com/v1/boleto/carteiras/{id}Atualização parcial: envie só o que mudou. Em branco, os segredos e certificados atuais são mantidos. Campos de conta enviados se misturam com os já gravados.
Ativar / inativar
https://api.apisimples.com/v1/boleto/carteiras/{id}/ativarhttps://api.apisimples.com/v1/boleto/carteiras/{id}/inativar
Excluir carteira
https://api.apisimples.com/v1/boleto/carteiras/{id}/excluirPayload da carteira
Corpo usado em POST /boleto/carteiras e, em parte, em POST /boleto/carteiras/{id}.
Campos do payload
Apelido da carteira no seu sistema.
Até 80 caracteres.
Código do banco da integração de boleto.
Aceita com ou sem zeros à esquerda (001 ou 1).
- 001 — Banco do Brasil
- 033 — Santander
- 077 — Inter
- 341 — Itaú
- 364 — Efí
- 461 — Asaas
- 748 — Sicredi
- 756 — Sicoob
Credenciais exigidas pelo banco escolhido. Os campos mudam conforme codigo_banco.
Veja a seção Campos por banco.
Dados da conta, convênio ou carteira de cobrança. Obrigatório nos bancos que listam o objeto conta.
Veja conta.obrigatorios em GET /boleto/bancos.
Nenhum campo corresponde à busca.
Campos por banco
Use GET /boleto/bancos para a lista atualizada. Abaixo, o detalhe por instituição.
001 — Banco do Brasil
Campos do payload
Identificador OAuth do aplicativo cadastrado no banco.
Segredo OAuth do aplicativo. Na resposta aparece mascarado.
Identificador da aplicação no Banco do Brasil (developer application key / gw-dev-app-key).
Número do convênio bancário.
Código da carteira de cobrança / carteira do documento.
Variação da carteira de cobrança.
Código da modalidade de cobrança.
Nenhum campo corresponde à busca.
{
"nome": "Cobrança Banco do Brasil",
"codigo_banco": "001",
"autenticacao": {
"client_id": "seu-client-id",
"client_secret": "seu-client-secret",
"id_aplicacao": "d27b477108ffabf2136be18d80050f56b9a1a5b6"
},
"conta": {
"convenio": "123456",
"carteira": "17",
"variacao_carteira": "19",
"codigo_modalidade": "1"
}
}033 — Santander
Campos do payload
Identificador OAuth do aplicativo cadastrado no banco.
Segredo OAuth do aplicativo. Na resposta aparece mascarado.
Certificado do portal (.pem ou .cer) em base64.
Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.
Chave privada (.key) do mesmo certificado em base64.
Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.
Número do convênio bancário.
Nenhum campo corresponde à busca.
{
"nome": "Cobrança Santander",
"codigo_banco": "033",
"autenticacao": {
"client_id": "seu-client-id",
"client_secret": "seu-client-secret",
"certificado_chave_publica": "conteudo-do-certificado-em-base64",
"certificado_chave_privada": "conteudo-do-certificado-em-base64"
},
"conta": {
"convenio": "123456"
}
}077 — Inter
Campos do payload
Identificador OAuth do aplicativo cadastrado no banco.
Segredo OAuth do aplicativo. Na resposta aparece mascarado.
Certificado do portal (.pem ou .cer) em base64.
Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.
Chave privada (.key) do mesmo certificado em base64.
Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.
Nenhum campo corresponde à busca.
{
"nome": "Cobrança Inter",
"codigo_banco": "077",
"autenticacao": {
"client_id": "seu-client-id",
"client_secret": "seu-client-secret",
"certificado_chave_publica": "conteudo-do-certificado-em-base64",
"certificado_chave_privada": "conteudo-do-certificado-em-base64"
}
}341 — Itaú
Campos do payload
Identificador OAuth do aplicativo cadastrado no banco.
Segredo OAuth do aplicativo. Na resposta aparece mascarado.
Certificado do portal (.pem ou .cer) em base64.
Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.
Chave privada (.key) do mesmo certificado em base64.
Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.
Número da agência ou cooperativa.
Número da conta corrente onde será creditada a liquidação.
Código da carteira de cobrança / carteira do documento.
Nenhum campo corresponde à busca.
{
"nome": "Cobrança Itaú",
"codigo_banco": "341",
"autenticacao": {
"client_id": "seu-client-id",
"client_secret": "seu-client-secret",
"certificado_chave_publica": "conteudo-do-certificado-em-base64",
"certificado_chave_privada": "conteudo-do-certificado-em-base64"
},
"conta": {
"numero_agencia": "123456",
"numero_conta_corrente": "123456",
"carteira": "17"
}
}364 — Efí
Campos do payload
Identificador OAuth do aplicativo cadastrado no banco.
Segredo OAuth do aplicativo. Na resposta aparece mascarado.
Nenhum campo corresponde à busca.
{
"nome": "Cobrança Efí",
"codigo_banco": "364",
"autenticacao": {
"client_id": "seu-client-id",
"client_secret": "seu-client-secret"
}
}461 — Asaas
Campos do payload
Segredo OAuth do aplicativo. Na resposta aparece mascarado.
Nenhum campo corresponde à busca.
{
"nome": "Cobrança Asaas",
"codigo_banco": "461",
"autenticacao": {
"client_secret": "seu-client-secret"
}
}748 — Sicredi
Campos do payload
Identificador OAuth do aplicativo cadastrado no banco.
Segredo OAuth do aplicativo. Na resposta aparece mascarado.
Número da agência ou cooperativa.
Código do beneficiário no Sicredi.
Número do posto no Sicredi.
Nenhum campo corresponde à busca.
{
"nome": "Cobrança Sicredi",
"codigo_banco": "748",
"autenticacao": {
"client_id": "seu-client-id",
"client_secret": "seu-client-secret"
},
"conta": {
"numero_agencia": "123456",
"codigo_beneficiario": "123456",
"numero_posto": "123456"
}
}756 — Sicoob
Campos do payload
Identificador OAuth do aplicativo cadastrado no banco.
Certificado do portal (.pem ou .cer) em base64.
Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.
Chave privada (.key) do mesmo certificado em base64.
Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.
Código do beneficiário na cooperativa Sicoob.
Número da conta corrente onde será creditada a liquidação.
Código da modalidade de cobrança.
Número do contrato de cobrança quando o beneficiário possui mais de um contrato.
Nenhum campo corresponde à busca.
{
"nome": "Cobrança Sicoob",
"codigo_banco": "756",
"autenticacao": {
"client_id": "seu-client-id",
"certificado_chave_publica": "conteudo-do-certificado-em-base64",
"certificado_chave_privada": "conteudo-do-certificado-em-base64"
},
"conta": {
"numero_cliente": "123456",
"numero_conta_corrente": "123456",
"codigo_modalidade": "1",
"numero_contrato_cobranca": "123456"
}
}Formato da resposta
A resposta completa inclui autenticacao mascarada e, no boleto, o objeto conta quando cadastrado.
{
"id": "8f3c2a10-6b4e-4d2a-9c11-2e5a7b9d0f31",
"tipo": "boleto",
"codigo_banco": "001",
"banco": "Banco do Brasil",
"nome": "Cobrança BB",
"status": "ativa",
"autenticacao": {
"client_id": "seu-****",
"client_secret": "***",
"id_aplicacao": "d27b****"
},
"conta": {
"convenio": "1234567",
"carteira": "17",
"variacao_carteira": "19",
"codigo_modalidade": "1"
}
}Erros
Erros de validação vêm com HTTP 422 e a lista erros no formato campo + mensagem (ex.: conta.convenio).