APIs

Visão Geral

As APIs de vagas são um conjunto de ferramentas que permitem às empresas integrarem seus sistemas de cadastro de vagas com a Catho, sem que haja necessidade de cadastrar a vaga no site manualmente.


Modelagem das APIs

Todos os serviços disponibilizados por meio da API usam a tecnologia REST (Representational State Transfer), uma arquitetura para a disponibilização de recursos por meio de sistemas distribuídos, popularmente usado sobre HTTP. Abaixo podemos ver exemplos de como os serviços são formados:

Ilustração modelagem das APIs

Sendo que:

  • • Hostname: endereço principal dos serviços.
  • • Versão da API: versão do serviço que está sendo consumido.
  • • Recurso Raiz: nome do serviço.

A partir do Recurso Raiz, podemos acessar as principais operações do serviço (CRUD), pelos métodos do padrão HTTP, conforme tabela abaixo:

CRUD Métodos HTTP
Create POST
Read GET
Update PUT
Delete DELETE
Recurso GET POST PUT DELETE
/vagas Lista as vagas Cria nova vaga * *
/vagas/123 Recupera a vaga 123 *** ** Edita a vaga 123 *
/vagas/123/reativada * * Reativa a vaga 123 *
/vagas/123/renovada * * Renova a vaga 123 *
/vagas/123/desativada * * Desativa a vaga 123 *
* O método não deve ser implementado em coleções, então espera-se o retorno com ERRO 405 - method not allowed
** O método não deve ser implementado em itens, então espera-se o retorno com ERRO 405 - method not allowed. No entanto, é usado no caso de uma chamada assíncrona.
*** Como o pedido é um recurso agregador, deverá retornar por default todos os itens associados

Ou seja, no serviço /vagas do exemplo acima, se fizermos uma operação GET, obteremos como resposta uma lista de vagas e, se fizermos um POST, iremos salvar uma nova vaga (disponível apenas em ambiente de Sandbox).


HTTP 1.1

O protocolo padrão para comunicação com as APIs é o HTTP versão 1.1. Para mais informações sobre esse protocolo, consulte:

http://www.w3.org/Protocols/rfc2616/rfc2616.html
http://www.ietf.org/rfc/rfc2616.txt


UTF-8

O Charset padrão para chamadas às APIs é o UTF-8.

Para mais informações sobre essa codificação, consulte:

https://tools.ietf.org/html/rfc3629


JSON

JSON (JavaScript Object Notation) é um formato padrão aberto que usa texto para transmitir dados entre um servidor e aplicação da web, como uma alternativa para XML.

Por padrão toda a API trafega JSON, tanto para receber informações (métodos POST e PUT) quanto no retorno (método GET).

Devido a essa padronização, para as chamadas POST e PUT, é necessário informar dois parâmetros no Header:

  • • Accept: application/json
  • • Content-Type:application/json

Do contrário, você receberá um erro HTTP 415: Unsupported Media Type.


Endpoints

Há dois endpoints para acessar os serviços da API: use o endpoint de Produção apenas quando sua aplicação estiver publicada e, enquanto sua aplicação é desenvolvida, use o endpoint de Sandbox.

Para acessar em Produção, utilize a URL abaixo:

https://api.catho.com.br/v1/vagas/

Para testar os serviços de Sandbox, utilize a URL abaixo:

http://sandbox.catho.com.br/v1/vagas/


 

Status HTTP

Os códigos HTTP abaixo indicam retornos com sucesso:

  • • HTTP 200: Indica que o processamento foi realizado corretamente e o retorno será conforme a expectativa.
  • • HTTP 201: Indica que a objeto enviado no corpo da requisição foi incluído.

Os códigos HTTP abaixo indicam retornos com erro:

  • • HTTP 400: Requisição Inválida.
  • • HTTP 401: Autenticação Inválida.
  • • HTTP 403: Autenticação Negada.
  • • HTTP 404: Não Encontrado.
  • • HTTP 405: Método não Permitido.
  • • HTTP 408: Tempo Esgotado.
  • • HTTP 409: Conflito.
  • • HTTP 413: Requisição Excede Tamanho Máximo Permitido.
  • • HTTP 415: Tipo de Mídia Inválido.
  • • HTTP 422: Exceções de Negócio.
  • • HTTP 500: Erro Interno no Servidor.

