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 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 parameterTypeEncoding
filterstringURL-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:
TypeNotes
stringUnquoted (identifier-like) or quoted.
numberInteger or floating-point.
booleantrue, false, TRUE, FALSE.
timestampRFC 3339.
enumAllowlisted values; case-sensitive.

​
Literals

FormExamples
Unquoted stringsACTIVE, SUCCESS, br.gov.bcb.pix
Double-quoted strings"John Doe", "ACME \"Corp\""
Single-quoted strings'John Doe', 'a\'b'
Numbers42, 3.14, 2.997e9
Booleanstrue, false, TRUE, FALSE
Nullnull, 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

OperatorAllowed 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

ReasonWhen
INVALID_FILTERMalformed syntax; unknown field; invalid literal; uncoercible value.
UNSUPPORTED_FILTER_OPERATIONOperator 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.

​
Next

Filtering concepts

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

Pagination

filter combines with order_by, page_size, page_token.