YourVisa Travel Visa MCP

Servidor MCP remoto de solo lectura que permite a los asistentes de IA consultar requisitos y tarifas de visas, eVisa, ETA y ESTA por país, y obtener enlaces oficiales de solicitud. Se requiere clave de API.

Ver en yourvisa.aiPrueba este MCPPatrocinado

Servidor MCP alojado

npx add-mcp 'https://mcp.yourvisa.ai/api/mcp'

Se instala en Claude Code, Codex, Cursor y más

Documentación

Base URL:

https://api.yourvisa.ai

¿Estás creando un asistente de viajes o inmigración impulsado por IA? Lee nuestra historia sobre cómo un servidor MCP de Travel Visa evitó que el chatbot de una agencia diera respuestas incorrectas sobre visados, y nuestro análisis técnico sobre Integración de servidores MCP para documentación de viajes en e-visa, ETA y ETIAS.

Bienvenido a la documentación de YourVisa.ai

Esta documentación completa de la API te guiará en la integración de nuestros servicios de visados en tu aplicación. Tanto si eres principiante como desarrollador experimentado, encontrarás todo lo que necesitas para empezar.

Rápido y Fiable

Tiempos de respuesta rápidos con garantía de disponibilidad del 99,9%

Seguro

Seguridad de nivel empresarial con autenticación OAuth 2.0

Bien Documentado

Ejemplos claros y explicaciones detalladas para cada endpoint

Guía de Inicio Rápido

1

Obtén tus Credenciales de API

Regístrate para obtener una cuenta y genera tu clave y secreto de API de producción y/o sandbox desde el panel de control.

Key: your-api-key Secret: your-api-secret

Genera un Token de Acceso

Envía tu clave y secreto mediante POST para obtener un token bearer. La respuesta incluye agencyId e isApiSandbox (true para credenciales sandbox, false para producción). No envíes un campo de entorno: se deduce de qué credenciales coinciden.

curl -X POST "https://api.yourvisa.ai/unprotected/generate-programmatic-token" -H "Content-Type: application/json" -d '{"key": "your-api-key","secret": "your-api-secret"}'

Realiza tu Primera Llamada a la API

Usa el token para autenticar tus solicitudes a los endpoints protegidos.

curl -X GET "https://api.yourvisa.ai/agents-api/get-products-from-countries?from=IL&to=IN" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

URL Base

Todas las solicitudes a la API deben realizarse a la siguiente URL base:

https://api.yourvisa.ai

Autenticación

La mayoría de los endpoints requieren autenticación mediante un token Bearer. Incluye el token en el encabezado Authorization de tus solicitudes:

Authorization: Bearer YOUR_ACCESS_TOKEN

Importante: Mantén tus credenciales de API seguras. Nunca las expongas en código del lado del cliente ni en repositorios públicos. Usa credenciales sandbox para pruebas de integración; los tokens sandbox marcan las reservas como de prueba y omiten los cargos de saldo.

Manejo de Errores

La API utiliza códigos de estado HTTP estándar para indicar éxito o fracaso:

  • 200Éxito - Solicitud completada correctamente
  • 400Solicitud Incorrecta - Parámetros inválidos o campos obligatorios faltantes
  • 401No Autorizado - Token de acceso inválido o caducado
  • 404No Encontrado - Recurso no encontrado
  • 500Error Interno del Servidor - Algo salió mal en nuestro lado

¿Necesitas Ayuda?

Si tienes preguntas o necesitas asistencia, no dudes en contactarnos:

post /unprotected/generate-programmatic-token

Generar token programático

Intercambia una clave y secreto de API de Agents por un token de acceso JWT (válido durante 12 horas). Envía credenciales de producción o sandbox: el entorno se deduce de qué clave coincide en la base de datos. No envíes un campo de entorno. Cuando coinciden credenciales sandbox, la respuesta incluye isApiSandbox: true y el JWT lleva la misma marca para que las reservas creadas con ese token se marquen como de prueba.

Cuerpo de la Solicitud

Esquema: GenerateProgrammaticToken

key Obligatoriostring

Clave de API de producción o sandbox

secret Obligatoriostring

Secreto de API de producción o sandbox correspondiente

Respuestas

200 Respuesta exitosa

Esquema: GenerateProgrammaticTokenResponse

success boolean

Predeterminado: true

token string

Token de acceso JWT válido durante 12 horas

agencyId string

ID de la agencia asociada a las credenciales de API

isApiSandbox boolean

true cuando la clave/secreto proporcionados son credenciales sandbox; false para producción. Los tokens sandbox marcan las reservas creadas mediante la API de Agents como de prueba y omiten los cargos de saldo.

Ejemplo false

400 Solicitud incorrecta

Esquema: GenerateProgrammaticTokenBadRequest

success boolean

Predeterminado: false

message string

Valores posibles:

Faltan camposEl usuario con acceso programático no existe

404 No encontrado

500 Error interno del servidor

Pruébalo

curl -X POST "https://api.yourvisa.ai/unprotected/generate-programmatic-token" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "string",
  "secret": "string"
}'

get /agents-api/get-products-from-countries?from={from}&to={to}

Obtener productos de países

Requiere Autenticación (Token Bearer)

Parámetros

from Obligatoriopathstring

País de origen

to Obligatoriopathstring

País de destino

currency pathstring

Moneda de visualización opcional (código ISO 4217 compatible). Cuando se proporciona, cada producto paymentDetails incluye displayPricing con montos convertidos.

Valores posibles:

AUD BRL CAD CHF CNY CZK DKK EGP ETB EUR GBP GHS HKD HUF IDR ILS INR ISK JPY KES KRW MAD MXN MYR NGN NOK NZD PHP PLN RON SEK SGD THB TND TRY TZS UGX USD XAF XOF ZAR

Country codes string

AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CK, CR, CI, HR, CU, CW, CY, CZ, CD, DK, DJ, DM, DO, TL, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, XK, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, KP, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, KR, SS, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, VG, UA, AE, GB, US, UM, UY, VI, UZ, VU, VA, VE, VN, WF, EH, YE, ZM, ZW

Tipos de Respuesta

Tipo de respuesta - Obtener productos de países

Respuestas

200 Respuesta exitosa

Esquema: GetProductsFromCountriesSupportedResponse

success boolean

Predeterminado: true

products array

Matriz de objeto(click para ver propiedades)

400 Solicitud incorrecta

Esquema: GetProductsFromCountriesBadRequest

success boolean

Predeterminado: false

message string

Valores posibles:

El país de origen (from) o el país de destino (to) no se proporcionaEl código de país (from o to) no es válidoEl código de moneda no es válido. Valores compatibles: AUD, BRL, CAD, CHF, CNY, CZK, DKK, EGP, ETB, EUR, GBP, GHS, HKD, HUF, IDR, ILS, INR, ISK, JPY, KES, KRW, MAD, MXN, MYR, NGN, NOK, NZD, PHP, PLN, RON, SEK, SGD, THB, TND, TRY, TZS, UGX, USD, XAF, XOF, ZAR

401 No Autorizado

Esquema: Unauthorized

success boolean

Predeterminado: false

message string

Valores posibles:

No tienes credencialesNo tienes permisoToken de acceso inválidoTu token de acceso no es válido o ha caducado

404 No encontrado

500 Error interno del servidor

Pruébalo

curl -X GET "https://api.yourvisa.ai/agents-api/get-products-from-countries?from={from}&to={to}" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

get /agents-api/get-supported-destinations?from={from}

Obtener códigos de países de destino compatibles

Devuelve códigos de país de destino ISO 3166-1 alfa-2 distintos que tienen productos de visado con isSupportedVisa true para el país de origen dado. El país de origen nunca se incluye como destino.

Requiere Autenticación (Token Bearer)

Parámetros

from Obligatoriopathstring