Erros de validação

Esses erros impedem a efetivação da ação enviada, para reenviar a requisição é necessário alterar o dados do corpo, cabeçalho ou parâmetros da url, conforme instruções dos erros retornados.

Veja um exemplo em que o campo "titulo" não foi informado no corpo do POST:

https://api.catho.com.br/v1/vagas/:

{
    erros:
    {
        E010201: "Título inválido."
    }
}

Confira abaixo a lista de todos os erros que podem ser retornados:

Código Mensagem
E010000 Vaga não pertencente a empresa.
E010201 Campo 'titulo' inválido.
E010202 Campo 'titulo' deve ter no máximo 255 caracteres.
E010301 Campo 'atividades' é obrigatório.
E010401 Campo 'regimeContratacao' deve ser um array.
E010402 Quantidade de itens de 'regimeContratacao' ultrapassou ao limite 2.
E010501 Campo 'beneficios' deve ser um array.
E010801 Campo 'tipo' inválido esperado o valor 'NOVA' ou 'SUBSTITUICAO'.
E011001 Campo 'periodo' de 'estagio' deve possuir os valores 'INTEGRAL', 'DIURNO', 'VESPERTINO' ou 'NOTURNO'.
E011003 Campo 'finaisSemana' de 'estagio' deve ser do tipo 'boolean'
E011101 Campo 'valor' de 'salario' não informado.
E011102 Campo 'valor' de 'salario' deve ser um número.
E011104 Faixa salarial 'id' não cadastrada.
E011105 Campo 'confidencial' de 'salario' deve ser do tipo 'boolean'.
E011201 O campo 'recrutadores' deve ser do tipo 'array'.
E011202 Campo 'email' de 'recrutadores' inválido.
E011204 Campo 'email' de 'recrutadores' inválido.
E011205 O tamanho do campo 'email' de 'recrutadores' excedeu ao tamanho máximo.
E011206 Recrutador não encontrado.
E011301 Não é permitido repetir cidades.
E011302 Não é permitido informar o Brasil quando se passa uma lista de países.
E011303 É obrigatório informar pelo menos um tipo de localidade válida por vaga.
E011305 Localidade não encontrada.
E011306 Campo 'tipo' de 'localidade' não informado.
E011307 Campo 'tipo' de 'localidade' deve ter o valor 'PAIS' ou 'CIDADE'.
E011310 O campo 'locais' de 'localidade' deve ser do tipo 'array'.
E011311 Campo 'nome' de 'locais' de 'localidade' é obrigatório.
E011312 Campo 'nome' de 'locais' de 'localidade' deve ter até 255 caracteres.
E011313 Campo 'nome' de 'locais' de 'localidade' deve ser do tipo 'string'.
E011316 Campo 'quantidade' de 'locais' de 'localidade' deve ser maior que 0.
E011318 Campo 'quantidade' de 'locais' de 'localidade' é obrigatório.
E011321 Campo 'uf' de 'locais' de 'localidade ' é obrigatório.
E011322 Campo 'uf' de 'locais' de 'localidade' deve ter 2 caracteres.
E011323 Campo 'uf' de 'locais' de 'localidade' deve ter 2 caracteres.
E011324 Campo 'uf' de 'locais' de 'localidade' deve ser do tipo 'string'.
E011326 Cidade/UF não encontrado.
E011327 Pais não encontrado.
E011401 Campo 'nome' de 'contratante' não informado.
E011402 Campo 'nome' de 'contratante' deve ter até 255 caracteres.
E011403 Campo 'nome' de 'contratante' deve ser do tipo 'string'.
E011405 Nome contratante inválido.
E011406 Campo 'ramo' de 'contratante' não informado.
E011407 Campo 'ramo' deve ser do tipo 'inteiro'.
E011408 Ramo inválido.
E011410 Campo 'nacionalidade' de 'contratante' não informada.
E011411 Campo 'nacionalidade' de 'contratante' deve ter o valor 'NACIONAL' ou 'MULTINACIONAL'.
E011413 Campo 'porte' de 'contratante' não informado.
E011414 Campo 'porte' de 'contratante' deve ter o valor 'P', 'M', 'G'.
E011416 Campo 'descricao' de 'contratante' não informado.
E011417 Campo 'confidencial' de 'contratante' deve ser do tipo 'boolean'.
E011418 O campo 'contratante' deve ser do tipo 'object'.
E011500 O campo 'idiomas' de 'requisitos' deve ser do tipo 'array'.
E011501 O campo 'requisitos' deve ser do tipo 'object'.
E011504 Campo 'nivel' de 'idiomas' de 'requisitos' é obrigatório.
E011505 Campo 'nivel' de 'idiomas' de 'requisitos' deve ter o valor 1, 2 ou 3.
E011506 O campo 'estagio' de 'requisitos' deve ser do tipo 'object'.
E011507 Campo 'ano' de 'estagio' de 'requisitos' deve ser do tipo 'array'
E011508 O valor do array não é do tipo requerido.
E011509 Campo 'ano' de 'estagio' de 'requisitos' pode ter até 6 itens.
E011510 O campo "escolaridade" de "requisitos" é obrigatório quando o cargo da vaga é de perfil estagiário.
E011602 Campo 'pergunta' de 'questionario' é obrigatório.
E011603 Campo 'tipo' de 'questionario' é obrigatório.
E011604 Campo 'tipo' de 'questionario' deve ter o valor 'ALTERNATIVA' ou 'DISSERTATIVA'
E011605 Campo 'respostas' de 'questionarios' deve ter o valor 'S' ou 'N'.
E011606 O campo 'questionario' deve ser do tipo 'array
E011607 No campo 'questionario' são permitidos no máximo 5 itens.
E011701 O campo 'pcd' deve ser do tipo 'object'.
E011702 Campo 'tipo' de 'pcd' é obrigatório.
E011703 Campo 'tipo' de 'pcd' deve ter o valor 'FISICA', 'AUDITIVA', 'VISUAL', 'MENTAL' ou 'MULTIPLA'.
E011705 Campo 'descricao' de 'pcd' é obrigatório.
E011706 O campo 'opcoes' de 'pcd' deve ser do tipo 'object'.
E011707 Campo 'acompanhante' de 'opcoes' de 'pcd' deve ser do tipo 'boolean'.
E011708 Campo 'braille' de 'opcoes' de 'pcd' deve ser do tipo 'boolean'.
E011709 Campo 'instalacoesAdaptadas' de 'opcoes' de 'pcd' deve ser do tipo 'boolean'.
E011710 Campo 'leituraLabial' de 'opcoes' de 'pcd' deve ser do tipo 'boolean'.
E011711 Campo 'libras' de 'opcoes' de 'pcd' deve ser do tipo 'boolean'.
E011712 Campo 'transporteColetivo' de 'opcoes' de 'pcd' deve ser do tipo 'boolean'.
E011713 Campo 'veiculoAdaptado' de 'opcoes' de 'pcd' deve ser do tipo 'boolean'.
E011802 Campo 'sexo' de 'filtros' deve ter o valor 'M' ou 'F'.
E011804 A idade não pode ser menor que 18 ou maior que 80 anos
E011806 O campo 'localidade' de 'filtros' deve ser do tipo 'object'.
E011807 Campo 'tipo' de 'localidades' de 'filtros' deve ter o valor 'ESTADO', 'REGIAO' ou 'CIDADE'.
E011808 Campo 'criterio' de 'localidade' de 'filtros' deve ser do tipo 'array'.
E011811 Campo 'uf' de 'criterios' de 'localidade' de 'filtros' deve ter 2 caracteres.
E011812 Campo 'uf' de 'criterios' de 'localidade' de 'filtros' deve ter 2 caracteres.
E011813 Nenhum critério para o filtro idade foi informado.
E011902 Campo 'alertaEmail' de 'configuracoes' deve ser do tipo 'boolean'.
E011903 Campo 'anuncianteConfidencial' de 'configuracoes' deve ser do tipo 'boolean'.
E020001 Vaga não encontrada.
E020002 Ops, essa vaga já foi desativada.
E020101 Campo 'contratado' não pode ser vazio.
E020102 Campo 'contratado' deve receber um valor do tipo boolean.
E020201 O campo 'nome' deve receber um valor do tipo 'array'.
E020202 O campo 'nome' deve receber um 'array' com 'strings'.
E030000 O motivo deve ser um dos seguintes valores: POUCOS_CURRICULOS,FORA_PERFIL,VAGA_ABERTA,MAIS_CANDIDATOS,DISPONIVEL_NOVAMENTE
E030001 Vaga não encontrada.
E030002 Ops, essa vaga não tem 50 dias de anúncio.
E030003 Ops, essa vaga não pode ser renovada porque não está ativa.
E030005 Ops, essa vaga já foi renovada.
E040000 Ops, a vaga não pode ser reativada.
E040001 Vaga não encontrada.

