API Iterpec

Cada serviço depende de contratação e habilitação próprias. Se Hotel, RentACar, Transfer, Tour, Flight, Insurance, Payment, ClientBackOffice ou Commons ainda não estiver contratado/habilitado, contate comercial@iterpec.com; acesso a um serviço não habilita os demais. Melhorias documentais preservam a URL base dinâmica https://ws.iterpec.com; Commons mantém seu endereço próprio.

Testes em produção: reservas reais e cancelamento obrigatório
hubGraphQL · v2.5.0

Catálogo Iterpec via GraphQL

Endpoint autenticado POST /api/catalog/graphql que serve o conteúdo dos ZIPs oficiais (hotéis + destinos) já normalizado, paginado e versionado por release. Use este endpoint para montar e manter seu catálogo local. Na carga inicial, cacheie Hotel.svc/HotelDetail de todos os hotéis em segundo plano; depois renove somente os novos ou alterados, usando a data da fonte.

lockPré-requisitos

  • Token de workspace wsk_* emitido pela Iterpec após contrato assinado e formuláriocliente preenchido.
  • O mesmo token usado no MCP Server autentica o GraphQL — não há chave separada.
  • Rate-limit por workspace: 120 req/min. Resposta 429 vem com header Retry-After.

schemaSchema

# GraphQL Schema — trecho de referência (read-only)
type Destination {
  id: ID!
  name: String!
  countryCode: String
  type: String
  nameEn: String
  nameEs: String
  namePt: String
  parentDestinationId: String
}

type Hotel {
  id: ID!
  name: String!
  destinationId: String
  countryCode: String
  category: String
  address: String
  latitude: Float
  longitude: Float
  lastUpdateSource: String
  chain: String
  phone: String
  zipCode: String
  website: String
  thumbnailUrl: String
  fax: String
}

type Release {
  id: Int!
  version: String!
  releasedAt: String!
  hotelsCount: Int!
  destinationsCount: Int!
  hotelsSha256: String
  destinationsSha256: String
  isCurrent: Boolean!
}

type SyncStatus {
  workspaceCid: String!
  currentReleaseId: Int
  lastFullSyncReleaseId: Int
  lastFullSyncAt: String
  daysSinceSync: Int
  isStale: Boolean!
  note: String
}

type Query {
  currentRelease: Release
  destinations(country: String, search: String, limit: Int = 50, offset: Int = 0): [Destination!]!
  destination(id: ID!): Destination
  hotels(destinationId: ID, country: String, search: String, limit: Int = 50, offset: Int = 0): [Hotel!]!
  hotel(id: ID!): Hotel
  syncStatus: SyncStatus!
}

receipt_longHeaders de resposta

  • X-Catalog-Release-Id — id do release atual; mude o cache local quando mudar.
  • X-Catalog-Version — versão semântica do release.
  • X-RateLimit-Limit / X-RateLimit-Remaining — controle de quota.

terminalExemplo cURL — hotéis de um destino

curl -X POST https://iterpec.com/api/catalog/graphql \
  -H "Authorization: Bearer wsk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query($d:ID!,$l:Int!,$o:Int!){ hotels(destinationId:$d,limit:$l,offset:$o){ id name category latitude longitude } }",
    "variables": { "d": "1006065", "l": 500, "o": 0 }
  }'

syncFull sync paginado (Node.js)

Inclua destinations e hotels na mesma operação para o servidor marcar last_full_sync_at do workspace.

// Full sync paginado (destinos + hotéis) — marca last_full_sync_at no workspace
const ENDPOINT = "https://iterpec.com/api/catalog/graphql";
const TOKEN = process.env.ITERPEC_WORKSPACE_TOKEN; // wsk_*

async function gql(query, variables) {
  const res = await fetch(ENDPOINT, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query, variables }),
  });
  if (res.status === 429) {
    const retry = Number(res.headers.get("Retry-After") ?? 30);
    await new Promise(r => setTimeout(r, retry * 1000));
    return gql(query, variables);
  }
  const releaseId = res.headers.get("X-Catalog-Release-Id");
  const body = await res.json();
  if (body.errors) throw new Error(JSON.stringify(body.errors));
  return { data: body.data, releaseId };
}

const LIMIT = 500;
const all = { destinations: [], hotels: [] };
let offset = 0;
while (true) {
  const { data, releaseId } = await gql(
    `query($l:Int!,$o:Int!){
        destinations(limit:$l, offset:$o){ id name countryCode type }
        hotels(limit:$l, offset:$o){ id name destinationId category address latitude longitude lastUpdateSource }
      }`,
    { l: LIMIT, o: offset },
  );
  all.destinations.push(...data.destinations);
  all.hotels.push(...data.hotels);
  console.log(`offset=${offset} release=${releaseId} +${data.hotels.length} hotels`);
  if (data.hotels.length < LIMIT && data.destinations.length < LIMIT) break;
  offset += LIMIT;
}
console.log("done", all.destinations.length, all.hotels.length);

