API VaaS /Vagas as a Service/

1.0.0

O VaaS /Vagas as a Service/ é um verdadeiro agente de recrutamento para permitir que qualquer software possa usar a Vaga Inteligente.

Com o VaaS, clientes da Vagas que utilizam outros softwares podem publicar vagas automaticamente no Vagas.com Empresas por meio de uma chamada HTTP em formato JSON. Diferente do processo tradicional de publicação, essa API permite incluir uma URL externa na vaga, redirecionando os candidatos para outro sistema no momento em que clicarem para se candidatar.

Outro diferencial do VaaS é que, caso o cliente utilize um parceiro para realizar publicações, esse parceiro poderá efetuar a chamada em nome da empresa dentro do sistema Vagas.com Empresas. Isso possibilita que ele publique vagas representando terceiros, desde que autorizado, utilizando os dados da empresa representada na requisição da API.

Requisitos Técnicos

Entrega dos dados

• Contrato: JSON
• Formato: JSON, UTF-8
• Autenticação: OAuth2/API Key
• Tráfego: TLS 1.2
• Proteções: CSRF, Rate limit , WAF

Requisitos do cliente

• TLS suportado, versões de HTTP (1.2)
• Timeouts/retries desejados
• User-Agent identificável. Ex: X-Idempotency-Key/X-Client-Id/X-Tenant-Id

Autenticação

A autenticação para utilização desta API pode ser feita de 02 maneiras:

• Client Credencials
  • A vaga será criada com o usuário de identificação Admin como responsável
• Autorization Code (3-legged)
  • A vaga será criada com o usuário informado na autorização como responsável

Client Credencials

Esse processo consiste em uma chamada POST direto ao gateway indicando as credencias para obter o token de acesso.

Considerando que as credencias foram criadas no gateway, basta realizar uma chamada conforme o exemplo:

curl -X POST -k -H 'Content-Type: application/x-www-form-urlencoded' -i 'https://apigateway.vagas.com.br/oauth/token' --data 'grant_type=client_credentials' -u 'client_id:client_secret'

O retorno dessa execução será:

{
  "access_token": "asd23sde12e123sd",
  "expires_in": 2591999,
  "token_type": "Bearer"
}

Para todas as demais requisições abaixo, o access_token deve ser incluído na requisição como um atributo do HEADER em formato BEARER

Lembrando que o access_token tem um limite de tempo para uso, a informação retornada na chave expires_in indica a quantidades de segundos que o token será expirado a partir de sua data de geração.

Exemplo de chamada usando o __access_token:__

# Valor exemplo que deve ser incluido no HEADER da requisição:
# Authorization: Bearer asd23sde12e123sd
CURL example:
curl -XGET <URL TBD>
    --header “Authorization: Bearer asd23sde12e123sd”

Authorization Code (Three-Legged OAuth)

Este processo implementa a especificação OAuth 2.0 para autenticação e autorização.

A autenticação utiliza o fluxo Authorization Code (Three-Legged OAuth), no qual o sistema cliente direciona o usuário (cadastrado no Vagas.com) para o servidor de autorização da API da Vagas.

Obtenção do Token de Acesso

Para iniciar o processo de autenticação, a aplicação cliente deve realizar uma requisição para o endpoint /oauth/authorize da API da Vagas. A requisição deve incluir os seguintes parâmetros:

• client_id: Identificador da aplicação fornecido pela Vagas.
• login_type: Tipo de autenticação utilizada. Deve ser enviado o valor “empresa”.
• response_type: Tipo de resposta esperada. Deve ser enviado o valor “code” para utilização do fluxo Authorization Code.
• redirect_uri: URL previamente cadastrada para a aplicação, para a qual o usuário será redirecionado após a conclusão do processo de autenticação, independentemente de sucesso ou falha.

Exemplo:

https://apigateway.vagas.com.br/oauth/authorize?response_type=code&client_id=some_application_id&login_type=empresa&redirect_uri=http%3A%2F%2Flocalhost%2Foauth%2Fcode_callback

O usuário deverá autenticar-se utilizando suas credenciais de acesso e conceder autorização para que a aplicação utilize as suas informações para acessar os recursos disponibilizados pela API da Vagas.

Após a autenticação e a confirmação da autorização pelo usuário, o servidor de autorização da API da Vagas redirecionará o navegador para a URL informada no parâmetro redirect_uri, incluindo um código de autorização (authorization code) na resposta.

Exemplo:

http://localhost/oauth/code_callback?code=AixUbVTop239876

Em caso de falha na autenticação ou autorização, o servidor redirecionará a requisição para a mesma URL informada no parâmetro redirect_uri, incluindo o parâmetro de erro na resposta.

Exemplo:

http://localhost/oauth/code_callback?error=unauthorized-request

Com base no authorization code retornado na etapa anterior, a aplicação cliente deverá solicitar um access token, que será utilizado para autenticar todas as requisições subsequentes à API.

Para isso, deve ser realizada uma requisição HTTP POST para o endpoint /oauth/token, utilizando o formato application/x-www-form-urlencoded.

• code: Código de autorização obtido na etapa anterior.
• grant_type: Tipo de concessão OAuth. Deve ser enviado com o valor “authorization_code”.

Também deve ser incluído no cabeçalho da requisição (HEADER) um atributo contendo as credenciais de autenticação, composto pelo client_id e client_secret, concatenados por dois pontos (:), e codificados em Base64

Exemplo:

• client_id: "exemplo"
• client_secret: "emi40QrBjUiPaVC2eGK5"
• A concatenação dos valores será: exemplo:emi40QrBjUiPaVC2eGK5
• Após a codificação em Base64, o resultado será: ZXhlbXBsbzplbWk0MFFyQmpVaVBhVkMyZUdLNQ==

Esse valor deve ser enviado no header da requisição utilizando o esquema Basic Authentication, conforme abaixo: Authorization: Basic ZXhlbXBsbzplbWk0MFFyQmpVaVBhVkMyZUdLNQ==

Exemplo:

curl -XPOST https://apigateway.vagas.com.br/oauth/token \
    --header “Authorization: Basic ZXhlbXBsbzplbWk0MFFyQmpVaVBhVkMyZUdLNQ==” \
    --data “code=AixUbVTop239876&grant_type=authorization_code”

Em caso de sucesso, o retorno da requisição será:

 {
   "access_token": "asd23sde12e123sd",
   "expired_in": 2591999
 }

Para todas as demais requisições, o access_token deverá ser incluído no HEADER da requisição utilizando o esquema Bearer.

É importante ressaltar que o access_token possui tempo de expiração. O valor retornado no campo expires_in indica a quantidade de segundos em que o token permanecerá válido a partir do momento de sua geração.

Exemplo:

# Valor exemplo que deve ser incluido no HEADER da requisição:
# Authorization: Bearer asd23sde12e123sd
CURL example:
curl -XGET <URL TBD>
    --header “Authorization: Bearer asd23sde12e123sd”

This is version 1.0.0 of this API documentation. Last update on Sep 22, 2026.