YourVisa Travel Visa MCP

Servidor MCP remoto somente leitura que permite que assistentes de IA consultem requisitos e taxas de visto, eVisa, ETA e ESTA por país e obtenham links oficiais de solicitação. Chave de API necessária.

Ver em yourvisa.aiExperimente este MCPPatrocinado

Servidor MCP hospedado

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

Instala no Claude Code, Codex, Cursor e outros

Documentação

Base URL:

https://api.yourvisa.ai

Construindo um assistente de viagens ou imigração com IA? Leia nossa história sobre como um servidor MCP de vistos de viagem impediu que o chatbot de uma agência desse respostas erradas sobre vistos, e nosso artigo técnico sobre Integração de servidor MCP para documentação de viagens em e-visa, ETA e ETIAS.

Bem-vindo à documentação do YourVisa.ai

Esta documentação abrangente da API irá guiá-lo na integração dos nossos serviços de visto ao seu aplicativo. Seja você um iniciante ou um desenvolvedor experiente, encontrará tudo o que precisa para começar.

Rápido e Confiável

Tempos de resposta rápidos com garantia de disponibilidade de 99,9%

Seguro

Segurança de nível empresarial com autenticação OAuth 2.0

Bem Documentado

Exemplos claros e explicações detalhadas para cada endpoint

Guia de Início Rápido

1

Obtenha Suas Credenciais de API

Cadastre-se para obter uma conta e gere sua chave e segredo de API de produção e/ou sandbox no painel.

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

Gere um Token de Acesso

Envie sua chave e segredo via POST para obter um token bearer. A resposta inclui agencyId e isApiSandbox (true para credenciais sandbox, false para produção). Não envie um campo de ambiente — ele é inferido a partir de quais credenciais correspondem.

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"}'

Faça Sua Primeira Chamada de API

Use o token para autenticar suas solicitações aos 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 as solicitações de API devem ser feitas para a seguinte URL base:

https://api.yourvisa.ai

Autenticação

A maioria dos endpoints exige autenticação usando um token Bearer. Inclua o token no cabeçalho Authorization das suas solicitações:

Authorization: Bearer YOUR_ACCESS_TOKEN

Importante: Mantenha suas credenciais de API seguras. Nunca as exponha em código do lado do cliente ou em repositórios públicos. Use credenciais sandbox para testes de integração; tokens sandbox marcam reservas como teste e ignoram cobranças de saldo.

Tratamento de Erros

A API usa códigos de status HTTP padrão para indicar sucesso ou falha:

  • 200Sucesso - Solicitação concluída com sucesso
  • 400Solicitação Inválida - Parâmetros inválidos ou campos obrigatórios ausentes
  • 401Não Autorizado - Token de acesso inválido ou expirado
  • 404Não Encontrado - Recurso não encontrado
  • 500Erro Interno do Servidor - Algo deu errado em nosso lado

Precisa de Ajuda?

Se você tiver dúvidas ou precisar de assistência, não hesite em entrar em contato:

post /unprotected/generate-programmatic-token

Gerar token programático

Troque uma chave e segredo da API de Agentes por um token de acesso JWT (válido por 12 horas). Envie credenciais de produção ou sandbox — o ambiente é inferido a partir de qual chave corresponde no banco de dados. Não envie um campo de ambiente. Quando credenciais sandbox correspondem, a resposta inclui isApiSandbox: true e o JWT carrega o mesmo sinalizador, de modo que as reservas criadas com esse token são marcadas como teste.

Corpo da Solicitação

Schema: GenerateProgrammaticToken

key Obrigatóriostring

Chave de API de produção ou sandbox

secret Obrigatóriostring

Segredo de API de produção ou sandbox correspondente

Respostas

200 Resposta bem-sucedida

Schema: GenerateProgrammaticTokenResponse

success boolean

Padrão: true

token string

Token de acesso JWT válido por 12 horas

agencyId string

ID da agência associada às credenciais de API

isApiSandbox boolean

true quando a chave/segredo fornecidos são credenciais sandbox; false para produção. Tokens sandbox marcam reservas criadas via API de Agentes como teste e ignoram cobranças de saldo.

Exemplo false

400 Solicitação inválida

Schema: GenerateProgrammaticTokenBadRequest

success boolean

Padrão: false

message string

Valores possíveis:

Campos ausentesUsuário com acesso programático não existe

404 Não encontrado

500 Erro interno do servidor

Experimente

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}

Obter produtos de países

Requer Autenticação (Token Bearer)

Parâmetros

from Obrigatóriopathstring

País de origem

to Obrigatóriopathstring

País de destino

currency pathstring

Moeda de exibição opcional (código ISO 4217 suportado). Quando fornecida, cada paymentDetails do produto inclui displayPricing com valores convertidos.

Valores possíveis:

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 Resposta

Tipo de resposta - Obter produtos de países

Respostas

200 Resposta bem-sucedida

Schema: GetProductsFromCountriesSupportedResponse

success boolean

Padrão: true

products array

Matriz de objeto(clique para ver propriedades)

400 Solicitação inválida

Schema: GetProductsFromCountriesBadRequest

success boolean

Padrão: false

message string

Valores possíveis:

País de origem (de) ou país de destino (para) não fornecidoCódigo do país (de ou para) inválidoCódigo de moeda inválido. Valores suportados: 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 Não Autorizado

Schema: Unauthorized

success boolean

Padrão: false

message string

Valores possíveis:

Você não tem credenciaisVocê não tem permissãoToken de acesso inválidoSeu token de acesso não é válido ou expirou

404 Não encontrado

500 Erro interno do servidor

Experimente

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}

Obter códigos de países de destino suportados

Retorna códigos de país de destino ISO 3166-1 alfa-2 distintos que possuem produtos de visto com isSupportedVisa true para o país de origem fornecido. O país de origem nunca é incluído como destino.

