// docs

Pede.ai PLP

Extrai merchants do pede.ai a partir de um CEP brasileiro. O backend resolve cityId + areaId internamente via /v1/extract/lookups/pede.ai/resolve-zip-code e retorna apenas URLs publicas sinteticas do pede.ai.

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": "pede.ai",
  "type": "plp",
  "zipCode": "45300-000"
}'

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

pede_ai_plp

Auth

Bearer ou X-API-Key

pede_ai_plp tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "pede_ai_plp",
    "arguments": {
      "zipCode": "45300-000",
      "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
zipCode CEP brasileiro usado em APIs com resolucao geografica automatica, como iFood PLP e pede.ai PLP/PDP. A API aceita com ou sem hifen e normaliza para 8 digitos.	string (CEP)	Obrigatório	Obrigatorio no pede.ai PLP. Aceita CEP com ou sem hifen; a API normaliza o valor e resolve cityId + areaId automaticamente.	-	80010-000
target Fonte alvo da extração.	enum	Obrigatório	Sempre obrigatorio no payload e deve ser pede.ai.	-	mercadolivre.com.br
type Tipo da extração: pdp, idp, plp, quote, review ou places.	enum	Obrigatório	Sempre obrigatorio no payload e deve ser plp.	-	pdp

Exemplos de request

PLP por CEP

Fluxo recomendado: envie apenas o CEP. O backend geocodifica, resolve cityId + areaId e consulta o PLP internamente.

PLP por CEP

{
  "target": "pede.ai",
  "type": "plp",
  "zipCode": "45300-000"
}

Schema de response (leaf paths)

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

responseSchema

{
  "requestId": "string (uuid)",
  "executionId": "string (uuid)",
  "data.source": "string",
  "data.type": "string",
  "data.url": "string",
  "data.requestUrl": "string",
  "data.extractedAt": "string (iso datetime)",
  "data.cityId": "string",
  "data.areaId": "string",
  "data.city": "string",
  "data.state": "string",
  "data.neighborhood": "string",
  "data.locationResolution.zipCode": "string",
  "data.locationResolution.formattedZipCode": "string",
  "data.locationResolution.state": "string",
  "data.locationResolution.stateName": "string",
  "data.locationResolution.city": "string",
  "data.locationResolution.neighborhood": "string",
  "data.locationResolution.cityId": "string",
  "data.locationResolution.areaId": "string",
  "data.locationResolution.geocoderProvider": "string",
  "data.locationResolution.latitude": "number",
  "data.locationResolution.longitude": "number",
  "data.locationResolution.matchStrategy": "string",
  "data.locationResolution.rankedCandidates[].areaId": "string",
  "data.locationResolution.rankedCandidates[].cityId": "string",
  "data.locationResolution.rankedCandidates[].city": "string",
  "data.locationResolution.rankedCandidates[].state": "string",
  "data.locationResolution.rankedCandidates[].neighborhood": "string",
  "data.locationResolution.rankedCandidates[].minimumRate": "number",
  "data.locationResolution.rankedCandidates[].typeOperation": "string",
  "data.locationResolution.rankedCandidates[].externalProvider": "string",
  "data.locationResolution.rankedCandidates[].active": "boolean",
  "data.locationResolution.rankedCandidates[].matchStrategy": "string",
  "data.locationResolution.rankedCandidates[].matchedLabel": "string",
  "data.locationResolution.rankedCandidates[].score": "number",
  "data.categories[].id": "number",
  "data.categories[].name": "string",
  "data.openCount": "number",
  "data.closedCount": "number",
  "data.items[].position": "number",
  "data.items[].merchantId": "string",
  "data.items[].name": "string",
  "data.items[].slug": "string",
  "data.items[].logo": "string",
  "data.items[].banner": "string",
  "data.items[].isOpen": "boolean",
  "data.items[].deliveryTimeText": "string",
  "data.items[].deliveryTimeMinMinutes": "number",
  "data.items[].deliveryTimeMaxMinutes": "number",
  "data.items[].deliveryTimeAverageMinutes": "number",
  "data.items[].deliveryFee": "number",
  "data.items[].minimumOrderValue": "number",
  "data.items[].freeDeliveryMinimum": "number",
  "data.items[].rating": "number",
  "data.items[].ratingDisplay": "string",
  "data.items[].acceptsCoupon": "boolean",
  "data.items[].acceptsOnlinePayment": "boolean",
  "data.items[].acceptsInPersonPayment": "boolean",
  "data.items[].acceptsPix": "boolean",
  "data.items[].acceptsNuPay": "boolean",
  "data.items[].acceptsPicPay": "boolean",
  "data.items[].isNew": "boolean",
  "data.items[].isBrief": "boolean",
  "data.items[].isExclusive": "boolean",
  "data.items[].deliveryDisabled": "boolean",
  "data.items[].offerDiscount": "number",
  "data.items[].fullCompanyOffer": "boolean",
  "data.items[].storeDisplayType": "number",
  "data.items[].storeTypes[].id": "number",
  "data.items[].storeTypes[].name": "string",
  "data.items[].categories[].id": "number",
  "data.items[].categories[].name": "string"
}

Exemplo de response

responseExample

{
  "requestId": "77777777-1111-4111-8111-777777777777",
  "executionId": "77777777-2222-4222-8222-777777777777",
  "data": {
    "source": "pede.ai",
    "type": "plp",
    "url": "https://pede.ai/lista?cep=45300-000",
    "requestUrl": "https://pede.ai/lista?cep=45300-000",
    "extractedAt": "2026-04-17T18:00:00.000Z",
    "cityId": "508",
    "areaId": "19590",
    "city": "Amargosa",
    "state": "BA",
    "neighborhood": "Alto da Bela Vista",
    "locationResolution": {
      "zipCode": "45300000",
      "formattedZipCode": "45300-000",
      "state": "BA",
      "stateName": "Bahia",
      "city": "Amargosa",
      "neighborhood": "Alto da Bela Vista",
      "cityId": "508",
      "areaId": "19590",
      "geocoderProvider": "brasilapi",
      "latitude": -13.0303,
      "longitude": -39.6031,
      "matchStrategy": "exact",
      "rankedCandidates": [
        {
          "areaId": "19590",
          "cityId": "508",
          "city": "Amargosa",
          "state": "BA",
          "neighborhood": "Alto da Bela Vista",
          "minimumRate": 5,
          "typeOperation": "OPL",
          "externalProvider": "Leve.ai",
          "active": true,
          "matchStrategy": "exact",
          "matchedLabel": "Alto da Bela Vista",
          "score": 400
        }
      ]
    },
    "categories": [
      {
        "id": 4,
        "name": "Almoco",
        "image": "https://cdn.aiboodelivery.com.br/appv3/marmitex.png",
        "icon": "https://pedeai-common.sfo2.cdn.digitaloceanspaces.com/cuisine/resized/694236.png"
      }
    ],
    "openCount": 1,
    "closedCount": 1,
    "items": [
      {
        "position": 1,
        "merchantId": "17642",
        "name": "Bella Roma",
        "slug": "bella-roma1",
        "logo": "https://merchant-assets.pede.ai/bella-roma/logo.png",
        "banner": "https://merchant-assets.pede.ai/bella-roma/banner.png",
        "isOpen": true,
        "deliveryTimeText": "20-40",
        "deliveryTimeMinMinutes": 20,
        "deliveryTimeMaxMinutes": 40,
        "deliveryTimeAverageMinutes": 30,
        "deliveryFee": 7,
        "minimumOrderValue": 0,
        "freeDeliveryMinimum": 120,
        "rating": 4.5,
        "ratingDisplay": "4.5",
        "acceptsCoupon": true,
        "acceptsOnlinePayment": true,
        "acceptsInPersonPayment": true,
        "acceptsPix": true,
        "acceptsNuPay": true,
        "acceptsPicPay": true,
        "isNew": false,
        "isBrief": false,
        "isExclusive": false,
        "deliveryDisabled": false,
        "offerDiscount": 0,
        "fullCompanyOffer": false,
        "storeDisplayType": 0,
        "storeTypes": [
          {
            "id": 1,
            "name": "Restaurantes",
            "icon": "https://pedeai-common.sfo2.cdn.digitaloceanspaces.com/restaurantes2.png",
            "order": 1,
            "status": "S"
          }
        ],
        "categories": [
          {
            "id": 4,
            "name": "Almoco",
            "image": "https://cdn.aiboodelivery.com.br/appv3/marmitex.png",
            "icon": "https://pedeai-common.sfo2.cdn.digitaloceanspaces.com/cuisine/resized/694236.png"
          }
        ]
      }
    ]
  }
}

Referência completa de campos

Path	Tipo	Descrição	Exemplo
data.areaId	string	areaId efetivamente resolvido para a consulta interna do pede.ai.	19590
data.categories[].id	number	Campo data.categories[].id retornado no payload de resposta.	4
data.categories[].name	string	Campo data.categories[].name retornado no payload de resposta.	Almoco
data.city	string	Cidade resolvida para a consulta.	Amargosa
data.cityId	string	cityId efetivamente resolvido para a consulta interna do pede.ai.	508
data.closedCount	number	Quantidade de merchants fechados no resultado.	1
data.extractedAt	string (iso datetime)	Campo data.extractedAt retornado no payload de resposta.	2026-04-17T18:00:00.000Z
data.items[].acceptsCoupon	boolean	Campo data.items[].acceptsCoupon retornado no payload de resposta.	true
data.items[].acceptsInPersonPayment	boolean	Campo data.items[].acceptsInPersonPayment retornado no payload de resposta.	true
data.items[].acceptsNuPay	boolean	Campo data.items[].acceptsNuPay retornado no payload de resposta.	true
data.items[].acceptsOnlinePayment	boolean	Campo data.items[].acceptsOnlinePayment retornado no payload de resposta.	true
data.items[].acceptsPicPay	boolean	Campo data.items[].acceptsPicPay retornado no payload de resposta.	true
data.items[].acceptsPix	boolean	Campo data.items[].acceptsPix retornado no payload de resposta.	true
data.items[].banner	string	Campo data.items[].banner retornado no payload de resposta.	https://merchant-assets.pede.ai/bella-roma/banner.png
data.items[].categories[].id	number	Campo data.items[].categories[].id retornado no payload de resposta.	4
data.items[].categories[].name	string	Campo data.items[].categories[].name retornado no payload de resposta.	Almoco
data.items[].deliveryDisabled	boolean	Campo data.items[].deliveryDisabled retornado no payload de resposta.	false
data.items[].deliveryFee	number	Campo data.items[].deliveryFee retornado no payload de resposta.	7
data.items[].deliveryTimeAverageMinutes	number	Campo data.items[].deliveryTimeAverageMinutes retornado no payload de resposta.	30
data.items[].deliveryTimeMaxMinutes	number	Campo data.items[].deliveryTimeMaxMinutes retornado no payload de resposta.	40
data.items[].deliveryTimeMinMinutes	number	Campo data.items[].deliveryTimeMinMinutes retornado no payload de resposta.	20
data.items[].deliveryTimeText	string	Campo data.items[].deliveryTimeText retornado no payload de resposta.	20-40
data.items[].freeDeliveryMinimum	number	Campo data.items[].freeDeliveryMinimum retornado no payload de resposta.	120
data.items[].fullCompanyOffer	boolean	Campo data.items[].fullCompanyOffer retornado no payload de resposta.	false
data.items[].isBrief	boolean	Campo data.items[].isBrief retornado no payload de resposta.	false
data.items[].isExclusive	boolean	Campo data.items[].isExclusive retornado no payload de resposta.	false
data.items[].isNew	boolean	Campo data.items[].isNew retornado no payload de resposta.	false
data.items[].isOpen	boolean	Campo data.items[].isOpen retornado no payload de resposta.	true
data.items[].logo	string	Campo data.items[].logo retornado no payload de resposta.	https://merchant-assets.pede.ai/bella-roma/logo.png
data.items[].merchantId	string	Identificador do merchant que deve ser reutilizado no pede.ai PDP.	17642
data.items[].minimumOrderValue	number	Campo data.items[].minimumOrderValue retornado no payload de resposta.	0
data.items[].name	string	Campo data.items[].name retornado no payload de resposta.	Bella Roma
data.items[].offerDiscount	number	Campo data.items[].offerDiscount retornado no payload de resposta.	0
data.items[].position	number	Posicao do merchant na lista unificada do PLP.	1
data.items[].rating	number	Campo data.items[].rating retornado no payload de resposta.	4.5
data.items[].ratingDisplay	string	Campo data.items[].ratingDisplay retornado no payload de resposta.	4.5
data.items[].slug	string	Campo data.items[].slug retornado no payload de resposta.	bella-roma1
data.items[].storeDisplayType	number	Campo data.items[].storeDisplayType retornado no payload de resposta.	0
data.items[].storeTypes[].id	number	Campo data.items[].storeTypes[].id retornado no payload de resposta.	1
data.items[].storeTypes[].name	string	Campo data.items[].storeTypes[].name retornado no payload de resposta.	Restaurantes
data.locationResolution.areaId	string	areaId efetivamente resolvido para a consulta interna do pede.ai.	19590
data.locationResolution.city	string	Cidade resolvida a partir do CEP.	Amargosa
data.locationResolution.cityId	string	cityId efetivamente resolvido para a consulta interna do pede.ai.	508
data.locationResolution.formattedZipCode	string	CEP formatado com hifen usado na URL publica sintetica.	45300-000
data.locationResolution.geocoderProvider	string	Provider usado na geocodificacao do CEP.	brasilapi
data.locationResolution.latitude	number	Latitude associada ao CEP quando disponivel.	-13.0303
data.locationResolution.longitude	number	Longitude associada ao CEP quando disponivel.	-39.6031
data.locationResolution.matchStrategy	string	Estrategia textual usada para selecionar a melhor area do pede.ai.	exact
data.locationResolution.neighborhood	string	Bairro/localidade textual retornado pelo geocoder.	Alto da Bela Vista
data.locationResolution.rankedCandidates[].active	boolean	Campo data.locationResolution.rankedCandidates[].active retornado no payload de resposta.	true
data.locationResolution.rankedCandidates[].areaId	string	Campo data.locationResolution.rankedCandidates[].areaId retornado no payload de resposta.	19590
data.locationResolution.rankedCandidates[].city	string	Campo data.locationResolution.rankedCandidates[].city retornado no payload de resposta.	Amargosa
data.locationResolution.rankedCandidates[].cityId	string	Campo data.locationResolution.rankedCandidates[].cityId retornado no payload de resposta.	508
data.locationResolution.rankedCandidates[].externalProvider	string	Campo data.locationResolution.rankedCandidates[].externalProvider retornado no payload de resposta.	Leve.ai
data.locationResolution.rankedCandidates[].matchedLabel	string	Campo data.locationResolution.rankedCandidates[].matchedLabel retornado no payload de resposta.	Alto da Bela Vista
data.locationResolution.rankedCandidates[].matchStrategy	string	Campo data.locationResolution.rankedCandidates[].matchStrategy retornado no payload de resposta.	exact
data.locationResolution.rankedCandidates[].minimumRate	number	Campo data.locationResolution.rankedCandidates[].minimumRate retornado no payload de resposta.	5
data.locationResolution.rankedCandidates[].neighborhood	string	Campo data.locationResolution.rankedCandidates[].neighborhood retornado no payload de resposta.	Alto da Bela Vista
data.locationResolution.rankedCandidates[].score	number	Campo data.locationResolution.rankedCandidates[].score retornado no payload de resposta.	400
data.locationResolution.rankedCandidates[].state	string	Campo data.locationResolution.rankedCandidates[].state retornado no payload de resposta.	BA
data.locationResolution.rankedCandidates[].typeOperation	string	Campo data.locationResolution.rankedCandidates[].typeOperation retornado no payload de resposta.	OPL
data.locationResolution.state	string	UF resolvida a partir do CEP.	BA
data.locationResolution.stateName	string	Nome do estado resolvido a partir do CEP.	Bahia
data.locationResolution.zipCode	string	CEP normalizado para 8 digitos usado na resolucao geografica.	45300000
data.neighborhood	string	Bairro/area selecionado para a consulta.	Alto da Bela Vista
data.openCount	number	Quantidade de merchants abertos no resultado.	1
data.requestUrl	string	Mesmo valor da URL publica sintetica usada no request.	https://pede.ai/lista?cep=45300-000
data.source	string	Campo data.source retornado no payload de resposta.	pede.ai
data.state	string	UF resolvida para a consulta.	BA
data.type	string	Campo data.type retornado no payload de resposta.	plp
data.url	string	URL publica sintetica usada como identificador canonico do request.	https://pede.ai/lista?cep=45300-000
executionId	string (uuid)	Campo executionId retornado no payload de resposta.	77777777-2222-4222-8222-777777777777
requestId	string (uuid)	Campo requestId retornado no payload de resposta.	77777777-1111-4111-8111-777777777777

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.