Boletos

Em desenvolvimento

Este módulo ainda não está disponível na API. A documentação abaixo é uma prévia da funcionalidade planejada.

Emissão, consulta e cancelamento de boletos bancários registrados.

Endpoints

Método	Endpoint	Descrição	Permissão
POST	`/baas/api/v1/boletos`	Emitir boleto	`BAAS_BOLETOS_CREATE`
GET	`/baas/api/v1/boletos`	Listar boletos	`BAAS_BOLETOS_READ`
GET	`/baas/api/v1/boletos/:id`	Obter boleto por ID	`BAAS_BOLETOS_READ`
POST	`/baas/api/v1/boletos/:id/cancel`	Cancelar boleto	`BAAS_BOLETOS_CANCEL`

Atributos

Campo	Tipo	Descrição
`accountId`	string (UUID)	ID da conta emissora
`amount`	number	Valor do boleto
`status`	enum	Status: `PENDING`, `REGISTERED`, `PAID`, `OVERDUE`, `CANCELED`
`dueDate`	date	Data de vencimento (YYYY-MM-DD)
`payer`	object	Dados do pagador
`barcode`	string	Código de barras (gerado pelo provedor)
`digitableLine`	string	Linha digitável (gerada pelo provedor)
`description`	string	Descrição do boleto
`fine`	object	Configuração de multa
`interest`	object	Configuração de juros
`discount`	object	Configuração de desconto
`paidAmount`	number	Valor pago (quando aplicável)
`paidAt`	datetime	Data do pagamento
`externalRef`	string	Referência no provedor bancário
`createdAt`	datetime	Data de criação
`updatedAt`	datetime	Data da última atualização

Estrutura do Pagador (payer)

Campo	Tipo	Descrição
`name`	string	Nome do pagador
`document`	string	CPF/CNPJ
`documentType`	enum	`CPF` ou `CNPJ`
`email`	string	E-mail
`address`	object	Endereço (street, number, city, state, zipCode, country)

Estrutura de Multa (fine)

Campo	Tipo	Descrição
`type`	enum	`PERCENTAGE` ou `FIXED`
`value`	number	Valor da multa (% ou R$)
`daysAfterDue`	integer	Dias após vencimento para aplicar

Estrutura de Juros (interest)

Campo	Tipo	Descrição
`type`	enum	`DAILY_PERCENTAGE` ou `MONTHLY_PERCENTAGE`
`value`	number	Valor dos juros (%)

Estrutura de Desconto (discount)

Campo	Tipo	Descrição
`type`	enum	`PERCENTAGE` ou `FIXED`
`value`	number	Valor do desconto (% ou R$)
`daysBeforeDue`	integer	Dias antes do vencimento para aplicar

Emitir Boleto

POST /baas/api/v1/boletos

Emite um novo boleto bancário registrado.

Atributos

Campo	Tipo	Obrigatório	Descrição
`accountId`	string	Sim	ID da conta emissora
`amount`	number	Sim	Valor do boleto
`dueDate`	date	Sim	Data de vencimento
`payer`	object	Sim	Dados do pagador
`description`	string	Não	Descrição
`fine`	object	Não	Configuração de multa
`interest`	object	Não	Configuração de juros
`discount`	object	Não	Configuração de desconto

cURL
JavaScript

curl -X POST 'https://baas.stg.catalisa.app/baas/api/v1/boletos' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "boletos",
      "attributes": {
        "accountId": "550e8400-e29b-41d4-a716-446655440100",
        "amount": 1200.00,
        "dueDate": "2024-02-15",
        "description": "Mensalidade fevereiro/2024",
        "payer": {
          "name": "João Silva",
          "document": "123.456.789-00",
          "documentType": "CPF",
          "email": "joao@email.com",
          "address": {
            "street": "Rua das Flores",
            "number": "100",
            "city": "São Paulo",
            "state": "SP",
            "zipCode": "01234-567",
            "country": "Brasil"
          }
        },
        "fine": {
          "type": "PERCENTAGE",
          "value": 2.0,
          "daysAfterDue": 1
        },
        "interest": {
          "type": "MONTHLY_PERCENTAGE",
          "value": 1.0
        },
        "discount": {
          "type": "PERCENTAGE",
          "value": 5.0,
          "daysBeforeDue": 10
        }
      }
    }
  }'

const response = await fetch('https://baas.stg.catalisa.app/baas/api/v1/boletos', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'boletos',
      attributes: {
        accountId: '550e8400-e29b-41d4-a716-446655440100',
        amount: 1200.00,
        dueDate: '2024-02-15',
        description: 'Mensalidade fevereiro/2024',
        payer: {
          name: 'João Silva',
          document: '123.456.789-00',
          documentType: 'CPF',
          email: 'joao@email.com',
          address: {
            street: 'Rua das Flores',
            number: '100',
            city: 'São Paulo',
            state: 'SP',
            zipCode: '01234-567',
            country: 'Brasil',
          },
        },
        fine: {
          type: 'PERCENTAGE',
          value: 2.0,
          daysAfterDue: 1,
        },
        interest: {
          type: 'MONTHLY_PERCENTAGE',
          value: 1.0,
        },
        discount: {
          type: 'PERCENTAGE',
          value: 5.0,
          daysBeforeDue: 10,
        },
      },
    },
  }),
});

const { data } = await response.json();
console.log(`Boleto emitido: ${data.id}`);
console.log(`Código de barras: ${data.attributes.barcode}`);
console.log(`Linha digitável: ${data.attributes.digitableLine}`);

