Fluxo de Boleto

Este guia descreve o ciclo de vida completo de um boleto na plataforma FluxiQ NPC, desde a criacao ate a liquidacao final.

Visao Geral

O diagrama abaixo ilustra os estados de um boleto ao longo do seu ciclo de vida:

┌─────────────────────────────────────────────────────────────────────────────┐
│                         Ciclo de Vida do Boleto                             │
└─────────────────────────────────────────────────────────────────────────────┘

    ┌─────────┐      ┌────────────┐      ┌────────┐      ┌──────────┐
    │  DRAFT  │─────▶│ REGISTERED │─────▶│  PAID  │─────▶│ SETTLED  │
    └─────────┘      └────────────┘      └────────┘      └──────────┘
         │                 │
         │                 │
         ▼                 ▼
    ┌───────────────────────┐
    │      CANCELLED        │
    └───────────────────────┘

    Status:
    - DRAFT      : Boleto criado, aguardando registro
    - REGISTERED : Registrado na Nuclea (PCR)
    - PAID       : Pagamento confirmado
    - SETTLED    : Liquidado (fundos creditados)
    - CANCELLED  : Cancelado

Passo 1: Criar Boleto

O primeiro passo e criar o boleto na API. O boleto sera automaticamente registrado na Nuclea (PCR).

cURLJavaScriptPython

bash

curl -X POST "https://api.pixconnect.com.br/api/v1/central/boletos" \
  -H "X-API-Key: pk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "boleto": {
      "nosso_numero": "12345678901",
      "amount_cents": 15000,
      "due_date": "2026-03-15",
      "payer_document": "12345678901",
      "payer_name": "Joao Silva Santos",
      "beneficiary_ispb": "02992335",
      "beneficiary_name": "Empresa XYZ Ltda"
    }
  }'

javascript

async function createBoleto() {
  const response = await fetch(
    "https://api.pixconnect.com.br/api/v1/central/boletos",
    {
      method: "POST",
      headers: {
        "X-API-Key": "pk_live_abc123def456",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        boleto: {
          nosso_numero: "12345678901",
          amount_cents: 15000,
          due_date: "2026-03-15",
          payer_document: "12345678901",
          payer_name: "Joao Silva Santos",
          beneficiary_ispb: "02992335",
          beneficiary_name: "Empresa XYZ Ltda"
        }
      }),
    }
  );

  const data = await response.json();

  if (data.success) {
    console.log("Boleto criado:", data.data.nosso_numero);
    console.log("Codigo de barras:", data.data.barcode);
    console.log("Linha digitavel:", data.data.linha_digitavel);
  }

  return data;
}

python

import requests

def create_boleto():
    url = "https://api.pixconnect.com.br/api/v1/central/boletos"
    headers = {
        "X-API-Key": "pk_live_abc123def456",
        "Content-Type": "application/json"
    }
    payload = {
        "boleto": {
            "nosso_numero": "12345678901",
            "amount_cents": 15000,
            "due_date": "2026-03-15",
            "payer_document": "12345678901",
            "payer_name": "Joao Silva Santos",
            "beneficiary_ispb": "02992335",
            "beneficiary_name": "Empresa XYZ Ltda"
        }
    }

    response = requests.post(url, headers=headers, json=payload)
    data = response.json()

    if data.get("success"):
        print(f"Boleto criado: {data['data']['nosso_numero']}")
        print(f"Codigo de barras: {data['data']['barcode']}")
        print(f"Linha digitavel: {data['data']['linha_digitavel']}")

    return data

Resposta esperada:

json

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "nosso_numero": "12345678901",
    "barcode": "23793381286000000000000000012345678901500001",
    "linha_digitavel": "23793.38128 60000.000003 00001.234567 8 90150000015000",
    "amount_cents": 15000,
    "due_date": "2026-03-15",
    "status": "registered",
    "pcr_protocol": "PCR2026021512345678"
  }
}

Passo 2: Aguardar Registro

Apos a criacao, o boleto e automaticamente registrado na Nuclea. Voce pode acompanhar isso de duas formas:

Opcao A: Webhook (Recomendado)

Configure um endpoint para receber o evento boleto_registered:

javascript