Requer Autenticação (Token Bearer)

Parâmetros

from Obrigatóriopathstring

País de origem

Respostas

200 Resposta bem-sucedida

Schema: GetSupportedDestinationsResponse

success boolean

Padrão: true

countryCodes array

Matriz de string

400 Solicitação inválida

Schema: GetSupportedDestinationsBadRequest

success boolean

Padrão: false

message string

Valores possíveis:

País de origem (de) não fornecidoCódigo do país (de) inválido

401 Não Autorizado

Schema: Unauthorized

success boolean

Padrão: false

message string

Valores possíveis:

Você não tem credenciaisVocê não tem permissãoToken de acesso inválidoSeu token de acesso não é válido ou expirou

500 Erro interno do servidor

Experimente

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

Obter detalhes de produto específico

Requer Autenticação (Token Bearer)

Parâmetros

productId Obrigatóriopathstring

ID do produto

Respostas

200 Resposta bem-sucedida

Schema: GetSpecificProductDetailsResponse

success boolean

Padrão: true

productInputDetails array

Matriz de objeto(clique para ver propriedades)

productDetails object

400 Solicitação inválida

Schema: GetSpecificProductDetailsBadRequest

success boolean

Padrão: false

message string

401 Não Autorizado

Schema: Unauthorized

success boolean

Padrão: false

message string

Valores possíveis:

Você não tem credenciaisVocê não tem permissãoToken de acesso inválidoSeu token de acesso não é válido ou expirou

404 Não encontrado

500 Erro interno do servidor

Experimente

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

Criar um novo produto de visto reservado

Registre uma nova reserva de visto com os dados do cliente via API. A combinação isPaidByCustomer=true com isFilledByCustomer=false (cliente paga, agência preenche) não é suportada e retorna 400. Quando corporateIdForCharging é fornecido, a reserva é paga pela organização e cobrada dessa empresa (saldo rotativo ou back-to-back conforme as configurações de cobrança da empresa). A agência deve ter isAllowedToChargeCorporatesViaApi habilitado pelo administrador do YourVisa.ai. Se o token Bearer foi emitido a partir de credenciais de API sandbox (isApiSandbox: true de POST /unprotected/generate-programmatic-token), a reserva é automaticamente marcada como visto de teste e cobranças de saldo são ignoradas.

Requer Autenticação (Token Bearer)

Corpo da Solicitação

Schema: CommitNewVisaRequest

productId Obrigatóriostring

O ID do produto de visto

isPaidByCustomer boolean

Se o cliente pagará (true) ou o agente pagará (false). Não pode ser true quando isFilledByCustomer é false.

isFilledByCustomer boolean

Se o cliente preencherá o formulário (true) ou o agente o preencherá (false). Não pode ser false quando isPaidByCustomer é true.

customerFirstName Obrigatóriostring

Primeiro nome do cliente

customerLastName Obrigatóriostring

Sobrenome do cliente

customerEmail Obrigatóriostring

Endereço de e-mail do cliente

voucherInvoiceNumber string

Referência opcional de voucher ou fatura armazenada com a reserva

Exemplo "INV-2026-001"

travelFileNumber string

Número opcional de arquivo de viagem do Travel CRM vinculado a esta reserva

Exemplo "1252813"

messageForTraveler string

