// docs

Catho PLP

Extrai listagem de vagas (PLP) da Catho com filtros e paginação.

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.

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": "catho.com.br",
  "type": "plp",
  "jobTitle": "desenvolvedor",
  "city": "Sao Paulo",
  "state": "SP",
  "workModel": [
    "remote",
    "hybrid"
  ],
  "page": 2
}'

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)	Condicional	Opcional; quando ausente deve haver jobTitle (ou keyword).	-	https://www.mercadolivre.com.br/p/MLB123456
keyword Palavra-chave para buscas PLP. Em Booking PLP é obrigatória; em outros PLPs pode substituir a URL.	string	Condicional	Aceito como alternativa a jobTitle quando url nao for enviada.	-	iphone 15 pro max
jobTitle Título/cargo para buscas da Catho PLP quando a URL não for enviada.	string	Condicional	Obrigatorio quando url nao for enviada, salvo uso de keyword.	-	desenvolvedor backend
city Cidade usada em Webmotors PLP e opcionalmente em Catho PLP (deve vir em par com state).	string	Condicional	Opcional, mas se informado exige state.	-	Sao Paulo
state UF usada em Webmotors PLP e opcionalmente em Catho PLP (deve vir em par com city).	string (UF 2 letras)	Condicional	Opcional, mas se informado exige city.	-	SP
workModel Filtro de modelo de trabalho na Catho PLP.	array<"remote" \| "hybrid" \| "presential">	Opcional	Opcional para filtro de modelo de trabalho.	-	["remote", "hybrid"]
target Fonte alvo da extração.	enum	Obrigatório	Sempre obrigatorio no payload e deve combinar com o seam.	-	mercadolivre.com.br
type Tipo da extração: pdp, plp ou review.	enum	Obrigatório	Sempre obrigatorio no payload e deve combinar com o seam.	-	pdp
page Paginação. Em PLP inicia em 1; em MercadoLivre review inicia em 0.	integer	Opcional	Suportado para PLP; deve ser inteiro >= 1.	-	2

Exemplos de request

PLP por jobTitle/city/state

Busca de vagas com filtros estruturados (sem URL).

PLP por jobTitle/city/state

{
  "target": "catho.com.br",
  "type": "plp",
  "jobTitle": "desenvolvedor",
  "city": "Sao Paulo",
  "state": "SP",
  "workModel": [
    "remote",
    "hybrid"
  ],
  "page": 2
}

PLP por URL

Quando URL e enviada, os filtros podem ser opcionais.

PLP por URL

{
  "url": "https://www.catho.com.br/vagas/desenvolvedor/sao-paulo-sp/?page=2&work_model[0]=remote",
  "target": "catho.com.br",
  "type": "plp"
}

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.query.jobTitle": "string",
  "data.query.city": "string",
  "data.query.state": "string",
  "data.query.workModel[]": "string",
  "data.query.page": "number",
  "data.totalResults": "number",
  "data.totalJobAds": "number",
  "data.page": "number",
  "data.resultsPerPage": "number",
  "data.nextPage": "number",
  "data.nextPageUrl": "string",
  "data.items[].id": "number",
  "data.items[].url": "string",
  "data.items[].title": "string",
  "data.items[].description": "string",
  "data.items[].benefits[]": "string",
  "data.items[].salary.min": "number",
  "data.items[].salary.max": "number",
  "data.items[].jobLocation": "string",
  "data.items[].employmentType": "string",
  "data.items[].hiringOrganization": "string",
  "data.items[].datePublished": "string",
  "data.items[].workSchedule": "string",
  "data.items[].active": "boolean",
  "data.items[].score": "number"
}

Exemplo de response

responseExample

{
  "requestId": "bbbbbbbb-1111-4111-8111-bbbbbbbbbbbb",
  "executionId": "bbbbbbbb-2222-4222-8222-bbbbbbbbbbbb",
  "data": {
    "source": "catho.com.br",
    "type": "jlp",
    "url": "https://www.catho.com.br/vagas/desenvolvedor/sao-paulo-sp/?work_model[0]=remote",
    "requestUrl": "https://www.catho.com.br/vagas/desenvolvedor/sao-paulo-sp/?page=2&work_model[0]=remote&work_model[1]=hybrid",
    "extractedAt": "2026-02-12T21:20:00.000Z",
    "query": {
      "jobTitle": "desenvolvedor",
      "city": "Sao Paulo",
      "state": "SP",
      "workModel": [
        "remote",
        "hybrid"
      ],
      "page": 2
    },
    "totalResults": 9027,
    "totalJobAds": 960,
    "page": 2,
    "resultsPerPage": 15,
    "nextPage": 3,
    "nextPageUrl": "https://www.catho.com.br/vagas/desenvolvedor/sao-paulo-sp/?page=3&work_model[0]=remote&work_model[1]=hybrid",
    "items": [
      {
        "id": 35324036,
        "url": "https://www.catho.com.br/vagas/desenvolvedor/35324036/",
        "title": "Desenvolvedor Backend Node.js",
        "description": "Atuacao em APIs, mensageria e arquitetura em nuvem.",
        "benefits": [
          "Vale Alimentacao",
          "Plano de Saude"
        ],
        "salary": {
          "min": 8000,
          "max": 12000
        },
        "jobLocation": "Sao Paulo - SP",
        "employmentType": "Prestador de servicos (PJ)",
        "hiringOrganization": "HRSOUL",
        "datePublished": "2026-02-10T23:59:59.000Z",
        "workSchedule": "Periodo Integral",
        "active": true,
        "score": 0.92
      }
    ]
  }
}

