Criar operação de devolução de transferência bancária
Pré-requisito: a operação pai deve estar SETTLED antes de uma devolução; leia seu estado via getOperation (GET /v1/str/operations/); o segmento de rota vincula estruturalmente a devolução ao seu pai. O handler resolve a operação original por operationId, valida que o estado do ciclo de vida admite uma devolução (SPB-3006 caso contrário) e delega à rota de devolução STR0010. Idempotente: reenviar a mesma chave X-Idempotency com o mesmo corpo retorna a resposta em cache.
Autorizações
JWT bearer token issued by the identity provider.
Cabeçalhos
Bearer JWT token.
Idempotency key (canonical).
Idempotency key (legacy alias).
Idempotency key TTL in seconds.
Parâmetros de caminho
Original bank-transfer operation UUID.
Corpo
ISPB of the participant receiving the return, the 8-digit BACEN institution identifier.
38166
BACEN STR return reason code (devolução) for the reversal.
"01"
ISPB of the participant initiating the return, the 8-digit BACEN institution identifier.
"12345678"
Optional partial return amount as a decimal string in BRL, minor-unit precision; defaults to the full original amount when omitted.
^[0-9]+(\.[0-9]+)?$"50.00"
Optional free-text description of the return.
"Wrong account"
Opaque client-side metadata forwarded verbatim to the legacy submit DTO; not persisted on the return intent.
Resposta
Created
UTC RFC 3339 timestamp at which the command was accepted.
"2026-05-06T18:30:00Z"
STR capability identifier resolved for the accepted operation (e.g. STR0004).
"STR0004"
Request correlation identifier for tracing the accept across logs and traces.
"req-7c8b3a2e-9f1d-4a55-9b8e-1e1234567890"
True when this response replays a prior idempotent accept rather than creating a new operation.
false
Operation family the accepted command belongs to (e.g. bankTransfer).
"bankTransfer"
Server-assigned operation aggregate UUID used for subsequent status, return, and cancellation calls.
"7c8b3a2e-9f1d-4a55-9b8e-1e1234567890"
Current control-plane lifecycle status of the operation; ACCEPTED on initial accept.
"ACCEPTED"
Optional SAFE protocol correlation fields; present once the operation is mapped to STR wire identifiers.