Avisos

Avisos são mensagens informativas associadas a determinadas características da vaga. Diferente dos erros, avisos não impedem a inserção da vaga.

Lembre-se de que, apesar de não impedirem a inserção da vaga, avisos devem ser tratados, pois se referem à qualidade dessa vaga. Vagas com muitos avisos tendem a ser rejeitadas pela nossa Inspeção.

Código Mensagem
W010401 Regimes de Contratação repetidos foram unificados.
W010402 Vagas temporárias sazonais estão fora do escopo da Catho.
W010403 Identificador de regime de contratação inválido.
W010501 Beneficios repetidos foram unificados.
W010502 Identificador de benefício '' inválido.
W011101 Recomendamos que não anuncie vagas de emprego com salário inferior a R$ 100,00.
W011102 A faixa de remuneração escolhida, acima de R$ 3.000,00, não é a mais adequada para vagas de estágio.
W011103 A faixa de remuneração escolhida, abaixo de R$ 1.000,00, não é a mais adequada para vagas de diretoria e gerência.
W011201 O email '' não foi encontrado.
W011401 Recomendamos que só anuncie vagas confidenciais se for para substituição de algum colaborador ainda não desligado.
W011501 Informação repetida em campos da descrição (conhecimentos/experiencias/atividades).
W011502 Idiomas repetidos foram unificados.
W011503 Idioma '' não encontrado.
W011504 Ano de estágio 'id' inválido e ignorado.
W011601 O filtro só pode ser usado para questões alternativas.
W011602 A pergunta '' está repetida.
W011701 Habilidade de PCD '' não compatível com o tipo de deficiência informado
W011801 Vagas com filtro de cidades podem receber poucos currículos. Filtros mais abrangentes, como estado ou região, aumentam as chances de receber mais currículos.
W011802 No filtro de localidade, a região com nome '' e UF '' não foi encontrada.
W011803 No filtro de localidade, a cidade '' não foi encontrada para a UF ''.
W011804 Para utilizar o filtro de localidade é necessário informar pelo menos uma cidade para a vaga.
W011805 Cidade '' repetida nos filtros.
W011806 Campo '' não informado. Filtro não cadastrado.
W011901 Não é possivel destacar essa vaga no trabalhe conosco se o campo 'disponivel' estiver como false.
W011902 Dados de 'Trabalhe Conosco' ignorados. Para utilizar o 'Trabalhe Conosco' você precisa ter o produto configurado.

