Create Conta-PI liquidity transfer

Prerequisite: the rail must be ready before a submit — an active certificate (see rotateCertificate, activateCertificate), a READY readiness report (see getReadiness), and a passing connectivity test (see createConnectivityTest). Accepts an LPI Conta-PI liquidity transfer through the operation-centric API: direction aporte funds the FI’s Conta PI from its RB/CL (the platform DERIVES wire code LPI0001), resgate recalls funds (LPI0003) — the platform never composes the wire code. A resgate to RB_CL names its finalidadeLPI (BACEN FinlddLPI domain): 1 is Movimentação própria ou para conta em Liquidante no STR; 2 is Devolução de aporte recebido indevidamente and quotes that aporte’s STR control number in originalControlNumber (RLPI0005). Persists a PENDING liquidity-transfer projection and returns the operation id, the PENDING status, and the derived wire code. This means dispatch was accepted, not BACEN settlement confirmation; the settlement arrives asynchronously on the inbound STR R-leg and is read via getLiquidityTransfer. An out-of-window aporte is rejected (RLPI0007). Lerian SPB EMITS the movement fact and projects the Conta-PI balance verbatim; it never computes a position. Idempotent — the X-Idempotency key lives with the movement: 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 movement with X-Idempotency-Replayed: true, also after X-TTL has dropped the cached response, and the same key with another request answers 422.

POST /v1/str/operations/liquidity-transfers

Create Conta-PI liquidity transfer

cURL

curl --request POST \
  --url https://api.example.com/v1/str/operations/liquidity-transfers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "amount": "1500.25",
  "direction": "aporte",
  "accountType": "RB_CL",
  "contaPiISPB": "00038166",
  "finalidadeLPI": "1",
  "originalControlNumber": "STR20260610000000123"
}
'

202

{
  "correlationId": "req-7a3f9c2e",
  "operationId": "7c8b3a2e-9f1d-4a55-9b8e-1e1234567890",
  "status": "PENDING",
  "wireCode": "LPI0001"
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Idempotency · string · requerido

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 movement.

Cuerpo

application/json

amount · string · requerido

Movement amount as a decimal-reais string, forwarded verbatim into the LPI submit — 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}$

Ejemplo:

"1500.25"

direction · enum<string> · requerido

Operator-facing movement direction: aporte funds the FI's Conta PI; resgate recalls funds from Conta PI.

Opciones disponibles: aporte, resgate

Ejemplo:

"aporte"

accountType · enum<string>

Counterparty account type. RB_CL = Reservas Bancárias / Conta de Liquidação ((aporte,RB_CL)->LPI0001, (resgate,RB_CL)->LPI0003); CCME = Conta Correspondente a Moeda Eletrônica, own-account only ((aporte,CCME)->LPI0002, (resgate,CCME)->LPI0004). Omitting the key defaults to RB_CL; an explicit empty string is refused.

Opciones disponibles: RB_CL, CCME

Ejemplo:

"RB_CL"

contaPiISPB · string

Optional Conta-PI owner ISPB (8 uppercase alphanumeric characters). Empty means the FI's OWN Conta PI (own-account path); a value differing from the issuer ISPB is the liquidante-funded path (RB_CL only). For CCME it must be empty or equal the issuer ISPB — CCME is own-account only.

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

Ejemplo:

"00038166"

finalidadeLPI · enum<string>

Purpose of the Conta-PI withdrawal (wire field FinlddLPI), a code of the BACEN FinlddLPI domain (dicionário de domínios): 1 = Movimentação própria ou para conta em Liquidante no STR; 2 = Devolução de aporte recebido indevidamente. REQUIRED for a resgate to RB_CL — the only LPI liquidity layout that declares it — and rejected for every other direction/accountType pair. Distinct from the STR purposeCode (FinlddCli/FinlddIF); do not send one for the other.

Opciones disponibles: 1, 2

Ejemplo:

"1"

originalControlNumber · string

STR control number (NumCtrlSTR, official type Controle: exactly 20 characters) of the undue aporte this resgate returns, carried on the wire as NumCtrlSTROr. REQUIRED when finalidadeLPI is 2 and refused under finalidadeLPI 1 and on every other direction/accountType pair (RLPI0005).

Required string length: 20

Ejemplo:

"STR20260610000000123"

Respuesta

202

application/json

Accepted

correlationId · string · requerido

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

Ejemplo:

"req-7a3f9c2e"

operationId · string<uuid> · requerido

Server-assigned operation UUID to poll on GET /v1/str/operations/liquidity-transfers/{operationId}.

Ejemplo:

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

status · enum<string> · requerido

Projection lifecycle status; PENDING on accept (awaiting the STR R-leg settlement confirmation).

Opciones disponibles: PENDING, SETTLED, REJECTED

Ejemplo:

"PENDING"

wireCode · enum<string> · requerido

LPI wire code derived server-side from (direction, accountType): (aporte,RB_CL)=LPI0001, (aporte,CCME)=LPI0002, (resgate,RB_CL)=LPI0003, (resgate,CCME)=LPI0004.

Opciones disponibles: LPI0001, LPI0002, LPI0003, LPI0004

Ejemplo:

"LPI0001"