Response (201 Created)

{
  "data": {
    "type": "boletos",
    "id": "550e8400-e29b-41d4-a716-446655440400",
    "links": {
      "self": "/baas/api/v1/boletos/550e8400-e29b-41d4-a716-446655440400"
    },
    "attributes": {
      "accountId": "550e8400-e29b-41d4-a716-446655440100",
      "amount": 1200.00,
      "status": "PENDING",
      "dueDate": "2024-02-15",
      "description": "Mensalidade fevereiro/2024",
      "payer": {
        "name": "João Silva",
        "document": "123.456.789-00",
        "documentType": "CPF",
        "email": "joao@email.com"
      },
      "barcode": null,
      "digitableLine": null,
      "fine": {
        "type": "PERCENTAGE",
        "value": 2.0,
        "daysAfterDue": 1
      },
      "interest": {
        "type": "MONTHLY_PERCENTAGE",
        "value": 1.0
      },
      "discount": {
        "type": "PERCENTAGE",
        "value": 5.0,
        "daysBeforeDue": 10
      },
      "paidAmount": null,
      "paidAt": null,
      "externalRef": null,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  },
  "links": {
    "self": "/baas/api/v1/boletos/550e8400-e29b-41d4-a716-446655440400"
  }
}

Listar Boletos

GET /baas/api/v1/boletos

Lista boletos com suporte a paginação e filtros.

Query Parameters

Parâmetro	Tipo	Descrição
`page[number]`	integer	Número da página
`page[size]`	integer	Itens por página
`filter[accountId]`	UUID	Filtrar por conta emissora
`filter[status]`	enum	Filtrar por status
`filter[dueDateFrom]`	date	Vencimento a partir de (YYYY-MM-DD)
`filter[dueDateTo]`	date	Vencimento até (YYYY-MM-DD)

cURL
JavaScript

curl 'https://baas.stg.catalisa.app/baas/api/v1/boletos?filter[accountId]=550e8400-e29b-41d4-a716-446655440100&filter[status]=REGISTERED&page[size]=20' \
  -H 'Authorization: Bearer SEU_TOKEN'

const params = new URLSearchParams({
  'filter[accountId]': '550e8400-e29b-41d4-a716-446655440100',
  'filter[status]': 'REGISTERED',
  'page[size]': '20',
});

const response = await fetch(`https://baas.stg.catalisa.app/baas/api/v1/boletos?${params}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data, meta } = await response.json();
console.log(`Total de boletos: ${meta.totalItems}`);

Obter Boleto por ID

GET /baas/api/v1/boletos/:id

Obtém os detalhes de um boleto específico.

cURL
JavaScript

curl 'https://baas.stg.catalisa.app/baas/api/v1/boletos/550e8400-e29b-41d4-a716-446655440400' \
  -H 'Authorization: Bearer SEU_TOKEN'

const boletoId = '550e8400-e29b-41d4-a716-446655440400';

const response = await fetch(`https://baas.stg.catalisa.app/baas/api/v1/boletos/${boletoId}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(`Valor: R$ ${data.attributes.amount.toFixed(2)}`);
console.log(`Vencimento: ${data.attributes.dueDate}`);
console.log(`Status: ${data.attributes.status}`);
console.log(`Linha digitável: ${data.attributes.digitableLine}`);

Cancelar Boleto

POST /baas/api/v1/boletos/:id/cancel

Cancela um boleto. Apenas boletos com status PENDING ou REGISTERED podem ser cancelados.

cURL
JavaScript

curl -X POST 'https://baas.stg.catalisa.app/baas/api/v1/boletos/550e8400-e29b-41d4-a716-446655440400/cancel' \
  -H 'Authorization: Bearer SEU_TOKEN'

const boletoId = '550e8400-e29b-41d4-a716-446655440400';

const response = await fetch(`https://baas.stg.catalisa.app/baas/api/v1/boletos/${boletoId}/cancel`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(`Status: ${data.attributes.status}`); // CANCELED

Response (200 OK)

{
  "data": {
    "type": "boletos",
    "id": "550e8400-e29b-41d4-a716-446655440400",
    "attributes": {
      "status": "CANCELED",
      "updatedAt": "2024-01-16T09:00:00Z"
    }
  }
}

Erros Comuns

Código	Erro	Descrição
400	`VALIDATION`	Dados inválidos (valor, vencimento, pagador, etc.)
404	`NOT_FOUND`	Boleto ou conta não encontrada
409	`CONFLICT`	Boleto já pago ou cancelado (cancelamento)
409	`CONFLICT`	Conta não está ativa
422	`UNPROCESSABLE`	Data de vencimento no passado

Endpoints​

Atributos​

Estrutura do Pagador (payer)​

Estrutura de Multa (fine)​

Estrutura de Juros (interest)​

Estrutura de Desconto (discount)​

Emitir Boleto​

Atributos​

Response (201 Created)​

Listar Boletos​

Query Parameters​

Obter Boleto por ID​

Cancelar Boleto​

Response (200 OK)​

Erros Comuns​

Endpoints

Atributos

Estrutura do Pagador (payer)

Estrutura de Multa (fine)

Estrutura de Juros (interest)

Estrutura de Desconto (discount)

Emitir Boleto

Atributos

Response (201 Created)

Listar Boletos

Query Parameters

Obter Boleto por ID

Cancelar Boleto

Response (200 OK)

Erros Comuns