Integrações - API REST V1

O que é

A API REST V1 do Viagilize é o canal técnico que permite a sistemas externos (ERPs, CRMs, motores de reserva, automações) ler e escrever dados da sua empresa em tempo real. Todos os endpoints ficam sob o prefixo /api/v1, respondem em JSON e exigem um token Bearer emitido na página Configurações > API, na aba Tokens de Acesso.

Este artigo é a referência técnica complementar ao artigo principal de configuração - quem cria/revoga tokens e webhooks deve ler antes Configurações - API e Webhooks. Aqui está o detalhe que o desenvolvedor precisa: como autenticar, qual o formato padrão das respostas, quais escopos cada endpoint exige e a lista completa de rotas com os respectivos verbos HTTP.

O time normalmente chega aqui depois de já ter gerado o token e precisa entender quais chamadas fazer, por exemplo: "como crio uma reserva via API?", "como registro um pagamento de passageiro?" ou "como consulto as excursões publicadas?".

Como usar

1. Gere um token de API em Configurações > API > Tokens de Acesso (ver artigo pai).
2. Defina a URL Base das chamadas usando o domínio da sua empresa: https://{dominio-do-tenant}/api/v1.
3. Em toda requisição, envie o header Authorization: Bearer {seu_token} (formato do token: vgl_ seguido de 48 caracteres).
4. Use Content-Type: application/json para POST, PUT e PATCH. Respostas sempre vêm em JSON.

Formato padrão das respostas

Sucesso simples:

{
  "success": true,
  "data": { ... }
}

Sucesso paginado (listagens com ?per_page e ?page):

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 120,
    "last_page": 8
  }
}

Erro:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Os dados fornecidos são inválidos.",
    "details": { ... }
  }
}

Códigos de erro usados: AUTHENTICATION_ERROR (401), AUTHORIZATION_ERROR (403), NOT_FOUND (404), VALIDATION_ERROR (422) e códigos específicos do recurso retornados pelo controller.

Escopos disponíveis

Cada token recebe um ou mais escopos. O uma trava de acesso valida o escopo declarado na rota. Se faltar permissão, retorna HTTP 403 com o campo required_scopes.

Recurso	Escopos
Excursões	excursoes:read, excursoes:write, excursoes:delete
Clientes	clientes:read, clientes:write, clientes:delete
Passageiros	passageiros:read, passageiros:write, passageiros:delete
Reservas (Orders)	reservas:read, reservas:write
Financeiro	financeiro:read, financeiro:write
Guias	guias:read, guias:write, guias:delete
Transportes	transportes:read, transportes:write, transportes:delete
Veículos	veiculos:read, veiculos:write, veiculos:delete
Check-in	checkin:read, checkin:write
Webhooks	webhooks:manage

Endpoints - Excursões

Base: /api/v1/excursoes.

Método	Rota	Escopo
GET	/api/v1/excursoes	excursoes:read
GET	/api/v1/excursoes/{id}	excursoes:read
GET	/api/v1/excursoes/{id}/stats	excursoes:read
POST	/api/v1/excursoes	excursoes:write
PUT	/api/v1/excursoes/{id}	excursoes:write
DELETE	/api/v1/excursoes/{id}	excursoes:delete
GET	/api/v1/excursoes/{excursaoId}/conteudo	excursoes:read
PUT	/api/v1/excursoes/{excursaoId}/conteudo	excursoes:write
POST	/api/v1/excursoes/{excursaoId}/conteudo/publicar	excursoes:write
POST	/api/v1/excursoes/{excursaoId}/conteudo/despublicar	excursoes:write
GET	/api/v1/excursoes/{excursaoId}/fotos	excursoes:read
POST	/api/v1/excursoes/{excursaoId}/fotos	excursoes:write
PUT	/api/v1/excursoes/{excursaoId}/fotos/{id}	excursoes:write
DELETE	/api/v1/excursoes/{excursaoId}/fotos/{id}	excursoes:delete
POST	/api/v1/excursoes/{excursaoId}/fotos/reorder	excursoes:write
POST	/api/v1/excursoes/{excursaoId}/capa	excursoes:write
GET	/api/v1/excursoes/{excursaoId}/categorias	excursoes:read
POST	/api/v1/excursoes/{excursaoId}/categorias	excursoes:write
GET	/api/v1/excursoes/{excursaoId}/embarques	excursoes:read
POST	/api/v1/excursoes/{excursaoId}/embarques	excursoes:write
GET	/api/v1/excursoes/{excursaoId}/precos	excursoes:read
POST	/api/v1/excursoes/{excursaoId}/precos	excursoes:write
PATCH	/api/v1/excursoes/{excursaoId}/precos/bulk	excursoes:write
GET	/api/v1/excursoes/{excursaoId}/guias	guias:read
POST	/api/v1/excursoes/{excursaoId}/guias	guias:write
GET	/api/v1/excursoes/{excursaoId}/transportes	transportes:read
POST	/api/v1/excursoes/{excursaoId}/transportes	transportes:write