País de origen

Respuestas

200 Respuesta exitosa

Esquema: GetSupportedDestinationsResponse

success boolean

Predeterminado: true

countryCodes array

Matriz de string

400 Solicitud incorrecta

Esquema: GetSupportedDestinationsBadRequest

success boolean

Predeterminado: false

message string

Valores posibles:

El país de origen (from) no se proporcionaEl código de país (from) no es válido

401 No Autorizado

Esquema: Unauthorized

success boolean

Predeterminado: false

message string

Valores posibles:

No tienes credencialesNo tienes permisoToken de acceso inválidoTu token de acceso no es válido o ha caducado

500 Error interno del servidor

Pruébalo

curl -X GET "https://api.yourvisa.ai/agents-api/get-supported-destinations?from={from}" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

get /agents-api/get-specific-product-details?productId=66a9ebe9572eb2904562c3ad

Obtener detalles de un producto específico

Requiere Autenticación (Token Bearer)

Parámetros

productId Obligatoriopathstring

ID del producto

Respuestas

200 Respuesta exitosa

Esquema: GetSpecificProductDetailsResponse

success boolean

Predeterminado: true

productInputDetails array

Matriz de objeto(click para ver propiedades)

productDetails object

400 Solicitud incorrecta

Esquema: GetSpecificProductDetailsBadRequest

success boolean

Predeterminado: false

message string

401 No Autorizado

Esquema: Unauthorized

success boolean

Predeterminado: false

message string

Valores posibles:

No tienes credencialesNo tienes permisoToken de acceso inválidoTu token de acceso no es válido o ha caducado

404 No encontrado

500 Error interno del servidor

Pruébalo

curl -X GET "https://api.yourvisa.ai/agents-api/get-specific-product-details?productId=66a9ebe9572eb2904562c3ad" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

post /agents-api/commit-new-visa

Crear un nuevo producto de visado reservado

Confirma una nueva reserva de visado con los datos del cliente mediante la API. La combinación isPaidByCustomer=true con isFilledByCustomer=false (el cliente paga, la agencia completa) no es compatible y devuelve 400. Cuando se proporciona corporateIdForCharging, la reserva es pagada por la organización y se factura a esa corporación (saldo rotativo o back-to-back según la configuración de facturación corporativa). La agencia debe tener isAllowedToChargeCorporatesViaApi habilitado por el administrador de YourVisa.ai. Si el token Bearer se emitió con credenciales de API sandbox (isApiSandbox: true desde POST /unprotected/generate-programmatic-token), la reserva se marca automáticamente como visado de prueba y se omiten los cargos de saldo.

Requiere Autenticación (Token Bearer)

Cuerpo de la Solicitud

Esquema: CommitNewVisaRequest

productId Obligatoriostring

El ID del producto de visado

isPaidByCustomer boolean

Si el cliente pagará (true) o el agente pagará (false). No puede ser true cuando isFilledByCustomer es false.

isFilledByCustomer boolean

Si el cliente completará el formulario (true) o el agente lo completará (false). No puede ser false cuando isPaidByCustomer es true.

customerFirstName Obligatoriostring

Nombre del cliente

customerLastName Obligatoriostring

Apellido del cliente

customerEmail Obligatoriostring

Dirección de correo electrónico del cliente

voucherInvoiceNumber string

Referencia opcional de vale o factura almacenada con la reserva

Ejemplo "INV-2026-001"

travelFileNumber string

Número de archivo de viaje opcional de Travel CRM vinculado a esta reserva

Ejemplo "1252813"

messageForTraveler string

Mensaje opcional incluido en el correo electrónico de solicitud del viajero cuando isFilledByCustomer es true. Solo letras, números, espacios y puntuación básica (.,!? ' -).

Ejemplo "Please complete the form and upload a clear passport scan."

preferredLanguage string

Código de idioma opcional para correos electrónicos dirigidos al viajero: en (inglés, predeterminado), de (alemán), es (español), ru (ruso), he (hebreo), ar (árabe), fr (francés)

Valores posibles:

endeesruhearfr

corporateIdForCharging string

ID corporativo opcional para facturar esta reserva en lugar del saldo de la agencia. Requiere que la agencia tenga isAllowedToChargeCorporatesViaApi, que la corporación pertenezca a la agencia y que la corporación tenga una configuración de pago válida (tarjeta guardada para back-to-back, o recarga automática con tarjeta guardada para saldo rotativo). Cuando se establece, isPaidByCustomer se trata como false y el correo electrónico del viajero se agrega a la lista blanca corporativa.

Ejemplo "66a9ebe9572eb2904562c3ae"

customKeys object

Pares clave-valor personalizados opcionales para seguimiento o metadatos (máximo 5 claves). Ejemplo: {"customKey1": "customKey1 value", "customKey2": "customKey2 value", "customKey3": "customKey3 value", "customKey4": "customKey4 value", "customKey5": "customKey5 value"}

Respuestas

201 Producto reservado creado exitosamente

Esquema: CommitNewVisaResponse

success boolean Ejemplo true

bookedProductId string

Ejemplo "66a9ebe9572eb2904562c3ae"

isPaymentTest boolean

true cuando la reserva se creó como visa de prueba (credenciales de API de sandbox o modo de prueba de integración de agencia/corporativo). Las reservas de prueba omiten los cargos de saldo.

Ejemplo false

message string

Ejemplo "Visa booking created successfully"

400 Solicitud incorrecta - error de validación

Esquema: CommitNewVisaBadRequest

success boolean

message string

401 No autorizado - token inválido o faltante

Esquema: Unauthorized

success boolean

Predeterminado: false

message string

Valores posibles:

No tienes credencialesNo tienes permisoToken de acceso inválidoTu token de acceso no es válido o ha expirado

403 Prohibido - la agencia no tiene permitido crear reservas pagadas por la agencia

Esquema: CommitNewVisaForbidden

success boolean

message string

Ejemplo "Your agency is not allowed to create agent-paid bookings"

404 Producto o agencia no encontrado

Esquema: CommitNewVisaNotFound

success boolean

message string

Pruébalo

curl -X POST "https://api.yourvisa.ai/agents-api/commit-new-visa" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
  "productId": "string",
  "isPaidByCustomer": true,
  "isFilledByCustomer": true,
  "customerFirstName": "string",
  "customerLastName": "string",
  "customerEmail": "string",
  "voucherInvoiceNumber": "string",
  "travelFileNumber": "string",
  "messageForTraveler": "string",
  "preferredLanguage": "en",
  "corporateIdForCharging": "string",
  "customKeys": {
    "customKey1": "customKey1 value",
    "customKey2": "customKey2 value",
    "customKey3": "customKey3 value",
    "customKey4": "customKey4 value",
    "customKey5": "customKey5 value"
  }
}'

post /agents-api/get-application-link

Generar enlace de solicitud para una reserva existente

Genera una URL de solicitud con token incorporado para un producto ya reservado. Úsalo después de crear una reserva mediante POST /agents-api/commit-new-visa, o después de recibir un bookedProductId desde una transferencia de pago instantáneo. Establece isIframe en true (predeterminado) para una URL compatible con iframe, o false para la URL regular del asistente de visa. Nota: este enlace solo es válido para solicitudes de visa que aún no se han enviado. El entorno se infiere del token Bearer: los tokens de sandbox solo pueden generar enlaces para reservas de prueba; los tokens de producción solo pueden generar enlaces para reservas que no son de prueba.

Requiere Autenticación (Token Bearer)

Cuerpo de la Solicitud

Esquema: GetApplicationLinkRequest

bookedProductId Requeridostring

El ID del producto reservado existente. Puede provenir de POST /agents-api/commit-new-visa o de una URL de retorno de pago instantáneo del socio.

langKey string

