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. Dependendo do seu contrato, você também pode sobrescrever o spread por cotação — como percentual ou como valor fixo. Veja Ajustes de Spread.
• 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").

Tanto o spread quanto a tarifa configurados podem ser sobrescritos em uma requisição de cotação individual. Quando você não envia uma sobrescrita, aplicam-se os valores configurados do corredor.

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

Ajustes de Spread

Seu corredor tem um spread de FX configurado, mas se o seu contrato permitir você pode sobrescrevê-lo em uma cotação individual — útil para taxas promocionais, precificação específica por parceiro ou acordos pontuais negociados. A sobrescrita afeta apenas a cotação em que você a envia; não altera a configuração do seu corredor.

Há dois tipos de spread:

Envie a sobrescrita como um objeto spread:

# Spread percentual — 2,5% de margem nesta cotaçã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,
  "spread": { "rate": 0.025, "type": "PERCENTAGE" }
}'

# Spread fixo — subtrai 0,08 da taxa nesta cotaçã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,
  "spread": { "rate": 0.08, "type": "FIXED" }
}'

Precedência — a API resolve o spread nesta ordem:

1. O objeto spread (spread.rate + spread.type), se presente.
2. Caso contrário, spreadRate — um atalho legado que sempre significa uma sobrescrita PERCENTAGE.
3. Caso contrário, o spread configurado do corredor.

spreadRate e o objeto spread são mutuamente exclusivos na prática — se você enviar spread.rate, spreadRate é ignorado. Use o objeto spread em novas integrações; é a única forma de solicitar um spread FIXED.

Sobrescrevendo a Tarifa

A tarifa de transação é uma sobrescrita separada e independente — envie um objeto fee com um amount (e currency opcional). Ela se aplica sobre qualquer spread vigente, e um fee.amount de 0 é a forma de emitir uma cotação promocional sem tarifa.

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