// Seu servidor (exemplo com Express.js)
app.post("/webhooks/pixconnect", async (req, res) => {
  const { event, data } = req.body;

  // Valide a assinatura primeiro (veja documentacao de Webhooks)
  if (!validateSignature(req)) {
    return res.status(401).json({ error: "Assinatura invalida" });
  }

  if (event === "boleto_registered") {
    console.log("Boleto registrado:", data.nosso_numero);
    console.log("Protocolo PCR:", data.pcr_protocol);

    // Atualizar seu banco de dados
    await updateBoletoStatus(data.nosso_numero, "registered", {
      pcr_protocol: data.pcr_protocol,
      registered_at: data.registered_at
    });
  }

  res.status(200).json({ received: true });
});

Opcao B: Polling

Se nao puder usar webhooks, consulte periodicamente o status:

javascript

async function waitForRegistration(nossoNumero, maxAttempts = 10) {
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.pixconnect.com.br/api/v1/central/boletos/${nossoNumero}`,
      {
        headers: {
          "X-API-Key": "pk_live_abc123def456",
          "Content-Type": "application/json",
        },
      }
    );

    const data = await response.json();

    if (data.data.status === "registered") {
      console.log("Boleto registrado com sucesso!");
      return data.data;
    }

    // Aguardar 2 segundos antes da proxima tentativa
    await new Promise(resolve => setTimeout(resolve, 2000));
  }

  throw new Error("Timeout aguardando registro do boleto");
}

Uso do Polling

O polling consome mais recursos da API. Use webhooks sempre que possivel. Se usar polling, respeite os rate limits.

Passo 3: Exibir Boleto ao Cliente

Com o boleto registrado, exiba as informacoes de pagamento ao cliente:

javascript

function displayBoleto(boleto) {
  return {
    // Codigo de barras (44 digitos - para leitura por scanner)
    barcode: boleto.barcode,

    // Linha digitavel (47 digitos formatados - para digitacao manual)
    linhaDigitavel: boleto.linha_digitavel,

    // Valor formatado
    valor: (boleto.amount_cents / 100).toLocaleString("pt-BR", {
      style: "currency",
      currency: "BRL"
    }),

    // Data de vencimento formatada
    vencimento: new Date(boleto.due_date).toLocaleDateString("pt-BR"),

    // Beneficiario
    beneficiario: boleto.beneficiary_name
  };
}

// Exemplo de uso
const boletoDisplay = displayBoleto(boleto);
// {
//   barcode: "23793381286000000000000000012345678901500001",
//   linhaDigitavel: "23793.38128 60000.000003 00001.234567 8 90150000015000",
//   valor: "R$ 150,00",
//   vencimento: "15/03/2026",
//   beneficiario: "Empresa XYZ Ltda"
// }

Geracao de PDF

Para gerar um PDF do boleto, inclua os seguintes elementos:

Codigo de barras: Use uma biblioteca de codigo de barras para gerar a imagem
Linha digitavel: Exiba de forma legivel para digitacao
Dados do beneficiario: Nome, CNPJ/CPF, endereco
Dados do pagador: Nome, CPF/CNPJ
Valor e vencimento: Claramente visiveis
Instrucoes: Informacoes para o caixa

Passo 4: Receber Notificacao de Pagamento

Quando o cliente paga o boleto, voce recebera o webhook boleto_paid:

javascript

app.post("/webhooks/pixconnect", async (req, res) => {
  const { event, data } = req.body;

  if (!validateSignature(req)) {
    return res.status(401).json({ error: "Assinatura invalida" });
  }

  switch (event) {
    case "boleto_paid":
      console.log("Pagamento recebido!");
      console.log("Nosso numero:", data.nosso_numero);
      console.log("Valor pago:", data.valor_pago / 100);
      console.log("Data pagamento:", data.data_pagamento);

      // Atualizar status no seu sistema
      await updateBoletoStatus(data.nosso_numero, "paid", {
        valor_pago: data.valor_pago,
        data_pagamento: data.data_pagamento,
        canal_pagamento: data.canal_pagamento,
        settlement_id: data.settlement_id
      });

      // Liberar servico/produto para o cliente
      await fulfillOrder(data.nosso_numero);

      // Enviar email de confirmacao
      await sendPaymentConfirmation(data.nosso_numero);
      break;

    // ... outros eventos
  }

  res.status(200).json({ received: true });
});

Payload do evento boleto_paid:

json

{
  "event": "boleto_paid",
  "timestamp": "2026-02-04T09:15:00Z",
  "data": {
    "nosso_numero": "12345678901",
    "valor_original": 15000,
    "valor_pago": 15000,
    "valor_desconto": 0,
    "valor_juros": 0,
    "valor_multa": 0,
    "data_pagamento": "2026-02-04",
    "data_credito": "2026-02-05",
    "canal_pagamento": "internet_banking",
    "settlement_id": "stl_abc123def456"
  }
}

Passo 5: Reconciliacao na Liquidacao

O ciclo se completa com a liquidacao, quando os fundos sao efetivamente creditados:

javascript

app.post("/webhooks/pixconnect", async (req, res) => {
  const { event, data } = req.body;

  if (!validateSignature(req)) {
    return res.status(401).json({ error: "Assinatura invalida" });
  }

  switch (event) {
    case "settlement_completed":
      console.log("Ciclo de liquidacao concluido!");
      console.log("ID:", data.settlement_id);
      console.log("Total boletos:", data.total_boletos);
      console.log("Total valor:", data.total_valor / 100);

      // Atualizar contabilidade
      await updateAccountingRecords(data);

      // Gerar relatorio do ciclo
      await generateSettlementReport(data);
      break;

    case "payment_received":
      // Confirmacao individual de cada pagamento no ciclo
      console.log("Pagamento liquidado:", data.nosso_numero);
      console.log("Valor:", data.valor_pago / 100);

      // Marcar como liquidado
      await updateBoletoStatus(data.nosso_numero, "settled", {
        data_credito: data.data_credito
      });
      break;
  }

  res.status(200).json({ received: true });
});

Tratamento de Erros

Falha no Registro

Se o boleto falhar no registro na Nuclea, voce pode receber um evento de erro:

javascript

app.post("/webhooks/pixconnect", async (req, res) => {
  const { event, data } = req.body;

  if (event === "boleto_registration_failed") {
    console.error("Falha no registro:", data.nosso_numero);
    console.error("Motivo:", data.error_code, data.error_message);

    // Notificar equipe de suporte
    await alertSupport({
      type: "registration_failed",
      boleto: data.nosso_numero,
      error: data.error_message
    });

    // Tentar novamente ou cancelar
    if (isRetryable(data.error_code)) {
      await retryRegistration(data.nosso_numero);
    } else {
      await cancelBoleto(data.nosso_numero);
    }
  }

  res.status(200).json({ received: true });
});

function isRetryable(errorCode) {
  const retryableCodes = ["TIMEOUT", "SERVICE_UNAVAILABLE", "RATE_LIMITED"];
  return retryableCodes.includes(errorCode);
}

Boleto Vencido

Trate boletos que venceram sem pagamento:

javascript

// Verificacao diaria de boletos vencidos
async function checkExpiredBoletos() {
  const hoje = new Date().toISOString().split("T")[0];

  const response = await fetch(
    `https://api.pixconnect.com.br/api/v1/central/boletos?status=registered&due_date_lt=${hoje}`,
    {
      headers: {
        "X-API-Key": "pk_live_abc123def456",
        "Content-Type": "application/json",
      },
    }
  );

  const { data: boletos } = await response.json();

  for (const boleto of boletos) {
    console.log("Boleto vencido:", boleto.nosso_numero);

    // Verificar politica de negocio
    const diasVencido = daysSince(boleto.due_date);

    if (diasVencido > 30) {
      // Cancelar apos 30 dias
      await cancelBoleto(boleto.nosso_numero);
      await notifyCustomerCancelled(boleto);
    } else if (diasVencido > 7) {
      // Lembrete apos 7 dias
      await sendPaymentReminder(boleto);
    }
  }
}

