Crear operación de transferencia bancaria

Prerrequisito: el rail debe estar listo antes de un envío: un certificado activo (ver rotateCertificate, activateCertificate), un reporte de disponibilidad READY (ver getReadiness) y una prueba de conectividad aprobada (ver createConnectivityTest). Acepta una operación de transferencia bancaria a través de la API centrada en operaciones. El cliente declara los roles tipados de deudor y acreedor (sender.party / recipient.party); la plataforma DERIVA el código de transferencia STR de BACEN (STR0004 institución→institución, STR0005 no titulares de cuenta, STR0006 cliente→IF, STR0007 IF→cliente, STR0008 cliente→cliente), persiste el agregado de operación y el trabajo de relay de salida SUBMITTED, y devuelve el sobre canónico OperationAccepted. Esto significa que el despacho fue aceptado, no una confirmación de liquidación de BACEN. Idempotente: reenviar la misma clave X-Idempotency con el mismo cuerpo devuelve la respuesta en caché.

POST /v1/str/operations/bank-transfers

Crear operación de transferencia bancaria

cURL

curl --request POST \
  --url https://spb.sandbox.lerian.net/v1/str/operations/bank-transfers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": "<string>",
  "purposeCode": "<string>",
  "recipient": {
    "ispb": "<string>",
    "account": "<string>",
    "accountType": "<string>",
    "branch": "<string>",
    "document": "<string>",
    "name": "<string>",
    "party": "<string>",
    "paymentAccount": "<string>"
  },
  "sender": {
    "ispb": "<string>",
    "account": "<string>",
    "accountType": "<string>",
    "branch": "<string>",
    "document": "<string>",
    "name": "<string>",
    "party": "<string>",
    "paymentAccount": "<string>"
  },
  "clientReference": "<string>",
  "description": "<string>",
  "metadata": {},
  "scheduledExecutionAt": "2023-11-07T05:31:56Z"
}
'

201

{
  "acceptedAt": "2023-11-07T05:31:56Z",
  "capabilityId": "<string>",
  "correlationId": "<string>",
  "isReplay": true,
  "operationFamily": "<string>",
  "operationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "<string>",
  "protocolMetadata": {
    "controlNumber": "<string>",
    "nuOp": "<string>"
  }
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Encabezados

Authorization · string

Bearer JWT token.

X-Idempotency · string

Idempotency key (canonical; legacy alias X-Idempotency-Key is rejected on this control-plane route).

X-Idempotency-Key · string

Idempotency key (legacy alias; rejected on this control-plane route).

X-TTL · string

Idempotency key TTL in seconds (overrides the configured default).

Cuerpo

application/json

amount · string · requerido

Transfer amount as a decimal string in BRL, minor-unit precision (two decimal places).

Pattern: ^[0-9]+(\.[0-9]+)?$

Ejemplo:

"150.00"

purposeCode · string · requerido

BACEN STR purpose code (finalidade), exactly 5 digits.

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

Ejemplo:

"00001"

recipient · object · requerido

Crediting (creditor) participant account receiving the transfer; its party role drives STR-code derivation.

Show child attributes

sender · object · requerido

Debiting (debtor) participant account originating the transfer; its party role drives STR-code derivation.

Show child attributes

clientReference · string

Optional caller-supplied correlation reference echoed back for client-side reconciliation.

Ejemplo:

"client-ref-1"

description · string

Optional free-text description carried with the operation.

Ejemplo:

"Wire transfer for invoice 2026-Q2-A47"

metadata · object

Opaque client-side metadata forwarded verbatim to the legacy submit DTO. NOT persisted on the operation intent or sanitized payload; do not include sensitive fields (the legacy pipeline sees the raw value).

Show child attributes

scheduledExecutionAt · string<date-time>

Optional future settlement instant for a scheduled (agendada) STR transfer (RFC3339). BACEN window: at most 3 business days ahead, settlement hour must be one of 8/9/10/11/12 (Brasília), and at least 15 minutes ahead for same-day. Absent means immediate.

Ejemplo:

"2026-06-23T10:00:00Z"

Respuesta

201

application/json

Created

acceptedAt · string<date-time> · requerido

UTC RFC 3339 timestamp at which the command was accepted.

Ejemplo:

"2026-05-06T18:30:00Z"

capabilityId · string · requerido

STR capability identifier resolved for the accepted operation (e.g. STR0004).

Ejemplo:

"STR0004"

correlationId · string · requerido

Request correlation identifier for tracing the accept across logs and traces.

Ejemplo:

"req-7c8b3a2e-9f1d-4a55-9b8e-1e1234567890"

isReplay · boolean · requerido

True when this response replays a prior idempotent accept rather than creating a new operation.

Ejemplo:

false

operationFamily · string · requerido

Operation family the accepted command belongs to (e.g. bankTransfer).

Ejemplo:

"bankTransfer"

operationId · string<uuid> · requerido

Server-assigned operation aggregate UUID used for subsequent status, return, and cancellation calls.

Ejemplo:

"7c8b3a2e-9f1d-4a55-9b8e-1e1234567890"

status · string · requerido

Current control-plane lifecycle status of the operation; ACCEPTED on initial accept.

Ejemplo:

"ACCEPTED"

protocolMetadata · object

Optional SAFE protocol correlation fields; present once the operation is mapped to STR wire identifiers.

Show child attributes