Compose and send a curated STR message

Catalog-gated, maker-checker-routed, per-type CURATED message-compose surface. The chosen capabilityId must be in the compose allowlist (STR0004/STR0005/STR0006/STR0007/STR0008/STR0046/STR0047/STR0048/STR0052/STR0053), resolve in the catalog, and be PUBLICLY_SUBMITTABLE; otherwise the request is rejected SPB-0003 (HTTP 422). The message builds through the shared compose pipeline and inherits the alçada emission gate: an amount above its band PARKS in PENDING_APPROVAL (visible in GET /v1/str/emission-approvals, emissionApprovalId set) and dispatches on quorum; below band it is SUBMITTED. Idempotent — the X-Idempotency key lives with the message: the same key and parsed request (member order and whitespace do not count; any other difference, such as number spelling, null for an absent field, or an unknown member, is another request) answer the stored message with X-Idempotency-Replayed: true, also after X-TTL has dropped the cached response, and the same key with another request answers 422. The declared amount is forwarded verbatim; no position is summed.

POST /v1/str/messages/compose

Compose and send a curated STR message

cURL

curl --request POST \
  --url https://api.example.com/v1/str/messages/compose \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "amount": "150000.00",
  "capabilityId": "STR0008",
  "recipient": {
    "ispb": "12345678",
    "account": "123456",
    "accountType": "CC",
    "branch": "0001",
    "document": "12345678901",
    "name": "João da Silva",
    "paymentAccount": "00000000123456"
  },
  "sender": {
    "ispb": "12345678",
    "account": "123456",
    "accountType": "CC",
    "branch": "0001",
    "document": "12345678901",
    "name": "João da Silva",
    "paymentAccount": "00000000123456"
  },
  "description": "Wire transfer for invoice 2026-Q2-A47",
  "finlddCli": "00001",
  "metadata": {},
  "purposeCode": "00001"
}
'

202

{
  "controlNumber": "20260621000000000001",
  "correlationId": "req-7a3f9c2e",
  "messageId": "6f2c8a1e-...",
  "nuOp": "12345678202606210000001",
  "status": "PENDING_APPROVAL",
  "emissionApprovalId": "6f2c8a1e-...",
  "requiredSignatures": 2
}

Autorizações

Authorization · string · header · obrigatório

JWT bearer token issued by the identity provider.

Cabeçalhos

X-Idempotency · string · obrigatório

Idempotency key. Required on every mutation.

X-TTL · string

Seconds the cached response is kept; it may only shorten IDEMPOTENCY_DEFAULT_TTL_SEC. The key itself lives with the message.

Corpo

application/json

amount · string · obrigatório

Transfer amount as a decimal string in BRL, minor-unit precision (two decimal places). Forwarded VERBATIM into the submit DTO and the alçada gate — Lerian SPB performs NO arithmetic on it. Canonical form only: exactly two decimal places and no leading integer zeros — the single spelling the durable column stores; anything else is refused at the door with 422.

Pattern: ^(0|[1-9][0-9]*)\.[0-9]{2}$

Exemplo:

"150000.00"

capabilityId · string · obrigatório

STR capability code to compose. Required and non-blank. Must resolve in the catalog, be PUBLICLY_SUBMITTABLE, and be in the compose allowlist (STR0004/STR0005/STR0006/STR0007/STR0008/STR0046/STR0047/STR0048/STR0052/STR0053).

Minimum string length: 1

Exemplo:

"STR0008"

recipient · object · obrigatório

Crediting (creditor) participant account receiving the transfer.

Show child attributes

sender · object · obrigatório

Debiting (debtor) participant account originating the transfer.

Show child attributes

description · string

Optional free-text description; mandatory when purposeCode or finlddCli is 99999 (RSTR0034). Serialized into the STR Hist element.

Exemplo:

"Wire transfer for invoice 2026-Q2-A47"

finlddCli · string

