List boleto batches

curl --request GET \
  --url https://api.example.com/v1/boletos/batches \
  --header 'Authorization: Bearer <token>'

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/boletos/batches"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/v1/boletos/batches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "items": [
    {
      "batchId": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b",
      "closed": true,
      "counts": {
        "canceled": 1,
        "failed": 1,
        "inactivated": 0,
        "overdue": 0,
        "processing": 1,
        "registered": 2,
        "requested": 5,
        "settled": 0
      },
      "createdAt": "2026-10-14T19:34:00Z",
      "finished": true,
      "ledgerId": "7c1e5b9a-3d2f-4a6b-8e0c-1f2a3b4c5d6e",
      "midazAccountId": "3f9a2c1e-5b7d-4e8f-9a0b-1c2d3e4f5a6b",
      "organizationId": "0f9d6c2a-1b3e-4f5a-8c7d-6e5f4a3b2c1d",
      "status": "CREATED"
    }
  ],
  "limit": 20,
  "page": 1,
  "total": 42
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

List boleto batches

Lists the boleto batches of the X-Organization-Id organization, most recent first, each with its outcome and counts and without its items; read one batch by its batchId for the items. The outcome, the counts, closed and finished are derived from the items on every read. The parameters are validated as on GET /v1/boletos: 400 PBP-0001 when page, limit, from or to is malformed or out of range, or when from or to names a day that does not exist, and 422 PBP-0006 when from is after to. An organization with no batch in the window is answered an empty page: items is [] and total is 0. A request refused earlier keeps its own status: 401 or 403 for authentication and authorization, and 400 PBP-0025 when X-Organization-Id is missing or not a canonical UUID.

GET

boletos

batches

List boleto batches

curl --request GET \
  --url https://api.example.com/v1/boletos/batches \
  --header 'Authorization: Bearer <token>'

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/boletos/batches"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/v1/boletos/batches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "items": [
    {
      "batchId": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b",
      "closed": true,
      "counts": {
        "canceled": 1,
        "failed": 1,
        "inactivated": 0,
        "overdue": 0,
        "processing": 1,
        "registered": 2,
        "requested": 5,
        "settled": 0
      },
      "createdAt": "2026-10-14T19:34:00Z",
      "finished": true,
      "ledgerId": "7c1e5b9a-3d2f-4a6b-8e0c-1f2a3b4c5d6e",
      "midazAccountId": "3f9a2c1e-5b7d-4e8f-9a0b-1c2d3e4f5a6b",
      "organizationId": "0f9d6c2a-1b3e-4f5a-8c7d-6e5f4a3b2c1d",
      "status": "CREATED"
    }
  ],
  "limit": 20,
  "page": 1,
  "total": 42
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Authorizations

Authorization

string

header

required

JWT bearer token issued by the identity provider.

Headers

X-Organization-Id

string

Organization whose batches are listed. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. Only batches of this organization are listed and counted.

Query Parameters

from

string

Created-from bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and starts at its first instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T00:00:00-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B).

Pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}(T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2}))?$

Example:

"2026-10-01"

string

Created-to bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and covers it to its last instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T23:59:59.999999-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B).

Pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}(T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2}))?$

Example:

"2026-10-31"

page

integer<int64>

default:1

Page number, one-based.

Required range: x >= 1

Example:

1

limit

integer<int64>

default:20

Items per page.

Required range: 1 <= x <= 100

Example:

20

Response

A page of the organization's batches, most recent first. A page with no batch carries an empty items list, never null.

items

object[] | null

required

Batches of the page, most recent first.

Show child attributes

limit

integer<int64>

required

Items per page.

Example:

20

page

integer<int64>

required

Page number, one-based.

Example:

1

total

integer<int64>

required

Number of batches of the organization that match the filter.

Example:

42

Boletos API

Boleto batches API

Payments API

Dashboards API

Admin API

Pix receiver API

Webhooks API

Error handling

List boleto batches

Authorizations

Headers

Query Parameters

Response