Skip to main content
API docs by Redocly

ONZ SPB

Download OpenAPI specification:Download

Conectividade ponta-a-ponta com o Sistema de Pagamentos Brasileiro.

O ONZ SPB é a camada que conecta sua instituição ao Banco Central do Brasil pela Rede do Sistema Financeiro Nacional (RSFN). Em um único contrato de API, você envia, recebe e audita mensagens do SPB com segurança, rastreabilidade e idempotência por padrão.

Como funciona

Fluxo do ONZ SPB

O ciclo de uma mensagem segue quatro passos:

  1. Envio — sua aplicação publica uma operação em POST /api/v1/operations (payload SPB cru) ou em POST /api/v1/operations/:evento (mapeada por tipo de evento, ex.: STR0007, STR0008).
  2. Despacho — a plataforma valida, cifra e entrega a mensagem ao BCB pela RSFN.
  3. Resposta assíncrona — o BCB devolve o retorno quando estiver pronto.
  4. Entrega — sua aplicação consome a resposta em GET /longpolling/v1/messages/:pullNext, com a conexão mantida aberta até a próxima mensagem chegar.

O que está incluído

  • Criação de operações — POST /api/v1/operations para o payload SPB cru, ou POST /api/v1/operations/:evento para um modelo de domínio mais conveniente, com mapeamento automático para a mensagem do BCB (:evento aceita códigos como STR0007, STR0008, STR0025, entre outros).
  • Consumo por long polling — GET /longpolling/v1/messages/:pullNext entrega respostas assim que chegam, sem polling agressivo nem webhooks para manter.
  • Mensageria BCB — envio e recepção via IBM MQ sobre RSFN, com gestão de filas transparente.
  • Criptografia — cifra/decifra automática das mensagens, com gerenciamento de chaves pública/privada.
  • Validação XSD — toda mensagem XML é validada contra os schemas oficiais do BCB antes de sair.
  • Idempotência — chaves de idempotência garantem processamento único mesmo sob retries.
  • Suporte a STR — operações do Sistema de Transferência de Reservas (STR0005, STR0006, STR0007, STR0008, STR0025, STR0034, STR0037, STR0041, STR0051) com controle de limites, validações condicionais.
  • Segurança — autenticação por token e autorização baseada em roles.
Sistema de filtros de consulta — clique para expandir

Endpoints de listagem aceitam um DSL de filtros que permite compor consultas complexas via query string, sem precisar de um corpo POST.

Anatomia de um filtro

Cada filtro tem três partes:

Parâmetro Função
queryFilter[{i}][column] Coluna/campo a filtrar
queryFilter[{i}][operation] Operador de comparação
queryFilter[{i}][value] ou queryFilter[{i}][valueArray][] Valor(es) a comparar

Operadores escalares (use com value)

Operador Significado
EQUALS / NOT_EQUALS Igual / diferente
ILIKE / NOT_ILIKE Contém / não contém — use % como curinga
HIGHER / LOWER Maior / menor que
EQUALS_DATE / AFTER_DATE / BEFORE_DATE Comparações por data
EQUALS_DATETIME / AFTER_DATETIME / BEFORE_DATETIME Comparações por data e hora

Operadores de conjunto (use com valueArray)

Operador Significado
IN / NOT_IN Pertence / não pertence ao conjunto
BETWEEN_DATETIME Entre duas datas/horas (exatamente 2 valores)

Exemplos

# Filtro único
?queryFilter[0][column]=status
&queryFilter[0][operation]=EQUALS
&queryFilter[0][value]=active

# Filtro com lista de valores
?queryFilter[0][column]=type
&queryFilter[0][operation]=IN
&queryFilter[0][valueArray][0]=TYPE1
&queryFilter[0][valueArray][1]=TYPE2

# Múltiplos filtros combinados (AND)
?queryFilter[0][column]=status&queryFilter[0][operation]=EQUALS&queryFilter[0][value]=active
&queryFilter[1][column]=type&queryFilter[1][operation]=IN&queryFilter[1][valueArray][0]=TYPE1

audit-events

List audit events (global)

Paginated audit-log entries for the tenant, optionally filtered by period, actor, resource, action, operation, event or document.

Authorizations:
BearerAuth
query Parameters
page
integer >= 1

1-indexed page (default 1)

perPage
integer [ 1 .. 100 ]

Page size (default 20, max 100)

sort
string
Enum: "occurred_at_asc" "occurred_at_desc"

Sort key

from
string

Start date (inclusive) YYYY-MM-DD

to
string

