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.

GET/boleto/bancosLista os bancos com integração de boleto e os campos exigidos.
GET/boleto/carteirasLista as carteiras de boleto do emitente.
POST/boleto/carteirasCadastra uma carteira de boleto.
GET/boleto/carteiras/{id}Consulta uma carteira pelo id.
POST/boleto/carteiras/{id}Atualiza nome, banco, autenticação ou conta.
POST/boleto/carteiras/{id}/ativarAtiva a carteira.
POST/boleto/carteiras/{id}/inativarInativa a carteira.
POST/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.

GEThttps://api.apisimples.com/v1/boleto/bancos

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

GEThttps://api.apisimples.com/v1/boleto/bancos

Devolve 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"

Listar carteiras

GEThttps://api.apisimples.com/v1/boleto/carteiras

Lista só as carteiras com tipo = boleto do emitente autenticado.

Criar

POSThttps://api.apisimples.com/v1/boleto/carteiras

HTTP 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"
    }
}

Consultar

GEThttps://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

POSThttps://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

POSThttps://api.apisimples.com/v1/boleto/carteiras/{id}/ativar
POSThttps://api.apisimples.com/v1/boleto/carteiras/{id}/inativar

Excluir carteira

POSThttps://api.apisimples.com/v1/boleto/carteiras/{id}/excluir

Payload da carteira

Corpo usado em POST /boleto/carteiras e, em parte, em POST /boleto/carteiras/{id}.

Campos do payload

CampoDescrição
nome
stringopcional

Apelido da carteira no seu sistema.

Até 80 caracteres.

codigo_banco
stringobrigatório

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
autenticacao
objectobrigatório

Credenciais exigidas pelo banco escolhido. Os campos mudam conforme codigo_banco.

Veja a seção Campos por banco.

conta
objectcondicional

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.

Campos por banco

Use GET /boleto/bancos para a lista atualizada. Abaixo, o detalhe por instituição.

001 — Banco do Brasil

Campos do payload

CampoDescrição
autenticacao.client_id
stringobrigatório

Identificador OAuth do aplicativo cadastrado no banco.

autenticacao.client_secret
stringobrigatório

Segredo OAuth do aplicativo. Na resposta aparece mascarado.

autenticacao.id_aplicacao
stringobrigatório

Identificador da aplicação no Banco do Brasil (developer application key / gw-dev-app-key).

conta.convenio
stringobrigatório

Número do convênio bancário.

conta.carteira
stringobrigatório

Código da carteira de cobrança / carteira do documento.

conta.variacao_carteira
stringobrigatório

Variação da carteira de cobrança.

conta.codigo_modalidade
stringopcional

Código da modalidade de cobrança.

{
    "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

CampoDescrição
autenticacao.client_id
stringobrigatório

Identificador OAuth do aplicativo cadastrado no banco.

autenticacao.client_secret
stringobrigatório

Segredo OAuth do aplicativo. Na resposta aparece mascarado.

autenticacao.certificado_chave_publica
string (base64)obrigatório

Certificado do portal (.pem ou .cer) em base64.

Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.

autenticacao.certificado_chave_privada
string (base64)obrigatório

Chave privada (.key) do mesmo certificado em base64.

Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.

conta.convenio
stringobrigatório

Número do convênio bancário.

{
    "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

CampoDescrição
autenticacao.client_id
stringobrigatório

Identificador OAuth do aplicativo cadastrado no banco.

autenticacao.client_secret
stringobrigatório

Segredo OAuth do aplicativo. Na resposta aparece mascarado.

autenticacao.certificado_chave_publica
string (base64)obrigatório

Certificado do portal (.pem ou .cer) em base64.

Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.

autenticacao.certificado_chave_privada
string (base64)obrigatório

Chave privada (.key) do mesmo certificado em base64.

Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.

{
    "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

CampoDescrição
autenticacao.client_id
stringobrigatório

Identificador OAuth do aplicativo cadastrado no banco.

autenticacao.client_secret
stringobrigatório

Segredo OAuth do aplicativo. Na resposta aparece mascarado.

autenticacao.certificado_chave_publica
string (base64)obrigatório

Certificado do portal (.pem ou .cer) em base64.

Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.

autenticacao.certificado_chave_privada
string (base64)obrigatório

Chave privada (.key) do mesmo certificado em base64.

Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.

conta.numero_agencia
stringobrigatório

Número da agência ou cooperativa.

conta.numero_conta_corrente
stringobrigatório

Número da conta corrente onde será creditada a liquidação.

conta.carteira
stringobrigatório

Código da carteira de cobrança / carteira do documento.

{
    "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

CampoDescrição
autenticacao.client_id
stringobrigatório

Identificador OAuth do aplicativo cadastrado no banco.

autenticacao.client_secret
stringobrigatório

Segredo OAuth do aplicativo. Na resposta aparece mascarado.

{
    "nome": "Cobrança Efí",
    "codigo_banco": "364",
    "autenticacao": {
        "client_id": "seu-client-id",
        "client_secret": "seu-client-secret"
    }
}

461 — Asaas

Campos do payload

CampoDescrição
autenticacao.client_secret
stringobrigatório

Segredo OAuth do aplicativo. Na resposta aparece mascarado.

{
    "nome": "Cobrança Asaas",
    "codigo_banco": "461",
    "autenticacao": {
        "client_secret": "seu-client-secret"
    }
}

748 — Sicredi

Campos do payload

CampoDescrição
autenticacao.client_id
stringobrigatório

Identificador OAuth do aplicativo cadastrado no banco.

autenticacao.client_secret
stringobrigatório

Segredo OAuth do aplicativo. Na resposta aparece mascarado.

conta.numero_agencia
stringobrigatório

Número da agência ou cooperativa.

conta.codigo_beneficiario
stringobrigatório

Código do beneficiário no Sicredi.

conta.numero_posto
stringobrigatório

Número do posto no Sicredi.

{
    "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

CampoDescrição
autenticacao.client_id
stringobrigatório

Identificador OAuth do aplicativo cadastrado no banco.

autenticacao.certificado_chave_publica
string (base64)obrigatório

Certificado do portal (.pem ou .cer) em base64.

Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.

autenticacao.certificado_chave_privada
string (base64)obrigatório

Chave privada (.key) do mesmo certificado em base64.

Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.

conta.numero_cliente
stringobrigatório

Código do beneficiário na cooperativa Sicoob.

conta.numero_conta_corrente
stringobrigatório

Número da conta corrente onde será creditada a liquidação.

conta.codigo_modalidade
stringobrigatório

Código da modalidade de cobrança.

conta.numero_contrato_cobranca
stringopcional

Número do contrato de cobrança quando o beneficiário possui mais de um contrato.

{
    "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).