Mensagem opcional incluída no e-mail de aplicação do viajante quando isFilledByCustomer é true. Apenas letras, números, espaços e pontuação básica (.,!? ' -).

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

preferredLanguage string

Código de idioma opcional para e-mails voltados ao viajante: en (inglês, padrão), de (alemão), es (espanhol), ru (russo), he (hebraico), ar (árabe), fr (francês)

Valores possíveis:

endeesruhearfr

corporateIdForCharging string

ID corporativo opcional para cobrar esta reserva em vez do saldo da agência. Requer isAllowedToChargeCorporatesViaApi da agência, a empresa deve pertencer à agência e a empresa deve ter uma configuração de pagamento válida (cartão salvo para back-to-back, ou recarga automática com cartão salvo para saldo rotativo). Quando definido, isPaidByCustomer é tratado como false e o e-mail do viajante é adicionado à lista de permissões da empresa.

Exemplo "66a9ebe9572eb2904562c3ae"

customKeys object

Pares opcionais de chave-valor personalizados para rastreamento ou metadados (máximo de 5 chaves). Exemplo: {"customKey1": "customKey1 value", "customKey2": "customKey2 value", "customKey3": "customKey3 value", "customKey4": "customKey4 value", "customKey5": "customKey5 value"}

Respostas

201 Produto reservado criado com sucesso

Schema: CommitNewVisaResponse

success boolean Exemplo true

bookedProductId string

Exemplo "66a9ebe9572eb2904562c3ae"

isPaymentTest boolean

true quando a reserva foi criada como um visto de teste (credenciais de API de sandbox ou modo de teste de integração de agência/corporativo). Reservas de teste não são cobradas no saldo.

Exemplo false

message string

Exemplo "Visa booking created successfully"

400 Requisição inválida - erro de validação

Schema: CommitNewVisaBadRequest

success boolean

message string

401 Não autorizado - token inválido ou ausente

Schema: Unauthorized

success boolean

Padrão: false

message string

Valores possíveis:

Você não tem credenciaisVocê não tem permissãoToken de acesso inválidoSeu token de acesso não é válido ou expirou

403 Proibido - agência não autorizada a criar reservas pagas pela agência

Schema: CommitNewVisaForbidden

success boolean

message string

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

404 Produto ou agência não encontrado

Schema: CommitNewVisaNotFound

success boolean

message string

Experimente

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

Gerar link de aplicação para uma reserva existente

Gere uma URL de aplicação com token embutido para um produto já reservado. Use isto após criar uma reserva via POST /agents-api/commit-new-visa, ou após receber um bookedProductId de um handoff de pagamento instantâneo. Defina isIframe como true (padrão) para uma URL pronta para iframe, ou false para a URL regular do assistente de visto. Observação: este link só é válido para aplicações de visto que ainda não foram enviadas. O ambiente é inferido do token Bearer: tokens de sandbox só podem gerar links para reservas de teste; tokens de produção só podem gerar links para reservas que não são de teste.

Requer Autenticação (Token Bearer)

Corpo da Requisição

Schema: GetApplicationLinkRequest

bookedProductId Obrigatóriostring

O ID do produto reservado existente. Pode vir de POST /agents-api/commit-new-visa ou de uma URL de retorno de pagamento instantâneo do parceiro.

langKey string

Preferência de idioma opcional para o formulário de aplicação: en (inglês, padrão), de (alemão), es (espanhol), ru (russo), he (hebraico), ar (árabe), fr (francês)

Valores possíveis:

endeesruhearfr

isIframe boolean

Se deve gerar uma URL de iframe (true, padrão) apontando para /iframe/visa-wizard, ou uma URL regular (false) apontando para /visa-wizard

Padrão:

Respostas

200 Link de aplicação gerado com sucesso

Schema: GetApplicationLinkResponse

success boolean

Exemplo true

bookedProductId string

O ID do produto reservado

Exemplo "66a9ebe9572eb2904562c3ae"

applicationUrl string

A URL completa incluindo o domínio base.
Com isIframe=true (padrão): https://www.yourvisa.ai/iframe/visa-wizard?productId=...&token=...
Com isIframe=false: https://www.yourvisa.ai/visa-wizard?productId=...&token=...

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

path string

A parte de caminho e consulta da URL (tudo após o domínio base).
Com isIframe=true (padrão): /iframe/visa-wizard?productId=...&token=...
Com isIframe=false: /visa-wizard?productId=...&token=...

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

message string

Exemplo "Application link generated successfully"

400 Requisição inválida - erro de validação

Schema: GetApplicationLinkBadRequest

success boolean

message string

Valores possíveis:

Campos obrigatórios ausentesID de produto reservado inválidoID de agência inválido

401 Não autorizado - token inválido ou ausente

Schema: Unauthorized

success boolean

Padrão: false

message string

Valores possíveis:

Você não tem credenciaisVocê não tem permissãoToken de acesso inválidoSeu token de acesso não é válido ou expirou

403 Proibido - a reserva não pertence à sua agência

Schema: GetApplicationLinkForbidden

success boolean

message string

Valores possíveis:

A reserva não pertence à sua agência

404 Produto reservado ou agência não encontrado

Schema: GetApplicationLinkNotFound

success boolean

message string

Valores possíveis:

Produto reservado não encontradoAgência não encontrada

Experimente

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

Obter histórico de produtos

Retorna produtos reservados para a agência autenticada. Filtros opcionais são combinados com AND. Campos de viajante consultam applicantDetails em cada reserva. Cada item inclui paymentDetails (custos do visto e quem paga). Se o administrador do YourVisa habilitar o compartilhamento de dados do solicitante para a agência, cada item também inclui applicantDetails completos e URLs de download com tempo limitado para applicantUploads. As URLs de download expiram após 5 minutos e podem ser obtidas com um GET HTTPS normal. Os resultados são ordenados por dateCreated decrescente (mais recentes primeiro). No máximo 100 itens são retornados. O ambiente é inferido do token Bearer: tokens de sandbox (isApiSandbox: true de generate-programmatic-token) retornam apenas reservas de teste; tokens de produção retornam apenas reservas que não são de teste.

Requer Autenticação (Token Bearer)

Parâmetros

dateStart querystring

Limite inferior opcional para dateCreated da reserva (data ISO ou datetime). Omita com dateEnd para deixar o intervalo aberto no lado inferior.

dateEnd querystring

Limite superior opcional para dateCreated da reserva (data ISO ou datetime). Omita com dateStart para deixar o intervalo aberto no lado superior.

bookedProductId querystring

ObjectId do MongoDB do produto reservado (hex de 24 caracteres)

statusCode query

Filtro de status de reserva voltado para a agência (mesmos valores de status em cada item).

Valores possíveis:

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

fromCountry querystring

País de origem na reserva (correspondência exata sem diferenciar maiúsculas/minúsculas)

toCountry querystring

País de destino na reserva (correspondência exata sem diferenciar maiúsculas/minúsculas)

visaType querystring

Tipo de visto na reserva (correspondência exata sem diferenciar maiúsculas/minúsculas)

firstName querystring

Correspondência de substring em applicantDetails.firstName (sem diferenciar maiúsculas/minúsculas)

lastName querystring

Correspondência de substring em applicantDetails.lastName (sem diferenciar maiúsculas/minúsculas)

email querystring

Correspondência de substring em applicantDetails.email (sem diferenciar maiúsculas/minúsculas)

customKey1 querystring

Correspondência exata em customKeys.customKey1. Use para dados de rastreamento ou consulta definidos pelo parceiro.

customKey2 querystring

Correspondência exata em customKeys.customKey2. Recomendado para um ID de reserva externo do parceiro.

customKey3 querystring

Correspondência exata em customKeys.customKey3. Recomendado para um ID de viajante externo do parceiro.

customKey4 querystring

Correspondência exata em customKeys.customKey4. Recomendado para um ID de viagem externo do parceiro.

customKey5 querystring

Correspondência exata em customKeys.customKey5. Use para contexto extra do parceiro quando necessário.

Respostas

200 Resposta bem-sucedida

Schema: GetHistoryOfProductsResponse

success boolean

Exemplo true

message string

Presente quando nenhuma reserva corresponde aos filtros (success ainda é true).

Exemplo "There are no matching products"

bookedProducts array

Reservas mais recentes primeiro; limitado a 100 itens.

Array de objeto(clique para ver propriedades)

400 Requisição inválida

Schema: GetHistoryOfProductsBadRequest

success boolean

Padrão: false

message string

Exemplos incluem dateStart/dateEnd inválidos, data inicial após data final, bookedProductId inválido, statusCode inválido.

401 Não autorizado

Schema: Unauthorized

success boolean

Padrão: false

message string

Valores possíveis:

Você não tem credenciaisVocê não tem permissãoToken de acesso inválidoSeu token de acesso não é válido ou expirou

404 Não encontrado

500 Erro interno do servidor

Experimente

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

Pagamentos instantâneos: complete aplicações dentro da sua plataforma

Use este fluxo quando quiser que o viajante pague no YourVisa antes da aplicação completa do visto, e depois retorne à sua plataforma para completar a aplicação dentro de um iframe do YourVisa.

Pagamento InstantâneoSua PlataformaIframe

Detalhes

Passo 1: Verifique produtos de visto

Chame GET /agents-api/get-products-from-countries?from={from}&to={to} para encontrar produtos disponíveis. Use o productId selecionado na URL de entrada do checkout.

Passo 2: Inicie o checkout instantâneo

Envie o viajante para https://www.yourvisa.ai/instant-visa-checkout (autônomo) ou https://www.yourvisa.ai/iframe/instant-visa-checkout (embutido no seu site) com productId, affiliatedAgencyId, travelerClient, isInstantPayment=true, campos opcionais de preenchimento do viajante e customKey1..5. productId é usado na entrada porque bookedProductId não existe até o checkout criar a reserva.

Passo 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}

