Command a compulsory-account movement

Commands a movement between this institution’s compulsory deposits at BACEN and its own Reservas Bancárias: a withdrawal (RCO0010) or a deposit (RCO0011), derived server-side from the direction. The PENDING row commits with its frame, so a failed submit leaves neither. The response is an acceptance, never a settlement: the state comes from the BACEN answer (SitLancRCO) and from nothing else. 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. The amount is forwarded verbatim; no compulsory position is computed or held.

POST /v1/str/rco-movements

Command a compulsory-account movement

cURL

curl --request POST \
  --url https://api.example.com/v1/str/rco-movements \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "amount": "1500000.00",
  "compulsoryCode": "9",
  "kind": "deposit",
  "beneficiaryCNPJ": "12345678000199",
  "modality": "1",
  "preferenceLevel": "B"
}
'

202

{
  "amount": "1500000.00",
  "id": "<string>",
  "kind": "deposit",
  "messageCode": "RCO0011",
  "status": "PENDING",
  "correlationId": "<string>",
  "nuOp": "12345678202609150000001",
  "numCtrlIF": "<string>"
}

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 — replaying it produces one outbound frame, never two.

X-TTL · string

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

Corpo

application/json

amount · string · obrigatório

Movement amount in decimal reais, two places. Forwarded to BACEN verbatim — this rail performs no arithmetic on it and holds no compulsory position.

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

Exemplo:

"1500000.00"

compulsoryCode · string · obrigatório

CodRCO — which compulsory reserve the movement is against. The demand-deposit compulsory is refused on both directions (RRCO0005).

Exemplo:

"9"

kind · enum<string> · obrigatório

Direction of the movement. withdrawal takes value OUT of the compulsory deposits into Reservas Bancárias (RCO0010); deposit funds the compulsory deposits from Reservas Bancárias (RCO0011). The BACEN message code is derived from this server-side.

Opções disponíveis: withdrawal, deposit

Exemplo:

"deposit"

beneficiaryCNPJ · string

CNPJIF — carried by a DEPOSIT only (RRCO0004): the institution whose compulsory deposits this movement funds, when that institution holds neither a Reservas Bancárias nor a settlement account. Supplying it on a withdrawal is refused, not ignored.

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

Exemplo:

"12345678000199"

modality · string

CodMod — the optional modality of the reserve.

Exemplo:

"1"

preferenceLevel · string

NivelPref — the optional settlement priority the participant asks for. A letter (A/B/C/D) on the official type, not a digit.

Exemplo:

"B"

Resposta

202

application/json

Accepted

amount · string · obrigatório

Amount commanded, verbatim.

Exemplo:

"1500000.00"

id · string · obrigatório

Durable identifier of the commanded movement.

kind · string · obrigatório

Direction commanded.

Exemplo:

"deposit"

messageCode · string · obrigatório

BACEN message code derived from the direction.

Exemplo:

"RCO0011"

status · string · obrigatório

Projection state. PENDING until the R1 answer arrives: having sent the command is never a settlement.

Exemplo:

"PENDING"

correlationId · string

Request-scoped correlation identifier echoing X-Request-ID.

nuOp · string

Outbound operation number, once the frame is accepted onto the rail.

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

Exemplo:

"12345678202609150000001"

numCtrlIF · string

Participant control number — the handle the BACEN answer echoes, and the key this movement is read back by.