End date (inclusive) YYYY-MM-DD

actor
string

Actor filter (exact match)

resource
string

Resource filter (exact match)

action
string

Action filter (exact match)

operation_id
string

Operation id filter

event_id
string

Event id filter

document_id
integer

Document id filter

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

List audit events for an operation

Paginated audit-log entries scoped to a single operation, with the same query-filter protocol used by /transactions.

Authorizations:
BearerAuth
path Parameters
operation_id
required
string

Operation ID

query Parameters
event_id
string

Event ID filter

page
integer >= 1

1-indexed page (default 1)

perPage
integer [ 1 .. 100 ]

Page size (default 20, max 100)

sortBy
string
Value: "occurred_at"

Sort column

order
string
Enum: "asc" "desc"

Sort order

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

balances

List balance history

Paginated balance snapshots for a given period. Defaults to today when no query is supplied. Period must not exceed 30 days.

Authorizations:
BearerAuth
query Parameters
from
string
Example: from=2026-04-01

Start date (inclusive) YYYY-MM-DD

to
string
Example: to=2026-04-30

End date (inclusive) YYYY-MM-DD

page
integer >= 1

1-indexed page number (default 1)

per_page
integer >= 1

Page size (default 3000)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Latest balance snapshot

Returns the most recent balance snapshot plus the projected balance and delta computed from STR reserve movements since the snapshot.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

certificates

Upload participant private key

Upload the participant's SPB signing private key (multipart/form-data). Fields: ispb (8-digit), certificate (file).

Authorizations:
BearerAuth
Request Body schema: multipart/form-data
required
ispb
required
string

Participant ISPB (8 digits)

certificate
required
string <binary>

PEM-encoded private key file (max 10 MB)

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Upload participant public key

Upload the participant's SPB signing public key (multipart/form-data). Fields: ispb (8 digits), certifier, asymmetric_key_algorithm, certificate (file).

Authorizations:
BearerAuth
Request Body schema: multipart/form-data
required
ispb
required
string

Participant ISPB (8 digits)

certifier
required
string

Certificate authority id

asymmetric_key_algorithm
string

Asymmetric key algorithm (e.g. RSA, ECDSA)

certificate
required
string <binary>

PEM-encoded public key file (max 10 MB)

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

operations

List operations

Paginated list of operations with the standard query-filter protocol (same as /transactions).

Authorizations:
BearerAuth
query Parameters
page
integer >= 1

1-indexed page (default 1)

perPage
integer [ 1 .. 100 ]

Page size (default 25, max 100)

sortBy
string

Column to sort by (requires order)

order
string
Enum: "asc" "desc"

Sort order

filter
string

Raw filter expression (advanced)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create operation (raw XML)

Post a raw SPB XML event (SISMSG envelope). The event type is inferred from the body. Signature + idempotency enforced via headers.

Authorizations:
BearerAuth
header Parameters
X-Idempotency-Key
required
string

Idempotency key

X-Message-Type
required
string

SPB message type

X-Recipient
string

Recipient ISPB (required for events that address a specific participant)

X-Domain
string

Override operation domain (optional)

X-Request-Timeout
integer

Wait for response up to N seconds; 0 for fire-and-forget (default 0)

Request Body schema: application/xml
required

Raw SPB SISMSG XML

string

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "created_by": "string",
  • "decided_by": "string",
  • "domain": "string",
  • "event_type": "string",
  • "events": [
    ],
  • "id": "string",
  • "operation_type": "string",
  • "recipient": "string",
  • "sender": "string",
  • "status": "string",
  • "str_id": "string",
  • "timeline": [
    ]
}

Create operation (mapped payload)

Post a typed payload (JSON or proprietary format) for the given event_type. The registry converts it to canonical SPB XML before processing.

Authorizations:
BearerAuth
path Parameters
event_type
required
string

Event type (e.g. SLB0001, STR0003)

header Parameters
X-Idempotency-Key
required
string

Idempotency key

X-Message-Type
required
string

SPB message type

X-Recipient
string

Recipient ISPB (when applicable)

X-Domain
string

Override operation domain (optional)

X-Request-Timeout
integer

Wait for response up to N seconds (default 0)

Request Body schema:
required

Mapped payload (JSON or XML)

object

Responses

Request samples

Content type
{ }

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "created_by": "string",
  • "decided_by": "string",
  • "domain": "string",
  • "event_type": "string",
  • "events": [
    ],
  • "id": "string",
  • "operation_type": "string",
  • "recipient": "string",
  • "sender": "string",
  • "status": "string",
  • "str_id": "string",
  • "timeline": [
    ]
}

