// docs

Decolar Flights Search

Extrai resultados de passagens aereas da Decolar por aeroporto de origem/destino, datas e ocupacao. O backend consulta o endpoint interno necessario, mas a resposta expoe apenas a URL publica de resultados da Decolar.

Tempo de resposta: Em algumas execuções, esta API pode levar até 1 minuto para responder. Isso é normal para este endpoint. Aguarde a conclusão da requisição e tenha paciência.

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": "decolar.com",
  "type": "plp",
  "from": "CAC",
  "to": "GRU",
  "departureDate": "2026-04-25",
  "returnDate": "2026-04-30",
  "numAdults": 1,
  "numChildren": 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

decolar_com_plp

Auth

Bearer ou X-API-Key

decolar_com_plp tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "decolar_com_plp",
    "arguments": {
      "from": "CAC",
      "to": "GRU",
      "departureDate": "2026-04-25",
      "returnDate": "2026-04-30",
      "numAdults": 1,
      "numChildren": 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
url URL alvo da extração. Para alguns PLPs pode ser omitida quando a API monta a URL a partir de outros campos.	string (URL)	Opcional	Opcional. Quando informado, deve ser uma URL da Decolar em decolar.com. O backend normaliza a URL para o endpoint estavel suportado.	-	https://www.mercadolivre.com.br/p/MLB123456
from Codigo IATA do aeroporto de origem para busca PLP da Decolar.	string (IATA 3 letras)	Obrigatório	Codigo IATA do aeroporto de origem com 3 letras (ex: CAC). Obrigatorio quando url nao for enviada.	-	CAC
to Codigo IATA do aeroporto de destino para busca PLP da Decolar.	string (IATA 3 letras)	Obrigatório	Codigo IATA do aeroporto de destino com 3 letras (ex: GRU). Obrigatorio quando url nao for enviada.	-	GRU
departureDate Data de saida para busca PLP da ClickBus.	string (YYYY-MM-DD)	Obrigatório	Data de ida no formato YYYY-MM-DD. Obrigatorio quando url nao for enviada.	-	2026-02-24
returnDate Data de retorno opcional para busca PLP da ClickBus.	string (YYYY-MM-DD)	Opcional	Data de volta no formato YYYY-MM-DD. Deve ser >= departureDate.	-	2026-02-25
target Fonte alvo da extração.	enum	Obrigatório	Sempre obrigatorio e deve ser decolar.com.	-	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 e Hoteis.com PDP/PLP.	integer (1-30)	Obrigatório	Quantidade de adultos. Obrigatorio quando url nao for enviada.	1	2
numChildren Quantidade de crianças para Booking e Hoteis.com PDP/PLP.	integer (0-30)	Opcional	Quantidade de criancas.	0	0

Exemplos de request

Busca Decolar - ida e volta

Busca round-trip por aeroportos IATA com adultos e criancas.

Busca Decolar - ida e volta

{
  "target": "decolar.com",
  "type": "plp",
  "from": "CAC",
  "to": "GRU",
  "departureDate": "2026-04-25",
  "returnDate": "2026-04-30",
  "numAdults": 1,
  "numChildren": 0
}

Busca Decolar - somente ida

Busca one-way por aeroportos IATA sem data de retorno.

Busca Decolar - somente ida

{
  "target": "decolar.com",
  "type": "plp",
  "from": "CAC",
  "to": "SAO",
  "departureDate": "2026-05-02",
  "numAdults": 2,
  "numChildren": 1
}

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.searchId": "string | null",
  "data.initialCurrency": "string | null",
  "data.totalResults": "number",
  "data.primaryResults": "number",
  "data.page": "number",
  "data.pageCount": "number",
  "data.resultsPerPage": "number",
  "data.directFlightsCount": "number | null",
  "data.flightsWithStopsCount": "number | null",
  "data.additionalServices[]": "string",
  "data.items[].position": "number",
  "data.items[].id": "string | null",
  "data.items[].validatingCarrier": "string | null",
  "data.items[].nonStop": "boolean | null",
  "data.items[].price.totalAmount": "number | null",
  "data.items[].routeChoices[].type": "string | null",
  "data.items[].routeChoices[].routes[].stopsCount": "number | null",
  "data.items[].routeChoices[].routes[].segments[].flightId": "string | null"
}

Exemplo de response

responseExample