Endpoints - Clientes

Base: /api/v1/clientes.

Método	Rota	Escopo
GET	/api/v1/clientes	clientes:read
GET	/api/v1/clientes/cpf	clientes:read
GET	/api/v1/clientes/{id}	clientes:read
GET	/api/v1/clientes/{id}/reservas	clientes:read
POST	/api/v1/clientes	clientes:write
PUT	/api/v1/clientes/{id}	clientes:write
DELETE	/api/v1/clientes/{id}	clientes:delete
POST	/api/v1/clientes/{id}/auto-login	clientes:write
DELETE	/api/v1/clientes/{id}/auto-login	clientes:write
GET	/api/v1/clientes/{id}/dependentes	clientes:read
POST	/api/v1/clientes/{id}/dependentes	clientes:write
PUT	/api/v1/clientes/{id}/dependentes/{dependenteId}	clientes:write
DELETE	/api/v1/clientes/{id}/dependentes/{dependenteId}	clientes:delete

Endpoints - Reservas

Base: /api/v1/reservas. Cria a Order completa (cliente comprador + passageiros agrupados).

Método	Rota	Escopo
GET	/api/v1/reservas	reservas:read
GET	/api/v1/reservas/{id}	reservas:read
GET	/api/v1/reservas/{id}/contrato-status	reservas:read
POST	/api/v1/reservas	reservas:write
POST	/api/v1/reservas/{id}/payment-link	reservas:write
POST	/api/v1/reservas/{id}/magic-link	reservas:write
POST	/api/v1/reservas/{id}/payments	reservas:write
POST	/api/v1/reservas/{id}/cancel	reservas:write

Endpoints - Passageiros (vinculados a uma excursão)

Base: /api/v1/excursoes/{excursaoId}/passageiros.

Método	Rota	Escopo
GET	/api/v1/excursoes/{excursaoId}/passageiros	passageiros:read
GET	/api/v1/excursoes/{excursaoId}/passageiros/{id}	passageiros:read
POST	/api/v1/excursoes/{excursaoId}/passageiros	passageiros:write
PUT	/api/v1/excursoes/{excursaoId}/passageiros/{id}	passageiros:write
DELETE	/api/v1/excursoes/{excursaoId}/passageiros/{id}	passageiros:delete
POST	/api/v1/excursoes/{excursaoId}/passageiros/{id}/checkin	checkin:write
GET	/api/v1/excursoes/{excursaoId}/passageiros/{id}/cartao-embarque	passageiros:read

Endpoints - Financeiro do passageiro

Método	Rota	Escopo
GET	/api/v1/excursoes/{excursaoId}/passageiros/{passageiroId}/financeiro	financeiro:read
GET	/api/v1/excursoes/{excursaoId}/passageiros/{passageiroId}/pagamentos	financeiro:read
POST	/api/v1/excursoes/{excursaoId}/passageiros/{passageiroId}/pagamentos	financeiro:write
GET	/api/v1/excursoes/{excursaoId}/financeiro/resumo	financeiro:read

Endpoints - Lista de espera

Método	Rota	Escopo
GET	/api/v1/lista-espera	reservas:read
GET	/api/v1/lista-espera/{id}	reservas:read
POST	/api/v1/lista-espera	reservas:write
DELETE	/api/v1/lista-espera/{id}	reservas:write

Endpoints - Webhooks (CRUD via API)

Base: /api/v1/webhooks. Os mesmos webhooks gerenciados pela UI podem ser criados/listados via API.

Método	Rota	Escopo
GET	/api/v1/webhooks/events	webhooks:manage
GET	/api/v1/webhooks	webhooks:manage
GET	/api/v1/webhooks/{id}	webhooks:manage
POST	/api/v1/webhooks	webhooks:manage
PUT	/api/v1/webhooks/{id}	webhooks:manage
DELETE	/api/v1/webhooks/{id}	webhooks:manage
POST	/api/v1/webhooks/{id}/regenerate-secret	webhooks:manage
POST	/api/v1/webhooks/{id}/test	webhooks:manage

Endpoints - Dados mestres (Guias, Transportes, Veículos)

