# API VaaS /Vagas as a Service/ OpenAPI file: https://vaas.vag.as/doc/publicacao-vagas-vaas-pt.yaml ## Description 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 --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 --header “Authorization: Bearer asd23sde12e123sd” ``` ## Servers - https://apigateway.vagas.com.br/v1: https://apigateway.vagas.com.br/v1 () ## Topics ### [Authentications](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) [Powered by Bump.sh](https://bump.sh)