# Obter uma coleção de cotações Antes de poder criar um pagamento, você solicita uma **coleção de cotações**: um conjunto de cotações precificadas para uma transferência proposta. Cada cotação fixa uma taxa de câmbio, o detalhamento das tarifas e uma janela de validade, para que você possa revisar as condições antes de se comprometer com um pagamento. Este guia abrange: 1. Criar uma coleção de cotações, cotando pelo valor de origem ou de destino. 2. Ler a resposta. 3. Tratar o caso em que a cotação expira. 4. Recuperar uma coleção de cotações ou uma cotação individual após a criação. Para o embasamento conceitual, consulte [Cotações](/pt-br/products/payments-direct-2/introduction/concepts/quotes). ## Antes de começar Para seguir este guia, você precisa de: - Acesso ao ambiente UAT da API do Payments Direct. - Um **token de acesso** OAuth2 válido com o escopo `quote_collections:write`. Consulte [Solicitar um token de acesso](/pt-br/products/payments-direct-2/api-docs/developer-guides/request-an-access-token). - As moedas e os países de origem e de destino do pagamento proposto. - Um `payinCategory` que corresponda ao seu modelo de financiamento (`PRE_FUNDING`, `CREDIT_FUNDING` ou `JIT_FUNDING`). Consulte [Métodos de financiamento](/pt-br/products/payments-direct-2/introduction/concepts/funding-methods). - Um `payoutCategory` igual a `BANK` ou `CRYPTO`. ## Etapa 1: Criar uma coleção de cotações `POST /v2/quotes/quote-collection` Uma requisição de coleção de cotações especifica o corredor, a categoria de payout e o valor que você quer precificar. Uma coleção de cotações normalmente contém uma única cotação. ### Parâmetros da requisição | Parâmetro | Obrigatório | Descrição | | --- | --- | --- | | `quoteAmount` | Sim | O valor a cotar. | | `quoteAmountType` | Sim | Se `quoteAmount` é o valor enviado (`SOURCE_AMOUNT`) ou o valor recebido (`DESTINATION_AMOUNT`). | | `sourceCurrency` | Sim | A moeda que você está enviando (ISO 4217, de 3 a 5 caracteres). | | `destinationCurrency` | Sim | A moeda que o beneficiário recebe (ISO 4217, de 3 a 5 caracteres). | | `payinCategory` | Sim | O seu modelo de financiamento: `PRE_FUNDING`, `CREDIT_FUNDING` ou `JIT_FUNDING`. | | `payoutCategory` | Sim | O tipo de payout: `BANK` para pagamentos em conta bancária, `CRYPTO` para pagamentos em ativos digitais. | | `sourceCountry` | Não | O país do remetente (ISO 3166-1 alfa-2). | | `destinationCountry` | Não | O país do beneficiário (ISO 3166-1 alfa-2). | | `destinationBlockchainNetwork` | Não | Obrigatório quando `payoutCategory` é `CRYPTO`. Especifica a rede blockchain do payout. | Cotação por valor de origem Use `SOURCE_AMOUNT` quando você controla quanto quer enviar. A API calcula quanto o beneficiário recebe depois de aplicar a taxa de câmbio e as tarifas. Neste exemplo, o remetente quer enviar **10.000 USD** a um beneficiário no México que recebe em MXN. ```bash curl -i -X POST \ https://api.test.ripple.com/v2/quotes/quote-collection \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "quoteAmount": 10000.00, "quoteAmountType": "SOURCE_AMOUNT", "sourceCurrency": "USD", "destinationCurrency": "MXN", "sourceCountry": "US", "destinationCountry": "MX", "payinCategory": "PRE_FUNDING", "payoutCategory": "BANK" }' ``` Cotação por valor de destino Use `DESTINATION_AMOUNT` quando o beneficiário precisa receber um valor exato, por exemplo ao pagar uma fatura em moeda estrangeira. A API calcula quanto você precisa enviar para cobrir o câmbio e as tarifas. Neste exemplo, o beneficiário precisa receber exatamente **200.000 MXN**. ```bash curl -i -X POST \ https://api.test.ripple.com/v2/quotes/quote-collection \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "quoteAmount": 200000.00, "quoteAmountType": "DESTINATION_AMOUNT", "sourceCurrency": "USD", "destinationCurrency": "MXN", "sourceCountry": "US", "destinationCountry": "MX", "payinCategory": "PRE_FUNDING", "payoutCategory": "BANK" }' ``` ## Etapa 2: Revisar a resposta Uma requisição bem-sucedida retorna HTTP `201` com uma coleção de cotações. O `quoteCollectionId` de nível superior identifica a coleção; o array `quotes` contém a cotação retornada. ```json { "quoteCollectionId": "11111111-aaaa-2222-bbbb-222222222222", "quotes": [ { "quoteId": "7ea3399c-1234-5678-8d8f-d320ea406630", "quoteStatus": "ACTIVE", "quoteAmountType": "SOURCE_AMOUNT", "sourceAmount": 10000.00, "destinationAmount": 204533.30, "sourceCurrency": "USD", "destinationCurrency": "MXN", "sourceCountry": "US", "destinationCountry": "MX", "payoutCategory": "BANK", "payinCategory": "PRE_FUNDING", "adjustedExchangeRate": { "adjustedRate": 20.4136 }, "fees": [ { "totalFee": 14.00, "feeCurrency": "USD", "feeBreakdown": [ { "calculatedFee": 2.00, "feeName": "Fixed service fee", "feeDescription": "Fixed service fee for this transaction." }, { "calculatedFee": 12.00, "feeName": "Variable service fee", "feeDescription": "Variable service fee for this transaction." } ] } ], "createdAt": "2025-11-13T22:44:34.711Z", "expiresAt": "2025-11-13T22:59:34.711Z" } ] } ``` ### Campos principais | Campo | Descrição | | --- | --- | | `quoteCollectionId` | O ID desta coleção. Use-o para recuperar a coleção mais tarde com `GET /v2/quotes/quote-collection/{quote-collection-id}`. | | `quoteId` | O ID de uma cotação individual. Use o `quoteId` para criar um pagamento. | | `quoteStatus` | `ACTIVE` significa que a cotação pode ser usada. `EXPIRED` significa que a janela de validade passou e é necessária uma nova coleção de cotações. | | `payoutCategory` | O tipo de payout desta cotação (`BANK` ou `CRYPTO`). | | `paymentRail` | Quando presente, o payment rail usado nesta cotação (por exemplo, `SPEI`, `ACH`). | | `adjustedExchangeRate.adjustedRate` | A taxa de câmbio que a Ripple aplicará. Essa taxa fica fixada durante toda a janela de validade da cotação. | | `fees[].totalFee` | Tarifa total de serviço da transação. | | `taxes` | Tributos sobre consumo aplicáveis às tarifas da Ripple (VAT, GST e afins). Ausente quando não há tributos aplicáveis. | | `createdAt` / `expiresAt` | A janela de validade da cotação. Por padrão, as cotações são válidas por 15 minutos. | quoteId e paymentId O `quoteId` se torna o `paymentId` quando você cria o pagamento. Armazene-o antes de passar para a próxima etapa. ## Etapa 3: Tratar quando a cotação expira As cotações são válidas por tempo limitado (15 minutos por padrão). Antes de criar um pagamento, verifique se `quoteStatus` é `ACTIVE`. - Se `quoteStatus` for `ACTIVE`, a cotação pode ser usada para criar um pagamento. - Se `quoteStatus` for `EXPIRED`, a cotação não pode mais ser usada. Solicite uma nova coleção de cotações, que refletirá a taxa de câmbio e as tarifas atuais. Use `expiresAt` para implementar uma lógica de atualização no cliente, por exemplo, pedindo a confirmação do usuário antes que a cotação expire, ou recotando automaticamente quando o tempo restante ficar abaixo de um limite. ``` remainingSeconds = expiresAt - now() if remainingSeconds <= 0: request a new quote collection ``` Recotar gera um novo `quoteCollectionId` e novos valores de `quoteId`. ## Etapa 4: Recuperar uma coleção de cotações `GET /v2/quotes/quote-collection/{quote-collection-id}` Use este endpoint para recuperar uma coleção de cotações criada anteriormente, por exemplo em um fluxo assíncrono em que você armazenou o `quoteCollectionId` e está verificando o status da cotação antes de iniciar um pagamento. ```bash curl -i -X GET \ https://api.test.ripple.com/v2/quotes/quote-collection/11111111-aaaa-2222-bbbb-222222222222 \ -H "Authorization: Bearer " ``` O schema da resposta é idêntico ao da resposta do `POST`. Verifique o `quoteStatus` da cotação antes de prosseguir; ela pode ter expirado desde que foi criada. ## Etapa 5: Recuperar uma cotação individual `GET /v2/quotes/{quote-id}` Use este endpoint para recuperar uma cotação específica por ID. ```bash curl -i -X GET \ https://api.test.ripple.com/v2/quotes/7ea3399c-1234-5678-8d8f-d320ea406630 \ -H "Authorization: Bearer " ``` A resposta contém os mesmos campos de uma entrada única do array `quotes`, sem o invólucro `quoteCollectionId`. ## Tratamento de erros Os erros de cotação retornam uma resposta estruturada com um `status` e um array `errors`. Cada erro inclui `code`, `title`, `type`, `description` e `timestamp`. Os códigos de erro usam três prefixos: | Prefixo | Categoria | Causas comuns | | --- | --- | --- | | `USR_` | Erro de validação | Campos obrigatórios ausentes, códigos de moeda inválidos, valores fora da faixa permitida ou valores inválidos de `payinCategory` ou `payoutCategory`. | | `CFG_` | Erro de configuração | Corredor não compatível ou configuração de tenant ausente. | | `SYS_` | Erro de sistema | Falha interna ou upstream na precificação de câmbio. Envie a requisição novamente; entre em contato com o suporte se o erro persistir. | ### Erros de validação comuns **`payoutCategory` ausente**: o endpoint v2 exige `payoutCategory`. Omiti-lo retorna um erro de validação `USR_`. **Códigos de moeda ou de país inválidos**: `sourceCurrency` e `destinationCurrency` precisam ter de 3 a 5 caracteres alfabéticos. `sourceCountry` e `destinationCountry` precisam ser códigos ISO 3166-1 alfa-2 (exatamente 2 caracteres). **Valores de `payinCategory` obsoletos**: `FUNDED` e `T_PLUS_ONE` ainda são aceitos no endpoint v2, mas estão obsoletos. Use `PRE_FUNDING` no lugar de `FUNDED` e `CREDIT_FUNDING` no lugar de `T_PLUS_ONE`. Consulte [Métodos de financiamento](/pt-br/products/payments-direct-2/introduction/concepts/funding-methods). **Corredor não compatível**: se o par de moedas não estiver configurado para o seu tenant, a API retorna um erro `CFG_`. Entre em contato com o seu representante Ripple se o erro persistir. ## Próximos passos Assim que você tiver uma cotação `ACTIVE` e tiver selecionado um `quoteId`, estará pronto para criar um pagamento. Consulte [Criar um pagamento](/pt-br/products/payments-direct-2/api-docs/developer-guides/create-a-payment) para ver o passo a passo completo da etapa de criação do pagamento, incluindo como informar o `quoteId` junto com os IDs da identidade do beneficiário e do instrumento financeiro.