Paginação

Durante a exibição do resultado de alguns métodos da API você pode escolher o uso de parâmetros de paginação. Para paginar resultados você pode escolher usar dois parâmetros na própria Query String, "page" e "pageSize", conforme exemplo abaixo:

https://api.catho.com.br/api/v1/vagas?page=1&pageSize=10

Dessa forma, como resultado, temos uma lista contendo 10 objetos a partir do primeiro da lista. Caso você não use os parâmetros de paginação, por padrão, o retorno é sempre com 10 itens por página.

Abaixo seguem todos os parâmetros que podem ser passados pela URL:

dataCadastro: Período das vagas (apenas em GET):

page: Indica a página atual da consulta;

pageSize: Indica a quantidade de registros por página;

Abaixo seguem algumas das principais propriedades do resultado:

page_count: Quantidade de páginas no resultado da consulta;

page_size: Quantidade máxima de itens por página;

total_items: Quantidade de itens do resultado da consulta;

_links: São as referências de navegação para as páginas:

  • self: página atual
  • first: primeira página
  • last: última página
  • next: próxima página
  • prev: página anterior

Na listagem da vaga, 

links: 
{
self: 
{
href: "https://api.catho.com.br/vagas/vagas/?pageSize=10&page=2"
}
-
listagemCatho: 
{
href: "https://seguro.catho.com.br/login/index.php?redir=http://www.catho.com.br/area-empresa/minhas-vagas/"
}
-
first: 
{
href: "https://api.catho.com.br/vagas/vagas/?pageSize=10"
}
-
last: 
{
href: "https://api.catho.com.br/vagas/vagas/?pageSize=10&page=98"
}
-
prev: 
{
href: "https://api.catho.com.br/vagas/vagas/?pageSize=10&page=1"
}
-
next: 
{
href: "https://api.catho.com.br/vagas/vagas/?pageSize=10&page=3"
}
-
}

