# Cotações

As cotações permitem **visualizar o custo total e o resultado de um pagamento proposto antes de iniciá-lo**. Uma cotação reflete a **taxa de câmbio**, as **tarifas** e o **valor a ser entregue** entre uma moeda de origem e uma de destino, e tem **prazo limitado** (as cotações expiram após um período definido). As cotações são centrais no fluxo de pagamento do Payments Direct e devem ser criadas *antes* de você chamar o endpoint de pagamentos.

## O que uma cotação inclui

Uma cotação retorna as informações principais de que você precisa para decidir se prossegue com um pagamento, incluindo:

- **Valores de origem e de destino** (`sourceAmount`, `destinationAmount`), conforme você solicite a cotação pelo valor de origem ou pelo valor de destino. Os valores são arredondados para o número de casas decimais definido pela norma [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) para a moeda em questão (por exemplo, 2 para USD/EUR, 0 para JPY/KRW, 3 para BHD/KWD), com arredondamento HALF_UP.
- **Taxa de câmbio ajustada** (`adjustedExchangeRate`), que reflete a taxa usada na conversão.
- **Tarifas** (`fees`), com o total e itens de detalhamento opcionais.
- **Tributos** (`taxes`), quando aplicáveis (os tributos incidem sobre as tarifas de serviço da Ripple, não sobre o principal).
- **Timestamps e validade** (`createdAt`, `expiresAt`) e um **status** (`ACTIVE` ou `EXPIRED`).


## Como as cotações se encaixam no fluxo de pagamento

Um fluxo típico é:

1. **Criar uma coleção de cotações** para um pagamento proposto (normalmente retorna uma única cotação).
2. **Selecionar uma cotação** (use o quoteId retornado).
3. **Criar o pagamento** usando as informações da cotação.


Importante
No Payments Direct, uma cotação precisa ser aceita ou usada antes de expirar. As cotações vencidas são marcadas como `EXPIRED` e não podem ser usadas para criar pagamentos.

Nota de implementação
Internamente, os IDs de cotação são usados na criação do pagamento de modo que o `quoteId` utilizado se torna o `paymentId`. Garanta que a sua integração trate os identificadores de cotação de forma consistente nas etapas de cotação → pagamento.

## Coleções de cotações vs. cotações

A API usa a terminologia "quote collection", mas hoje, no Payments Direct, uma coleção de cotações normalmente contém uma única cotação. A coleção existe para permitir a recuperação e a rastreabilidade do evento de cotação e para viabilizar uma expansão futura a várias opções de cotação.

## Expiração e status da cotação

As cotações têm prazo limitado:

- `quoteStatus=ACTIVE` significa que a cotação pode ser usada para criar um pagamento.
- `quoteStatus=EXPIRED` significa que a cotação não é mais válida e precisa ser gerada novamente.
- Use `expiresAt` para implementar uma lógica no cliente (por exemplo, atualizar a cotação se estiver perto de a cotação expirar).


## Tributos nas cotações (apenas sobre tarifas)

Nas jurisdições em que a Ripple precisa cumprir normas de tributos sobre consumo (VAT/GST etc.), as respostas de cotação podem incluir tributos aplicados às tarifas de serviço da Ripple (componentes fixos e variáveis), e não ao valor principal do pagamento.

**Aspectos principais:**

- O cálculo dos tributos dá transparência de custo antecipada.
- Os tributos são calculados sobre a **parcela das tarifas**, não sobre o valor transferido.
- Se não houver tributos aplicáveis (ou se o tributo calculado for zero), a API não inclui o objeto `taxes` na resposta.


## Endpoints

Use estes endpoints para criar e recuperar cotações:

- `POST /v2/quotes/quote-collection` — cria uma coleção de cotações para um pagamento proposto.
- `GET /v2/quotes/quote-collection/{quote-collection-id}` — recupera uma coleção de cotações criada anteriormente.
- `GET /v2/quotes/{quote-id}` — recupera uma cotação específica por ID.


Para um guia passo a passo sobre como solicitar e usar cotações, consulte [Obter uma coleção de cotações](/pt-br/products/payments-direct-2/api-docs/developer-guides/fetch-a-quote-collection).

## Modelo de financiamento (payinCategory)

O campo `payinCategory` especifica como você financia o pagamento. Os seguintes valores são aceitos:

| Valor | Descrição |
|  --- | --- |
| `PRE_FUNDING` | O pagamento é financiado por um saldo que você depositou previamente na Ripple. Use este valor em modelos de conta com aporte prévio, em que você mantém um saldo de ledger pré-financiado. |
| `CREDIT_FUNDING` | O pagamento é liquidado por uma fatura em aberto. A Ripple executa o pagamento e depois fatura o valor para você. |
| `JIT_FUNDING` | O pagamento é financiado just-in-time: você precisa transferir os recursos para a sua conta de ledger da Ripple antes de o pagamento expirar. Consulte [Pagamentos financiados via JIT](#pagamentos-financiados-via-jit) abaixo. |
| `FUNDED` | **Obsoleto.** Equivalente a `PRE_FUNDING`. Ainda é aceito nos endpoints de cotação v2; migre para `PRE_FUNDING` quando puder. |
| `T_PLUS_ONE` | **Obsoleto.** Equivalente a `CREDIT_FUNDING`. Ainda é aceito nos endpoints de cotação v2; migre para `CREDIT_FUNDING` quando puder. |


Aviso de descontinuação
`FUNDED` e `T_PLUS_ONE` estão obsoletos e serão removidos em uma versão futura. O endpoint de cotação v2 aceita, no momento, os cinco valores. As novas integrações devem usar `PRE_FUNDING`, `CREDIT_FUNDING` ou `JIT_FUNDING`.

### Pagamentos financiados via JIT

Quando você usa `JIT_FUNDING`, o pagamento entra no estado `AWAITING_FUNDING` depois de criado. Você precisa transferir os recursos necessários para a sua conta de ledger da Ripple antes do timestamp `jitFundingExpiresAt` do objeto de pagamento. Se o financiamento não for recebido a tempo, o pagamento expira e você precisa criar uma nova cotação e um novo pagamento.

Para mais informações sobre os estados do pagamento, incluindo `AWAITING_FUNDING`, consulte [Ciclo de vida do pagamento](/pt-br/products/payments-direct-2/introduction/concepts/payment-lifecycle).

## Dados obrigatórios para cotar

Para criar uma coleção de cotações, informe:

- `quoteAmount` e `quoteAmountType` (`SOURCE_AMOUNT` ou `DESTINATION_AMOUNT`)
- `sourceCurrency`, `destinationCurrency`
- `sourceCountry`, `destinationCountry`
- `payinCategory` (por exemplo, `PRE_FUNDING`, `CREDIT_FUNDING`, `JIT_FUNDING`)
- `payoutCategory` (por exemplo, `BANK`, `CRYPTO`)
- Opcional: `destinationBlockchainNetwork` ao cotar pagamentos em criptomoedas.


## Tratamento de erros

Os erros do Quote Service são padronizados em categorias como:

- **AUTH_xxx** erros de autorização (token ausente ou inválido)
- **USR_xxx** erros de validação (campos da requisição ausentes ou inválidos)
- **SYS_xxx** falhas internas ou upstream


Os erros retornam um objeto estruturado com status e um array errors[] (code, title, type, description, timestamp).

## Boas práticas

- Use `SOURCE_AMOUNT` quando o remetente sabe quanto quer enviar.
- Use `DESTINATION_AMOUNT` quando o remetente precisa que o beneficiário receba um valor exato.


## Exemplo: criar uma coleção de cotações

**Requisição**

```bash
curl -i -X POST \
  http://127.0.0.1:4000/_mock/products/payments-direct-2/@v2026.03/api-docs/payments-direct-api/payments-direct-2-api/v2/quotes/quote-collection \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "quoteAmount": 123.45,
    "quoteAmountType": "SOURCE_AMOUNT",
    "sourceCurrency": "USD",
    "destinationCurrency": "MXN",
    "sourceCountry": "US",
    "destinationCountry": "PH",
    "payoutCategory": "BANK",
    "payinCategory": "PRE_FUNDING",
    "destinationBlockchainNetwork": "Ethereum"
  }'
```

**Resposta (trecho)**

```json
{
  "quoteCollectionId": "11111111-aaaa-2222-bbbb-222222222222",
  "quotes": [
    {
      "quoteId": "7ea3399c-1234-5678-8d8f-d320ea406630",
      "quoteStatus": "ACTIVE",
      "quoteAmountType": "SOURCE_AMOUNT",
      "sourceAmount": 123.45,
      "destinationAmount": 2438.19,
      "sourceCurrency": "USD",
      "destinationCurrency": "MXN",
      "sourceCountry": "US",
      "destinationCountry": "MX",
      "payoutCategory": "BANK",
      "payinCategory": "PRE_FUNDING",
      "adjustedExchangeRate": {
        "adjustedRate": 2
      },
      "fees": [
        {
          "totalFee": 12.23,
          "feeCurrency": "USD",
          "feeBreakdown": [
            {
              "calculatedFee": 2.43,
              "feeName": "Service fee",
              "feeDescription": "The service fee charged for this transaction."
            }
          ]
        }
      ],
      "taxes": [
        {
          "totalTaxes": 5.12,
          "taxCurrency": "USD",
          "taxBreakdown": [
            {
              "taxAmount": 2.43,
              "taxName": "ISS/ VAT/ GST etc",
              "taxDescription": "The service fee tax charged for this transaction.",
              "taxRate": 5
            }
          ]
        }
      ],
      "createdAt": "2025-11-02T18:26:00.000123Z",
      "expiresAt": "2025-11-02T18:26:00.000123Z",
      "destinationBlockchainNetwork": "Ethereum"
    }
  ]
}
```