monitoringStatus de sincronização

Workspaces que ficam >30 dias sem full sync entram em isStale=true. Após >50 dias, comercial@iterpec.com é notificado automaticamente.

query {
  syncStatus {
    workspaceCid
    currentReleaseId
    lastFullSyncAt
    daysSinceSync
    isStale
  }
  currentRelease {
    id version releasedAt hotelsCount destinationsCount hotelsSha256
  }
}

schedulePolítica de refresh

  • A Iterpec publica novo release mensal — nosso cron ingere automaticamente.
  • Cacheie por release_id. Se mudar → re-sync completo.
  • Lista GraphQL: capture todos os hotéis e destinos rapidamente, dentro da quota de 120 requisições/minuto; não aplicar o limite dos detalhes à listagem.
  • Detalhes completos: cada cliente mantém seu cache. Carga inicial em fila persistente de três hotéis por minuto (um a cada 20 segundos), iniciando no máximo uma nova sincronização por dia e retomando a existente.
  • A cada 30 dias, selecione lastUpdateSource pelo GraphQL e atualize detalhes apenas dos novos/alterados nos últimos 30 dias. Recupere também ciclos atrasados.
  • releasedAt é a data da release, não a data de alteração do hotel. Uma nova release não exige baixar todos os detalhes novamente.
  • Fotos e descrições vêm do cache; disponibilidade, tarifa e condições continuam consultadas ao vivo.
  • Sincronização regular dos detalhes: mensal e incremental, não durante a pesquisa. Os limites são práticas a implementar no cliente, não bloqueios novos do catálogo GraphQL.
  • HotelDetail em tempo real: consultar diretamente Cangooroo/Commons, com credenciais próprias e respeitando os limites do fornecedor.

updateHotelDetail — atualização incremental em 30 dias

O GraphQL retorna lastUpdateSource, mas ainda não aceita filtro por data. Percorra as páginas e compare as datas localmente. Hotel novo, data alterada ou data ausente exigem atualização; grave a versão no cache somente após sucesso.

query HotelsForDetailRefresh($limit: Int!, $offset: Int!) {
  hotels(limit: $limit, offset: $offset) {
    id name destinationId address latitude longitude lastUpdateSource
  }
}
// Exemplo de seleção no ambiente do cliente — depois de paginar o GraphQL.
// Catálogo leve: paginar o mais rápido possível dentro da quota existente;
// NÃO aplicar três hotéis/minuto à lista GraphQL.
// Só a fila de DETALHES: 3 hotéis/minuto, um hotel a cada 20 segundos.
// Iniciar no máximo uma sincronização de detalhes por dia; retomar a existente.
// Não há filtro por data no servidor: lastUpdateSource é um campo retornado.
const cutoff = Math.min(
  Date.now() - 30 * 24 * 60 * 60 * 1000,
  lastSuccessfulSyncAt ?? Date.now(), // recuperar ciclos atrasados
);
for (const hotel of allHotels) {
  const cached = await detailCache.get(hotel.id);
  const sourceTime = hotel.lastUpdateSource ? Date.parse(hotel.lastUpdateSource) : NaN;
  const refresh = !cached || !Number.isFinite(sourceTime)
    || sourceTime >= cutoff || cached.lastUpdateSource !== hotel.lastUpdateSource;
  if (!refresh) continue;
  // Fila persistente de detalhes: espaçamento mínimo 20.000 ms, Retry-After;
  // checkpoint e retomada. Nunca drenar essa fila durante Search.
  await detailQueue.enqueue({ hotelId: hotel.id, lastUpdateSource: hotel.lastUpdateSource });
}
// Worker da fila: Hotel.svc/HotelDetail -> persistir detalhes e lastUpdateSource
// SOMENTE após sucesso. Só avançar lastSuccessfulSyncAt ao concluir todos os lotes.
// Carga inicial: cache vazio -> todos os hotéis entram na fila.
// releasedAt e lastFullSyncAt NÃO substituem lastUpdateSource.

play_circleTry it — executar query agora

Cole seu token wsk_* e dispare uma query real contra /api/catalog/graphql. Útil para validar headers de release, paginação e rate-limit antes de codar.

O token fica apenas no seu navegador (não é enviado para nenhum servidor da Iterpec além do GraphQL endpoint).

errorErros comuns

  • 401 — token ausente, expirado ou não é wsk_* de workspace.
  • 429 — quota excedida; respeite Retry-After.
  • 422 — query inválida; valide com a aba Playground antes.
Dica MCP: peça à sua IA cliente para chamar as tools get_catalog_graphql_recipe e get_catalog_sync_status antes de implementar — elas retornam queries prontas e o estado atual do seu catálogo.