Voltar ao site
Contas de câmbio

Enviar documento da conta de destino

POST/v1/fx/payout-accounts/{id}/documents

Anexa o documento da operação a uma conta PENDING_DOCUMENT (SWIFT para terceiro). Aceita PDF, JPEG ou PNG de até 8 MB; o corpo inteiro, com os campos, cabe no limite de 10 MB do gateway.

  • type: INVOICE, PURCHASE_ORDER, DELIVERY_SLIP, CONTRACT, CUSTOMS_DECLARATION, BILL_OF_LADING ou OTHER.
  • Aceito o documento, a conta passa a ACTIVE.
  • Merchant sem câmbio habilitado → 422 FX.NOT_ENABLED.
  • Sem o escopo exigido → 403 AUTH.ENTITLEMENT_MISSING.

Authorization

kodanoOAuth fx:payout-accounts:write
headerAuthorizationBearer <token>

Token obtido no Zitadel do ambiente (POST /oauth/v2/token), fora do host da API, e enviado em Authorization: Bearer <access_token>.

  • Sandbox: https://kodano-uat-p55zt6.us1.zitadel.cloud/oauth/v2/token
  • Produção: https://kodano-prod-qe8hbt.us1.zitadel.cloud/oauth/v2/token

Use sempre o tokenUrl devolvido na emissão da credencial. Duas variantes: private_key_jwt (preferida; grant urn:ietf:params:oauth:grant-type:jwt-bearer com assertion RS256 assinada pela chave da credencial, iss = sub = userId, aud = authority do Zitadel, kid = keyId) e client_secret (grant client_credentials). O OpenAPI só modela a segunda.

O parâmetro scope do token é OIDC, não os escopos da API: openid urn:zitadel:iam:org:project:id:<projectId da API>:aud urn:zitadel:iam:user:resourceowner. Sem o :aud a API responde 401 AUTH.TOKEN_INVALID; sem resourceowner, 403 AUTH.TENANT_MISMATCH.

Os 28 escopos abaixo são os entitlements concedidos à credencial pelos produtos de integração (produto:recurso:ação; write não implica read), avaliados a cada requisição; não são pedidos no token. O tenant vem da organização do token; o merchant, de X-Merchant-Id. Revogar a credencial nega os tokens já emitidos em até 60 s.

Scope: fx:payout-accounts:write

Path Parameters

id*string

Id da conta de destino, fxa_ + 32 hexadecimais. Inexistente, malformado ou de outro merchant → 404 FX.PAYOUT_ACCOUNT_NOT_FOUND.

Header Parameters

X-Merchant-Id*string

Merchant da operação (mrc_ + Guid sem hífens, minúsculo). Obrigatório com credencial de organização (ausente → 400 MERCHANT.HEADER_REQUIRED); com credencial de merchant é opcional (ausente = o próprio merchant). Malformado, repetido, inexistente ou de outro tenant → 403 MERCHANT.FORBIDDEN (nunca 404). Vazio = ausente.

Match^mrc_[0-9a-f]{32}$
X-Correlation-Id?string

Opcional, sempre ecoado na resposta e repetido em correlationId do Problem. Ausente ou inválido → o serviço gera UUID v7.

Match^[A-Za-z0-9._-]{1,64}$

Request Body

Arquivo e tipo do documento.

multipart/form-data
  1. body
type*string
Value in"INVOICE""PURCHASE_ORDER""DELIVERY_SLIP""CONTRACT""CUSTOMS_DECLARATION""BILL_OF_LADING""OTHER"
file*file

PDF, JPEG ou PNG, até 8 MB.

Formatbinary

Response Body

Documento anexado.

application/json
  1. response
id*string
Match^fxa_[0-9a-f]{32}$
displayName*string
rail*FxRail

Meio de entrega do dólar na conta de destino.

Value in"ACH""WIRE""SWIFT""SEPA"
currency*"USD"
Value in"USD"
holderName*string
bankName*string|null
maskedAccount*string

Só os últimos 4 dígitos.

label*string
status*FxPayoutAccountStatus
Value in"ACTIVE""PENDING_DOCUMENT""INACTIVE"
createdAt*string
Formatdate-time
Example Request
curl -X POST 'https://api.sandbox.kodano.com.br/v1/fx/payout-accounts/fxa_0192f4a0b2c14d3e7f8a9b0c1d2e3f4a/documents' \  -H 'X-Merchant-Id: mrc_0f8fad5bd9cb469fa16570867728950e' \  -H 'X-Correlation-Id: erp-7f3a-0010' \  -F 'type=INVOICE' \  -F 'file=string'
Example Response
{  "id": "fxa_0192f4a0b2c14d3e7f8a9b0c1d2e3f4a",  "displayName": "Fornecedor EUA",  "rail": "SWIFT",  "currency": "USD",  "holderName": "Global Trade LLC",  "bankName": "Chase",  "maskedAccount": "••••3000",  "label": "Supplier GmbH · SWIFT · ••••3000",  "status": "ACTIVE",  "createdAt": "2026-11-02T14:50:00Z"}

Desativar conta de destino DELETE

Anterior