Passo 2A-iframe: URL de checkout web embutida

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}

Passo 2B: URL de checkout do app

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}

Passo 2C: Parâmetros do checkout

travelerClient é web ou app. Use web quando o viajante começa pelo seu site. Use app quando o viajante começa pelo seu aplicativo móvel e o pagamento abre em uma aba externa do navegador. travelerFirstName, travelerLastName, travelerEmail e travelerPhone são campos opcionais de preenchimento. customKey1..5 são seus campos de referência, por exemplo, ID de usuário externo, ID de pedido, ID de viajante, ID de viagem, campanha ou fonte.

Passo 3: Após o pagamento

O comportamento depende da configuração de handoff de pagamento instantâneo da sua agência (configurada pelo YourVisa — entre em contato para habilitar ou alterar): • Continuar no YourVisa (padrão): o viajante continua o assistente de visto no YourVisa. • Retornar ao parceiro: o viajante vê uma tela de pagamento concluído em vez de continuar no YourVisa. Se o YourVisa configurou uma URL de redirecionamento do parceiro para sua agência, ele é enviado para lá após uma breve contagem regressiva com bookedProductId, productId, paymentStatus=paid e quaisquer customKey1..5 não vazios — tanto para travelerClient=web quanto para travelerClient=app. Se nenhuma URL de redirecionamento estiver configurada, ele vê uma tela de agradecimento e retorna ao seu app ou site por conta própria. Embutidos de iframe recebem instant_payment_complete na página pai quando o handoff do parceiro está habilitado. O YourVisa também envia ao viajante um e-mail de confirmação de pagamento recebido com a marca da sua agência.

Passo 3A: Exemplo de URL de retorno web

https://partner.example.com/visa/payment-complete?bookedProductId={bookedProductId}&productId={productId}&paymentStatus=paid&customKey1={externalUserId}&customKey2={externalBookingId}&customKey3={externalTravelerId} As URLs de redirecionamento são configuradas pelo YourVisa para sua agência — entre em contato com o suporte para solicitar ou atualizar a sua.

Passo 3B: Consulta de reserva no app

Após o viajante retornar ao seu app, use suas chaves personalizadas originais para encontrar a reserva paga. Exemplo: GET /agents-api/get-products-history?customKey1={externalUserId}&customKey2={externalBookingId}. Os filtros usam correspondência exata, são limitados à sua agência e são combinados com outros filtros opcionais usando lógica AND. Use o bookedProducts[0]._id retornado como bookedProductId.

Passo 4: Obtenha o link de aplicação do iframe

Chame POST /agents-api/get-application-link com {"bookedProductId": "66a9ebe9572eb2904562c3ae", "langKey": "en", "isIframe": true}. A resposta inclui applicationUrl.

Passo 5: Embuta o iframe

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

Passo 6: Aguarde a conclusão

Depois que o YourVisa envia a solicitação dentro do iframe, ele exibe uma mensagem de Solicitação enviada e envia application_submitted para a página pai. Sua plataforma decide o que acontece em seguida: manter o iframe aberto, fechá-lo ou substituí-lo pela sua própria tela de status de viagem/solicitação.

Dicas para Implementação

  • Sempre valide os parâmetros antes de construir a URL para evitar erros.
  • Teste sua integração em um ambiente de desenvolvimento antes de ir para produção.
  • Mantenha suas credenciais de autenticação seguras e nunca as exponha em código do lado do cliente.
  • Entre em contato com o suporte se precisar de assistência com a implementação.

get /agents-api/download-evisa-document

Baixar documento de eVisa para uma reserva

Retorna uma URL pré-assinada de curta duração para baixar o documento de eVisa de um produto reservado. A reserva deve pertencer à agência autenticada. Agentes que não são gerentes só podem acessar reservas que criaram. Retorna 404 quando a reserva ainda não possui um documento de eVisa anexado. O ambiente é inferido do token Bearer: tokens de sandbox só podem baixar eVisas para reservas de teste; tokens de produção só podem baixar eVisas para reservas que não são de teste.

Requer Autenticação (Token Bearer)

Parâmetros

bookedProductId Obrigatórioquerystring

ObjectId MongoDB do produto reservado (hex de 24 caracteres)

Respostas

