// docs

GOL Itineraries Search

Extrai itinerários e tarifas da GOL por aeroporto de origem/destino, datas e passageiros. A API retorna voos, segmentos, marcas tarifárias e a menor tarifa disponível por itinerário.

Nota importante: alguns campos podem retornar null em produção, dependendo da página de origem. Nesta documentação, os exemplos de output são preenchidos intencionalmente com valores não nulos para facilitar integração.

Quando a entidade consultada não existe na origem, o extract e a tool MCP retornam 200 com data: null e notFound: true. Esse caso é tratado como resposta concluída, não como erro de servidor.

Chamada HTTP

cURL

curl -X POST https://api.geckoapi.com.br/v1/extract \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "target": "voegol.com.br",
  "type": "plp",
  "from": "GRU",
  "to": "GIG",
  "departureDate": "2026-05-17",
  "numAdults": 1,
  "numChildren": 0,
  "numInfants": 0
}'

Chamada MCP

A mesma seam também aparece no MCP hospedado como uma tool dedicada. Os argumentos reaproveitam os campos do extract, mas target e type já ficam fixos pela tool.

Ver guia completo do MCP

Endpoint

POST /v1/mcp

Tool name

voegol_com_br_plp

Auth

Bearer ou X-API-Key

voegol_com_br_plp tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "voegol_com_br_plp",
    "arguments": {
      "from": "GRU",
      "to": "GIG",
      "departureDate": "2026-05-17",
      "numAdults": 1,
      "numChildren": 0,
      "numInfants": 0,
      "executionId": "exec_example_123"
    }
  }
}

Possibilidades de input

Campos suportados nesta API do POST /v1/extract, com regras específicas de obrigatoriedade e condicionais.

Campo	Tipo	Status	Regra	Default	Exemplo
from Codigo IATA do aeroporto de origem para busca PLP da Decolar, GOL e LATAM.	string (IATA 3 letras)	Obrigatório	Codigo IATA do aeroporto de origem com 3 letras (ex: GRU).	-	GRU
to Codigo IATA do aeroporto de destino para busca PLP da Decolar, GOL e LATAM.	string (IATA 3 letras)	Obrigatório	Codigo IATA do aeroporto de destino com 3 letras (ex: GIG).	-	GIG
departureDate Data de saida para busca PLP da ClickBus, Decolar, GOL e LATAM.	string (YYYY-MM-DD)	Obrigatório	Data de ida no formato YYYY-MM-DD.	-	2026-05-17
returnDate Data de retorno opcional para busca PLP da ClickBus, Decolar, GOL e LATAM.	string (YYYY-MM-DD)	Opcional	Data de volta no formato YYYY-MM-DD. Deve ser maior ou igual a departureDate.	-	2026-05-20
target Fonte alvo da extração.	enum	Obrigatório	Sempre obrigatorio e deve ser voegol.com.br.	-	mercadolivre.com.br
type Tipo da extração: pdp, idp, plp, quote, review ou places.	enum	Obrigatório	Sempre obrigatorio e deve ser plp.	-	pdp
numAdults Quantidade de adultos para Booking, Airbnb, Hoteis.com, Decolar, GOL e LATAM.	integer (1-30)	Opcional	Quantidade de adultos. Deve ser inteiro entre 1 e 9.	1	2
numChildren Quantidade de crianças para Booking, Hoteis.com, Decolar, GOL e LATAM.	integer (0-30)	Opcional	Quantidade de crianças. Deve ser inteiro entre 0 e 9.	0	0
numInfants Quantidade de bebês para GOL e LATAM PLP. Deve ser menor ou igual à quantidade de adultos.	integer (0-9)	Opcional	Quantidade de bebês. Deve ser inteiro entre 0 e 9 e menor ou igual a numAdults.	0	0

Exemplos de request

Busca GOL - somente ida

Busca one-way por aeroportos IATA com adultos, crianças e bebês.

Busca GOL - somente ida

{
  "target": "voegol.com.br",
  "type": "plp",
  "from": "GRU",
  "to": "GIG",
  "departureDate": "2026-05-17",
  "numAdults": 1,
  "numChildren": 0,
  "numInfants": 0
}

Busca GOL - ida e volta

Busca round-trip por aeroportos IATA com data de retorno.

Busca GOL - ida e volta

{
  "target": "voegol.com.br",
  "type": "plp",
  "from": "BSB",
  "to": "SDU",
  "departureDate": "2026-06-10",
  "returnDate": "2026-06-15",
  "numAdults": 2,
  "numChildren": 1,
  "numInfants": 0
}

Schema de response (leaf paths)

Mapa de paths de saída com tipo esperado para esta API.

responseSchema