Preferencia de idioma opcional para el formulario de solicitud: en (inglés, predeterminado), de (alemán), es (español), ru (ruso), he (hebreo), ar (árabe), fr (francés)

Valores posibles:

endeesruhearfr

isIframe boolean

Si se genera una URL de iframe (true, predeterminado) que apunta a /iframe/visa-wizard, o una URL regular (false) que apunta a /visa-wizard

Predeterminado:

Respuestas

200 Enlace de solicitud generado exitosamente

Esquema: GetApplicationLinkResponse

success boolean

Ejemplo true

bookedProductId string

El ID del producto reservado

Ejemplo "66a9ebe9572eb2904562c3ae"

applicationUrl string

La URL completa incluido el dominio base.
Con isIframe=true (predeterminado): https://www.yourvisa.ai/iframe/visa-wizard?productId=...&token=...
Con isIframe=false: https://www.yourvisa.ai/visa-wizard?productId=...&token=...

Ejemplo "https://www.yourvisa.ai/iframe/visa-wizard?productId=66a9ebe9572eb2904562c3ad&token=eyJhbGc..."

path string

La parte de ruta y consulta de la URL (todo después del dominio base).
Con isIframe=true (predeterminado): /iframe/visa-wizard?productId=...&token=...
Con isIframe=false: /visa-wizard?productId=...&token=...

Ejemplo "/iframe/visa-wizard?productId=66a9ebe9572eb2904562c3ad&token=eyJhbGc..."

message string

Ejemplo "Application link generated successfully"

400 Solicitud incorrecta - error de validación

Esquema: GetApplicationLinkBadRequest

success boolean

message string

Valores posibles:

Faltan campos requeridosID de producto reservado inválidoID de agencia inválido

401 No autorizado - token inválido o faltante

Esquema: Unauthorized

success boolean

Predeterminado: false

message string

Valores posibles:

No tienes credencialesNo tienes permisoToken de acceso inválidoTu token de acceso no es válido o ha expirado

403 Prohibido - la reserva no pertenece a tu agencia

Esquema: GetApplicationLinkForbidden

success boolean

message string

Valores posibles:

La reserva no pertenece a tu agencia

404 Producto reservado o agencia no encontrado

Esquema: GetApplicationLinkNotFound

success boolean

message string

Valores posibles:

Producto reservado no encontradoAgencia no encontrada

Pruébalo

curl -X POST "https://api.yourvisa.ai/agents-api/get-application-link" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
  "bookedProductId": "string",
  "langKey": "en",
  "isIframe": true
}'

get /agents-api/get-products-history

Obtener historial de productos

Devuelve productos reservados para la agencia autenticada. Los filtros opcionales se combinan con AND. Los campos de viajero consultan applicantDetails en cada reserva. Cada elemento incluye paymentDetails (costos de visa y quién paga). Si el administrador de YourVisa habilita el intercambio de datos de solicitantes para la agencia, cada elemento también incluye applicantDetails completos y URL de descarga con límite de tiempo para applicantUploads. Las URL de descarga expiran después de 5 minutos y se pueden obtener con una solicitud HTTPS GET normal. Los resultados se ordenan por dateCreated descendente (más recientes primero). Se devuelven como máximo 100 elementos. El entorno se infiere del token Bearer: los tokens de sandbox (isApiSandbox: true de generate-programmatic-token) devuelven solo reservas de prueba; los tokens de producción devuelven solo reservas que no son de prueba.

Requiere Autenticación (Token Bearer)

Parámetros

dateStart querystring

Límite inferior opcional en dateCreated de la reserva (fecha ISO o fecha-hora). Omítelo con dateEnd para dejar el rango abierto en el lado inferior.

dateEnd querystring

Límite superior opcional en dateCreated de la reserva (fecha ISO o fecha-hora). Omítelo con dateStart para dejar el rango abierto en el lado superior.

bookedProductId querystring

ObjectId de MongoDB del producto reservado (hex de 24 caracteres)

statusCode query

Filtro de estado de reserva orientado a la agencia (mismos valores que status en cada elemento).

Valores posibles:

waitingForTravelerToFill pleaseFillVisaDetails wereProcessingYourVisa missingVisaDetails waitingForTravelerResponse handledByOurTeam governmentReviewing applicationNotApproved fraudFlagged visaProcessFinished refundInProgress refundCompleted

fromCountry querystring

País de origen en la reserva (coincidencia exacta sin distinción de mayúsculas)

toCountry querystring

País de destino en la reserva (coincidencia exacta sin distinción de mayúsculas)

visaType querystring

Tipo de visa en la reserva (coincidencia exacta sin distinción de mayúsculas)

firstName querystring

Coincidencia de subcadena en applicantDetails.firstName (sin distinción de mayúsculas)

lastName querystring

Coincidencia de subcadena en applicantDetails.lastName (sin distinción de mayúsculas)

email querystring

Coincidencia de subcadena en applicantDetails.email (sin distinción de mayúsculas)

customKey1 querystring

Coincidencia exacta en customKeys.customKey1. Úsalo para datos de seguimiento o búsqueda definidos por el socio.

customKey2 querystring

Coincidencia exacta en customKeys.customKey2. Recomendado para un ID de reserva externo del socio.

customKey3 querystring

Coincidencia exacta en customKeys.customKey3. Recomendado para un ID de viajero externo del socio.

customKey4 querystring

Coincidencia exacta en customKeys.customKey4. Recomendado para un ID de viaje externo del socio.

customKey5 querystring

Coincidencia exacta en customKeys.customKey5. Úsalo para contexto adicional del socio cuando sea necesario.

Respuestas

200 Respuesta exitosa

Esquema: GetHistoryOfProductsResponse

success boolean

Ejemplo true

message string

Presente cuando ninguna reserva coincide con los filtros (success sigue siendo true).

Ejemplo "There are no matching products"

bookedProducts array

Reservas más recientes primero; limitado a 100 elementos.

Array de objeto(clic para ver propiedades)

400 Solicitud incorrecta

Esquema: GetHistoryOfProductsBadRequest

success boolean

Predeterminado: false

message string

Los ejemplos incluyen dateStart/dateEnd inválidos, fecha de inicio posterior a la fecha de fin, bookedProductId inválido, statusCode inválido.

401 No autorizado

Esquema: Unauthorized

success boolean

Predeterminado: false

message string

Valores posibles:

No tienes credencialesNo tienes permisoToken de acceso inválidoTu token de acceso no es válido o ha expirado

404 No encontrado

500 Error interno del servidor

Pruébalo

curl -X GET "https://api.yourvisa.ai/agents-api/get-products-history" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Pagos instantáneos: completa solicitudes dentro de tu plataforma

Usa este flujo cuando quieras que el viajero pague en YourVisa antes de la solicitud de visa completa, y luego regrese a tu plataforma para completar la solicitud dentro de un iframe de YourVisa.

Pago InstantáneoTu PlataformaIframe

Detalles

Paso 1: Verifica los productos de visa

Llama a GET /agents-api/get-products-from-countries?from={from}&to={to} para encontrar productos disponibles. Usa el productId seleccionado en la URL de entrada al checkout.

Paso 2: Inicia el checkout instantáneo

Envía al viajero a https://www.yourvisa.ai/instant-visa-checkout (independiente) o https://www.yourvisa.ai/iframe/instant-visa-checkout (integrado en tu sitio) con productId, affiliatedAgencyId, travelerClient, isInstantPayment=true, campos opcionales de prellenado del viajero y customKey1..5. productId se usa al entrar porque bookedProductId no existe hasta que el checkout crea la reserva.

Paso 2A: URL de checkout web

https://www.yourvisa.ai/instant-visa-checkout?productId={productId}&affiliatedAgencyId={agencyId}&travelerClient= web &isInstantPayment=true&travelerFirstName={firstName}&travelerLastName={lastName}&travelerEmail={email}&travelerPhone={phone}&customKey1={externalUserId}&customKey2={externalBookingId}&customKey3={externalTravelerId}&customKey4={externalTripId}&customKey5={extraContext}