200 URL pré-assinada de download gerada com sucesso

Schema: DownloadEvisaDocumentResponse

success boolean

Exemplo true

data objeto

400 Requisição inválida - bookedProductId ausente ou inválido

Schema: DownloadEvisaDocumentBadRequest

success boolean

Padrão: false

message string

Exemplo "bookedProductId query parameter is required"

401 Não autorizado - token inválido ou ausente

Schema: Unauthorized

success boolean

Padrão: false

message string

Valores possíveis:

Você não tem credenciaisVocê não tem permissãoToken de acesso inválidoSeu token de acesso não é válido ou expirou

403 Proibido - reserva não encontrada ou acesso negado

Schema: DownloadEvisaDocumentForbidden

success boolean

Padrão: false

message string

Exemplo "Booking not found or access denied"

404 Nenhum documento de eVisa disponível para esta reserva

Schema: DownloadEvisaDocumentNotFound

success boolean

Padrão: false

message string

Exemplo "No eVisa document available for this booking"

errorCode string

Valores possíveis:

EVISA_DOCUMENT_NOT_AVAILABLEEVISA_DOCUMENT_FILE_NOT_FOUND

hasEvisaDocument boolean

false quando a reserva ainda não tem eVisa anexado; true quando os metadados existem, mas o arquivo está ausente

Exemplo "false"

Experimente

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

post /agents-api/create-corporate

Criar uma conta corporativa conectada

Cria uma empresa sob sua agência e seu identificador corporativo de parceiro. O identificador é armazenado como affiliatePartnerCorporateKey e pode ser usado com corporateIdentifier em outros endpoints corporativos. A pessoa de contato que você fornece também é criada como gerente corporativo.

Requer Autenticação (Token Bearer)

Corpo da Requisição

Schema: CreateCorporateRequest

corporateName Obrigatóriostring

partnerCorporateIdentifier Obrigatóriostring

Identificador corporativo de propriedade do parceiro, único dentro da sua agência

contact Obrigatórioobjeto

Contato principal que também é criado como gerente corporativo

Respostas

201 Empresa criada com sucesso

Schema: CreateCorporateResponse

success boolean

Exemplo true

corporateId string

partnerCorporateIdentifier string

400 Erro de validação

Schema: BadRequest

message string

errorCode string

Padrão: BadRequest

401 Não autorizado

Schema: Unauthorized

success boolean

Padrão: false

message string

Valores possíveis:

Você não tem credenciaisVocê não tem permissãoToken de acesso inválidoSeu token de acesso não é válido ou expirou

409 Identificador corporativo de parceiro já em uso

Schema: BadRequest

message string

errorCode string

Padrão: BadRequest

Experimente

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 empresas da agência

Lista as empresas da agência autenticada. Filtros opcionais são parâmetros de consulta (sem corpo de requisição). Até 100 resultados por página, ordenados do mais recente para o mais antigo. hasPaymentMethod é true quando a empresa tem cobrança configurada para pagar reservas.

Exemplo de URL de requisição

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

Requer Autenticação (Token Bearer)

Parâmetros

corporateId querystring

ObjectId MongoDB corporativo YourVisa

partnerCorporateIdentifier querystring

Identificador corporativo de propriedade do parceiro (correspondência exata)

corporateName querystring

Correspondência parcial de nome, sem diferenciar maiúsculas de minúsculas

page queryinteiro

Número da página (padrão 1)

Respostas

200 Empresas listadas com sucesso

Schema: GetCorporatesResponse

success boolean

Exemplo true

corporates array

Matriz de objeto(clique para ver propriedades)

page inteiro

pageSize inteiro

totalCount inteiro

totalPages inteiro

400 Erro de validação

Schema: BadRequest

message string

errorCode string

Padrão: BadRequest

401 Não autorizado

Schema: Unauthorized

success boolean

Padrão: false

message string

Valores possíveis:

Você não tem credenciaisVocê não tem permissãoToken de acesso inválidoSeu token de acesso não é válido ou expirou

Experimente

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

Configuração de link de pagamento corporativo

Cria um link seguro para o gerente corporativo adicionar um cartão de crédito em uma página hospedada pelo YourVisa. O link expira 12 horas após a criação. corporateIdentifier aceita tanto o ObjectId corporativo YourVisa quanto o identificador corporativo do seu parceiro. Defina isEmbeddedInPartnerPage como true ao incorporar a página de configuração no seu próprio site via iframe ou WebView móvel—a URL retornada tem como alvo /iframe/corporate-payment-setup/{token}, um layout sem barra de navegação que mostra o logotipo YourVisa.ai e links de política legal. O gerente deve aceitar os termos do YourVisa.ai antes de salvar um cartão. Depois que o gerente salva um cartão, a página incorporada emite um evento de host corporate_payment_method_saved. O langKey opcional define o idioma da interface na página de configuração (padrão: en).

Requer Autenticação (Token Bearer)

Corpo da Requisição

Schema: CreateCorporatePaymentSetupLinkRequest

corporateIdentifier Obrigatóriostring

ObjectId corporativo YourVisa ou identificador corporativo do parceiro

isEmbeddedInPartnerPage boolean

Quando true, setupUrl tem como alvo /iframe/corporate-payment-setup/{token} para incorporação em uma página de parceiro sem a barra de navegação YourVisa.

langKey string

Idioma opcional da interface para a página de configuração: en (inglês, padrão), de (alemão), es (espanhol), ru (russo), he (hebraico), ar (árabe), fr (francês)

Valores possíveis:

endeesruhearfr

Respostas

201 Link de configuração criado com sucesso

Schema: CreateCorporatePaymentSetupLinkResponse

success boolean

Exemplo true

token string

setupUrl string

URL completa para enviar ao gerente corporativo

path string

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

expiresAt string

Tempo de expiração do link (12 horas após a criação)

