> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /pt/openapi/v3-current/sta.yaml post /v1/transfers openapi: 3.1.0 info: description: >- API for Lerian STA — the participant-side rail that connects the institution to Banco Central do Brasil's STA (Sistema de Transferencia de Arquivos) file-exchange system. It covers outbound and inbound file transfers, BACEN credential management, and inbound source polling configuration. title: Lerian STA API version: v1.2.0 servers: - url: https://api.example.com description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] paths: /v1/transfers: post: tags: - transfers summary: Create outbound transfer description: >- 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. operationId: createTransfer parameters: - description: >- 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. in: header name: X-Idempotency required: true schema: description: >- 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. type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateTransferRequest' description: Outbound transfer creation payload required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/TransferView' description: Created headers: X-Idempotency-Replayed: schema: description: >- true when the response is a replay of the first request with this X-Idempotency key type: string '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Conflict. The idempotency middleware answers it in application/json with title IDEMPOTENCY_CONFLICT while a request with this X-Idempotency key is in flight (X-Idempotency-Replayed: true); retry once it settles. '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Unprocessable Entity. application/problem+json is request validation; application/json is an idempotency refusal (title IDEMPOTENCY_KEY_REUSE, IDEMPOTENCY_OUTCOME_UNRECORDED, IDEMPOTENCY_STATE_UNRECOGNISED or IDEMPOTENCY_RECORD_UNREADABLE): reconcile, never resend. '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error security: - BearerAuth: [] components: schemas: CreateTransferRequest: additionalProperties: false properties: credentialId: type: string documentType: type: string fileName: type: string fileRef: type: string institutionCode: type: string sourceProduct: type: string required: - sourceProduct - documentType - fileRef - fileName type: object TransferView: additionalProperties: false properties: bytesDownloaded: format: int64 type: integer bytesUploaded: format: int64 type: integer createdAt: format: date-time type: string credentialId: type: string currentState: type: string currentStateCode: format: int64 type: integer direction: type: string documentCode: description: >- 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. type: string documentType: description: >- 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. type: string errorCode: type: string expired: type: boolean expiresAt: format: date-time type: string fileName: type: string fileRef: type: string fileSizeBytes: format: int64 type: integer hashMismatchAttempts: description: >- Inbound only: count of downloads whose SHA-256 did not match BACEN's, driving the Inconsistent terminal. null for outbound transfers. format: int64 type: - integer - 'null' id: type: string lastTransitError: type: string originProtocolNumber: type: string protocolGeneratedAt: format: date-time type: string protocolNumber: type: string secondsRemaining: format: int64 type: integer sourceProduct: type: string transmissionAttempts: description: >- Inbound only: count of non-hash download failures, driving the Canceled / DOWNLOAD_FAILED terminal. null for outbound transfers. format: int64 type: - integer - 'null' updatedAt: format: date-time type: string uploadAttempts: description: >- 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. format: int64 type: - integer - 'null' urgentRequestedAt: format: date-time type: string required: - id - direction - credentialId - documentType - fileName - fileSizeBytes - bytesUploaded - bytesDownloaded - currentState - currentStateCode - uploadAttempts - hashMismatchAttempts - transmissionAttempts - createdAt - updatedAt - secondsRemaining - expired type: object ErrorResponse: additionalProperties: false properties: code: examples: - 400 format: int64 type: integer message: examples: - context name is required type: string title: examples: - invalid_request type: string required: - code - title - message type: object Detail: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.