Referência completa de campos

Path	Tipo	Descrição	Exemplo
data.extractedAt	string (iso datetime)	Campo data.extractedAt retornado no payload de resposta.	2026-02-12T21:20:00.000Z
data.items[].active	boolean	Campo data.items[].active retornado no payload de resposta.	true
data.items[].benefits[]	string	Campo data.items[].benefits[] retornado no payload de resposta.	Vale Alimentacao
data.items[].datePublished	string	Campo data.items[].datePublished retornado no payload de resposta.	2026-02-10T23:59:59.000Z
data.items[].description	string	Campo data.items[].description retornado no payload de resposta.	Atuacao em APIs, mensageria e arquitetura em nuvem.
data.items[].employmentType	string	Campo data.items[].employmentType retornado no payload de resposta.	Prestador de servicos (PJ)
data.items[].hiringOrganization	string	Campo data.items[].hiringOrganization retornado no payload de resposta.	HRSOUL
data.items[].id	number	Campo data.items[].id retornado no payload de resposta.	35324036
data.items[].jobLocation	string	Campo data.items[].jobLocation retornado no payload de resposta.	Sao Paulo - SP
data.items[].salary.max	number	Campo data.items[].salary.max retornado no payload de resposta.	12000
data.items[].salary.min	number	Campo data.items[].salary.min retornado no payload de resposta.	8000
data.items[].score	number	Campo data.items[].score retornado no payload de resposta.	0.92
data.items[].title	string	Campo data.items[].title retornado no payload de resposta.	Desenvolvedor Backend Node.js
data.items[].url	string	Campo data.items[].url retornado no payload de resposta.	https://www.catho.com.br/vagas/desenvolvedor/35324036/
data.items[].workSchedule	string	Campo data.items[].workSchedule retornado no payload de resposta.	Periodo Integral
data.nextPage	number	Campo data.nextPage retornado no payload de resposta.	3
data.nextPageUrl	string	Campo data.nextPageUrl retornado no payload de resposta.	https://www.catho.com.br/vagas/desenvolvedor/sao-paulo-sp/?page=3&work_model[0]=remote&work_model[1]=hybrid
data.page	number	Campo data.page retornado no payload de resposta.	2
data.query.city	string	Campo data.query.city retornado no payload de resposta.	Sao Paulo
data.query.jobTitle	string	Campo data.query.jobTitle retornado no payload de resposta.	desenvolvedor
data.query.page	number	Campo data.query.page retornado no payload de resposta.	2
data.query.state	string	Campo data.query.state retornado no payload de resposta.	SP
data.query.workModel[]	string	Campo data.query.workModel[] retornado no payload de resposta.	remote
data.requestUrl	string	Campo data.requestUrl retornado no payload de resposta.	https://www.catho.com.br/vagas/desenvolvedor/sao-paulo-sp/?page=2&work_model[0]=remote&work_model[1]=hybrid
data.resultsPerPage	number	Campo data.resultsPerPage retornado no payload de resposta.	15
data.source	string	Campo data.source retornado no payload de resposta.	catho.com.br
data.totalJobAds	number	Campo data.totalJobAds retornado no payload de resposta.	960
data.totalResults	number	Campo data.totalResults retornado no payload de resposta.	9027
data.type	string	Campo data.type retornado no payload de resposta.	jlp
data.url	string	Campo data.url retornado no payload de resposta.	https://www.catho.com.br/vagas/desenvolvedor/sao-paulo-sp/?work_model[0]=remote
executionId	string (uuid)	Campo executionId retornado no payload de resposta.	bbbbbbbb-2222-4222-8222-bbbbbbbbbbbb
requestId	string (uuid)	Campo requestId retornado no payload de resposta.	bbbbbbbb-1111-4111-8111-bbbbbbbbbbbb

Erros comuns

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.
500	WORKER_ERROR / INTERNAL_ERROR	Falha interna no worker ou no gateway.