corporateId string

partnerCorporateIdentifier stringnull

isEmbeddedInPartnerPage boolean

Se a página de configuração é destinada à incorporação via iframe

langKey string

Idioma resolvido da interface para a página de configuração

Valores possíveis:

endeesruhearfr

400 Erro de validação

Schema: BadRequest

message string

errorCode string

Padrão: BadRequest

401 Não autorizado

Schema: Unauthorized

success boolean

Padrão: false

message string

Valores possíveis:

Você não tem credenciaisVocê não tem permissãoToken de acesso inválidoSeu token de acesso não é válido ou expirou

403 A empresa não está configurada para cobrança paga pela organização

Schema: BadRequest

message string

errorCode string

Padrão: BadRequest

404 Empresa não encontrada

Schema: BadRequest

message string

errorCode string

Padrão: BadRequest

Detalhes

Etapa 1: Criar link incorporado

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}).

Etapa 2: Carregar o iframe

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

Etapa 3: Ouvir no navegador (pai do 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);
  }
});

Etapa 4: Ouvir no 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);
    }
  }}
/>

Estrutura do evento

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

Quando é disparado

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

Experimente

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"
}'

Criando um link para uma agência afiliada com produto específico

Esta seção explica como construir e usar uma URL especializada para incorporar a solicitação de visto para agências e agentes afiliados.

Uso de Agência Afiliada

Detalhes

Exemplo de URL com productId

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

Exemplo de URL para qualquer produto

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

Domínio

https://www.yourvisa.ai/ - A URL base do serviço, que deve ser incorporada usando um iframe ou aberta diretamente.

productId

Representa o ID único do produto que está sendo reservado.

affiliatedAgencyId

Representa o ID único da agência afiliada ou parceiro que integra o serviço.

affiliatedAgentId

(Campo opcional) Identifica o agente específico dentro da agência afiliada que está gerando o visto.

customKey1-5

(Opcional) Parâmetros de rastreamento personalizados. Você pode incluir até 5 chaves personalizadas (customKey1, customKey2, customKey3, customKey4, customKey5) para fins adicionais de rastreamento ou identificação. Elas serão armazenadas na reserva e enviadas via webhooks.

Dicas para Implementação

  • Sempre valide os parâmetros antes de construir a URL para evitar erros.
  • Teste sua integração em um ambiente de desenvolvimento antes de ir para produção.
  • Mantenha suas credenciais de autenticação seguras e nunca as exponha em código do lado do cliente.
  • Entre em contato com o suporte se precisar de assistência com a implementação.

Criando um link de página de viajante personalizada com informações de país pré-preenchidas

Esta seção explica como construir uma URL especializada que pré-preenche a busca de visto com países de origem e destino específicos, juntamente com o rastreamento de agência afiliada.

Uso de Agência AfiliadaLinks Personalizados

Detalhes

Exemplo de URL com países

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

Exemplo de URL mínima

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

Domínio

https://www.yourvisa.ai/ - A URL base do serviço.

from

(Obrigatório) Código de país de duas letras representando o país de origem do viajante ou nacionalidade do passaporte (ex.: 'IL' para Israel, 'US' para Estados Unidos).

to

(Obrigatório) Código de país de duas letras representando o país de destino (ex.: 'US' para Estados Unidos, 'GB' para Reino Unido).

visaType

(Opcional) Tipo de visto que está sendo solicitado (ex.: 'tourist', 'business', 'student'). Se não for especificado, o padrão é 'tourist'.

affiliatedAgencyId

Representa o ID único da agência afiliada ou parceiro que integra o serviço.

affiliatedAgentId

(Campo opcional) Identifica o agente específico dentro da agência afiliada que está gerando o visto.

customKey1-5

(Opcional) Parâmetros de rastreamento personalizados. Você pode incluir até 5 chaves personalizadas (customKey1, customKey2, customKey3, customKey4, customKey5) para fins adicionais de rastreamento ou identificação. Elas serão armazenadas na reserva e enviadas via webhooks.

Dicas para Implementação

  • Sempre valide os parâmetros antes de construir a URL para evitar erros.
  • Teste sua integração em um ambiente de desenvolvimento antes de ir para produção.
  • Mantenha suas credenciais de autenticação seguras e nunca as exponha em código do lado do cliente.
  • Entre em contato com o suporte se precisar de assistência com a implementação.

Ferramenta interativa

Baixar o testador de iframe

Obtenha uma página HTML autônoma para testar todos os fluxos de iframe incorporados localmente — busca de visto, assistente, checkout instantâneo, configuração de pagamento corporativo e eventos postMessage. Download iframe tester

Visão geral e eventos do host