{
  "requestId": "string (uuid)",
  "executionId": "string (uuid)",
  "notFound": "boolean (optional; true when the upstream entity was not found and data is null)",
  "data.source": "string",
  "data.type": "string",
  "data.parser": "string",
  "data.url": "string",
  "data.requestUrl": "string",
  "data.extractedAt": "string (iso datetime)",
  "data.searchType": "string (ONE_WAY | ROUND_TRIP)",
  "data.from": "string",
  "data.to": "string",
  "data.departureDate": "string (YYYY-MM-DD)",
  "data.returnDate": "string | null (YYYY-MM-DD)",
  "data.numAdults": "number",
  "data.numChildren": "number",
  "data.numInfants": "number",
  "data.success": "boolean | null",
  "data.totalResults": "number",
  "data.itineraries[].position": "number",
  "data.itineraries[].id": "string | null",
  "data.itineraries[].origin": "string | null",
  "data.itineraries[].destination": "string | null",
  "data.itineraries[].departure": "string | null",
  "data.itineraries[].arrival": "string | null",
  "data.itineraries[].stopsCount": "number",
  "data.itineraries[].duration": "string | null",
  "data.itineraries[].segments[].origin": "string | null",
  "data.itineraries[].segments[].destination": "string | null",
  "data.itineraries[].segments[].departure": "string | null",
  "data.itineraries[].segments[].arrival": "string | null",
  "data.itineraries[].segments[].duration": "string | null",
  "data.itineraries[].segments[].flight.airlineCode": "string | null",
  "data.itineraries[].segments[].flight.flightNumber": "string | null",
  "data.itineraries[].segments[].flight.equipmentCode": "string | null",
  "data.itineraries[].offers[].brandId": "string | null",
  "data.itineraries[].offers[].brandLabel": "string | null",
  "data.itineraries[].offers[].cabinClass": "string | null",
  "data.itineraries[].offers[].seatsRemaining": "number | null",
  "data.itineraries[].offers[].total.currency": "string | null",
  "data.itineraries[].offers[].total.amount": "number | null",
  "data.itineraries[].cheapestOffer.brandId": "string | null",
  "data.itineraries[].cheapestOffer.total.amount": "number | null"
}

Exemplo de response

responseExample

{
  "requestId": "99999999-1111-4111-8111-999999999999",
  "executionId": "99999999-2222-4222-8222-999999999999",
  "data": {
    "source": "voegol.com.br",
    "type": "plp",
    "parser": "json_api",
    "url": "https://www.voegol.com.br/itineraries?from=GRU&to=GIG&departureDate=2026-05-17&numAdults=1&numChildren=0&numInfants=0",
    "requestUrl": "https://b2c-api.voegol.com.br/api/sabre-default/flights?Flow=Issue&context=B2C",
    "extractedAt": "2026-04-30T18:00:00.000Z",
    "searchType": "ONE_WAY",
    "from": "GRU",
    "to": "GIG",
    "departureDate": "2026-05-17",
    "returnDate": "",
    "numAdults": 1,
    "numChildren": 0,
    "numInfants": 0,
    "success": true,
    "totalResults": 1,
    "itineraries": [
      {
        "position": 1,
        "id": "itinerary-1",
        "origin": "GRU",
        "destination": "GIG",
        "departure": "2026-05-17T13:25:00",
        "arrival": "2026-05-17T14:25:00",
        "stopsCount": 0,
        "duration": "PT1H",
        "segments": [
          {
            "origin": "GRU",
            "destination": "GIG",
            "departure": "2026-05-17T13:25:00",
            "arrival": "2026-05-17T14:25:00",
            "duration": "PT1H",
            "flight": {
              "airlineCode": "G3",
              "flightNumber": "1234",
              "equipmentCode": "738"
            }
          }
        ],
        "offers": [
          {
            "brandId": "LI",
            "brandLabel": "Light",
            "cabinClass": "Economy",
            "seatsRemaining": 9,
            "total": {
              "currency": "BRL",
              "amount": 1168.34
            }
          },
          {
            "brandId": "PL",
            "brandLabel": "Plus",
            "cabinClass": "Economy",
            "seatsRemaining": 9,
            "total": {
              "currency": "BRL",
              "amount": 1394.22
            }
          }
        ],
        "cheapestOffer": {
          "brandId": "LI",
          "brandLabel": "Light",
          "cabinClass": "Economy",
          "seatsRemaining": 9,
          "total": {
            "currency": "BRL",
            "amount": 1168.34
          }
        }
      }
    ]
  }
}

Referência completa de campos

