Quote

Un Quote es una cotización que define los términos y condiciones específicos para una transacción financiera —incluyendo las tasas de cambio, las tarifas aplicables y los montos convertidos—. El Quote actúa como un acuerdo preliminar que establece los detalles de la transferencia antes de que se cree la order definitiva.

Definición técnica

Un Quote establece las condiciones de la transferencia usando el source y el destination de los fondos y el payout_method. A partir de esto se determina la tasa de cambio y cualquier tarifa que aplique a la transacción.

Solicita un Quote con POST /quotations:

{
  "source": {
    "currency": "USDR"
  },
  "destination": {
    "country": "VE",
    "currency": "VES",
    "payout_method": { "type": "P2P_PHONE_TRANSFER" }
  },
  "quote": {
    "mode": "SEND_EXACT",
    "amount": "100.00"
  }
}

La respuesta devuelve una cotización con su id, la tasa de cambio fijada, las tarifas y los montos resultantes.

Uso de un Quote para crear una order

Una vez generado el Quote, se utiliza como base para crear una order, garantizando que la transacción se ejecute según las condiciones previamente acordadas. El Quote asegura que las tarifas, la tasa de cambio y el monto transferido permanezcan constantes durante la creación de la order.

La order referencia al Quote mediante quotation_id (POST /orders, con tu referencia de idempotencia en el header X-Idempotency-Key):

{
  "quotation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "metadata": { "invoice_id": "INV-2026-00456", "batch_id": "BATCH-VE-032" },
  "purpose": "FAMILY_SUPPORT",
  "sender": {
    "names": "Ana María",
    "last_names": "Pérez Gómez",
    "document": { "type": "CC", "id": "1020304050", "country": "CO" },
    "country": "CO"
  },
  "destination": {
    "receiver": {
      "names": "Carlos Andrés",
      "last_names": "Rodríguez López",
      "document": { "type": "V", "id": "12345678", "country": "VE" },
      "email": "[email protected]",
      "country": "VE"
    },
    "payment_instructions": {
      "bank_phone_account": { "bank_name": "BNC_VE", "phone_number": "+584121234567", "document_id": "12345678" }
    }
  }
}

El quotation_id vincula la order directamente al Quote generado previamente, usando los términos acordados.

Importancia técnica

• Base para la ejecución de orders — el Quote provee una referencia precisa para crear una order, asegurando que se mantengan las condiciones de la transacción.
• Estabilidad de tarifas y términos — una vez creado un Quote, la tasa de cambio y las tarifas permanecen constantes, sin fluctuaciones inesperadas durante la creación de la order.
• Optimización de costos — permite comparar las condiciones de varias cotizaciones antes de confirmar una transacción, eligiendo la opción más rentable.

Consideraciones

• Validez temporal — los Quotes tienen un tiempo de vida limitado; deben usarse para crear una order antes de que expiren.
• Correspondencia con orders — la order debe crearse con el mismo Quote para mantener la coherencia de las condiciones de la transacción.

Importante

El Quote es una pieza fundamental del proceso de dispersión de fondos: garantiza la transparencia y precisión de los términos de la transacción antes de que se ejecute definitivamente.