BlooBank API Documentation

Every list endpoint in the BlooBank API supports filtering via the filter query parameter. The syntax is SFS-1 (Soluts Filter Syntax v1) — a lightweight, predictable expression language designed for both API integrators and ad-hoc tooling. This page is the complete normative reference. For an overview of when and how to use filters, see Filtering concepts.

Restrictions in v1

SFS-1 intentionally supports only AND logic. The following are explicitly rejected with INVALID_FILTER (HTTP 400):

OR operator
NOT operator and negation with -
Parentheses for grouping
Functions (call(arg...))
Wildcards * with special semantics
Loose literals without a field (e.g., Victor Hugo)
Collection-specific operators (has, contains, any)

Future versions of SFS may add OR, NOT, and parentheses without breaking v1 semantics.

Request parameter

APIs adopting SFS expose exactly one filter field:

Query parameter	Type	Encoding
`filter`	`string`	URL-encoded (RFC 3986)

GET /wallets/production-main/paymentOrders?filter=status%3DSUCCESS%20AND%20createdAt%3E%3D2026-01-01

Decoded:

status=SUCCESS AND createdAt>=2026-01-01

Syntax

A filter is a list of comparisons joined by AND, and, or ;. Comparison format:

<field> <operator> <literal>

Examples:

status=ACTIVE;name=production-main
status = SUCCESS AND createdAt >= 2026-01-01
createdAt >= "2026-01-15T00:00:00Z" and direction = OUT

Field names

Field names are explicitly allowlisted per endpoint. Referencing a field not in the allowlist returns INVALID_FILTER. The allowlist is documented in each endpoint’s reference page. Supported field types:

Type	Notes
`string`	Unquoted (identifier-like) or quoted.
`number`	Integer or floating-point.
`boolean`	`true`, `false`, `TRUE`, `FALSE`.
`timestamp`	RFC 3339.
`enum`	Allowlisted values; case-sensitive.

Literals

Form	Examples
Unquoted strings	`ACTIVE`, `SUCCESS`, `br.gov.bcb.pix`
Double-quoted strings	`"John Doe"`, `"ACME \"Corp\""`
Single-quoted strings	`'John Doe'`, `'a\'b'`
Numbers	`42`, `3.14`, `2.997e9`
Booleans	`true`, `false`, `TRUE`, `FALSE`
Null	`null`, `NULL`
Timestamps (RFC 3339)	`"2026-01-15T10:30:00Z"`, `"2026-01-15T07:30:00-03:00"`

String escaping. Inside a quoted string, \ escapes the next character:

"a\"b" resolves to a"b
'a\'b' resolves to a'b

Timestamp validation. A timestamp literal must parse as RFC 3339. Failures return INVALID_FILTER.

Operators

Operator	Allowed on
`=`	All types
`!=`	All types
`<`	`number`, `timestamp` only
`<=`	`number`, `timestamp` only
`>`	`number`, `timestamp` only
`>=`	`number`, `timestamp` only

string, boolean, and enum types accept only = and !=. Using < / <= / > / >= on these types returns UNSUPPORTED_FILTER_OPERATION.

Validation

Filters are fully schema-validated before execution.

Only fields listed in the endpoint’s allowlist are accepted.
Each literal must be coercible to the declared field type.
Enum fields only accept values from their allowed set.
Operators must be compatible with the field type.
Servers enforce limits on filter length, comparison count, and token count.

Any violation returns INVALID_FILTER or UNSUPPORTED_FILTER_OPERATION with HTTP 400.

Examples

Basic equality

GET /wallets?filter=status=ACTIVE

Multiple clauses (AND)

GET /wallets?filter=status%3DACTIVE%20AND%20createdAt%3E%3D2026-01-01

Decoded: status=ACTIVE AND createdAt>=2026-01-01

Numeric range

GET /wallets/production-main/paymentOrders?filter=amount%3E%3D10000%3Bamount%3C100000

Decoded: amount>=10000;amount<100000

Timestamp range

GET /wallets/production-main/paymentOrders?filter=createdAt%3E%3D%222026-01-01T00%3A00%3A00Z%22

Decoded: createdAt>="2026-01-01T00:00:00Z"

Enum + direction

GET /wallets/production-main/paymentOrders?filter=direction%3DIN%20AND%20status%3DSUCCESS

Decoded: direction=IN AND status=SUCCESS

Formal grammar (EBNF)

filter        = ws? expr ws? ;

expr          = comparison ( ws? logical_sep ws? comparison )* ;

logical_sep   = "AND" | "and" | ";" ;

comparison    = field ws? op ws? literal ;

field         = ident ( "." ident )* ;
ident         = ( ALPHA | "_" ) ( ALPHA | DIGIT | "_" )* ;

op            = "=" | "!=" | "<" | ">" | "<=" | ">=" ;

literal       = string | number | boolean | null_lit | bare_string ;
null_lit      = "null" | "NULL" ;
bare_string   = ident ;

string        = sq_string | dq_string ;
sq_string     = "'" { sq_char | escape } "'" ;
dq_string     = '"' { dq_char | escape } '"' ;
escape        = "\" ANY_CHAR ;
sq_char       = ANY_CHAR - "'" - "\" ;
dq_char       = ANY_CHAR - '"' - "\" ;

number        = [ "-" ] int_part [ frac_part ] [ exp_part ] ;
int_part      = DIGIT { DIGIT } ;
frac_part     = "." DIGIT { DIGIT } ;
exp_part      = ( "e" | "E" ) [ "+" | "-" ] DIGIT { DIGIT } ;

boolean       = "true" | "false" | "TRUE" | "FALSE" ;

ws            = " " | "\t" | "\r" | "\n" ;

Errors

Reason	When
`INVALID_FILTER`	Malformed syntax; unknown field; invalid literal; uncoercible value.
`UNSUPPORTED_FILTER_OPERATION`	Operator not allowed on the field’s type (e.g., `<` on a string).

Both return HTTP 400. See Errors for the full envelope contract.

Versioning

SFS-1 guarantees only AND semantics and the six comparison operators. Future versions may add OR, NOT, and parentheses — those will be released as SFS-2 (or higher), additively, without changing v1 behavior.

Filtering concepts

When to filter, how to choose fields, performance considerations.

Pagination

filter combines with order_by, page_size, page_token.

Introduction

Conventions

Wallets

Payment Orders

Filtering (SFS-1)

Restrictions in v1

Request parameter

Syntax

Field names

Literals

Operators

Validation

Examples

Basic equality

Multiple clauses (AND)

Numeric range

Timestamp range

Enum + direction

Formal grammar (EBNF)

Errors

Versioning

Next

Filtering concepts

Pagination

​Restrictions in v1

​Request parameter

​Syntax

​Field names

​Literals

​Operators

​Validation

​Examples

​Basic equality

​Multiple clauses (AND)

​Numeric range

​Timestamp range

​Enum + direction

​Formal grammar (EBNF)

​Errors

​Versioning

​Next

Filtering concepts

Pagination

Restrictions in v1

Request parameter

Syntax

Field names

Literals

Operators

Validation

Examples

Basic equality

Multiple clauses (AND)

Numeric range

Timestamp range

Enum + direction

Formal grammar (EBNF)

Errors

Versioning

Next