Name: Brazilian Boleto Validator API: FEBRABAN Check Digits
Brand: dam4g
SKU: api-dam4g-boletovalidatorapi
Availability: InStock
Author: API Market

Heitor Santos Maia

# Brazilian Boleto Validator API

## Overview

The Brazilian Boleto Validator API validates, parses and converts Brazilian boletos, the payment slips used for invoices, subscriptions, utility bills, taxes and government fees. It runs the official FEBRABAN check-digit algorithms, so a valid result means every check digit in the code is mathematically consistent, not just that the length is right.

Send the 44-digit barcode or the 47 or 48-digit digitable line (linha digitável), with or without dots, dashes or spaces. The API detects whether it is a bank slip or a collection boleto (utility, tax or government payment) and returns the issuing bank, amount, due date, overdue status, segment and both representations of the code.

This is mathematical validation only. The API does not contact any bank and cannot tell whether a boleto has been paid or is fraudulent.

## Features

*   **Real check-digit verification**: Validates every field and the general barcode check digit with the FEBRABAN modulo-10 and modulo-11 rules, and reports which check failed.
*   **Bank slips and collection boletos**: Handles both formats automatically, including utility, tax and government boletos with their segment (for example Sanitation).
*   **Amount and due date parsing**: Returns the amount in reais and cents, the decoded due date and whether the boleto is overdue.
*   **Barcode and digitable line conversion**: Converts in either direction and returns a formatted digitable line for display.
*   **Bank lookup**: Returns the bank name for a 3-digit COMPE code from a curated list of Brazilian banks.
*   **GET or POST**: Send the code in the query string for quick tests, or in a JSON body.

## Use Cases

*   **Billing and ERP systems**: Catch transcription errors before a boleto is stored or scheduled for payment.
*   **Bill payment apps**: Confirm a boleto is structurally valid and show the bank, amount and due date before the user pays.
*   **Reconciliation**: Extract amounts and due dates automatically instead of parsing the digits by hand.
*   **OCR and scanning**: Turn a scanned barcode into the digitable line, or the reverse, for display or lookup.
*   **Overdue tracking**: Flag overdue boletos in a billing dashboard using the overdue field.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/dam4g/boletovalidatorapi
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Validate a Boleto (GET)

Validates a boleto passed in the query string and returns its full breakdown: validity, per-field checks, errors, warnings, bank, amount, due date and both code formats. An invalid boleto still returns 200 with `valid: false` and the list of failed checks.

**Method:** `GET`

**Endpoint:** `/v1/validate`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| code | query | Boleto barcode (44 digits) or digitable line (47 or 48 digits). Dots, dashes and spaces are ignored. | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/dam4g/boletovalidatorapi/v1/validate?code=21290001192110001210904475617405975870000002000" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "valid": true,
  "type": "bank_slip",
  "input_format": "digitable_line",
  "barcode": "21299758700000020000001121100012100447561740",
  "digitable_line": "21290001192110001210904475617405975870000002000",
  "digitable_line_formatted": "21290.00119 21100.012109 04475.617405 9 75870000002000",
  "checks": {
    "field_1_dv": true,
    "field_2_dv": true,
    "field_3_dv": true,
    "barcode_dv": true
  },
  "errors": [],
  "warnings": [
    {
      "code": "DUE_DATE_OUT_OF_WINDOW",
      "message": "The due date factor is outside the usual window (3000 days back, 5500 forward); the date is a best guess."
    }
  ],
  "bank": {
    "code": "212",
    "name": "Banco Original"
  },
  "currency": "BRL",
  "segment": null,
  "amount_cents": 2000,
  "amount": "20.00",
  "due_date": "2018-07-16",
  "due_date_status": "out_of_window",
  "overdue": true
}
```

#### 2. Validate a Boleto (POST)

Same as the GET version, with the code sent in a JSON body. This example is a collection boleto (a sanitation bill), which has a segment instead of a bank.

**Method:** `POST`

**Endpoint:** `/v1/validate`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| code | body | Boleto barcode (44 digits) or digitable line (47 or 48 digits). Dots, dashes and spaces are ignored. | string | Yes | - | - |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/dam4g/boletovalidatorapi/v1/validate" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"826300000013234500012021610150000004000000000000"}'
```

**Example Response (200 OK):**

```json
{
  "valid": true,
  "type": "collection",
  "input_format": "digitable_line",
  "barcode": "82630000001234500012026101500000000000000000",
  "digitable_line": "826300000013234500012021610150000004000000000000",
  "digitable_line_formatted": "82630000001-3 23450001202-1 61015000000-4 00000000000-0",
  "checks": {
    "block_1_dv": true,
    "block_2_dv": true,
    "block_3_dv": true,
    "block_4_dv": true,
    "barcode_dv": true
  },
  "errors": [],
  "warnings": [],
  "bank": null,
  "currency": "BRL",
  "segment": {
    "code": "2",
    "name": "Sanitation"
  },
  "amount_cents": 12345,
  "amount": "123.45",
  "due_date": null,
  "due_date_status": null,
  "overdue": null
}
```

