Initiate connectivity (ECO) test

Prerequisite: an active certificate (see rotateCertificate, activateCertificate) and a READY readiness report (see getReadiness) before the connectivity test; a passing connectivity test is itself the prerequisite for a submit operation (see createBankTransferOperation). Builds a GEN0001 echo request addressed to the given participant, persists it as SUBMITTED before rail dispatch, and lets the outbound relay dispatch it to the RSFN. The counterparty answers with GEN0001R1 echoing the message back; the response correlates by NUOp and confirms the test. Idempotent — replaying the same X-Idempotency key with the same 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) returns the cached response.

POST /v1/str/connectivity-tests

Initiate connectivity (ECO) test

cURL

curl --request POST \
  --url https://api.example.com/v1/str/connectivity-tests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "recipientIspb": "00038166",
  "certificateNotActivated": false,
  "message": "connectivity check"
}
'

201

{
  "controlNumber": "20260610000000000001",
  "correlationId": "req-7a3f9c2e",
  "messageType": "GEN0001",
  "nuOp": "12345678202606100000001",
  "status": "SUBMITTED",
  "submittedAt": "2026-06-10T12:00:00Z"
}

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.

X-TTL · string

Seconds the cached response is kept; it may only shorten IDEMPOTENCY_DEFAULT_TTL_SEC.

Corpo

application/json

recipientIspb · string · obrigatório

ISPB of the counterparty participant the echo is addressed to (8 uppercase alphanumeric characters).

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

Exemplo:

"00038166"

certificateNotActivated · boolean

Send the GEN0001 with SFN header C04 = 1: the frame is signed by a certificate BACEN has not activated yet (Manual de Segurança do SFN v6.00, items 5.6.2 and 5.6.3), so the echo can be tested before the GEN0006 activation. Default false sends the normal C04 = 0 frame.

Exemplo:

false

message · string

Optional free-text MsgECO payload echoed back by the counterparty. At most 50 characters (BACEN type MsgECO, Catálogo v5.13 Vol IV: Alfanumérico 0..50; the Vol III GEN0001 sample reads "texto de ate 50 posicoes"). Anything longer is refused by the wire facet before BACEN ever sees it.

Maximum string length: 50

Exemplo:

"connectivity check"

Resposta

201

application/json

Created

controlNumber · string · obrigatório

IF control number assigned to the GEN0001 submission (official ControleIF, 1-20 characters).

Required string length: 1 - 20

Exemplo:

"20260610000000000001"

correlationId · string · obrigatório

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

Exemplo:

"req-7a3f9c2e"

messageType · string · obrigatório

STR message code of the submission (always GEN0001 for connectivity tests).

Exemplo:

"GEN0001"

nuOp · string · obrigatório

BACEN protocol identifier (NUOp) assigned to the GEN0001 connectivity-test submission.

Required string length: 23

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

Exemplo:

"12345678202606100000001"

status · string · obrigatório

Submission status; SUBMITTED until the counterparty's GEN0001R1 echo correlates by NUOp and flips it to CONFIRMED.

Exemplo:

"SUBMITTED"

submittedAt · string · obrigatório

RFC3339 UTC timestamp when the submission was persisted before send.

Exemplo:

"2026-06-10T12:00:00Z"