Método	Rota	Escopo
GET	/api/v1/guias	guias:read
POST	/api/v1/guias	guias:write
PUT	/api/v1/guias/{id}	guias:write
PATCH	/api/v1/guias/{id}/status	guias:write
GET	/api/v1/transportes	transportes:read
POST	/api/v1/transportes	transportes:write
PUT	/api/v1/transportes/{id}	transportes:write
PATCH	/api/v1/transportes/{id}/status	transportes:write
GET	/api/v1/veiculos	veiculos:read
GET	/api/v1/veiculos/tipos	veiculos:read
POST	/api/v1/veiculos	veiculos:write
PATCH	/api/v1/veiculos/{id}/status	veiculos:write

Casos especiais

Parâmetros numéricos obrigatórios

Os parâmetros {id}, {excursaoId}, {passageiroId} e {dependenteId} são restritos a dígitos ([0-9]+) por pattern global. Chamadas com strings (ex.: /api/v1/excursoes/publicadas) caem como rota não encontrada antes de chegar ao controller - use o slug ou ID numérico correto.

Magic link e auto-login do cliente

O endpoint POST /api/v1/clientes/{id}/auto-login gera um link de uso único válido por 30 minutos para que o cliente acesse o portal sem precisar criar senha. Útil para sistemas externos que querem direcionar o cliente direto para a área dele depois de uma compra.

Geração de link de pagamento e magic link da reserva

Após criar a reserva via POST /api/v1/reservas, use POST /api/v1/reservas/{id}/payment-link para gerar a URL de checkout PIX/cartão, ou POST /api/v1/reservas/{id}/magic-link para um link direto ao status da reserva no portal do cliente.

Logs de requisições

Todas as chamadas autenticadas são gravadas em api_request_logs com método, endpoint, status, tempo de resposta, IP e user-agent. Você pode acompanhá-las em Configurações > API > Logs > Requisições com filtros por token, status, método e período (24h, 48h, 7 dias ou 30 dias).

Mascaramento de dados sensíveis nos logs de erro

Quando a API loga um erro 4xx/5xx, campos como password, token, secret, cpf, cnpj, rg, cartao, cvv e variações são automaticamente substituídos por *** antes de irem para o log do servidor. Isto preserva a LGPD e evita vazamento de credenciais nos logs de produção.

Token sem escopo correto

Se a rota exige excursoes:write e o token só tem excursoes:read, a resposta é HTTP 403 com payload contendo required_scopes. Solução: edite o token na UI marcando o escopo faltante, ou crie um novo token específico para a integração.

Erros comuns e como resolver

• HTTP 401 "Token de API não fornecido." - Causa: header Authorization ausente. Solução: envie Authorization: Bearer vgl_xxxxxxxxxxxx em toda requisição.
• HTTP 401 "Token de API inválido." - Causa: token não encontrado no banco, geralmente porque foi regenerado ou copiado errado. Solução: gere um novo token e atualize o sistema integrado.
• HTTP 401 "Token de API expirado." - Causa: a data informada em Data de Expiração foi alcançada. Solução: edite o token na UI para estender a validade ou crie um novo.
• HTTP 401 "Token de API revogado." - Causa: o token foi desativado pelo botão Revogar. Solução: reative apenas se for seguro, ou crie um novo token.
• HTTP 403 "Token não tem permissão para este recurso." - Causa: faltam escopos no token. Solução: confira o campo required_scopes na resposta e adicione os escopos ausentes.
• HTTP 404 (recurso não encontrado) - Causa: ID inexistente na sua empresa, ou parâmetro não-numérico em rota que exige [0-9]+. Solução: confirme o ID com GET /api/v1/{recurso} antes de operar.
• HTTP 422 VALIDATION_ERROR - Causa: payload com campos faltando ou em formato inválido. Solução: inspecione error.details no JSON de resposta - ele traz a lista de campos com a mensagem de cada erro.
• HTTP 500 inesperado - Causa: erro interno no Viagilize. Solução: registre o endpoint e o horário e acione o suporte; a equipe encontra o erro nos logs do servidor (com payload mascarado).

Onde encontrar

• URL Base: https://{dominio-do-tenant}/api/v1
• Gestão de tokens: /admin/configuracoes/api (aba Tokens de Acesso)
• Documentação interativa e downloads (Postman + OpenAPI): /admin/configuracoes/api#docs
• Permissão necessária para gerenciar tokens: ver as configurações e editar as configurações
• Módulo necessário: nenhum

Veja também

• Configurações - API e Webhooks
• Webhooks
• Integrações e Conectores