Como integrar

Visão geral

O Boleto OnLine registra o boleto direto na API do banco — suporta todos os bancos credenciados (lista logo abaixo) pelo mesmo motor (hoje validado em produção com Santander e Itaú) — não existe arquivo de remessa/CNAB nem processamento em lote. Toda operação é síncrona: a chamada à API já volta com o resultado (código de barras, linha digitável, ou o erro real que o banco recusou). O ciclo de vida de um boleto tem quatro fases (a última é opcional):

Bancos credenciados

O Boleto OnLine não trabalha só com um banco — o motor de registro suporta todos os bancos abaixo, pelo mesmo mecanismo (só muda o valor de banco.TipoCobranca na configuração da conta). O número não é o código FEBRABAN do banco.

Validado = a EXATA já rodou o fluxo inteiro (emitir → registrar → pagar → webhook) em produção com esse banco. Os demais são suportados pelo mesmo motor de registro, mas ainda não foram validados aqui — dependem de credencial/homologação junto ao banco.

Como um boleto é criado

POST /api/accounts/{account}/bankslips (aba Emitir boleto) envia os dados do título (valor, vencimento, sacado) direto para a API do banco — o Nosso Número é gerado pelo Boleto OnLine, não é informado por quem chama. Cada conta tem a sua sequência: a emissão usa o Nosso número atual da conta + 1. Esse valor fica na configuração da conta (aba Cedente) e pode ser ajustado, por exemplo para continuar a numeração de um sistema anterior ou para separar faixas quando outro sistema ainda emite na mesma conta. Ele não pode ficar abaixo do maior nosso número já emitido na conta. Emissão recusada não consome número: o próximo boleto reaproveita o número que falhou. O banco valida, registra e devolve na hora o código de barras e a linha digitável — não há espera nem processamento assíncrono. Se o banco recusar (dado inválido, limite, etc.), o erro real dele volta na resposta, com o campo recusado quando o banco informa.

Verificação automática de pagamento (o Boleto OnLine faz por você)

O banco não avisa quando um boleto é pago — não existe webhook/callback do lado do banco. Mas você não precisa ficar consultando: o próprio Boleto OnLine roda um verificador periódico interno, contra todas as contas configuradas, e já marca cada título como pago no seu histórico assim que detecta.

Toda rodada do verificador (a cada 15 minutos) fica registrada na tela Verificação de Pagamentos — inclusive quando não encontra nada de novo. É como você confirma que o monitoramento está ativo, e recebe um alerta (e-mail/WhatsApp) se ele parar de funcionar por 3 rodadas seguidas (cerca de 45 minutos).

Duas formas de saber que um boleto foi pago:

O corpo, a assinatura e o passo a passo de validação estão na aba Webhook.

Aviso de vencimento do certificado

Quando o certificado vence, a emissão de boletos daquela conta fica interrompida até um novo certificado ser enviado. Por isso o Boleto OnLine avisa automaticamente por e-mail (email_notificacao) e/ou WhatsApp (whatsapp_notificacao) — os dois canais, se os dois estiverem preenchidos.

O aviso não sai todo dia: só nos marcos de 30, 15, 7 e 1 dia antes do vencimento, e depois disso todo dia enquanto o certificado continuar vencido (a emissão continua interrompida até você trocar). A urgência da mensagem escala conforme o prazo (Aviso → URGENTE no dia anterior/no dia → CRÍTICO depois de vencido).

Na tela Configurar conta, ao lado de cada campo (e-mail e WhatsApp) tem um botão "Testar aviso" — dispara o mesmo texto oficial na hora, sem precisar esperar o certificado vencer de verdade nem o verificador automático rodar.

Enviar o boleto direto ao cliente (opcional)

Além de devolver o link na resposta da emissão, o Boleto OnLine pode entregar o boleto sozinho por e-mail e/ou WhatsApp direto ao cliente final (Sacado) — desligado por padrão, precisa ligar por conta.

