# API VaaS /Vagas as a Service/

> This is version `1.0.0` of this API documentation. Last update on Sep 22, 2026.
> 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á:
> 
> ```json
> {
> "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__:__
> 
> ```shell
> # 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:__
> 
> ```shell
> 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á:_
> ```json
> {
> "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:__
> 
> ```shell
> # Valor exemplo que deve ser incluido no HEADER da requisição:
> # Authorization: Bearer asd23sde12e123sd
> CURL example:
> curl -XGET <URL TBD>
> --header “Authorization: Bearer asd23sde12e123sd”
> ```

[Documentation](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt.md)

OpenAPI file: https://vaas.vag.as/doc/publicacao-vagas-vaas-pt.yaml

## MCP server

Connect AI agents to this documentation with the publicacao-vagas-vaas-pt MCP server (Model Context Protocol, no authentication, Streamable HTTP transport):

- URL: `https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/mcp`

## [Servers](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/servers.md)
- https://apigateway.vagas.com.br/v1: https://apigateway.vagas.com.br/v1


## Topics

### [Authentication](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/authentication.md)


## Endpoints

### [VaaS](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/group/endpoint-vaas.md)

- [Publicar Vaga](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/operation/operation-publicarvagavaas.md)

- [Atualizar Vaga](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/operation/operation-atualizarvagavaas.md)

- [Atualizar Vaga Representada](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/operation/operation-atualizarvagarepresentadavaas.md)

- [Suspender Vaga](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/operation/operation-suspendervagavaas.md)


### [Listas](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/group/endpoint-listas.md)

- [Apresentações](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/operation/operation-apresentacoes.md)

- [Áreas de Atuação](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/operation/operation-areasdeatuacao.md)

- [Beneficíos](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/operation/operation-beneficios.md)

- [Canais de publicação](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/operation/operation-canaisdepublicacao.md)

- [Cidades](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/operation/operation-cidades.md)

- [Divisões da Empresa](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/operation/operation-divisoesdaempresa.md)

- [Estados](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/operation/operation-estados.md)

- [Fases](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/operation/operation-fases.md)

- [Idiomas](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/operation/operation-idiomas.md)

- [Locais de Trabalho](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/operation/operation-locaisdetrabalho.md)

- [Níveis de Escolaridade](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/operation/operation-niveisdeescolaridade.md)

- [Níveis Hierárquicos](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/operation/operation-niveishierarquicos.md)

- [Paises](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/operation/operation-paises.md)

- [Tipo de contratação](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/operation/operation-tipodecontratacao.md)




## Changelog

- [Changelog](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/changes.md)
- [Changelog index (llms.txt)](https://vaas.vag.as/doc/publicacao-vagas-vaas-pt/changes/llms.txt)

[Powered by Bump.sh](https://bump.sh)