{
  "requestId": "99999999-1111-4111-8111-999999999999",
  "executionId": "99999999-2222-4222-8222-999999999999",
  "data": {
    "source": "decolar.com",
    "type": "plp",
    "parser": "json_api",
    "url": "https://www.decolar.com/shop/flights/results/multioneway/CAC/GRU/2026-04-25/2026-04-30/1/0/0",
    "requestUrl": "https://www.decolar.com/shop/flights/results/multioneway/CAC/GRU/2026-04-25/2026-04-30/1/0/0",
    "extractedAt": "2026-04-13T12:00:00.000Z",
    "searchType": "ROUND_TRIP",
    "from": "CAC",
    "to": "GRU",
    "departureDate": "2026-04-25",
    "returnDate": "2026-04-30",
    "numAdults": 1,
    "numChildren": 0,
    "searchId": "search-123",
    "initialCurrency": "BRL",
    "totalResults": 1,
    "primaryResults": 1,
    "page": 1,
    "pageCount": 1,
    "resultsPerPage": 10,
    "directFlightsCount": 1,
    "flightsWithStopsCount": 0,
    "additionalServices": [
      "refund_protection"
    ],
    "items": [
      {
        "position": 1,
        "id": "itinerary-1",
        "validatingCarrier": "G3",
        "nonStop": true,
        "price": {
          "totalAmount": 531
        },
        "routeChoices": [
          {
            "type": "OUTBOUND",
            "routes": [
              {
                "stopsCount": 0,
                "segments": [
                  {
                    "flightId": "G31234"
                  }
                ]
              }
            ]
          },
          {
            "type": "INBOUND",
            "routes": [
              {
                "stopsCount": 0,
                "segments": [
                  {
                    "flightId": "G31235"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

Referência completa de campos

Path	Tipo	Descrição	Exemplo
data.additionalServices[]	string	Campo data.additionalServices[] retornado no payload de resposta.	refund_protection
data.departureDate	string (YYYY-MM-DD)	Campo data.departureDate retornado no payload de resposta.	2026-04-25
data.directFlightsCount	number \| null	Campo data.directFlightsCount retornado no payload de resposta.	1
data.extractedAt	string (iso datetime)	Campo data.extractedAt retornado no payload de resposta.	2026-04-13T12:00:00.000Z
data.flightsWithStopsCount	number \| null	Campo data.flightsWithStopsCount retornado no payload de resposta.	0
data.from	string	Campo data.from retornado no payload de resposta.	CAC
data.initialCurrency	string \| null	Campo data.initialCurrency retornado no payload de resposta.	BRL
data.items[].id	string \| null	Campo data.items[].id retornado no payload de resposta.	itinerary-1
data.items[].nonStop	boolean \| null	Campo data.items[].nonStop retornado no payload de resposta.	true
data.items[].position	number	Campo data.items[].position retornado no payload de resposta.	1
data.items[].price.totalAmount	number \| null	Campo data.items[].price.totalAmount retornado no payload de resposta.	531
data.items[].routeChoices[].routes[].segments[].flightId	string \| null	Campo data.items[].routeChoices[].routes[].segments[].flightId retornado no payload de resposta.	G31234
data.items[].routeChoices[].routes[].stopsCount	number \| null	Campo data.items[].routeChoices[].routes[].stopsCount retornado no payload de resposta.	0
data.items[].routeChoices[].type	string \| null	Campo data.items[].routeChoices[].type retornado no payload de resposta.	OUTBOUND
data.items[].validatingCarrier	string \| null	Campo data.items[].validatingCarrier retornado no payload de resposta.	G3
data.numAdults	number	Campo data.numAdults retornado no payload de resposta.	1
data.numChildren	number	Campo data.numChildren retornado no payload de resposta.	0
data.page	number	Campo data.page retornado no payload de resposta.	1
data.pageCount	number	Campo data.pageCount retornado no payload de resposta.	1
data.parser	string	Campo data.parser retornado no payload de resposta.	json_api
data.primaryResults	number	Campo data.primaryResults retornado no payload de resposta.	1
data.requestUrl	string	Mesmo valor da URL publica retornada ao cliente para referencia e reproducao da busca no site.	https://www.decolar.com/shop/flights/results/multioneway/CAC/GRU/2026-04-25/2026-04-30/1/0/0
data.resultsPerPage	number	Campo data.resultsPerPage retornado no payload de resposta.	10
data.returnDate	string \| null (YYYY-MM-DD)	Campo data.returnDate retornado no payload de resposta.	2026-04-30
data.searchId	string \| null	Campo data.searchId retornado no payload de resposta.	search-123
data.searchType	string (ONE_WAY \| ROUND_TRIP)	Campo data.searchType retornado no payload de resposta.	ROUND_TRIP
data.source	string	Campo data.source retornado no payload de resposta.	decolar.com
data.to	string	Campo data.to retornado no payload de resposta.	GRU
data.totalResults	number	Campo data.totalResults retornado no payload de resposta.	1
data.type	string	Campo data.type retornado no payload de resposta.	plp
data.url	string	URL publica de resultados da Decolar, sem expor o endpoint interno consultado pelo backend.	https://www.decolar.com/shop/flights/results/multioneway/CAC/GRU/2026-04-25/2026-04-30/1/0/0
executionId	string (uuid)	Campo executionId retornado no payload de resposta.	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)	Campo requestId retornado no payload de resposta.	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.