Create outbound transfer

curl --request POST \
  --url https://api.example.com/v1/transfers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "documentType": "<string>",
  "fileName": "<string>",
  "fileRef": "<string>",
  "sourceProduct": "<string>",
  "credentialId": "<string>",
  "institutionCode": "<string>"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/transfers"

	payload := strings.NewReader("{\n  \"documentType\": \"<string>\",\n  \"fileName\": \"<string>\",\n  \"fileRef\": \"<string>\",\n  \"sourceProduct\": \"<string>\",\n  \"credentialId\": \"<string>\",\n  \"institutionCode\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    documentType: '<string>',
    fileName: '<string>',
    fileRef: '<string>',
    sourceProduct: '<string>',
    credentialId: '<string>',
    institutionCode: '<string>'
  })
};

fetch('https://api.example.com/v1/transfers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/transfers"

payload = {
    "documentType": "<string>",
    "fileName": "<string>",
    "fileRef": "<string>",
    "sourceProduct": "<string>",
    "credentialId": "<string>",
    "institutionCode": "<string>"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "bytesDownloaded": 123,
  "bytesUploaded": 123,
  "createdAt": "2023-11-07T05:31:56Z",
  "credentialId": "<string>",
  "currentState": "<string>",
  "currentStateCode": 123,
  "direction": "<string>",
  "documentType": "<string>",
  "expired": true,
  "fileName": "<string>",
  "fileSizeBytes": 123,
  "hashMismatchAttempts": 123,
  "id": "<string>",
  "secondsRemaining": 123,
  "transmissionAttempts": 123,
  "updatedAt": "2023-11-07T05:31:56Z",
  "uploadAttempts": 123,
  "documentCode": "<string>",
  "errorCode": "<string>",
  "expiresAt": "2023-11-07T05:31:56Z",
  "fileRef": "<string>",
  "lastTransitError": "<string>",
  "originProtocolNumber": "<string>",
  "protocolGeneratedAt": "2023-11-07T05:31:56Z",
  "protocolNumber": "<string>",
  "sourceProduct": "<string>",
  "urgentRequestedAt": "2023-11-07T05:31:56Z"
}

{
  "code": 400,
  "message": "context name is required",
  "title": "invalid_request"
}

{
  "code": 400,
  "message": "context name is required",
  "title": "invalid_request"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Create outbound transfer

Creates a new outbound transfer. The worker streams the referenced object to BACEN STA asynchronously. A 5xx frees the X-Idempotency key for a resend unless it carries X-Idempotency-Fenced: then the transfer may exist. With true, every same-key resend is refused 422 IDEMPOTENCY_OUTCOME_UNRECORDED for the key’s 7 days; with false, the key is unprotected. Either way, check GET /v1/transfers and resend under a new key only if nothing was created.

POST

transfers

curl --request POST \
  --url https://api.example.com/v1/transfers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "documentType": "<string>",
  "fileName": "<string>",
  "fileRef": "<string>",
  "sourceProduct": "<string>",
  "credentialId": "<string>",
  "institutionCode": "<string>"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/transfers"

	payload := strings.NewReader("{\n  \"documentType\": \"<string>\",\n  \"fileName\": \"<string>\",\n  \"fileRef\": \"<string>\",\n  \"sourceProduct\": \"<string>\",\n  \"credentialId\": \"<string>\",\n  \"institutionCode\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    documentType: '<string>',
    fileName: '<string>',
    fileRef: '<string>',
    sourceProduct: '<string>',
    credentialId: '<string>',
    institutionCode: '<string>'
  })
};