#### 3. Convert Barcode and Digitable Line (GET)

Returns both the 44-digit barcode and the digitable line for a valid boleto, plus a formatted digitable line. The boleto must pass its check digits first; otherwise the API returns 422 with the failed checks.

**Method:** `GET`

**Endpoint:** `/v1/convert`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| code | query | Boleto barcode (44 digits) or digitable line (47 or 48 digits). Dots, dashes and spaces are ignored. | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/dam4g/boletovalidatorapi/v1/convert?code=21290001192110001210904475617405975870000002000" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "converted": true,
  "type": "bank_slip",
  "barcode": "21299758700000020000001121100012100447561740",
  "digitable_line": "21290001192110001210904475617405975870000002000",
  "digitable_line_formatted": "21290.00119 21100.012109 04475.617405 9 75870000002000"
}
```

#### 4. Convert Barcode and Digitable Line (POST)

Same as the GET version, with the code sent in a JSON body. This example converts a collection boleto barcode into its 48-digit digitable line.

**Method:** `POST`

**Endpoint:** `/v1/convert`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| code | body | Boleto barcode (44 digits) or digitable line (47 or 48 digits). Dots, dashes and spaces are ignored. | string | Yes | - | - |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/dam4g/boletovalidatorapi/v1/convert" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"82630000001234500012026101500000000000000000"}'
```

**Example Response (200 OK):**

```json
{
  "converted": true,
  "type": "collection",
  "barcode": "82630000001234500012026101500000000000000000",
  "digitable_line": "826300000013234500012021610150000004000000000000",
  "digitable_line_formatted": "82630000001-3 23450001202-1 61015000000-4 00000000000-0"
}
```

#### 5. Look Up a Bank

Returns the bank name for a 3-digit COMPE code. The list covers well-known Brazilian banks, not the full official list, so a 404 here does not mean a boleto is invalid.

**Method:** `GET`

**Endpoint:** `/v1/banks/{code}`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| code | path | 3-digit COMPE bank code, for example `001` (Banco do Brasil) or `260` (Nubank). | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/dam4g/boletovalidatorapi/v1/banks/001" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "code": "001",
  "name": "Banco do Brasil"
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | Request processed. For validate, check the `valid` field: an invalid boleto also returns 200. |
| 400 | Bad Request | The `code` parameter is missing. |
| 401 | Unauthorized | Missing or invalid `x-api-market-key` header. |
| 404 | Not Found | The bank code is not in the lookup table. |
| 422 | Unprocessable Entity | Convert was called with a boleto whose check digits are invalid. The response lists the failed checks. |
| 429 | Too Many Requests | You exceeded your plan's requests-per-second limit. |
| 500 | Internal Server Error | Unexpected server error. Retry the request. |

## Rate Limits

Each plan has a requests-per-second limit: Free 10, Pro 30, Mega 60 and Ultra 100. The Free plan includes 500 calls, Pro includes 10,000 calls a month and Mega 100,000 a month, with extra calls on Pro and Mega billed at $0.001 each. Ultra is pay-as-you-go at $0.0008 per call. Every 2xx response counts as one call, including validate responses with `valid: false`.

## FAQ

*   **Does a valid result mean the boleto is genuine?**

    No. It means the check digits are consistent. A fraudulent boleto can still have correct check digits, so use your payment provider to confirm payment status.

*   **What happens if I send an invalid boleto to validate?**

    You get HTTP 200 with `valid: false` and an `errors` list, for example `INVALID_FIELD_DV` when a field check digit does not match, or `INVALID_LENGTH` when the code has the wrong number of digits.

*   **Can I convert a boleto with invalid check digits?**

    No. Convert returns 422 with the failed checks, because converting an invalid code would produce another invalid code.

*   **Why is due_date null?**

    Many collection boletos do not encode a due date, so `due_date` and `overdue` are null. For very old or far-future bank slips, the API returns a best-guess date with a `DUE_DATE_OUT_OF_WINDOW` warning.

*   **Do I need to remove dots and spaces?**

    No. Dots, dashes and spaces are ignored.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Validate and convert Brazilian boletos with FEBRABAN check-digit verification. Get the bank, amount, due date and overdue status from any barcode or line.

Brazilian Boleto Validator API: FEBRABAN Check Digits

Free

DAM4G

Ultra

Mega

Validate and convert Brazilian boletos with real FEBRABAN check-digit verification for bank slips and utility or tax bills, from a barcode or digitable line.