Boletos — emissão e gestão via API

Documentação dos endpoints públicos da API Vexa Pagamentos para emitir boletos de cobrança, consultar status, cancelar e sincronizar. Para pagar um boleto de terceiro com saldo, use Pagar boleto.

Visão geral

Todos os endpoints desta seção usam o mesmo fluxo de autenticação dos demais recursos da API v1: obtenha um access_token em POST /api/v1/oauth e envie nas requisições o header Authorization: Bearer <token>.

Base URL (produção): https://api.vexapagamentos.com.br

Taxa de emissão: a emissão debita a taxa configurada para sua conta na carteira em BRL. É necessário saldo suficiente antes de criar um novo boleto.

Emitir boleto

POST /api/v1/boleto

Gera o título via ONZ e retorna linha digitável, código de barras e URL do PDF (quando disponível).

Corpo (JSON)

Campos do boleto

  • valor — obrigatório, número ≥ 1,00
  • vencimento — obrigatório, data em YYYY-MM-DD ou ISO (entre 1 e 30 dias a partir de hoje)
  • descricao — obrigatório
  • instrucoes — opcional
  • external_id — opcional, até 191 caracteres; referência sua para idempotência (mesmo valor na mesma credencial retorna o boleto já existente)

Objeto pagador (obrigatório)

  • nome_completo — mínimo 3 caracteres
  • email
  • cpf_cnpj — CPF ou CNPJ (com ou sem máscara)
  • telefone
  • Endereço opcional: cep, endereco, numero, complemento, bairro, cidade, estado
{
  "external_id": "PEDIDO-2026-001",
  "valor": 150.5,
  "vencimento": "2026-12-31",
  "descricao": "Mensalidade abril",
  "instrucoes": "Não receber após o vencimento",
  "pagador": {
    "nome_completo": "Maria Silva",
    "email": "pagador@email.com",
    "cpf_cnpj": "123.456.789-00",
    "telefone": "11999998888",
    "cep": "01310100",
    "endereco": "Av. Paulista",
    "numero": "1000",
    "bairro": "Bela Vista",
    "cidade": "São Paulo",
    "estado": "SP"
  }
}

Resposta (200)

{
  "statusCode": 200,
  "message": "Boleto gerado com sucesso",
  "idempotent": false,
  "data": {
    "id": 1,
    "uuid": "…",
    "nosso_numero": "…",
    "numero_titulo_beneficiario_bb": "…",
    "numero_titulo_bb": "…",
    "external_id": "PEDIDO-2026-001",
    "codigo_barras": "…",
    "linha_digitavel": "…",
    "pdf_url": "https://…",
    "qr_code_pix": "…",
    "valor": 150.5,
    "vencimento": "2026-12-31"
  }
}

Em reenvio com o mesmo external_id, a API pode retornar idempotent: true e a mensagem indicando boleto já existente.

Listagem de Boletos

GET /api/v1/boletos

Retorna todos os boletos emitidos pela mesma credencial de API (integração externa). Não há parâmetros de query; a lista reflete apenas títulos criados via POST /api/v1/boleto para essa credencial.

Resposta (200)

{
  "statusCode": 200,
  "message": "Boletos listados com sucesso",
  "data": [
    {
      "uuid": "…",
      "nosso_numero": "…",
      "numero_titulo_beneficiario_bb": "…",
      "numero_titulo_bb": "…",
      "external_id": "PEDIDO-2026-001",
      "status": "PENDING",
      "valor": 150.5,
      "vencimento": "2026-12-31",
      "descricao": "Mensalidade abril",
      "instrucoes": "Não receber após o vencimento",
      "codigo_barras": "…",
      "linha_digitavel": "…",
      "pdf_url": "https://…",
      "qr_code_pix": "…",
      "data_pagamento": null,
      "valor_pago": null,
      "pagador": {
        "nome": "Maria Silva",
        "email": "pagador@email.com",
        "cpf_cnpj": "12345678900"
      },
      "created_at": "2026-04-01T12:00:00.000Z",
      "updated_at": "2026-04-01T12:00:00.000Z"
    }
  ]
}

data é um array; sem boletos via API, vem []. Cada item segue o mesmo formato de Consultar boleto.

Consultar boleto

GET /api/v1/boleto/:nossoNumero

O parâmetro :nossoNumero pode ser o valor retornado em nosso_numero, numero_titulo_beneficiario_bb ou numero_titulo_bb.

Resposta (200)

{
  "statusCode": 200,
  "message": "Boleto encontrado",
  "data": {
    "uuid": "…",
    "nosso_numero": "…",
    "numero_titulo_beneficiario_bb": "…",
    "numero_titulo_bb": "…",
    "external_id": "PEDIDO-2026-001",
    "status": "PENDING",
    "valor": 150.5,
    "vencimento": "2026-12-31",
    "descricao": "Mensalidade abril",
    "instrucoes": "Não receber após o vencimento",
    "codigo_barras": "…",
    "linha_digitavel": "…",
    "pdf_url": "https://…",
    "qr_code_pix": "…",
    "data_pagamento": null,
    "valor_pago": null,
    "pagador": {
      "nome": "Maria Silva",
      "email": "pagador@email.com",
      "cpf_cnpj": "12345678900"
    },
    "created_at": "2026-04-01T12:00:00.000Z",
    "updated_at": "2026-04-01T12:00:00.000Z"
  }
}

Quando liquidado, data_pagamento e valor_pago vêm preenchidos.

Cancelar boleto

POST /api/v1/boleto/:nossoNumero/cancel

Cancela boleto pendente no provedor e no sistema. Podem aplicar-se taxas conforme a regra da plataforma.

Sincronizar status com o provedor

POST /api/v1/boleto/:nossoNumero/sync-status

Consulta a situação da cobrança na ONZ e atualiza o registro local — útil se o webhook de liquidação não tiver sido recebido.

Exemplo cURL (emissão)

curl -X POST https://api.vexapagamentos.com.br/api/v1/boleto \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "valor": 150.5,
    "vencimento": "2026-12-31",
    "descricao": "Mensalidade",
    "pagador": {
      "nome_completo": "Maria Silva",
      "email": "pagador@email.com",
      "cpf_cnpj": "12345678900",
      "telefone": "11999998888"
    }
  }'

Webhooks

Após a emissão bem-sucedida, a plataforma pode disparar o evento boleto.created para sua URL de webhook configurada. Detalhes de assinatura e boas práticas estão na documentação de Webhooks.