fetch('https://api.example.com/v1/transfers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/transfers"

payload = {
    "documentType": "<string>",
    "fileName": "<string>",
    "fileRef": "<string>",
    "sourceProduct": "<string>",
    "credentialId": "<string>",
    "institutionCode": "<string>"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "bytesDownloaded": 123,
  "bytesUploaded": 123,
  "createdAt": "2023-11-07T05:31:56Z",
  "credentialId": "<string>",
  "currentState": "<string>",
  "currentStateCode": 123,
  "direction": "<string>",
  "documentType": "<string>",
  "expired": true,
  "fileName": "<string>",
  "fileSizeBytes": 123,
  "hashMismatchAttempts": 123,
  "id": "<string>",
  "secondsRemaining": 123,
  "transmissionAttempts": 123,
  "updatedAt": "2023-11-07T05:31:56Z",
  "uploadAttempts": 123,
  "documentCode": "<string>",
  "errorCode": "<string>",
  "expiresAt": "2023-11-07T05:31:56Z",
  "fileRef": "<string>",
  "lastTransitError": "<string>",
  "originProtocolNumber": "<string>",
  "protocolGeneratedAt": "2023-11-07T05:31:56Z",
  "protocolNumber": "<string>",
  "sourceProduct": "<string>",
  "urgentRequestedAt": "2023-11-07T05:31:56Z"
}

{
  "code": 400,
  "message": "context name is required",
  "title": "invalid_request"
}

{
  "code": 400,
  "message": "context name is required",
  "title": "invalid_request"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Autorizações

Authorization

string

header

obrigatório

JWT bearer token issued by the identity provider.

Cabeçalhos

X-Idempotency

string

obrigatório

Idempotency key, one per submission (max 256 bytes). A repeat with the same key and the same parsed request (member order and whitespace do not count) replays the original outcome; the same key with another request is refused 422.

Corpo

application/json

Outbound transfer creation payload

documentType

string

obrigatório

fileName

string

obrigatório

fileRef

string

obrigatório

sourceProduct

string

obrigatório

credentialId

string

institutionCode

string

Resposta

Created

bytesDownloaded

integer<int64>

obrigatório

bytesUploaded

integer<int64>

obrigatório

createdAt

string<date-time>

obrigatório

credentialId

string

obrigatório

currentState

string

obrigatório

currentStateCode

integer<int64>

obrigatório

direction

string

obrigatório

documentType

string

obrigatório

Document type in the MNEMONIC vocabulary (ACCS002) whenever it is known. Outbound: always the mnemonic the caller supplied, unchanged. Inbound: the mnemonic BACEN sent in , published only when the de-para table agrees it names the code that arrived with it. ⚠️ Inbound transfers created before this field was recorded — and BACEN's legacy query envelopes, which omit the element — have no mnemonic stored and are NOT backfilled: those rows answer with the numeric code here, the same value they have always returned. Compare against documentCode to tell the two vocabularies apart.

expired

boolean

obrigatório

fileName

string

obrigatório

fileSizeBytes

integer<int64>

obrigatório

hashMismatchAttempts

integer<int64> | null

obrigatório

Inbound only: count of downloads whose SHA-256 did not match BACEN's, driving the Inconsistent terminal. null for outbound transfers.

string

obrigatório

secondsRemaining

integer<int64>

obrigatório

transmissionAttempts

integer<int64> | null

obrigatório

Inbound only: count of non-hash download failures, driving the Canceled / DOWNLOAD_FAILED terminal. null for outbound transfers.

updatedAt

string<date-time>

obrigatório

uploadAttempts

integer<int64> | null

obrigatório

Count of FAILED outbound transmission attempts, and the value the retry budget consumes: the worker stops retrying once it reaches 5. It counts failures, not attempts, so a transfer that succeeded on the first try reports 0. null for inbound transfers, which have no upload leg.

documentCode

string

BACEN identifier for the same document (6002). Its provenance differs by direction: on an inbound transfer it is OBSERVED — the BACEN delivered — while on an outbound transfer it is DERIVED from the CURRENT de-para table at read time — it is what that table resolves the mnemonic to today, NOT a persisted record of the identifier that went on the wire. The two coincide while the table is unchanged; if an entry is ever corrected, this field answers the new value for an old transfer. The identifier actually sent is recorded in the log line and, on a BACEN rejection, in the terminal reason. Treat it as an opaque token, not a number: some documents resolve to a non-numeric identifier (ARQTEST resolves to TEST). Omitted entirely when neither source resolves it, which is a valid state for an outbound document type absent from the table — an empty string is never published, because it would be indistinguishable from a genuinely empty code.

errorCode

string

expiresAt

string<date-time>

fileRef

string

lastTransitError

string

originProtocolNumber

string

protocolGeneratedAt

string<date-time>

protocolNumber

string

sourceProduct

string

urgentRequestedAt

string<date-time>

Credenciais

Configurações de fontes de entrada

Transferências

Auditoria

Tratamento de erros

Create outbound transfer

Autorizações

Cabeçalhos

Corpo

Resposta