Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.bloobank.com/llms.txt

Use this file to discover all available pages before exploring further.

Every list endpoint accepts a filter query parameter using SFS-1 (Soluts Filter Syntax v1) — a lightweight, predictable filter language. This page covers the mental model and common patterns; the Filtering reference is the full normative contract.

​
The mental model

A filter is a list of comparisons joined by AND (or ; as shorthand): 
status=SUCCESS AND createdAt>=2026-01-01
Each comparison has three parts: a field, an operator, and a literal. The server validates everything against the endpoint’s schema before executing the query. That is the whole language. There is no OR, no parentheses, no functions, no wildcards — and that is deliberate. SFS-1 prioritizes predictability over expressiveness.

​
Operators

OperatorAllowed on
= !=All types
< <= > >=Numbers and timestamps only
For strings, booleans, and enums, you can only check equality. This keeps query performance bounded and prevents accidental full-text scans.

​
Common patterns

​
Equality

status=SUCCESS
Most filters are equality checks. They are also the fastest — these always hit an index.

​
Range

createdAt>=2026-01-01 AND createdAt<2026-02-01
Date and amount ranges are the second-most-common filter. The half-open form (>= start, < end) is the canonical way to express “all items in January” without overlap.

​
Multiple criteria

status=SUCCESS;direction=IN;createdAt>=2026-01-01
; is shorthand for AND — both are equivalent. Whitespace is optional but improves readability.

​
Enum filtering

direction=IN
network=br.gov.bcb.pix
status=AWAITING_APPROVAL
Enum values are case-sensitive. direction=in will fail with INVALID_FILTER.

​
What you cannot do (and why)

You might wantWhy SFS-1 rejects itWhat to do instead
status=SUCCESS OR status=FAILEDNo OR in v1.Issue two filtered queries and merge client-side.
name LIKE 'prod-*'No wildcards.Use exact name= if you know the value; design for known identifiers.
NOT status=SUCCESSNo negation.Use status!=SUCCESS (yes, that one works — it is !=, not NOT).
(a=1 AND b=2) OR (c=3)No parentheses, no OR.Two queries client-side.
tags has "vip"No collection operators.Filter the field that exists on the resource.
The design rationale: filters should be cheap to plan, fast to execute, predictable to non-technical users. Complex boolean algebra defeats those goals.

​
Which fields can you filter on?

Filterable fields are explicitly allowlisted by each endpoint. Each endpoint’s reference page lists its filterable fields.
EndpointCommon filterable fields
GET /walletsid, status, name, createdAt
GET /wallets/{wallet}/paymentOrdersid, direction, status, network, createdAt
Trying to filter on a field not in the allowlist returns INVALID_FILTER.

​
Literal forms

FormExample
Unquoted identifierACTIVE, SUCCESS, br.gov.bcb.pix
Double-quoted string"John Doe", "ACME \"Corp\""
Single-quoted string'John Doe'
Integer42
Float3.14, 2.997e9
Booleantrue, false
Nullnull
Timestamp (RFC 3339)"2026-01-15T00:00:00Z"
For values that contain spaces, dots, dashes that look like operators, or any non-identifier characters, quote them.

​
URL encoding

The filter value lives in the URL. Spaces, >, <, = must be encoded per RFC 3986: 
filter=status%20%3D%20SUCCESS%20AND%20amount%20%3E%3D%2010000
Most HTTP clients encode automatically. Hand-built URLs must encode explicitly — see the Filtering reference for the full table.

​
Filtering and pagination interact

When you paginate (page_token), the filter you used on the first call must stay identical for every subsequent page. Changing it returns INVALID_PAGE_TOKEN. This is intentional — pagination tokens are bound to the filter context.

​
Reference

Filtering (SFS-1) — full reference contract

Operators, literals, validation, formal grammar.