function daysSince(dateString) {
  const date = new Date(dateString);
  const now = new Date();
  return Math.floor((now - date) / (1000 * 60 * 60 * 24));
}

Diagrama de Sequencia

┌────────┐          ┌────────────┐          ┌────────┐          ┌────────┐
│ Cliente│          │  Sua API   │          │ FluxiQ NPC│         │ Nuclea │
└───┬────┘          └─────┬──────┘          └────┬────┘          └───┬────┘
    │                     │                      │                   │
    │  1. Solicita boleto │                      │                   │
    │────────────────────▶│                      │                   │
    │                     │                      │                   │
    │                     │  2. POST /boletos    │                   │
    │                     │─────────────────────▶│                   │
    │                     │                      │                   │
    │                     │                      │  3. Registra PCR  │
    │                     │                      │──────────────────▶│
    │                     │                      │                   │
    │                     │                      │  4. Confirmacao   │
    │                     │                      │◀──────────────────│
    │                     │                      │                   │
    │                     │  5. 201 Created      │                   │
    │                     │◀─────────────────────│                   │
    │                     │  (barcode, linha)    │                   │
    │                     │                      │                   │
    │  6. Exibe boleto    │                      │                   │
    │◀────────────────────│                      │                   │
    │                     │                      │                   │
    │  7. Paga boleto     │                      │                   │
    │────────────────────────────────────────────────────────────────▶
    │                     │                      │                   │
    │                     │                      │  8. Pagamento     │
    │                     │                      │◀──────────────────│
    │                     │                      │                   │
    │                     │  9. Webhook          │                   │
    │                     │     boleto_paid      │                   │
    │                     │◀─────────────────────│                   │
    │                     │                      │                   │
    │  10. Confirma       │                      │                   │
    │      pagamento      │                      │                   │
    │◀────────────────────│                      │                   │
    │                     │                      │                   │
    │                     │  11. Webhook         │                   │
    │                     │      settlement_     │                   │
    │                     │      completed       │                   │
    │                     │◀─────────────────────│                   │
    │                     │                      │                   │
