Crear operación de devolución de transferencia bancaria
Prerrequisito: la operación padre debe estar SETTLED antes de una devolución; lee su estado mediante getOperation (GET /v1/str/operations/); el segmento de ruta vincula estructuralmente la devolución con su padre. El handler resuelve la operación original por operationId, valida que el estado del ciclo de vida admita una devolución (SPB-3006 en caso contrario) y delega en la ruta de devolución STR0010. Idempotente: reenviar la misma clave X-Idempotency con el mismo cuerpo devuelve la respuesta en caché.
Autorizaciones
JWT bearer token issued by the identity provider.
Encabezados
Bearer JWT token.
Idempotency key (canonical).
Idempotency key (legacy alias).
Idempotency key TTL in seconds.
Parámetros de ruta
Original bank-transfer operation UUID.
Cuerpo
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.
Respuesta
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.

