Voltar ao site
Câmbio

Consultar operação de câmbio

GET/v1/fx/operations/{id}

Detalhe, linha do tempo e instruções de pagamento ativas.

  • Acompanhe a operação por polling neste endpoint (a cada 5 a 10 s enquanto estiver em andamento): o desfecho final é SETTLED, EXPIRED, FAILED ou REFUNDED.
  • ACTION_REQUIRED: o pagamento foi recebido mas o envio não se completou; a Kodano abre a devolução e acompanha com você pelo supportReference.
  • supportReference é o código curto para falar com o suporte da Kodano.
  • Sem o escopo exigido → 403 AUTH.ENTITLEMENT_MISSING.

Authorization

kodanoOAuth fx:operations:read
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:operations:read

Path Parameters

id*string

Id da operação, fxo_ + 32 hexadecimais. Inexistente, malformado ou de outro merchant → 404 FX.OPERATION_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}$

Response Body

Operação.

application/json
  1. response
id*string
Match^fxo_[0-9a-f]{32}$
type*"SPOT"

Câmbio à vista. Único valor hoje.

Value in"SPOT"
status*FxOperationStatus

UNKNOWN: a Kodano ainda não confirmou a criação. AWAITING_PAYMENT: Pix à espera do pagamento. PAYMENT_RECEIVED, CONVERTING, PAYOUT_IN_PROGRESS: em andamento. SETTLED: dólar entregue (terminal). EXPIRED: Pix não pago no prazo (terminal). FAILED: falha sem dinheiro recebido (terminal). ACTION_REQUIRED: pagamento recebido sem entrega, a Kodano abre a devolução. REFUND_PENDING, REFUNDED (terminal), REFUND_FAILED: devolução.

Value in"UNKNOWN""AWAITING_PAYMENT""PAYMENT_RECEIVED""CONVERTING""PAYOUT_IN_PROGRESS""SETTLED""EXPIRED""FAILED""ACTION_REQUIRED""REFUND_PENDING""REFUNDED""REFUND_FAILED"
direction*"BRL_TO_USD"

Do real para o dólar. Única direção hoje.

Value in"BRL_TO_USD"
rate*|

Reais por dólar da operação; nulo em UNKNOWN.

payin*|null
payout*|null
fees*array<>
repricedFromQuote*boolean

true quando os valores da operação diferem da cotação.

payoutAccount*|null
customerReference*string|null
paymentInstructions*|

Presente enquanto a operação espera o pagamento (AWAITING_PAYMENT); nulo depois.

timeline*array<>
supportReference*string

Código curto para falar com o suporte da Kodano.

receiptAvailable*boolean
createdAt*string
Formatdate-time
updatedAt*string
Formatdate-time
Example Request
curl -X GET 'https://api.sandbox.kodano.com.br/v1/fx/operations/fxo_0192f4a2d4e35f6a9b0c1d2e3f4a5b6c' \  -H 'X-Merchant-Id: mrc_0f8fad5bd9cb469fa16570867728950e' \  -H 'X-Correlation-Id: erp-7f3a-0010'
Example Response
{  "id": "fxo_0192f4a2d4e35f6a9b0c1d2e3f4a5b6c",  "type": "SPOT",  "status": "SETTLED",  "direction": "BRL_TO_USD",  "rate": "5.2400",  "payin": {    "amount": 500260,    "currency": "BRL"  },  "payout": {    "amount": 95412,    "currency": "USD"  },  "fees": [    {      "type": "COVER_FEE",      "rail": "ACH",      "amount": {        "amount": 262,        "currency": "BRL"      },      "reference": {        "amount": 50,        "currency": "USD"      }    }  ],  "repricedFromQuote": true,  "payoutAccount": {    "id": "fxa_0192f4a0b2c14d3e7f8a9b0c1d2e3f4a",    "label": "Fornecedor EUA · ACH · ••••0288",    "rail": "ACH"  },  "customerReference": "pedido-8841",  "paymentInstructions": null,  "timeline": [    {      "status": "AWAITING_PAYMENT",      "at": "2026-11-02T15:00:30Z"    },    {      "status": "PAYMENT_RECEIVED",      "at": "2026-11-02T15:02:10Z"    },    {      "status": "CONVERTING",      "at": "2026-11-02T15:02:40Z"    },    {      "status": "PAYOUT_IN_PROGRESS",      "at": "2026-11-02T15:03:00Z"    },    {      "status": "SETTLED",      "at": "2026-11-03T14:00:00Z"    }  ],  "supportReference": "GA-7K2M9Q",  "receiptAvailable": true,  "createdAt": "2026-11-02T15:00:30Z",  "updatedAt": "2026-11-03T14:00:00Z"}

Criar operação de câmbio POST

Anterior

Obter comprovante da operação GET

Próxima