Optional client-level purpose code (5 digits) carried on STR0004/STR0008. When 99999 the description is required (RSTR0034).

Pattern: ^[0-9]{5}$

Exemplo:

"00001"

metadata · object

Opaque client-side metadata forwarded verbatim to the submit DTO (NOT sent to BACEN). Do not include sensitive fields.

Show child attributes

openFinancePortability · object

STR0052 (portabilidade de crédito no âmbito do Open Finance) elements: the IPOC code of the ported credit operation, its modality and the portability UUID. Required when composing STR0052; refused on any other capabilityId. sender/recipient account, document (CNPJ) and name fill the optional financial-agent groups (RSTR0024).

Show child attributes

portability · object

STR0047 (portabilidade de operação de crédito de pessoas naturais) elements: the unique portability number and the service provider ISPB. Required when composing STR0047; refused on any other capabilityId. sender/recipient account, document (CNPJ) and name fill the optional financial-agent groups, used only when that IF has no Reservas Bancárias or settlement account (RSTR0024).

Show child attributes

portabilityReturn · object

STR0048 (devolução de portabilidade indevida) elements: the return reason, the STR control number of the portability credit being returned and the service provider ISPB. The return is unique and for the full amount received (RSTR0033). Required when composing STR0048; refused on any other capabilityId.

Show child attributes

purposeCode · string

BACEN STR purpose code (finalidade), exactly 5 digits, and one the BACEN purpose dictionary names: 176 codes for the institution-level FinlddIF and 113 for the client-level FinlddCli. An unassigned five-digit number is refused. Required for every code that declares a Finalidade element (refused with 422 when absent); omitted for STR0053, which declares none. When 99999 (Outros) a description is mandatory (RSTR0034).

Pattern: ^[0-9]{5}$

Exemplo:

"00001"

repasse · object

STR0053 repasse identification: the [1..1] identifier and date, the optional originator CNPJ and transaction count, and the [0..n] segregation-informe group. Required when composing STR0053; refused on any other capabilityId, which has no repasse element on the wire.

Show child attributes

split · object

Optional IBS/CBS tax-split group (all three children required when the group is present). Carried on STR0005/STR0007/STR0008.

Show child attributes

taxRepasseReturn · object

STR0046 (devolução de repasse de receitas de tributos) elements: collection type and date, the collected and remuneration amounts, the return reason and the STR control number of the repasse being returned. Required when composing STR0046; refused on any other capabilityId.

Show child attributes

Resposta

202

application/json

Accepted

controlNumber · string · obrigatório

Participant control number identifying the message on the SPB network (official ControleIF, 1-20 characters).

Required string length: 1 - 20

Exemplo:

"20260621000000000001"

correlationId · string · obrigatório

Request-scoped correlation identifier echoing X-Request-ID, for pivoting from response to trace.

Exemplo:

"req-7a3f9c2e"

messageId · string · obrigatório

Internal outbound-message id assigned at persistence time; the key for the approval queue when parked.

Exemplo:

"6f2c8a1e-..."

nuOp · string · obrigatório

23-character STR operation number stamped on the composed message (protocol correlation).

Pattern: ^[0-9A-Z]{8}[0-9]{15}$

Exemplo:

"12345678202606210000001"

status · enum<string> · obrigatório

Emission status: SUBMITTED (dispatched / liquidatable) or PENDING_APPROVAL (parked awaiting maker-checker quorum).

Opções disponíveis: SUBMITTED, PENDING_APPROVAL

Exemplo:

"PENDING_APPROVAL"

emissionApprovalId · string

Set ONLY when the emission parked: the maker-checker queue id (equal to messageId). Poll GET /v1/str/emission-approvals to track it. Empty when SUBMITTED immediately.

Exemplo:

"6f2c8a1e-..."

requiredSignatures · integer<int64>

N-of-M distinct-actor quorum the parked emission must collect (the alçada band requirement). Omitted/0 when SUBMITTED immediately.

Exemplo:

2