Dois passos, os dois na tela Configurar conta, seção "Notificar cliente ao emitir boleto":

Botões "Testar e-mail" / "Testar WhatsApp" disparam um envio real com dados de exemplo (sem precisar emitir um boleto de verdade) — pedem o destino na hora, não usam o e-mail/WhatsApp de aviso de certificado.

Como autenticar

Toda requisição vai para https://boleto.seacweb.com.br/api/..., com o token do seu cliente (tenant) no cabeçalho Authorization e o corpo (quando houver) em JSON. O token é único por cliente/integração e nunca deve ser compartilhado.

POST /api/accounts/{account}/bankslips HTTP/1.1
Host: boleto.seacweb.com.br
Authorization: Bearer <SEU_TOKEN_AQUI>
Content-Type: application/json

{ ... }

Toda resposta segue o mesmo envelope, sucesso ou erro:

{
  "status": "success",
  "message": "descrição legível do resultado",
  "data": { ... }
}

Sem token, com token inválido ou de um cliente diferente, a resposta é sempre HTTP 401. Novo cliente/integração: solicite o token ao administrador da plataforma (onboarding manual).

Configurar uma conta bancária

POST /api/accounts — chamado uma vez (ou sempre que a credencial/certificado mudar). Pode ser feito por aqui (tela Configurar conta) ou via API, útil para integrações que provisionam contas automaticamente.

{
  "account": "santander",
  "bank": { "code": 2 },
  "webservice": { "environment": 0, "version": "V1" },
  "company": {
    "tax_id_type": 1,
    "tax_id": "01183645000170",
    "name": "MINHA EMPRESA LTDA",
    "address": {
      "street": "RUA TESTE", "number": "100", "district": "CENTRO",
      "city": "CASIMIRO DE ABREU", "state": "RJ", "zip_code": "28860000"
    },
    "agency": "3190", "agency_digit": "5",
    "account": "9860193", "account_digit": "1",
    "agreement": "9860193",
    "modality": "101"
  },
  "credentials": { "client_id": "...", "client_secret": "...", "scope": "" },
  "certificate": {
    "crt": "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----",
    "key": "-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----"
  },
  "notification_email": "financeiro@meucliente.com.br",
  "notification_whatsapp": "+5511999999999"
}

Emitir / registrar um boleto

POST /api/accounts/{account}/bankslips

{
  "reference": "ST0001",
  "value": 150.00,
  "due_date": "2026-12-31",
  "payer": {
    "name": "CLIENTE TESTE",
    "document": "11144477735",
    "address": {
      "street": "RUA TESTE", "number": "100", "district": "CENTRO",
      "city": "CASIMIRO DE ABREU", "state": "RJ", "zip_code": "28860000"
    }
  },
  "notify": { "email": "cliente@exemplo.com.br", "whatsapp": "+5511999999999" }
}

Resposta (sucesso, HTTP 201):

{
  "status": "success",
  "message": "Boleto created successfully.",
  "data": {
    "our_number": "00000042",
    "reference": "ST0001",
    "barcode": "...",
    "digitable_line": "...",
    "due_date": "2026-12-31",
    "link": "https://boleto.seacweb.com.br/boleto_view.php?id=42&sig=..."
  }
}

Alterar o vencimento de um boleto em aberto

PATCH /api/accounts/{account}/bankslips/{our_number} — corpo JSON com due_date (yyyy-mm-dd), obrigatório. O restante do título (pagador, referência) é mantido como foi emitido.

PATCH /api/accounts/santander/bankslips/00000042

{ "due_date": "2026-10-15" }

Resposta (sucesso) — mesmo formato de "Emitir boleto":

{
  "status": "success",
  "message": "Bankslip updated successfully!",
  "data": { "our_number": "00000042", "barcode": "...", "digitable_line": "...", "due_date": "2026-10-15", "link": "..." }
}

Cancelar (dar baixa em) um boleto já emitido

