// 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.