Paso 2A-iframe: URL de checkout web integrada

https://www.yourvisa.ai/iframe/instant-visa-checkout?productId={productId}&affiliatedAgencyId={agencyId}&travelerClient= web &isInstantPayment=true&travelerFirstName={firstName}&travelerLastName={lastName}&travelerEmail={email}&travelerPhone={phone}&customKey1={externalUserId}&customKey2={externalBookingId}&customKey3={externalTravelerId}&customKey4={externalTripId}&customKey5={extraContext}

Paso 2B: URL de checkout de aplicación

https://www.yourvisa.ai/instant-visa-checkout?productId={productId}&affiliatedAgencyId={agencyId}&travelerClient= app &isInstantPayment=true&travelerFirstName={firstName}&travelerLastName={lastName}&travelerEmail={email}&travelerPhone={phone}&customKey1={externalUserId}&customKey2={externalBookingId}&customKey3={externalTravelerId}&customKey4={externalTripId}&customKey5={extraContext}

Paso 2C: Parámetros de checkout

travelerClient es web o app. Usa web cuando el viajero comienza desde tu sitio web. Usa app cuando el viajero comienza desde tu aplicación móvil y el pago se abre en una pestaña de navegador externa. travelerFirstName, travelerLastName, travelerEmail y travelerPhone son campos opcionales de prellenado. customKey1..5 son tus campos de referencia, por ejemplo, ID de usuario externo, ID de pedido, ID de viajero, ID de viaje, campaña o fuente.

Paso 3: Después del pago

El comportamiento depende de la configuración de transferencia de pago instantáneo de tu agencia (configurada por YourVisa — contáctanos para habilitarla o cambiarla): • Continuar en YourVisa (predeterminado): el viajero continúa el asistente de visa en YourVisa. • Regresar al socio: el viajero ve una pantalla de pago completado en lugar de continuar en YourVisa. Si YourVisa configuró una URL de redirección de socio para tu agencia, se les envía allí después de una breve cuenta regresiva con bookedProductId, productId, paymentStatus=paid y cualquier customKey1..5 no vacío — tanto para travelerClient=web como para travelerClient=app. Si no se configura una URL de redirección, ven una pantalla de agradecimiento y regresan a tu aplicación o sitio web por su cuenta. Las integraciones de iframe reciben instant_payment_complete en la página principal cuando la transferencia al socio está habilitada. YourVisa también envía al viajero un correo de confirmación de pago recibido con la marca de tu agencia.

Paso 3A: Ejemplo de URL de retorno web

https://partner.example.com/visa/payment-complete?bookedProductId={bookedProductId}&productId={productId}&paymentStatus=paid&customKey1={externalUserId}&customKey2={externalBookingId}&customKey3={externalTravelerId} Las URL de redirección son configuradas por YourVisa para tu agencia — contacta al soporte para solicitar o actualizar la tuya.

Paso 3B: Búsqueda de reserva en la aplicación

Después de que el viajero regrese a tu aplicación, usa tus claves personalizadas originales para encontrar la reserva pagada. Ejemplo: GET /agents-api/get-products-history?customKey1={externalUserId}&customKey2={externalBookingId}. Los filtros usan coincidencia exacta, están limitados a tu agencia y se combinan con otros filtros opcionales usando lógica AND. Usa el bookedProducts[0]._id devuelto como bookedProductId.

Paso 4: Obtén el enlace de solicitud de iframe

Llama a POST /agents-api/get-application-link con {"bookedProductId": "66a9ebe9572eb2904562c3ae", "langKey": "en", "isIframe": true}. La respuesta incluye applicationUrl.

Paso 5: Integra el iframe

<iframe src="{applicationUrl}" width="100%" height="700" frameborder="0"></iframe>

Paso 6: Escucha la finalización

Después de que YourVisa envía la solicitud dentro del iframe, muestra un mensaje de Solicitud enviada y envía application_submitted a la página principal. Tu plataforma controla lo que sucede a continuación: mantener el iframe abierto, cerrarlo o reemplazarlo con tu propia pantalla de estado del viaje/solicitud.

Consejos para la implementación

  • Valida siempre los parámetros antes de construir la URL para evitar errores.
  • Prueba tu integración en un entorno de desarrollo antes de ponerla en producción.
  • Mantén tus credenciales de autenticación seguras y nunca las expongas en código del lado del cliente.
  • Contacta con soporte si necesitas ayuda con la implementación.

get /agents-api/download-evisa-document

Descargar el documento eVisa de una reserva

Devuelve una URL prefirmada de corta duración para descargar el documento eVisa de un producto reservado. La reserva debe pertenecer a la agencia autenticada. Los agentes que no son gerentes solo pueden acceder a las reservas que ellos crearon. Devuelve 404 cuando la reserva aún no tiene un documento eVisa adjunto. El entorno se deduce del token Bearer: los tokens de sandbox solo pueden descargar eVisa para reservas de prueba; los tokens de producción solo pueden descargar eVisa para reservas que no son de prueba.

Requiere autenticación (token Bearer)

Parámetros

bookedProductId Requeridoquery string

ObjectId de MongoDB del producto reservado (hex de 24 caracteres)

Respuestas

200 URL prefirmada de descarga generada correctamente

Esquema: DownloadEvisaDocumentResponse

success booleano

Ejemplo true

data objeto

400 Solicitud incorrecta: falta bookedProductId o no es válido

Esquema: DownloadEvisaDocumentBadRequest

success booleano

Predeterminado: false

message cadena

Ejemplo "bookedProductId query parameter is required"

401 No autorizado: token no válido o faltante

Esquema: Unauthorized

success booleano

Predeterminado: false

message cadena

Valores posibles:

No tienes credencialesNo tienes permisoToken de acceso no válidoTu token de acceso no es válido o ha caducado

403 Prohibido: reserva no encontrada o acceso denegado

Esquema: DownloadEvisaDocumentForbidden

success booleano

Predeterminado: false

message cadena

Ejemplo "Booking not found or access denied"

404 No hay documento eVisa disponible para esta reserva

Esquema: DownloadEvisaDocumentNotFound

success booleano

Predeterminado: false

message cadena

Ejemplo "No eVisa document available for this booking"

errorCode cadena

Valores posibles:

EVISA_DOCUMENT_NOT_AVAILABLEEVISA_DOCUMENT_FILE_NOT_FOUND

hasEvisaDocument booleano

false cuando la reserva aún no tiene eVisa adjunto; true cuando los metadatos existen pero el archivo falta

Ejemplo "false"

Pruébalo

curl -X GET "https://api.yourvisa.ai/agents-api/download-evisa-document" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

post /agents-api/create-corporate

Crear una cuenta corporativa conectada

Crea una corporación bajo tu agencia y tu identificador corporativo de socio. El identificador se almacena como affiliatePartnerCorporateKey y se puede usar con corporateIdentifier en otros endpoints corporativos. La persona de contacto que proporciones también se crea como gerente corporativo.

Requiere autenticación (token Bearer)

Cuerpo de la solicitud

Esquema: CreateCorporateRequest

corporateName Requeridocadena

partnerCorporateIdentifier Requeridocadena

Identificador corporativo propiedad del socio, único dentro de tu agencia

contact Requeridoobjeto

Contacto principal que también se crea como gerente corporativo

Respuestas

201 Corporación creada correctamente

Esquema: CreateCorporateResponse

success booleano

Ejemplo true

corporateId cadena

partnerCorporateIdentifier cadena

400 Error de validación

Esquema: BadRequest

message cadena

errorCode cadena

Predeterminado: BadRequest

401 No autorizado

Esquema: Unauthorized