Preview operation XML (mapped)

Convert a mapped payload (JSON or proprietary format) for the given event_type into canonical SPB XML, without dispatching.

Authorizations:
BearerAuth
path Parameters
event_type
required
string

Event type (e.g. SLB0001, STR0003)

header Parameters
X-Message-Type
required
string

SPB message type

X-Recipient
string

Recipient ISPB (when applicable)

X-Domain
string

Override operation domain (optional)

Request Body schema:
required

Mapped payload

object

Responses

Request samples

Content type
{ }

Get operation

Return the full operation detail (including its events) by ID.

Authorizations:
BearerAuth
path Parameters
operation_id
required
string

Operation ID

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "created_by": "string",
  • "decided_by": "string",
  • "domain": "string",
  • "event_type": "string",
  • "events": [
    ],
  • "id": "string",
  • "operation_type": "string",
  • "recipient": "string",
  • "sender": "string",
  • "status": "string",
  • "str_id": "string",
  • "timeline": [
    ]
}

Approve operation

Approve an operation currently in pending_approval (moves it back into processing).

Authorizations:
BearerAuth
path Parameters
operation_id
required
string

Operation ID

header Parameters
X-Domain
string

Operation domain (required by domain middleware)

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "created_by": "string",
  • "decided_by": "string",
  • "domain": "string",
  • "event_type": "string",
  • "events": [
    ],
  • "id": "string",
  • "operation_type": "string",
  • "recipient": "string",
  • "sender": "string",
  • "status": "string",
  • "str_id": "string",
  • "timeline": [
    ]
}

List audit events for an operation

Paginated audit-log entries scoped to a single operation, with the same query-filter protocol used by /transactions.

Authorizations:
BearerAuth
path Parameters
operation_id
required
string

Operation ID

query Parameters
event_id
string

Event ID filter

page
integer >= 1

1-indexed page (default 1)

perPage
integer [ 1 .. 100 ]

Page size (default 20, max 100)

sortBy
string
Value: "occurred_at"

Sort column

order
string
Enum: "asc" "desc"

Sort order

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

List events for an operation

Paginated list of events associated with an operation (operation_id OR original_operation_id match).

Authorizations:
BearerAuth
path Parameters
operation_id
required
string

Operation ID

query Parameters
page
integer >= 1

1-indexed page (default 1)

perPage
integer >= 1

Page size (default 2)

sortBy
string

Column to sort by (requires order)

order
string
Enum: "asc" "desc"

Sort order

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get event

Return a single event detail for the given operation/event pair.

Authorizations:
BearerAuth
path Parameters
operation_id
required
string

Operation ID

event_id
required
integer

Event ID

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "event_type": "string",
  • "id": 0,
  • "idempotency_key": "string",
  • "message_type": "string",
  • "operation_id": "string",
  • "original_operation_id": "string",
  • "plaintext": "string",
  • "recipient": "string",
  • "sender": "string",
  • "sent_at": "string",
  • "updated_at": "string"
}

Get event XML document

Return the decrypted XML document associated with an event (the SPB message payload).

Authorizations:
BearerAuth
path Parameters
operation_id
required
string

Operation ID

event_id
required
integer

Event ID

Responses

Requeue event

Requeue a failed event so the operation can be reprocessed through the SPB pipeline.

Authorizations:
BearerAuth
path Parameters
operation_id
required
string

Operation ID

event_id
required
integer

Event ID

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "created_by": "string",
  • "decided_by": "string",
  • "domain": "string",
  • "event_type": "string",
  • "events": [
    ],
  • "id": "string",
  • "operation_type": "string",
  • "recipient": "string",
  • "sender": "string",
  • "status": "string",
  • "str_id": "string",
  • "timeline": [
    ]
}

Reject operation

Reject an operation currently in pending_approval. Terminal transition.

Authorizations:
BearerAuth
path Parameters
operation_id
required
string

Operation ID

header Parameters
X-Domain
string

Operation domain (required by domain middleware)

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "created_by": "string",
  • "decided_by": "string",
  • "domain": "string",
  • "event_type": "string",
  • "events": [
    ],
  • "id": "string",
  • "operation_type": "string",
  • "recipient": "string",
  • "sender": "string",
  • "status": "string",
  • "str_id": "string",
  • "timeline": [
    ]
}

Acknowledge operation (SLB0002)

Send the SLB0002 acknowledgement for a previously received operation back to BACEN.

Authorizations:
BearerAuth
path Parameters
operation_id
required
string

