API e MCP do PaxWays

Crie uma chave no painel em Configurações → API e MCP e escolha o que ela pode fazer. Envie a chave em toda chamada:

Authorization: Bearer mtb_live_...

A chave vale para um workspace. Cada pessoa da equipe pode criar a própria chave, que vê e faz só o que essa pessoa pode no painel (webhooks: só o dono). Limite: 120 chamadas por minuto por chave. Envio de mensagens tem limite próprio: 30 por minuto; primeiro contato (lead que nunca conversou, criado há menos de 24 h) 10 por minuto e 100 por dia. Lead antigo sem conversa não recebe mensagem pela API.

O servidor MCP fica em https://www.paxways.com/api/mcp. Com ele a IA consulta viagens, reservas e leads, cria leads e tarefas e muda etapas, sempre dentro das permissões que você der.

Claude (claude.ai e Claude Desktop): Configurações → Conectores → Adicionar conector personalizado → cole a URL acima. Você faz login no PaxWays e escolhe as permissões.

ChatGPT: Configurações → Conectores (modo desenvolvedor) → Criar → cole a URL acima e escolha OAuth.

Claude Code:

claude mcp add --transport http paxways https://www.paxways.com/api/mcp \
  --header "Authorization: Bearer mtb_live_..."

Cursor e outros clientes (arquivo mcp.json):

{
  "mcpServers": {
    "paxways": {
      "url": "https://www.paxways.com/api/mcp",
      "headers": { "Authorization": "Bearer mtb_live_..." }
    }
  }
}

Ações (criar lead, mudar etapa, criar tarefa, enviar mensagem): use o módulo HTTP / Webhooks da ferramenta com a URL base https://www.paxways.com/api/v1 e o cabeçalho de autorização acima. A especificação OpenAPI está em https://www.paxways.com/api/v1/openapi.json.

Gatilhos (quando algo acontece): crie um webhook em Configurações → API e MCP apontando para a URL do gatilho “Catch Hook” (Zapier), “Custom webhook” (Make) ou “Webhook” (n8n). Ou assine por API com POST /webhooks (eventos de lead exigem crm:read; de reserva e pagamento, bookings:read).

No n8n também dá para usar o nó “MCP Client” com a URL do MCP.

curl https://www.paxways.com/api/v1/leads \
  -H "Authorization: Bearer mtb_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Maria Souza","phone":"11999998888","note":"Veio do formulário do site"}'

Base: https://www.paxways.com/api/v1. Listas devolvem { data: [...], nextCursor }; passe ?cursor= para a próxima página. Erros vêm como { error: { code, message } }.

• get/meWorkspace e permissões da chave (teste de conexão).
• get/tripsLista viagens.trips:read
• get/trips/{tripId}Viagem com saídas, pacotes, vagas, roteiro dia a dia, incluso/não incluso e perguntas frequentes.trips:read
• get/itinerariesLista itinerários (propostas e roteiros do menu Itinerários).trips:read
• get/itineraries/{itineraryId}Itinerário com os dias e os itens de cada dia.trips:read
• get/bookingsLista reservas (comprador, total, pago, saldo).bookings:read
• get/bookings/overdueReservas com parcela vencida e o valor em atraso.bookings:read
• get/bookings/{booking}Reserva com participantes, pagamentos e parcelas.bookings:read
• get/pipelinesFunis do CRM e suas etapas.crm:read
• get/leadsLista leads.crm:read
• post/leadsCria um lead (e o contato, se vier e-mail ou telefone).crm:write
• get/leads/{leadId}Lead com notas, tarefas, reservas e últimas mensagens.crm:read
• patch/leads/{leadId}Muda o lead de etapa (dispara as automações da etapa).crm:write
• post/leads/{leadId}/notesAdiciona uma nota interna.crm:write
• post/leads/{leadId}/messagesEnvia mensagem ao cliente pelo WhatsApp/Instagram da conversa. Primeiro contato só com lead criado há menos de 24 h. Limites por chave: 30/min; primeiro contato 10/min e 100/dia.messages:send
• get/tasksLista tarefas.crm:read
• post/tasksCria uma tarefa num lead.crm:write
• get/contactsLista contatos.crm:read
• get/webhooksLista webhooks do workspace.webhooks:manage
• post/webhooksAssina eventos (REST hooks para Zapier/Make). Devolve o secret da assinatura. Eventos de lead exigem crm:read; de reserva e pagamento, bookings:read.webhooks:manage
• delete/webhooks/{webhookId}Remove a assinatura.webhooks:manage

Enviamos um POST JSON para a sua URL a cada evento. Se falhar, tentamos de novo em 1, 5, 30, 120 e 720 minutos.

• lead.created — Lead criado
• lead.stage_changed — Lead mudou de etapa
• booking.created — Reserva criada
• payment.confirmed — Pagamento confirmado
• payment.failed — Pagamento recusado
• payment.refunded — Pagamento reembolsado

{
  "id": "entrega-id",
  "event": "lead.created",
  "createdAt": "2026-10-28T12:00:00.000Z",
  "data": { ...o lead ou a reserva... }
}

Para conferir que veio do PaxWays, valide o cabeçalho X-PaxWays-Signature: t=<timestamp>,v1=<assinatura>: a assinatura é o HMAC-SHA256 de "<timestamp>.<corpo>" com o secret do webhook.

import crypto from "node:crypto";

function verify(secret, header, rawBody) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}