success booleano

Predeterminado: false

message cadena

Valores posibles:

No tienes credencialesNo tienes permisoToken de acceso no válidoTu token de acceso no es válido o ha caducado

409 El identificador corporativo del socio ya está en uso

Esquema: BadRequest

message cadena

errorCode cadena

Predeterminado: BadRequest

Pruébalo

curl -X POST "https://api.yourvisa.ai/agents-api/create-corporate" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
  "corporateName": "string",
  "partnerCorporateIdentifier": "string",
  "contact": {}
}'

get /agents-api/get-corporates

Listar corporaciones de la agencia

Lista las corporaciones de la agencia autenticada. Los filtros opcionales son parámetros de consulta (sin cuerpo de solicitud). Hasta 100 resultados por página, ordenados de más reciente a más antiguo. hasPaymentMethod es true cuando la corporación tiene configurada la facturación para pagar las reservas.

URL de solicitud de ejemplo

https://api.yourvisa.ai/agents-api/get-corporates?partnerCorporateIdentifier=acme-001&corporateName=Acme&page=1

Requiere autenticación (token Bearer)

Parámetros

corporateId query string

ObjectId de MongoDB de la corporación YourVisa

partnerCorporateIdentifier query string

Identificador corporativo propiedad del socio (coincidencia exacta)

corporateName query string

Coincidencia parcial de nombre sin distinguir mayúsculas/minúsculas

page queryentero

Número de página (predeterminado 1)

Respuestas

200 Corporaciones listadas correctamente

Esquema: GetCorporatesResponse

success booleano

Ejemplo true

corporates matriz

Matriz de objeto(click para ver propiedades)

page entero

pageSize entero

totalCount entero

totalPages entero

400 Error de validación

Esquema: BadRequest

message cadena

errorCode cadena

Predeterminado: BadRequest

401 No autorizado

Esquema: Unauthorized

success booleano

Predeterminado: false

message cadena

Valores posibles:

No tienes credencialesNo tienes permisoToken de acceso no válidoTu token de acceso no es válido o ha caducado

Pruébalo

curl -X GET "https://api.yourvisa.ai/agents-api/get-corporates?partnerCorporateIdentifier=acme-001&corporateName=Acme&page=1" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

post /agents-api/create-corporate-payment-setup-link

Configuración del enlace de pago corporativo

Crea un enlace seguro para que el gerente corporativo agregue una tarjeta de crédito en una página alojada por YourVisa. El enlace caduca 12 horas después de su creación. corporateIdentifier acepta tanto el ObjectId corporativo de YourVisa como tu identificador corporativo de socio. Establece isEmbeddedInPartnerPage en true al incrustar la página de configuración en tu propio sitio mediante iframe o WebView móvil: la URL devuelta apunta a /iframe/corporate-payment-setup/{token}, un diseño sin barra de navegación que muestra el logotipo de YourVisa.ai y enlaces de políticas legales. El gerente debe aceptar los términos de YourVisa.ai antes de guardar una tarjeta. Después de que el gerente guarde una tarjeta, la página incrustada emite un evento de host corporate_payment_method_saved. El langKey opcional establece el idioma de la interfaz en la página de configuración (predeterminado: en).

Requiere autenticación (token Bearer)

Cuerpo de la solicitud

Esquema: CreateCorporatePaymentSetupLinkRequest

corporateIdentifier Requeridocadena

ObjectId corporativo de YourVisa o identificador corporativo del socio

isEmbeddedInPartnerPage booleano

Cuando es true, setupUrl apunta a /iframe/corporate-payment-setup/{token} para incrustarlo en una página de socio sin la barra de navegación de YourVisa.

langKey cadena

Idioma opcional de la interfaz para la página de configuración: en (inglés, predeterminado), de (alemán), es (español), ru (ruso), he (hebreo), ar (árabe), fr (francés)

Valores posibles:

endeesruhearfr

Respuestas

201 Enlace de configuración creado correctamente

Esquema: CreateCorporatePaymentSetupLinkResponse

success booleano

Ejemplo true

token cadena

setupUrl cadena

URL completa para enviar al gerente corporativo

path cadena

Ejemplo "/corporate-payment-setup/abc123?langKey=de"

expiresAt cadena

Hora de caducidad del enlace (12 horas después de la creación)

corporateId cadena

partnerCorporateIdentifier cadenanull

isEmbeddedInPartnerPage booleano

Si la página de configuración está destinada a incrustarse en un iframe

langKey cadena

Idioma de interfaz resuelto para la página de configuración

Valores posibles:

endeesruhearfr

400 Error de validación

Esquema: BadRequest

message cadena

errorCode cadena

Predeterminado: BadRequest

401 No autorizado

Esquema: Unauthorized

success booleano

Predeterminado: false

message cadena

Valores posibles:

No tienes credencialesNo tienes permisoToken de acceso no válidoTu token de acceso no es válido o ha caducado

403 La corporación no está configurada para facturación pagada por la organización

Esquema: BadRequest

message cadena

errorCode cadena

Predeterminado: BadRequest

404 Corporación no encontrada

Esquema: BadRequest

message cadena

errorCode cadena

Predeterminado: BadRequest

Detalles

Paso 1: Crear enlace incrustado

POST /agents-api/create-corporate-payment-setup-link
{
  "corporateIdentifier": "acme-001",
  "isEmbeddedInPartnerPage": true,
  "langKey": "he"
}

Use setupUrl from the 201 response (targets /iframe/corporate-payment-setup/{token}).

Paso 2: Cargar el iframe

<iframe
  src="{setupUrl}"
  width="100%"
  height="700"
  frameborder="0"
  style="border: none; border-radius: 8px;"
></iframe>

Paso 3: Escuchar en el navegador (padre del iframe)

window.addEventListener("message", (event) => {
  // Optional but recommended: verify the iframe origin in production
  if (event.origin !== "https://www.yourvisa.ai") {
    return;
  }

  if (
    event.data?.source === "yourvisaai-iframe" &&
    event.data?.event === "corporate_payment_method_saved"
  ) {
    console.log("Card saved:", event.data.data);
  }
});

Paso 4: Escuchar en React Native WebView

<WebView
  source={{ uri: setupUrl }}
  onMessage={(event) => {
    const payload = JSON.parse(event.nativeEvent.data);
    if (
      payload?.source === "yourvisaai-iframe" &&
      payload?.event === "corporate_payment_method_saved"
    ) {
      console.log("Card saved:", payload.data);
    }
  }}
/>

Estructura del evento

{source: "yourvisaai-iframe", event: "corporate_payment_method_saved", data: {corporateId: "...", corporateName: "...", timestamp: "2026-07-02T13:25:50.110Z"}}

Cuándo se dispara

Only when isEmbeddedInPartnerPage was true on link creation and after the server confirms card save on POST /corporate-payment-setup/:token/complete.

Pruébalo

curl -X POST "https://api.yourvisa.ai/agents-api/create-corporate-payment-setup-link" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
  "corporateIdentifier": "string",
  "isEmbeddedInPartnerPage": true,
  "langKey": "en"
}'

Crear un enlace para una agencia afiliada con un producto específico

Esta sección explica cómo construir y usar una URL especializada para incrustar la solicitud de visa para agencias y agentes afiliados.

Uso de agencia afiliada

Detalles

URL de ejemplo con productId

https://www.yourvisa.ai/visa-wizard?productId={productId}&affiliatedAgencyId={affiliatedAgencyId}&affiliatedAgentId={affiliatedAgentId}&customKey1={value1}&customKey2={value2}

URL de ejemplo para cualquier producto

https://www.yourvisa.ai?affiliatedAgencyId={affiliatedAgencyId}&affiliatedAgentId={affiliatedAgentId}

Dominio

https://www.yourvisa.ai/ - La URL base del servicio, que debe incrustarse mediante un iframe o abrirse directamente.