Operation ID

header Parameters
X-Idempotency-Key
required
string

Idempotency key

X-Message-Type
required
string

SPB message type

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Respond to operation (raw XML)

Post the response XML for an in-flight operation (follow-up message such as STR0003 reply, LDL retorno, etc.).

Authorizations:
BearerAuth
path Parameters
operation_id
required
string

Operation ID

header Parameters
X-Idempotency-Key
required
string

Idempotency key

X-Message-Type
required
string

SPB message type

X-Domain
required
string

Operation domain

X-Recipient
string

Recipient ISPB (when applicable)

Request Body schema: application/xml
required

Raw SPB SISMSG XML

string

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "created_by": "string",
  • "decided_by": "string",
  • "domain": "string",
  • "event_type": "string",
  • "events": [
    ],
  • "id": "string",
  • "operation_type": "string",
  • "recipient": "string",
  • "sender": "string",
  • "status": "string",
  • "str_id": "string",
  • "timeline": [
    ]
}

Operations analytics

Aggregated analytics across operations / balances / statements / transactions for the requested period. Defaults to today when no query is supplied. Period must not exceed 30 days.

Authorizations:
BearerAuth
query Parameters
from
string
Example: from=2026-04-01

Start date YYYY-MM-DD

to
string
Example: to=2026-04-30

End date YYYY-MM-DD

Responses

Response samples

Content type
application/json
{
  • "balances": {
    },
  • "operations": {
    },
  • "period": {
    },
  • "statements": {
    },
  • "transactions": {
    }
}

Get operation by idempotency key

Return the operation tied to a given idempotency key (max 36 chars).

Authorizations:
BearerAuth
path Parameters
idempotency_key
required
string <= 36 characters

Idempotency key (max 36)

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "created_by": "string",
  • "decided_by": "string",
  • "domain": "string",
  • "event_type": "string",
  • "events": [
    ],
  • "id": "string",
  • "operation_type": "string",
  • "recipient": "string",
  • "sender": "string",
  • "status": "string",
  • "str_id": "string",
  • "timeline": [
    ]
}

Preview operation XML (raw)

Take a raw SPB XML body, validate it and return the canonical document that would be sent — without actually dispatching it. Useful for debugging / tooling.

Authorizations:
BearerAuth
header Parameters
X-Message-Type
required
string

SPB message type

X-Recipient
string

Recipient ISPB (when applicable)

X-Domain
string

Override operation domain (optional)

Request Body schema: application/xml
required

Raw SPB SISMSG XML

string

Responses

events

List events for an operation

Paginated list of events associated with an operation (operation_id OR original_operation_id match).

Authorizations:
BearerAuth
path Parameters
operation_id
required
string

Operation ID

query Parameters
page
integer >= 1

1-indexed page (default 1)

perPage
integer >= 1

Page size (default 2)

sortBy
string

Column to sort by (requires order)

order
string
Enum: "asc" "desc"

Sort order

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get event

Return a single event detail for the given operation/event pair.

Authorizations:
BearerAuth
path Parameters
operation_id
required
string

Operation ID

event_id
required
integer

Event ID

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "event_type": "string",
  • "id": 0,
  • "idempotency_key": "string",
  • "message_type": "string",
  • "operation_id": "string",
  • "original_operation_id": "string",
  • "plaintext": "string",
  • "recipient": "string",
  • "sender": "string",
  • "sent_at": "string",
  • "updated_at": "string"
}

Get event XML document

Return the decrypted XML document associated with an event (the SPB message payload).

Authorizations:
BearerAuth
path Parameters
operation_id
required
string

Operation ID

event_id
required
integer

Event ID

Responses

Requeue event

Requeue a failed event so the operation can be reprocessed through the SPB pipeline.

Authorizations:
BearerAuth
path Parameters
operation_id
required
string

Operation ID

event_id
required
integer

Event ID

Responses

Response samples

Content type
application/json
{
  • "created_at": "string",
  • "created_by": "string",
  • "decided_by": "string",
  • "domain": "string",
  • "event_type": "string",
  • "events": [
    ],
  • "id": "string",
  • "operation_type": "string",
  • "recipient": "string",
  • "sender": "string",
  • "status": "string",
  • "str_id": "string",
  • "timeline": [
    ]
}

statements

List statements

Paginated list of institution statements, with optional period and filter support (same protocol as /transactions).

Authorizations:
BearerAuth
query Parameters
page
integer >= 1

1-indexed page (default 1)

perPage
integer [ 1 .. 100 ]