No retorno unitário da vaga,

_links:
{
self: 
{
href: "https://api.catho.com.br/vagas/vagas/9230196/"
}
-
visualizacaoCatho: 
{
href: "https://seguro.catho.com.br/login/index.php?redir=http://www.catho.com.br/area-empresa/painel-vagas/9230196/"
}
-
}

_embedded: São as principais informações do retorno dos dados, neste caso, as vagas.


Fluxo de vaga publicada

Logo abaixo é possível entender qual o ciclo de vida de uma vaga no site da Catho.

Ilustração fluxo de vaga publicada

Cadastro da vaga: Este fluxo explica o ciclo da vaga na Catho. Ele contempla desde a sua inclusão até as etapas que a vaga passa quando está no ar.

Inspeção: Assim que for incluída uma vaga, ela é inspecionada pela nossa equipe de Inspeção de Vagas. É um time especializado na análise de descrições de vagas e na identificação de possíveis problemas, garantindo assim a qualidade das vagas publicadas no site da Catho.

Vaga aprovada: Legal! Sua vaga segue nosso padrão de qualidade e estará disponível no nosso site.

Vaga rejeitada: Ops, ocorreu algum problema. Sua vaga não foi aprovada em algum dos critérios de inspeção e não ficará disponível para candidatos enviarem currículos. Esta vaga não deve ser reenviada sem que sejam feitas as alterações necessárias.

Publicada: Muito bem! Sua vaga passou na inspeção e já está no ar. Agora sua vaga poderá ser visualizada pelos nossos candidatos, que poderão se cadastrar no seu processo seletivo.

Renovação: As vagas ficam no site por 60 dias e podem ser renovadas por mais um período, entre o 50º e o 60º dia. Muita atenção: somente uma vaga 'Publicada' pode ser renovada e isso só pode ser feito UMA vez.

Vaga desativada: Vagas que não forem renovadas dentro do período dos 60 dias serão desativadas e não serão exibidas no site da Catho.

Reativação: Caso sua vaga esteja desativada, você pode reativá-la para que ela volte para o site.


Referência de tabela de dados

Aqui podemos ver as tabelas das referências de dados dos campos passados como parâmetro.

Salário

É utilizado no recurso GET e POST /vagas/ no campo salario.valor atendendo a regra: quando o salário for abaixo de 50 significa que foi utilizada uma faixa para o salário. Confira abaixo os valores de cada faixa salarial:

Valor Descrição
2 Até R$ 1.000,00
3 De R$ 1.001,00 a R$ 2.000,00
4 De R$ 2.001,00 a R$ 3.000,00
5 De R$ 3.001,00 a R$ 4.000,00
6 De R$ 4.001,00 a R$ 5.000,00
7 De R$ 5.001,00 a R$ 6.000,00
8 De R$ 6.001,00 a R$ 7.000,00
9 De R$ 7.001,00 a R$ 8.000,00
10 De R$ 8.001,00 a R$ 9.000,00
11 De R$ 9.001,00 a R$ 10.000,00
12 De R$ 10.001,00 a R$ 15.000,00
13 De R$ 15.001,00 a R$ 20.000,00
14 Acima de R$ 20.000,00