Path	Tipo	Descrição	Exemplo
data.departureDate	string (YYYY-MM-DD)	Data de ida enviada na requisição.	2026-05-17
data.extractedAt	string (iso datetime)	Momento da extração em ISO 8601.	2026-04-30T18:00:00.000Z
data.from	string	Aeroporto IATA de origem.	GRU
data.itineraries[].arrival	string \| null	Data/hora de chegada do último segmento.	2026-05-17T14:25:00
data.itineraries[].cheapestOffer.brandId	string \| null	Marca tarifária da menor oferta encontrada.	LI
data.itineraries[].cheapestOffer.total.amount	number \| null	Menor preço total encontrado para o itinerário.	1168.34
data.itineraries[].departure	string \| null	Data/hora de partida do primeiro segmento.	2026-05-17T13:25:00
data.itineraries[].destination	string \| null	Destino do último segmento.	GIG
data.itineraries[].duration	string \| null	Duração total do itinerário quando disponível.	PT1H
data.itineraries[].id	string \| null	Identificador do itinerário quando o upstream informa.	itinerary-1
data.itineraries[].offers[].brandId	string \| null	Identificador da marca tarifária.	LI
data.itineraries[].offers[].brandLabel	string \| null	Nome legível da marca tarifária quando disponível.	Light
data.itineraries[].offers[].cabinClass	string \| null	Classe de cabine quando disponível.	Economy
data.itineraries[].offers[].seatsRemaining	number \| null	Assentos restantes quando disponível.	9
data.itineraries[].offers[].total.amount	number \| null	Valor total da oferta.	1168.34
data.itineraries[].offers[].total.currency	string \| null	Moeda do preço total.	BRL
data.itineraries[].origin	string \| null	Origem do primeiro segmento.	GRU
data.itineraries[].position	number	Posição do itinerário na resposta.	1
data.itineraries[].segments[].arrival	string \| null	Data/hora de chegada do segmento.	2026-05-17T14:25:00
data.itineraries[].segments[].departure	string \| null	Data/hora de partida do segmento.	2026-05-17T13:25:00
data.itineraries[].segments[].destination	string \| null	Destino do segmento.	GIG
data.itineraries[].segments[].duration	string \| null	Duração do segmento.	PT1H
data.itineraries[].segments[].flight.airlineCode	string \| null	Código da companhia aérea.	G3
data.itineraries[].segments[].flight.equipmentCode	string \| null	Código da aeronave/equipamento quando disponível.	738
data.itineraries[].segments[].flight.flightNumber	string \| null	Número do voo.	1234
data.itineraries[].segments[].origin	string \| null	Origem do segmento.	GRU
data.itineraries[].stopsCount	number	Número de paradas calculado a partir dos segmentos.	0
data.numAdults	number	Quantidade de adultos usada na busca.	1
data.numChildren	number	Quantidade de crianças usada na busca.	0
data.numInfants	number	Quantidade de bebês usada na busca.	0
data.parser	string	Parser usado para estruturar a resposta.	json_api
data.requestUrl	string	Endpoint interno da GOL usado pelo worker para consultar voos.	https://b2c-api.voegol.com.br/api/sabre-default/flights?Flow=Issue&context=B2C
data.returnDate	string \| null (YYYY-MM-DD)	Data de volta enviada na requisição, quando existir.
data.searchType	string (ONE_WAY \| ROUND_TRIP)	ONE_WAY quando não há returnDate; ROUND_TRIP quando há volta.	ONE_WAY
data.source	string	Fonte consultada.	voegol.com.br
data.success	boolean \| null	Flag de sucesso retornada pelo upstream quando disponível.	true
data.to	string	Aeroporto IATA de destino.	GIG
data.totalResults	number	Quantidade de itinerários estruturados na resposta.	1
data.type	string	Tipo da API executada.	plp
data.url	string	URL pública canônica da busca de itinerários GOL.	https://www.voegol.com.br/itineraries?from=GRU&to=GIG&departureDate=2026-05-17&numAdults=1&numChildren=0&numInfants=0
executionId	string (uuid)	Identificador idempotente da execução.	99999999-2222-4222-8222-999999999999
notFound	boolean (optional; true when the upstream entity was not found and data is null)	Present and true when the upstream entity was not found. In this case data is null and the request still completes successfully.	N/A
requestId	string (uuid)	Identificador da requisição no gateway da GeckoAPI.	99999999-1111-4111-8111-999999999999

Erros comuns

Respostas com notFound: true não entram nesta tabela, porque retornam sucesso HTTP 200.

Status	errorCode	Quando acontece
400	INVALID_PAYLOAD	JSON inválido ou violação das regras de validação do payload.
401	UNAUTHORIZED	Header Authorization ausente ou token/chave inválida.
402	INSUFFICIENT_CREDITS	Saldo de créditos insuficiente para a API solicitada.
403	FORBIDDEN	Usuário sem acesso ou API temporariamente desabilitada.
409	EXECUTION_CONFLICT	executionId conflita com uma execução em estado incompatível.
429	RATE_LIMIT_EXCEEDED / TOO_MANY_INFLIGHT_REQUESTS	Limite de taxa ou limite de requisições em voo excedido.
5xx	UPSTREAM_TIMEOUT / UPSTREAM_HTTP_ERROR / WORKER_INVOCATION_FAILED / WORKER_FUNCTION_ERROR / WORKER_INVALID_RESPONSE / INTERNAL_ERROR	Falha de servidor no worker, provider/proxy ou gateway. Nesses casos os créditos são estornados automaticamente.