Page size (default 25, max 100)

from
string

Start date YYYY-MM-DD

to
string

End date YYYY-MM-DD

sortBy
string

Column to sort by (requires order)

order
string
Enum: "asc" "desc"

Sort order

filter
string

Raw filter expression (advanced)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get statement

Return the full statement detail (including all entries) by ID.

Authorizations:
BearerAuth
path Parameters
id
required
integer

Statement ID

Responses

Response samples

Content type
application/json
{
  • "bacen_at": "string",
  • "created_at": "string",
  • "document_id": 0,
  • "entries": [
    ],
  • "event_id": 0,
  • "final_balance": "string",
  • "id": 0,
  • "if_at": "string",
  • "initial_balance": "string",
  • "movement_date": "string",
  • "operation_id": "string",
  • "sender_ispb": "string"
}

str

STR work hours / status

Returns BACEN STR window status (open/closed) and the current day's working hours.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "closing_time": "string",
  • "opening_time": "string",
  • "reference_date": "string",
  • "status": "open"
}

transactions

List transactions

Paginated list of transactions with rich query-filter support. See project docs for the queryFilter[i][column|operation|value|valueArray] protocol.

Authorizations:
BearerAuth
query Parameters
page
integer >= 1

1-indexed page (default 1)

perPage
integer [ 1 .. 100 ]

Page size (default 25, max 100)

sortBy
string

Column to sort by (requires order)

order
string
Enum: "asc" "desc"

Sort order

filter
string

Raw filter expression (advanced)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get transaction

Return the complete transaction detail by ID.

Authorizations:
BearerAuth
path Parameters
id
required
integer

Transaction ID

Responses

Response samples

Content type
application/json
{
  • "amount": 0,
  • "content": [
    ],
  • "contract_number": "string",
  • "control_number": "string",
  • "created_at": "string",
  • "description": "string",
  • "entry_type": "string",
  • "group_event_type": "string",
  • "id": 0,
  • "idempotency_key": "string",
  • "identifier_code": "string",
  • "operation_id": "string",
  • "operation_type": "string",
  • "priority": 0,
  • "reason": 0,
  • "receiver": {
    },
  • "reference_str_id": "string",
  • "schedule_datetime": "string",
  • "sender": {
    },
  • "status": "string",
  • "status_description": "string",
  • "str_id": "string",
  • "updated_at": "string"
}

Generate transaction receipt (PDF)

Generate and return a PDF receipt for the given transaction.

Authorizations:
BearerAuth
path Parameters
id
required
integer

Transaction ID

Responses

health

Liveness probe (SPB API)

Returns 200 when the process is up. Does not check dependencies.

Responses

Readiness probe (SPB API)

Returns 200 when the DB is reachable (1s ping). Returns 503 otherwise. Also updates DB connection pool gauges.

Responses

Liveness probe (Long Polling)

Returns OK when the process is up. No dependencies checked.

Responses

Response samples

Content type
application/json
"OK"

version

Build version

Returns the build version tag and commit SHA baked into the binary at build time.

Responses

Response samples

Content type
application/json
{
  • "commit": "a1b2c3d",
  • "version": "1.42.0"
}

longpolling

Pull the next SPB message

Long-polling endpoint. The first call MUST use pullNext=start; subsequent calls reuse the value returned in the onz-pull-next response header. The connection is held for up to ~5s waiting for a new message.

200 body is either the next message envelope (see the LpMessage schema) or an empty body for bootstrap requests. 204 means the polling window expired. The onz-pull-next response header always carries the cursor for the next call.

{



  "id": 1,
  "operation_id": "op-uuid",
  "event_type": "response",
  "message_type": "PACS008",
  "sender": "12345678",
  "recipient": "08253539",
  "plaintext": "<xml/>",
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z"
}
Authorizations:
BearerAuth
path Parameters
pullNext
required
string non-empty

start to bootstrap a session, otherwise the value of the previous onz-pull-next header.

Responses

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "operation_id": "string",
  • "event_type": "string",
  • "message_type": "string",
  • "sender": "string",
  • "recipient": "string",
  • "plaintext": "string",
  • "created_at": "string",
  • "updated_at": "string"
}

consumers

Start or cancel an ISPB consumer

Internal consumer management endpoint used by ops tooling to start or cancel the RabbitMQ consumer bound to a participant queue.

Authorizations:
BearerAuth
path Parameters
action
required
string
Enum: "start" "cancel"
ispb
required
string [ 4 .. 8 ] characters

Participant ISPB (4-8 char identifier).

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}