└───┴────┘          └─────┴──────┘          └────┴────┘          └───┴────┘

Checklist de Integracao

Use este checklist para validar sua integracao:

Criacao de Boleto

[ ] Gerar nosso_numero unico (11 digitos)
[ ] Enviar valor em centavos (amount_cents)
[ ] Formatar data de vencimento (YYYY-MM-DD)
[ ] Validar CPF/CNPJ do pagador
[ ] Configurar ISPB do beneficiario corretamente

Webhooks

[ ] Endpoint HTTPS configurado
[ ] Validacao de assinatura HMAC implementada
[ ] Handler para boleto_registered
[ ] Handler para boleto_paid
[ ] Handler para settlement_completed
[ ] Retorno 200 OK em ate 30 segundos

Exibicao

[ ] Codigo de barras legivel (scanner)
[ ] Linha digitavel formatada corretamente
[ ] Valor e vencimento visiveis
[ ] Dados do beneficiario exibidos

Tratamento de Erros

[ ] Handler para falhas de registro
[ ] Verificacao de boletos vencidos
[ ] Logs para depuracao
[ ] Alertas para equipe de suporte

Reconciliacao

[ ] Acompanhamento de status
[ ] Registro de pagamentos
[ ] Integracao com contabilidade
[ ] Relatorios de liquidacao

Proximos Passos

Fluxo de Liquidacao - Entenda o processo de liquidacao
Eventos de Webhook - Referencia completa de eventos
API de Boletos - Referencia da API

Fluxo de Boleto ​

Visao Geral ​

Passo 1: Criar Boleto ​

Passo 2: Aguardar Registro ​

Opcao A: Webhook (Recomendado) ​

Opcao B: Polling ​

Passo 3: Exibir Boleto ao Cliente ​

Geracao de PDF ​

Passo 4: Receber Notificacao de Pagamento ​

Passo 5: Reconciliacao na Liquidacao ​

Tratamento de Erros ​

Falha no Registro ​

Boleto Vencido ​

Diagrama de Sequencia ​

Checklist de Integracao ​

Criacao de Boleto ​

Webhooks ​

Exibicao ​

Tratamento de Erros ​

Reconciliacao ​

Proximos Passos ​

Fluxo de Boleto

Visao Geral

Passo 1: Criar Boleto

Passo 2: Aguardar Registro

Opcao A: Webhook (Recomendado)

Opcao B: Polling

Passo 3: Exibir Boleto ao Cliente

Geracao de PDF

Passo 4: Receber Notificacao de Pagamento

Passo 5: Reconciliacao na Liquidacao

Tratamento de Erros

Falha no Registro

Boleto Vencido

Diagrama de Sequencia

Checklist de Integracao

Criacao de Boleto

Webhooks

Exibicao

Tratamento de Erros

Reconciliacao

Proximos Passos