productId

Representa el ID único del producto que se está reservando.

affiliatedAgencyId

Representa el ID único de la agencia afiliada o socio que integra el servicio.

affiliatedAgentId

(Campo opcional) Identifica al agente específico dentro de la agencia afiliada que está generando la visa.

customKey1-5

(Opcional) Parámetros de seguimiento personalizados. Puedes incluir hasta 5 claves personalizadas (customKey1, customKey2, customKey3, customKey4, customKey5) para fines adicionales de seguimiento o identificación. Se almacenarán en la reserva y se enviarán mediante webhooks.

Consejos para la implementación

  • Valida siempre los parámetros antes de construir la URL para evitar errores.
  • Prueba tu integración en un entorno de desarrollo antes de ponerla en producción.
  • Mantén tus credenciales de autenticación seguras y nunca las expongas en código del lado del cliente.
  • Contacta con soporte si necesitas ayuda con la implementación.

Crear un enlace de página de viajero personalizada con información de país prellenada

Esta sección explica cómo construir una URL especializada que prellena la búsqueda de visa con países de origen y destino específicos, junto con el seguimiento de la agencia afiliada.

Uso de agencia afiliadaEnlaces personalizados

Detalles

URL de ejemplo con países

https://www.yourvisa.ai/traveler/{from}/{to}?visaType={visaType}&affiliatedAgencyId={affiliatedAgencyId}&affiliatedAgentId={affiliatedAgentId}&customKey1={value1}&customKey2={value2}

URL de ejemplo mínima

https://www.yourvisa.ai/traveler/IL/US

Dominio

https://www.yourvisa.ai/ - La URL base del servicio.

from

(Requerido) Código de país de dos letras que representa el país de origen del viajero o la nacionalidad del pasaporte (p. ej., 'IL' para Israel, 'US' para Estados Unidos).

to

(Requerido) Código de país de dos letras que representa el país de destino (p. ej., 'US' para Estados Unidos, 'GB' para Reino Unido).

visaType

(Opcional) Tipo de visa que se solicita (p. ej., 'tourist', 'business', 'student'). Si no se especifica, el valor predeterminado es 'tourist'.

affiliatedAgencyId

Representa el ID único de la agencia afiliada o socio que integra el servicio.

affiliatedAgentId

(Campo opcional) Identifica al agente específico dentro de la agencia afiliada que está generando la visa.

customKey1-5

(Opcional) Parámetros de seguimiento personalizados. Puedes incluir hasta 5 claves personalizadas (customKey1, customKey2, customKey3, customKey4, customKey5) para fines adicionales de seguimiento o identificación. Se almacenarán en la reserva y se enviarán mediante webhooks.

Consejos para la implementación

  • Valida siempre los parámetros antes de construir la URL para evitar errores.
  • Prueba tu integración en un entorno de desarrollo antes de ponerla en producción.
  • Mantén tus credenciales de autenticación seguras y nunca las expongas en código del lado del cliente.
  • Contacta con soporte si necesitas ayuda con la implementación.

Herramienta interactiva

Descargar el probador de iframes

Obtén una página HTML independiente para probar localmente todos los flujos de iframe incrustados: búsqueda de visa, asistente, pago instantáneo, configuración de pago corporativo y eventos postMessage. Download iframe tester

Resumen y eventos del host

