Cotações (FX)

A API de Cotação FX permite solicitar e travar taxas de câmbio para um corredor de moedas e valor específicos. O quoteId retornado garante a taxa por uma janela fixa, protegendo você e seu cliente de flutuações de câmbio durante o fluxo da transação.

Como Funciona a Precificação

Dois componentes determinam o custo para o usuário final:

• Spread de FX — Sua margem sobre a taxa de câmbio, configurada por corredor pela Inyo durante o onboarding.
• Tarifa de Transação — Uma tarifa por transação, também configurada durante o onboarding. Dependendo do seu contrato, você pode sobrescrever tarifas no nível da cotação (ex.: para ofertas promocionais de "tarifa zero").

Tipos de Valor

Ao solicitar uma cotação, o campo amountType controla como as tarifas são aplicadas:

Solicitando uma Cotação

Endpoint: POST /organizations/{tenant}/payout/quotes
Autenticação: Nível de agente (x-api-key + x-agent-id + x-agent-api-key)

Corpo da Requisição

Exemplo de Requisição

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/payout/quotes \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "fromCurrency": "USD",
  "toCurrency": "BRL",
  "amount": 1000,
  "fee": {
    "amount": 4.99,
    "currency": "USD"
  },
  "amountType": "NET"
}'

Exemplo de Resposta

{
  "quotes": [
    {
      "id": "f28be3f9-ad4d-4a6c-a85d-ae5515a4a158",
      "agentId": "8500786a-68e9-45fd-b1d8-c590f1e06450",
      "fromAsset": "USD",
      "toAsset": "BRL",
      "effectiveRate": 5.39023,
      "totalCost": {
        "amount": 1004.99,
        "currency": "USD"
      },
      "fee": {
        "amount": 4.99,
        "currency": "USD"
      },
      "amountType": "NET",
      "product": "REMITTANCE",
      "expireAt": "2025-09-15T12:07:01Z",
      "createdAt": "2025-09-15T11:37:01Z",
      "sourceAmount": {
        "amount": 1000.00,
        "currency": "USD"
      },
      "destinationAmount": {
        "amount": 5390.23,
        "currency": "BRL"
      }
    }
  ]
}

Campos da Resposta

Exemplo Passo a Passo de Conversão

Cenário: Converter 1.000 USD → BRL

Consultando uma Cotação

Endpoint: GET /organizations/{tenant}/payout/quotes/{quoteId}
Autenticação: Nível de agente

curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/payout/quotes/$QUOTE_ID \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY"

Use este endpoint para verificar se uma cotação ainda é válida antes de enviar uma transação.

Lidando com a Expiração de Cotações

As cotações são válidas por 30 minutos por padrão. A janela é configurável por tenant (até 24 horas) — verifique expireAt em vez de presumir uma duração. Siga estas diretrizes:

• Sempre verifique expireAt antes de usar uma cotação em uma transação.
• Atualize proativamente — solicite uma nova cotação quando ~90% do período de validade tiver decorrido.
• Nunca faça cache de cotações — ao contrário de destinos e listas de bancos, cotações são sensíveis ao tempo e devem ser buscadas sempre atualizadas.
• Cotações expiradas serão rejeitadas — se você enviar uma transação com um quoteId expirado, a API retorna um erro 400 ou 422.

Padrão de UX Recomendado

1. User selects amount and destination  →  Request quote
2. Display rate, fees, and receive amount
3. Start a countdown timer based on expireAt
4. If timer reaches ~80%, show "Rate expiring" warning
5. If expired, auto-refresh and update the display
6. On "Confirm", immediately submit the transaction with the quoteId

Todos os Endpoints

Documentação Interativa da API