POST /api/accounts/{account}/bankslips/cancel/{our_number} — sem corpo (o resto dos dados da baixa já vem da própria configuração da conta, confirmado no fonte do conector do banco).

POST /api/accounts/santander/bankslips/cancel/00000042

Resposta (sucesso) — mesmo formato de "Emitir boleto":

{
  "status": "success",
  "message": "Boleto cancel has been requested successfully!",
  "data": { "our_number": "00000042", "barcode": null, "digitable_line": null }
}

Consultar boletos pagos (baixas)

GET /api/accounts/{account}/bankslips?paid_from=&paid_to= — uso típico: consultar periodicamente para processar as baixas dos boletos já pagos.

GET /api/accounts/santander/bankslips?paid_from=2026-07-01&paid_to=2026-08-25

Resposta:

{
  "status": "success",
  "message": "Paid bankslips retrieved successfully!",
  "data": {
    "total": 1,
    "bankslips": [
      {
        "our_number": "00000042",
        "reference": "ST0001",
        "value": 150.00,
        "paid_value": 150.00,
        "due_date": "2026-12-31",
        "paid_at": "2026-08-20",
        "payer_name": "CLIENTE TESTE",
        "payer_document": "11144477735"
      }
    ]
  }
}

O que é

Quando o verificador automático (ver aba Como funciona) detecta que um boleto foi pago, o Boleto OnLine faz um POST para a webhook_url cadastrada naquela conta (tela Configurar conta). Sem webhook_url, nada é enviado — você consulta quando quiser.

O contrato segue o mesmo padrão do resto da API: envelope { event, sent_at, data }, campos snake_case em inglês, valores monetários como número e datas em yyyy-mm-dd.

Formato

POST /seu-endpoint HTTP/1.1
Content-Type: application/json
X-Webhook-Signature: sha256=<HMAC-SHA256 hex do corpo cru>
Authorization: Bearer <token do destino>   (opcional -- ver abaixo)

{
  "event": "bankslip.paid",
  "sent_at": "2026-08-28T02:00:00+00:00",
  "data": {
    "account": "santander",
    "reference": "ST0001",
    "our_number": "00000001",
    "value": 150.00,
    "paid_value": 150.00,
    "interest": 0.00,
    "discount": 0.00,
    "due_date": "2026-12-31",
    "paid_at": "2026-12-20",
    "credit_date": "2026-12-21",
    "payer_name": "FULANO DE TAL"
  }
}

Validar a assinatura

O header X-Webhook-Signature é sha256= + o HMAC-SHA256 (hex) do corpo cru recebido. Recalcule e compare com igualdade em tempo constante:

$corpo   = file_get_contents('php://input');
$esperado = 'sha256=' . hash_hmac('sha256', $corpo, $SEGREDO);
if (!hash_equals($esperado, $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}
$payload = json_decode($corpo, true);

Entrega e retentativa

Régua de cobrança

Com a régua ligada, o Boleto OnLine avisa o próprio sacado por e-mail (e WhatsApp, opcional) em marcos configuráveis antes e depois do vencimento, sempre com o link de pagamento. É opcional, por conta, e roda junto com o verificador de pagamentos (a cada 15 minutos).

Cobrar na hora

POST /api/accounts/{account}/bankslips/remind/{our_number} — dispara o lembrete imediatamente para um boleto em aberto (independe dos marcos). Corpo opcional { "channels": ["email","whatsapp"] }; sem ele, usa os canais da conta. No painel: Boletos Emitidos → menu da linha → "Cobrar agora".

POST /api/accounts/santander/bankslips/remind/00000042

{ "channels": ["email"] }

{
  "status": "success",
  "message": "Reminder sent successfully!",
  "data": { "sent_channels": 1, "detail": "" }
}

O acompanhamento (lembretes enviados, taxa de recuperação) aparece no Dashboard, seção Cobrança.

{
  "status": "error",
  "message": "descrição do problema",
  "data": null
}