Incorpora los flujos de YourVisa dentro de tu sitio web o WebView móvil sin la barra de navegación ni el pie de página de YourVisa. Usa las URL /iframe/* para la incrustación; usa las URL que no son iframe al abrir en una nueva pestaña del navegador. Las superficies de pago incrustadas en un iframe (pago instantáneo, configuración de tarjeta corporativa y el paso de pago del asistente de visas) también muestran el logotipo de YourVisa.ai y enlaces a los términos, privacidad, reembolso y políticas de cookies. La búsqueda de visas y los pasos del asistente que no son de pago no incluyen ese marco de pago.

Iframe incrustado

Detalles

Ruta base del iframe

Todas las rutas de iframe viven bajo https://www.yourvisa.ai/iframe/..... Suprimen la barra de navegación principal y el pie de página de YourVisa.

Marca de la página de pago

Las superficies de pago incrustadas muestran el logotipo de YourVisa.ai y enlaces a políticas legales: /iframe/instant-visa-checkout, /iframe/corporate-payment-setup/{token} y el paso de pago dentro de /iframe/visa-wizard. La búsqueda de visas y otros pasos del asistente no lo hacen.

Escuchar eventos (navegador)

window.addEventListener("message", (event) => { if (event.origin !== "https://www.yourvisa.ai") { return; } if (event.data?.source !== "yourvisaai-iframe") { return; } console.log(event.data.event, event.data.data); });

Evento: application_submitted

{source: "yourvisaai-iframe", event: "application_submitted", data: {bookedProductId: "...", productId: "...", timestamp: "2026-07-04T10:30:00.000Z", ...}} — fired after the traveler submits the visa application inside the iframe.

Evento: instant_payment_complete

{source: "yourvisaai-iframe", event: "instant_payment_complete", data: {bookedProductId: "66a9ebe9572eb2904562c3ae", productId: "68e94b68f0022238439d7d4b", paymentStatus: "paid", redirectUrl: "https://partner.example.com/visa/payment-complete?...", timestamp: "2026-07-04T10:30:00.000Z"}} — fired immediately on the partner handoff payment-complete screen when instant checkout runs inside an iframe, before any automatic redirect. redirectUrl is included when configured.

Evento: corporate_payment_method_saved

{source: "yourvisaai-iframe", event: "corporate_payment_method_saved", data: {corporateId: "...", corporateName: "...", timestamp: "2026-07-02T13:25:50.110Z"}} — fired after a corporate manager saves a card on the embedded payment-setup page.

React Native WebView

<WebView source={{ uri: iframeUrl }} onMessage={(event) => { const payload = JSON.parse(event.nativeEvent.data); if (payload?.source === "yourvisaai-iframe") { console.log(payload.event, payload.data); } }} />

Parámetros de consulta opcionales

En /iframe/traveler, /iframe/visa-wizard y /iframe/instant-visa-checkout puedes agregar: customKey1..5, langKey (por ejemplo, &langKey=he).

Soporte de idiomas (URL de iframe directas)

Agrega langKey como parámetro de consulta en las URL de iframe que construyas tú mismo. Valores admitidos: en (predeterminado), de, es, ru, he, ar, fr. Búsqueda de viajeros: https://www.yourvisa.ai/iframe/traveler?affiliatedAgencyId={agencyId}&customKey1={value1}&langKey=he Pago instantáneo: https://www.yourvisa.ai/iframe/instant-visa-checkout?productId={productId}&affiliatedAgencyId={agencyId}&isInstantPayment=true&travelerClient=web&customKey1={value1}&langKey=de

Soporte de idiomas (URL del asistente de visas)

Agrega langKey como parámetro de consulta cuando construyas la URL del iframe directamente. https://www.yourvisa.ai/iframe/visa-wizard?productId={productId}&affiliatedAgencyId={agencyId}&customKey1={value1}&langKey=de

Soporte de idiomas (enlace de solicitud firmado)

Si ya tienes un bookedProductId y necesitas un enlace tokenizado, pasa langKey en POST /agents-api/get-application-link. Usa applicationUrl de la respuesta como src del iframe.

Soporte de idiomas (configuración de pago corporativo)

Pasa langKey en POST /agents-api/create-corporate-payment-setup-link. La respuesta setupUrl lo incluye cuando se proporciona. {"corporateIdentifier": "acme-001", "isEmbeddedInPartnerPage": true, "langKey": "he"} Ejemplo de ruta setupUrl: /iframe/corporate-payment-setup/{token}?langKey=he

Marca personalizada

Si tu agencia tiene la marca personalizada habilitada, las rutas de iframe aplican automáticamente tu experiencia de marca.

Consejos para la implementación

  • Siempre valida los parámetros antes de construir la URL para evitar errores.
  • Prueba tu integración en un entorno de desarrollo antes de salir a producción.
  • Mantén tus credenciales de autenticación seguras y nunca las expongas en código del lado del cliente.
  • Contacta con soporte si necesitas ayuda con la implementación.

Asistente de solicitud de visa

Incorpora el asistente de solicitud de visa cuando ya sepas qué producto debe solicitar el viajero. Apunta el iframe a /iframe/visa-wizard con productId y tu affiliatedAgencyId.

Iframe incrustadoSolicitud de visa

Detalles

URL de iframe directa

https://www.yourvisa.ai/iframe/visa-wizard?productId={productId}&affiliatedAgencyId={agencyId}

Ejemplo

https://www.yourvisa.ai/iframe/visa-wizard?productId=68e94b68f0022238439d7d4b&affiliatedAgencyId={agencyId}&customKey1={value1}&langKey=he

Incrustar

<iframe src="https://www.yourvisa.ai/iframe/visa-wizard?productId={productId}&affiliatedAgencyId={agencyId}&customKey1={value1}&customKey2={value2}&langKey=en" width="100%" height="700" frameborder="0" style="border: none; border-radius: 8px;" ></iframe>

Parámetros requeridos

productId — el producto de visa que el viajero está solicitando. affiliatedAgencyId — el ID de tu agencia para que la reserva se atribuya a tu cuenta.

Parámetros opcionales

customKey1..5, langKey (por ejemplo, &langKey=he).

Independiente vs iframe

Usa /iframe/visa-wizard para incrustar dentro de tu sitio. Usa /visa-wizard con los mismos parámetros de consulta al abrir en una nueva pestaña del navegador.

Escuchar la finalización

Después del envío, el iframe envía application_submitted a la página principal.

¿Ya tienes un bookedProductId?

Si el viajero ya pagó o creaste una reserva mediante la API, usa POST /agents-api/get-application-link con isIframe: true en su lugar. Eso devuelve un applicationUrl firmado con un token para la reserva existente.

Consejos para la implementación

  • Siempre valida los parámetros antes de construir la URL para evitar errores.
  • Prueba tu integración en un entorno de desarrollo antes de salir a producción.
  • Mantén tus credenciales de autenticación seguras y nunca las expongas en código del lado del cliente.
  • Contacta con soporte si necesitas ayuda con la implementación.

Pago instantáneo

Incorpora el pago instantáneo cuando ya conozcas el productId.

Carga el pago en /iframe/instant-visa-checkout dentro de tu sitio o aplicación. La página muestra el logotipo de YourVisa.ai y enlaces a nuestras políticas legales.

Después del pago, tu integración sigue una de tres rutas: contacta con YourVisa para configurar la opción que se adapte a tu producto.

Iframe incrustadoPago instantáneo

Detalles

Después del pago — opción 1: Redirigir a tu sitio web

YourVisa envía al viajero a una URL de redirección que proporcionas de antemano. Los parámetros de consulta incluyen bookedProductId, productId, paymentStatus=paid y cualquier customKey1..5 no vacío. Funciona tanto para travelerClient=web como para travelerClient=app. Contacta con el soporte de YourVisa para solicitar o cambiar tu URL de redirección: no se puede configurar mediante la API.

Después del pago — opción 2: Permanecer incrustado (evento de iframe)

Cuando el pago se ejecuta dentro de un iframe, tu página principal recibe un postMessage instant_payment_complete tan pronto como el pago se realiza correctamente. Úsalo para cerrar el iframe, mostrar tu propia confirmación o continuar en tu interfaz. Consulta Escuchar pago completado y Evento: instant_payment_complete a continuación.

Después del pago — opción 3: Continuar con el asistente de visas

El viajero pasa directamente al asistente de visas de YourVisa en el mismo iframe o pestaña: sin redirección ni pantalla de transferencia al socio. No se envía instant_payment_complete en el momento del pago. Escucha application_submitted después de que el viajero termine y envíe el formulario de visa.

Combinar opciones 1 y 2

Cuando se configura una URL de redirección, el pago incrustado aún activa instant_payment_complete de inmediato, muestra una pantalla breve de pago completado y luego redirige dentro del iframe después de unos segundos. Eso le da tiempo a tu página para cerrar el iframe o manejar el evento antes de la redirección.

Incrustar pago

<iframe id="yourvisa-instant-checkout" src="https://www.yourvisa.ai/iframe/instant-visa-checkout?productId={productId}&affiliatedAgencyId={agencyId}&travelerClient=web&isInstantPayment=true&langKey=en&travelerFirstName={firstName}&travelerLastName={lastName}&travelerEmail={email}&travelerPhone={phone}&customKey1={externalUserId}&customKey2={externalBookingId}&customKey3={externalTravelerId}&customKey4={externalTripId}&customKey5={extraContext}" width="100%" height="700" frameborder="0" style="border: none; border-radius: 8px;" ></iframe>

Parámetros requeridos

productId, affiliatedAgencyId, isInstantPayment=true, travelerClient (web o app).

Parámetros opcionales

customKey1..5, langKey (por ejemplo, &langKey=he), travelerFirstName, travelerLastName, travelerEmail, travelerPhone.

travelerClient

web — el viajero comienza desde tu sitio web o iframe incrustado. app — el viajero comienza desde tu aplicación móvil nativa; el pago puede abrirse en una pestaña externa del navegador o WebView.

Sin URL de redirección configurada

Si la transferencia al socio está habilitada pero no se establece una URL de redirección, los viajeros ven una pantalla de agradecimiento que les indica que se recibió el pago y que deben volver a tu aplicación o sitio web. Encuentra la reserva pagada con GET /agents-api/get-products-history o reanuda con POST /agents-api/get-application-link.

Escuchar pago completado (navegador)

window.addEventListener("message", (event) => { if (event.origin !== "https://www.yourvisa.ai") { return; } if ( event.data?.source === "yourvisaai-iframe" && event.data?.event === "instant_payment_complete" ) { const { bookedProductId, productId, paymentStatus, redirectUrl } = event.data.data; console.log("Instant payment complete", { bookedProductId, productId, paymentStatus, redirectUrl }); // Close the iframe now, or let the traveler follow the in-iframe redirect } });

Evento: instant_payment_complete

{source: "yourvisaai-iframe", event: "instant_payment_complete", data: {bookedProductId: "66a9ebe9572eb2904562c3ae", productId: "68e94b68f0022238439d7d4b", paymentStatus: "paid", redirectUrl: "https://partner.example.com/visa/payment-complete?...", timestamp: "2026-07-04T10:30:00.000Z"}} Fired immediately on the partner handoff payment-complete screen when checkout runs inside an iframe — before any automatic redirect. redirectUrl is included when YourVisa configured one for your agency.

Ejemplo de integración completa

<iframe id="yourvisa-instant-checkout" src="https://www.yourvisa.ai/iframe/instant-visa-checkout?productId={productId}&affiliatedAgencyId={agencyId}&travelerClient=web&isInstantPayment=true&customKey1={externalUserId}&customKey2={externalBookingId}" width="100%" height="700" frameborder="0" style="border: none; border-radius: 8px;" ></iframe> <script> window.addEventListener("message", (event) => { if (event.origin !== "https://www.yourvisa.ai") { return; } if (event.data?.source !== "yourvisaai-iframe") { return; } if (event.data.event === "instant_payment_complete") { const { bookedProductId, productId } = event.data.data; document.getElementById("yourvisa-instant-checkout").style.display = "none"; // Resume in your UI, or load the wizard iframe with POST /agents-api/get-application-link } }); </script>

Ejemplo de URL de redirección

https://partner.example.com/visa/payment-complete?bookedProductId={bookedProductId}&productId={productId}&paymentStatus=paid&customKey1={externalUserId}&customKey2={externalBookingId}

Evento: application_submitted

{ "source": "yourvisaai-iframe", "event": "application_submitted", "data": { "bookedProductId": "6a493c9b8f46d0e57c31bd65", "productId": "68e94b68f0022238439d7d4b", "visaType": "tourist", "timestamp": "2026-07-04T17:08:29.646Z" } } Fired inside an iframe when the traveler submits the visa application after instant payment and continuing through the wizard. This is the completion signal for option 3 — not instant_payment_complete. applicantName may also be included when available.

Escuchar solicitud enviada (navegador)

window.addEventListener("message", (event) => { if (event.origin !== "https://www.yourvisa.ai") { return; } if ( event.data?.source === "yourvisaai-iframe" && event.data?.event === "application_submitted" ) { const { bookedProductId, productId, visaType } = event.data.data; console.log("Visa application submitted", { bookedProductId, productId, visaType }); // Close the iframe, show your own confirmation, or refresh trip status } });

Consejos para la implementación

  • Siempre valida los parámetros antes de construir la URL para evitar errores.
  • Prueba tu integración en un entorno de desarrollo antes de salir a producción.
  • Mantén tus credenciales de autenticación seguras y nunca las expongas en código del lado del cliente.
  • Contacta con soporte si necesitas ayuda con la implementación.

Configuración del método de pago corporativo

Incorpora la página de configuración de tarjeta corporativa para que un gerente corporativo pueda guardar un método de pago dentro de tu sitio. Requiere POST /agents-api/create-corporate-payment-setup-link con isEmbeddedInPartnerPage: true. La página incrustada muestra el logotipo de YourVisa.ai y enlaces a políticas legales.

Iframe incrustadoCorporativo

Detalles

Paso 1: Crear enlace incrustado

POST /agents-api/create-corporate-payment-setup-link { "corporateIdentifier": "acme-001", "isEmbeddedInPartnerPage": true, "langKey": "he" } langKey is set in the request body. Use setupUrl from the 201 response as the iframe src (targets /iframe/corporate-payment-setup/{token}?langKey=he).

Paso 2: Cargar el iframe

<iframe src="{setupUrl}" width="100%" height="700" frameborder="0" style="border: none; border-radius: 8px;" ></iframe>

Parámetros opcionales

Solo langKey: se establece en el cuerpo del POST al crear el enlace (por ejemplo, "langKey": "he"). El setupUrl devuelto lo incluye. customKey1..5 no se aplican a este flujo.

Paso 3: Escuchar en el navegador

window.addEventListener("message", (event) => { if (event.origin !== "https://www.yourvisa.ai") { return; } if ( event.data?.source === "yourvisaai-iframe" && event.data?.event === "corporate_payment_method_saved" ) { console.log("Card saved:", event.data.data); } });

Cuándo se activa

Solo cuando isEmbeddedInPartnerPage era true en la creación del enlace y después de que el servidor confirme el guardado de la tarjeta.

Consejos para la implementación

  • Siempre valida los parámetros antes de construir la URL para evitar errores.
  • Prueba tu integración en un entorno de desarrollo antes de salir a producción.
  • Mantén tus credenciales de autenticación seguras y nunca las expongas en código del lado del cliente.
  • Contacta con soporte si necesitas ayuda con la implementación.

Servidor MCP — conecta asistentes de IA a YourVisa.ai

El servidor MCP (Model Context Protocol) de YourVisa permite que cualquier asistente de IA compatible — Claude Desktop, Cursor y otros — consulte requisitos de visa, tarifas y genere enlaces de solicitud en tiempo real. Es un servicio HTTP remoto que utiliza el transporte HTTP Streamable y requiere una clave API.

Integración MCPIA

Detalles

1. Obtener una clave API

Inicia sesión en tu cuenta de YourVisa.ai, ve a Panel → pestaña API MCP y haz clic en 'Nueva clave'. Cópiala y guárdala: solo se muestra una vez.

2. Agregar a la configuración de tu cliente MCP

Agrega el bloque de configuración que se muestra a continuación al archivo de configuración de tu cliente MCP (por ejemplo, claude_desktop_config.json para Claude Desktop, o la configuración de MCP en Cursor).

3. Herramientas disponibles

search_visas · get_visa_details · get_visa_requirements · get_visa_fees · get_application_link · get_country_info

4. Sin estado y solo lectura

El servidor MCP solo lee datos. No se realizan reservas ni escrituras mediante MCP.

5. Límites de velocidad

Nivel gratuito: 60 solicitudes / minuto.

Ejemplo de respuesta

{
  "mcpServers": {
    "YourVisa.ai": {
      "url": "https://mcp.yourvisa.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer yv_mcp_your_key_here"
      }
    }
  }
}

Consejos para la implementación

  • Siempre valida los parámetros antes de construir la URL para evitar errores.
  • Prueba tu integración en un entorno de desarrollo antes de salir a producción.
  • Mantén tus credenciales de autenticación seguras y nunca las expongas en código del lado del cliente.
  • Contacta con soporte si necesitas ayuda con la implementación.

Configurar una URL de webhook para recibir notificaciones cuando se envíen solicitudes de visa

En la configuración de tu cuenta, puedes definir una URL de webhook para recibir notificaciones cada vez que tu agencia envíe una solicitud de visa. Cada notificación incluye los costos de la visa y quién paga.

Configuración de cuentaWebhook

Detalles

Dónde configurarlo

Inicia sesión en tu panel y ve a la pestaña 'Configuración de cuenta'. Allí puedes agregar o actualizar tu URL de webhook.

Para qué se usa

Tu webhook se activará cada vez que tu agencia envíe una solicitud de visa. El payload incluye los costos de la visa y si paga el viajero/empleado o la empresa/agencia.

Información de pago

paymentDetails incluye los costos de la visa (tarifa gubernamental, tarifa de servicio, tarifa de velocidad de procesamiento y total) y quién paga. paidBy es CLIENT cuando paga el viajero o empleado, y AGENT cuando paga la empresa o agencia. Si el administrador de YourVisa habilita el intercambio de datos del solicitante para tu agencia, el webhook también incluye applicantDetails y URL de descarga con límite de tiempo para cada archivo en applicantUploads. Esas URL caducan después de 5 minutos y funcionan con un GET HTTPS normal desde tu servidor.

Ejemplo de uso

Podrías usar esto para sincronizar solicitudes con tu CRM interno, enviar alertas o realizar lógica personalizada en nuevos envíos.

Ejemplo de respuesta

{
  "toCountry": "US",
  "fromCountry": "IL",
  "productId": "66a9ebe9572eb2904562c3ae",
  "bookedProductId": "66b0aae9572eb2904562c3af",
  "customKeys": {
    "customKey1": "travel-file-9",
    "customKey2": "string",
    "customKey3": "string",
    "customKey4": "string",
    "customKey5": "string"
  },
  "dateCreated": 1710000000000,
  "paymentDetails": {
    "currency": "USD",
    "govVisaCost": 35,
    "productServiceFee": 100,
    "partnerServiceFee": 0,
    "processingSpeedFee": 20,
    "partnerProcessingSpeedFee": 0,
    "totalCost": 155,
    "paymentStatus": "PAID",
    "paidBy": "AGENT"
  },
  "applicantDetails": {},
  "applicantUploads": {}
}

Consejos para la implementación

  • Siempre valida los parámetros antes de construir la URL para evitar errores.
  • Prueba tu integración en un entorno de desarrollo antes de salir a producción.
  • Mantén tus credenciales de autenticación seguras y nunca las expongas en código del lado del cliente.
  • Contacta con soporte si necesitas ayuda con la implementación.