Embuta os fluxos do YourVisa no seu site ou WebView móvel sem a barra de navegação ou rodapé do YourVisa. Use URLs /iframe/* para incorporação; use as URLs sem iframe ao abrir em uma nova aba do navegador. Superfícies de pagamento incorporadas em um iframe (checkout instantâneo, configuração de cartão corporativo e a etapa de pagamento do assistente de visto) também mostram o logotipo YourVisa.ai e links para termos, privacidade, reembolso e políticas de cookies. A pesquisa de vistos e as etapas do assistente que não envolvem pagamento não incluem essa interface de pagamento.

Iframe Incorporado

Detalhes

Caminho base do iframe

Todas as rotas de iframe estão sob https://www.yourvisa.ai/iframe/.... Elas suprimem a barra de navegação e o rodapé principais do YourVisa.

Marca da página de pagamento

As superfícies de pagamento incorporadas mostram o logotipo YourVisa.ai e links de políticas legais: /iframe/instant-visa-checkout, /iframe/corporate-payment-setup/{token} e a etapa de pagamento dentro de /iframe/visa-wizard. A pesquisa de vistos e outras etapas do assistente não mostram.

Ouça 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 opcionais

Em /iframe/traveler, /iframe/visa-wizard e /iframe/instant-visa-checkout, você pode anexar: customKey1..5, langKey (ex.: &langKey=he).

Suporte a idiomas (URLs de iframe diretas)

Anexe langKey como um parâmetro de consulta nas URLs de iframe que você mesmo construir. Valores suportados: en (padrão), de, es, ru, he, ar, fr. Pesquisa de viajante: https://www.yourvisa.ai/iframe/traveler?affiliatedAgencyId={agencyId}&customKey1={value1}&langKey=he Checkout instantâneo: https://www.yourvisa.ai/iframe/instant-visa-checkout?productId={productId}&affiliatedAgencyId={agencyId}&isInstantPayment=true&travelerClient=web&customKey1={value1}&langKey=de

Suporte a idiomas (URL do assistente de visto)

Anexe langKey como um parâmetro de consulta ao construir a URL do iframe diretamente. https://www.yourvisa.ai/iframe/visa-wizard?productId={productId}&affiliatedAgencyId={agencyId}&customKey1={value1}&langKey=de

Suporte a idiomas (link de aplicação assinado)

Se você já tiver um bookedProductId e precisar de um link tokenizado, passe langKey no POST /agents-api/get-application-link. Use applicationUrl da resposta como o src do iframe.

Suporte a idiomas (configuração de pagamento corporativo)

Passe langKey no POST /agents-api/create-corporate-payment-setup-link. A resposta setupUrl o inclui quando fornecido. {"corporateIdentifier": "acme-001", "isEmbeddedInPartnerPage": true, "langKey": "he"} Exemplo de caminho setupUrl: /iframe/corporate-payment-setup/{token}?langKey=he

Marca personalizada

Se sua agência tiver a marca personalizada ativada, as rotas de iframe aplicam automaticamente sua experiência com a marca.

Dicas para implementação

  • Sempre valide os parâmetros antes de construir a URL para evitar erros.
  • Teste sua integração em um ambiente de desenvolvimento antes de entrar em produção.
  • Mantenha suas credenciais de autenticação seguras e nunca as exponha no código do lado do cliente.
  • Entre em contato com o suporte se precisar de assistência com a implementação.

Assistente de aplicação de visto

Embuta o assistente de aplicação de visto quando você já sabe qual produto o viajante deve solicitar. Aponte o iframe para /iframe/visa-wizard com productId e seu affiliatedAgencyId.

Iframe IncorporadoAplicação de Visto

Detalhes

URL direta do iframe

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

Exemplo

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

Incorporar

<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 obrigatórios

productId — o produto de visto que o viajante está solicitando. affiliatedAgencyId — o ID da sua agência para que a reserva seja atribuída à sua conta.

Parâmetros opcionais

customKey1..5, langKey (ex.: &langKey=he).

Autônomo vs iframe

Use /iframe/visa-wizard para incorporar no seu site. Use /visa-wizard com os mesmos parâmetros de consulta ao abrir em uma nova aba do navegador.

Ouça a conclusão

Após o envio, o iframe envia application_submitted para a página pai.

Já tem um bookedProductId?

Se o viajante já pagou ou você criou uma reserva via API, use POST /agents-api/get-application-link com isIframe: true. Isso retorna um applicationUrl assinado com um token para a reserva existente.

Dicas para implementação

  • Sempre valide os parâmetros antes de construir a URL para evitar erros.
  • Teste sua integração em um ambiente de desenvolvimento antes de entrar em produção.
  • Mantenha suas credenciais de autenticação seguras e nunca as exponha no código do lado do cliente.
  • Entre em contato com o suporte se precisar de assistência com a implementação.

Checkout de pagamento instantâneo

Embuta o pagamento instantâneo quando você já sabe o productId.

Carregue o checkout em /iframe/instant-visa-checkout dentro do seu site ou aplicativo. A página mostra o logotipo YourVisa.ai e links para nossas políticas legais.

Após o pagamento, sua integração segue um de três caminhos — entre em contato com o YourVisa para configurar a opção que se adequa ao seu produto.

Iframe IncorporadoPagamento Instantâneo

Detalhes

Após o pagamento — opção 1: Redirecionar para seu site

O YourVisa envia o viajante para uma URL de redirecionamento que você fornece antecipadamente. Os parâmetros de consulta incluem bookedProductId, productId, paymentStatus=paid e quaisquer customKey1..5 não vazios. Funciona tanto para travelerClient=web quanto para travelerClient=app. Entre em contato com o suporte do YourVisa para solicitar ou alterar sua URL de redirecionamento — ela não pode ser definida pela API.

Após o pagamento — opção 2: Permanecer incorporado (evento de iframe)

Quando o checkout é executado dentro de um iframe, sua página pai recebe uma postMessage instant_payment_complete assim que o pagamento é bem-sucedido. Use isso para fechar o iframe, mostrar sua própria confirmação ou continuar na sua interface. Veja Ouça a conclusão do pagamento e Evento: instant_payment_complete abaixo.

Após o pagamento — opção 3: Continuar o assistente de visto

O viajante segue diretamente para o assistente de visto do YourVisa no mesmo iframe ou aba — sem redirecionamento e sem tela de transferência para o parceiro. Nenhum instant_payment_complete é enviado no momento do pagamento. Ouça application_submitted depois que o viajante terminar e enviar o formulário de visto.

Combinando as opções 1 e 2

Quando uma URL de redirecionamento está configurada, o checkout incorporado ainda dispara instant_payment_complete imediatamente, mostra uma breve tela de pagamento concluído e depois redireciona dentro do iframe após alguns segundos. Isso dá tempo à sua página para fechar o iframe ou lidar com o evento antes do redirecionamento.

Incorporar checkout

<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 obrigatórios

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

Parâmetros opcionais

customKey1..5, langKey (ex.: &langKey=he), travelerFirstName, travelerLastName, travelerEmail, travelerPhone.

travelerClient

web — o viajante começa pelo seu site ou iframe incorporado. app — o viajante começa pelo seu aplicativo móvel nativo; o pagamento pode abrir em uma aba externa do navegador ou WebView.

Nenhuma URL de redirecionamento configurada

Se a transferência para o parceiro estiver ativada, mas nenhuma URL de redirecionamento estiver definida, os viajantes veem uma tela de agradecimento informando que o pagamento foi recebido e que devem retornar ao seu aplicativo ou site. Encontre a reserva paga com GET /agents-api/get-products-history ou retome com POST /agents-api/get-application-link.

Ouça a conclusão do pagamento (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.

Exemplo completo de integração

<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>

Exemplo de URL de redirecionamento

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.

Ouça o envio da aplicação (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 } });

Dicas para implementação

  • Sempre valide os parâmetros antes de construir a URL para evitar erros.
  • Teste sua integração em um ambiente de desenvolvimento antes de entrar em produção.
  • Mantenha suas credenciais de autenticação seguras e nunca as exponha no código do lado do cliente.
  • Entre em contato com o suporte se precisar de assistência com a implementação.

Configuração de método de pagamento corporativo

Embuta a página de configuração de cartão corporativo para que um gerente corporativo possa salvar um método de pagamento dentro do seu site. Requer POST /agents-api/create-corporate-payment-setup-link com isEmbeddedInPartnerPage: true. A página incorporada mostra o logotipo YourVisa.ai e links de políticas legais.

Iframe IncorporadoCorporativo

Detalhes

Etapa 1: Criar link incorporado

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).

Etapa 2: Carregar o iframe

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

Parâmetros opcionais

Apenas langKey — definido no corpo do POST ao criar o link (ex.: "langKey": "he"). O setupUrl retornado o inclui. customKey1..5 não se aplicam a este fluxo.

Etapa 3: Ouvir no 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); } });

Quando dispara

Somente quando isEmbeddedInPartnerPage era true na criação do link e após o servidor confirmar o salvamento do cartão.

Dicas para implementação

  • Sempre valide os parâmetros antes de construir a URL para evitar erros.
  • Teste sua integração em um ambiente de desenvolvimento antes de entrar em produção.
  • Mantenha suas credenciais de autenticação seguras e nunca as exponha no código do lado do cliente.
  • Entre em contato com o suporte se precisar de assistência com a implementação.

Servidor MCP — conecte assistentes de IA ao YourVisa.ai

O servidor MCP (Model Context Protocol) do YourVisa permite que qualquer assistente de IA compatível — Claude Desktop, Cursor e outros — consulte requisitos de visto, taxas e gere links de aplicação em tempo real. É um serviço HTTP remoto usando o transporte HTTP Streamable e requer uma chave de API.

Integração MCPIA

Detalhes

1. Obtenha uma chave de API

Faça login na sua conta YourVisa.ai, vá para Painel → aba API MCP e clique em 'Nova Chave'. Copie e salve — ela é mostrada apenas uma vez.

2. Adicione à configuração do seu cliente MCP

Adicione o bloco de configuração mostrado abaixo ao arquivo de configuração do seu cliente MCP (ex.: claude_desktop_config.json para Claude Desktop, ou as configurações de MCP no Cursor).

3. Ferramentas disponíveis

search_visas · get_visa_details · get_visa_requirements · get_visa_fees · get_application_link · get_country_info

4. Sem estado e somente leitura

O servidor MCP apenas lê dados. Nenhuma reserva ou gravação é realizada via MCP.

5. Limites de taxa

Plano gratuito: 60 solicitações / minuto.

Exemplo de resposta

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

Dicas para implementação

  • Sempre valide os parâmetros antes de construir a URL para evitar erros.
  • Teste sua integração em um ambiente de desenvolvimento antes de entrar em produção.
  • Mantenha suas credenciais de autenticação seguras e nunca as exponha no código do lado do cliente.
  • Entre em contato com o suporte se precisar de assistência com a implementação.

Defina uma URL de webhook para receber notificações quando aplicações de visto forem enviadas

Nas configurações da sua conta, você pode definir uma URL de webhook para ser notificado sempre que sua agência enviar uma aplicação de visto. Cada notificação inclui os custos do visto e quem paga.

Configurações da ContaWebhook

Detalhes

Onde definir

Faça login no seu painel e vá para a aba 'Configurações da Conta'. Lá você pode adicionar ou atualizar sua URL de webhook.

Para que serve

Seu webhook será acionado toda vez que uma aplicação de visto for enviada pela sua agência. O payload inclui os custos do visto e se o viajante/empregado ou a empresa/agência paga.

Informações de pagamento

paymentDetails inclui os custos do visto (taxa governamental, taxa de serviço, taxa de velocidade de processamento e total) e quem paga. paidBy é CLIENT quando o viajante ou empregado paga, e AGENT quando a empresa ou agência paga. Se o administrador do YourVisa ativar o compartilhamento de dados do candidato para sua agência, o webhook também inclui applicantDetails e URLs de download com limite de tempo para cada arquivo em applicantUploads. Essas URLs expiram após 5 minutos e funcionam com um GET HTTPS normal do seu servidor.

Exemplo de uso

Você pode usar isso para sincronizar aplicações com seu CRM interno, enviar alertas ou executar lógica personalizada em novos envios.

Exemplo de resposta

{
  "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": {}
}

Dicas para implementação

  • Sempre valide os parâmetros antes de construir a URL para evitar erros.
  • Teste sua integração em um ambiente de desenvolvimento antes de entrar em produção.
  • Mantenha suas credenciais de autenticação seguras e nunca as exponha no código do lado do cliente.
  • Entre em contato com o suporte se precisar de assistência com a implementação.