Ramos

É utilizado no recurso GET e POST /vagas/ no campo contratante.ramo. Confira abaixo os valores de cada ramo:

Valor Descrição
2 Educação/ Idiomas
3 Alimentos
4 Petroquímico/ Petróleo
5 Farmacêutica/ Veterinária
6 Recursos Humanos
7 Gráfica/ Editoras
8 Contabilidade/ Auditoria
9 Importação/ Exportação
10 Relações Públicas
11 Automotivo
12 Informática
13 Estética/ Academias
14 Borracha
15 Saúde
16 Construção Civil
17 Jurídica
18 Prestadora de Serviços
19 Bebidas
20 Eletrônica/ Eletroeletrônica/ Eletrodomésticos
21 Publicidade / Propaganda
22 Telecomunicações
23 Engenharia
24 Têxtil/ Couro
25 Diversão/ Entretenimento
26 Turismo/ Hotelaria
27 Outros
28 Transportes
29 Papel e Derivados
30 Agricultura / Pecuária / Silvicultura
31 Órgãos públicos
32 Corretagem (Seguros)
33 Bancário / Financeiro
34 Comunicação
35 Automação
36 Bens de Consumo (Outros)
37 Bens de Capital
38 Comércio Atacadista
39 Comércio Varejista
40 Cosméticos
41 Concessionárias / Auto Peças
42 Corretagem (Imóveis)
43 Corretagem de Títulos e Valores Imobiliários
44 Embalagens
45 Financeiras
46 Indústrias
47 Internet/ Sites
48 Mecânica/ Manutenção
49 Metalúrgica / Siderúrgica
50 Sindicatos / Associações / ONGs
51 Plásticos
52 Restaurante/ Industrial/ Fast Food
53 Seguros/ Previdência Privada
54 Segurança Patrimonial
55 Telemarketing/ Call Center
56 Café
57 Açúcar e Álcool
58 Logística / Armazéns
59 Agências de Turismo / Viagem
60 Supermercado / Hipermercado
61 Administração e Participação
62 Energia/ Eletricidade
63 Materiais de Construção
64 Madeiras
65 Calçados
66 Mineração
67 Equipamentos médicos / precisão
68 Jornais
69 Material de Escritório
70 Equipamentos industriais
71 Móveis e Artefatos de decoração
72 Academia de Esportes / Artes Marciais
73 Consultoria Geral
74 Eventos
75 Representação Comercial
76 Arquitetura / Paisagismo / Urbanismo
77 Assessoria de Imprensa
78 Incorporadora

Idiomas

É utilizado no recurso GET e POST /vagas/ no campo requisitos.idiomas.nome atendendo a regra: O requisitos.idiomas recebe um array de objetos que contém o campo nome. Confira abaixo todos os idiomas aceitáveis:

Descrição
Inglês
Espanhol
Francês
Alemão
Italiano
Romeno
Grego
Russo
Japonês
Chinês
Hebraico
Sueco
Coreano
Árabe

Regime de Contratação

É utilizado no recurso GET e POST /vagas/ no campo regimeContratacao. Confira abaixo todos os regimes aceitáveis:

Valor Descrição
1 Autônomo
2 CLT (Efetivo)
5 Free-lancer
6 Prestador de serviços (PJ)
7 Temporário
8 Trainee

Benefícios

É utilizado no recurso GET e POST /vagas/ no campo beneficios. Confira abaixo todos os benefícios aceitáveis:

Valor Descrição
1 Seguro Saúde
2 Assistência Médica / Medicina em grupo
3 Assistência Odontológica
4 Convênio com Farmácia
5 Seguro de Vida em Grupo
6 Vale Refeição
7 Vale Alimentação
8 Cesta Básica
9 Carro fornecido pela empresa
10 Estacionamento
11 Combustível
12 Previdência Privada
13 Auxílio Creche
14 Estudo de Faculdade
15 Estudo de Pós-Graduação / MBA
16 Curso de Idiomas
17 Celular fornecido pela empresa
18 Transporte Fornecido pela empresa
19 Restaurante na empresa
20 Vale Transporte
21 Participação nos lucros