openapi: 3.0.3
info:
  title: API Exportação De Candidatos
  version: 1.0.0
  description: |
    A API de expotação de candidatos permite aos clientes do Vagas for Business exportarem todos candidatos de uma vaga na etapa de exportação, para que possam importar os dados em seus sitemas por meio de uma chamada HTTP no formato JSON.

    ## 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”
    ```


    ### Autorization Code (3-legged)

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

    Esta autenticação segue o padrão de "three leg":
    + O __serviço remoto__ requisita ao __usuário__ (funcionário do Vagas For Business)
     para que faça a autenticação em um servidor do __VAGAS API__

    #### Como obter o token

    O serviço remoto inicia o processo chamando uma URL para /oauth/authorize
    do servidor do VAGAS API, enviando como parametros:

    + __client_id__: Identificador da aplicação (Fornecido pela VAGAS)
    + __login_type__: Identificador do tipo de login (deve ser enviado o valor "empresa")
    + __response_type__: Identificador do tipo de resposta (deve ser enviado o valor "code")
    + __redirect_uri__: URI que será redirecionado quando a ação de login for sucesso ou não

    __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 irá autenticar com suas credencias e autorizará o uso de suas informações
    pelo serviço remoto.

    Quando o usuário aceitar a autorização, o servidor VAGAS API irá redirecionar de volta
    ao serviço remoto usando o endereço indicado pelo parametro redirect_uri
    com um código de autorização.

    __Exemplo:__
    ```
    http://localhost/oauth/code_callback?code=AixUbVTop239876
    ```

    No caso de requisição não autorizada, a chamada será para o mesmo URI
    informado no parametro redirect_uri com o parametro de erro.

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

    Usando o código retornado acima, o serviço remoto deve requisitar
    um token de acesso que será usado para todas as demais requisições.

    Fazendo uma nova requisição através de um HTTP POST para a rota
    /oauth/token usando o formato "application/x-www-form-urlencoded" com os seguintes parametros:
    + __code__: O código de autorização (recebido na chamada anterior)
    + __grant_type__: Com o valor "authorization_code"

    Também deve ser incluido no cabeçalho da requisição (HEADER)
    um atributo com as informações de client\_id e client\_secret concatenados
    por dois pontos (:) e codificado em Base64

    __Exemplo:__

    + Tendo o client\_id igual a `<client_id>` e um client\_secret igual a `<client_secret>`
    + Devem ser concatenados: `<client_id>:<client_secret>`
    + Aplicado Base64 no valor acima: `<base64(client_id:client_secret)>`
    + Incluído no HEADER da requisição: `Authorization: Basic <base64(client_id:client_secret)>`


    __Curl Exemplo:__

    ```shell
    curl -XPOST https://apigateway.vagas.com.br/oauth/token \
        --header “Authorization: Basic <base64(client_id:client_secret)>” \
        --data “code=AixUbVTop239876&grant_type=authorization_code”
    ```

    __O retorno da requisição, se bem sucedida será:__
    ```json
     {
       "access_token": "asd23sde12e123sd",
       "expired_in": 2591999
     }
    ```

    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”
    ```
servers:
  - url: https://apigateway.vagas.com.br/v1/applicants-export
security:
  - bearerAuth: []
tags:
  - name: Currículos de candidatos
paths:
  /jobs/approved-applicants.json:
    get:
      summary: Candidatos para exportação
      description: |
        A requisição pode ser feita através dos parâmetros a seguir, que são obrigatórios:
         * ID da vaga (job_id); ou
         * Intervalo de datas (export_date_start e export_date_end)

        Parâmetros opcionais:
         * page (se não for informado, retornará todos os registros em apenas 1 página)
         * per_page (se não for informado, retornará como padrão 10 registros por página)

        Importante:
         * O intervalo de datas leva em consideração a data em que o candidato foi movido para a fase de exportação
         * O intervalo máximo permitido entre datas é de 12 meses
      operationId: get_jobs_approved_applicants_json
      parameters:
        - name: job_id
          in: query
          required: false
          description: Id da vaga que será solicitados os candidatos.
          schema:
            type: string
          example: "123"
        - name: export_date_start
          in: query
          required: false
          description: Data de inicio para busca de candidatos.
          schema:
            type: string
            format: date
          example: "2023-01-10"
        - name: export_date_end
          in: query
          required: false
          description: Data de termino para busca de candidatos.
          schema:
            type: string
            format: date
          example: "2023-02-05"
        - name: page
          in: query
          required: false
          description: Número da página a ser retornada.
          schema:
            type: number
            default: 1
          example: 1
        - name: per_page
          in: query
          required: false
          description: Limite de registros para retornar por página.
          schema:
            type: number
            default: 10
          example: 10
      x-apib-request-headers:
        - "Authorization: Bearer <auth_token>"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/job_applicant_ok"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unauthorized"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/not_found"
        "412":
          description: |
            Resposta para quando algum dos parametros são inválidos, o retorno pode ser um ou mais dos valores
            definidos na resposta de exemplo
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/precondition_failed"
  /jobs/resumes.json:
    get:
      tags:
        - Currículos de candidatos
      summary: Currículos
      description: |
        A requisição pode ser feita através dos parâmetros a seguir, que são obrigatórios:
         * ID da vaga (job_id); ou
         * Intervalo de datas (export_date_start e export_date_end)

        Parâmetros opcionais:
         * page (se não for informado, retornará todos os registros em apenas 1 página)
         * per_page (se não for informado, retornará como padrão 10 registros por página)
         * include_additions (indica se os adendos serão incluidos no retorno)

        Importante:
         * O intervalo de datas leva em consideração a data em que o candidato foi movido para a fase de exportação
         * O intervalo máximo permitido entre datas é de 12 meses
      operationId: get_jobs_resumes_json
      parameters:
        - name: job_id
          in: query
          required: false
          description: Id da vaga que será solicitados os candidatos.
          schema:
            type: string
          example: "123"
        - name: export_date_start
          in: query
          required: false
          description: Data de inicio para busca de candidatos.
          schema:
            type: string
            format: date
          example: "2023-01-10"
        - name: export_date_end
          in: query
          required: false
          description: Data de termino para busca de candidatos.
          schema:
            type: string
            format: date
          example: "2023-02-05"
        - name: page
          in: query
          required: false
          description: Número da página a ser retornada.
          schema:
            type: number
            default: 1
          example: 1
        - name: per_page
          in: query
          required: false
          description: Limite de registros para retornar por página.
          schema:
            type: number
            default: 10
          example: 10
        - name: include_additions
          in: query
          required: false
          description: parametro para indicar se os adendos serão incluidos no retorno.
          schema:
            type: boolean
            default: false
          example: true
      x-apib-request-headers:
        - "Authorization: Bearer <auth_token>"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/job_resume_ok"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unauthorized"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/not_found"
        "412":
          description: |
            Resposta para quando algum dos parametros são inválidos, o retorno pode ser um ou mais dos valores
            definidos na resposta de exemplo
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/precondition_failed"
  /jobs/resumes/{resume_id}.pdf:
    get:
      tags:
        - Currículos de candidatos
      summary: Currículo em PDF
      operationId: get_jobs_resumes_resume_id_pdf
      parameters:
        - name: resume_id
          in: path
          required: true
          description: Id do currículo requisitado.
          schema:
            type: string
          example: "123"
        - name: job_id
          in: query
          required: true
          description: Id da vaga que o candidato está na fase de exportação
          schema:
            type: number
          example: 456
      x-apib-request-headers:
        - "Authorization: Bearer <auth_token>"
      responses:
        "200":
          description: OK
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/unauthorized"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/not_found"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: "Authorization: Bearer <auth_token>"
  schemas:
    job_applicant_ok:
      type: array
      items:
        $ref: "#/components/schemas/Applicant"
    job_resume_ok:
      type: array
      items:
        $ref: "#/components/schemas/Resume"
    unauthorized:
      type: object
      properties:
        error:
          type: string
          example: Usuário não autenticado
        status:
          type: number
          example: 401
    not_found:
      type: object
      properties:
        error:
          type: string
          example: Resource not found
        status:
          type: number
          example: 404
    precondition_failed:
      type: object
      properties:
        error:
          type: object
          properties:
            base:
              type: array
              items:
                type: string
              example:
                - Datas devem ter intervalo máximo de 1 ano
            export_date_start:
              type: array
              items:
                type: string
              example:
                - deve ser uma data
            export_date_end:
              type: array
              items:
                type: string
              example:
                - deve ser uma data
            job_id:
              type: array
              items:
                type: string
              example:
                - deve ser um numero
            page:
              type: array
              items:
                type: string
              example:
                - deve ser maior ou igual a 1
            per_page:
              type: array
              items:
                type: string
              example:
                - deve ser menor ou igual a 100
        status:
          type: number
          example: 412
    Applicant:
      type: object
      properties:
        nome_completo:
          type: string
          example: John Sousa
        data_de_nascimento:
          type: string
          example: 05/11/1980
        identidade_de_genero:
          type: string
          example: Homem Cisgenero
        genero:
          type: string
          example: M
        estado_civil:
          type: object
          properties:
            codigo:
              type: number
              example: 1
            estado:
              type: string
              example: Solteiro(a)
        raca:
          type: object
          properties:
            codigo:
              type: number
              example: 1
            classificacao:
              type: string
              example: Branco(a)
        pessoa_com_deficiencia:
          type: boolean
          example: true
        tipo_da_deficiencia:
          type: string
          example: Visual
        nome_da_mae:
          type: string
          example: Maria Sousa
        nivel_de_escolaridade:
          type: string
          example: Superior completo
        pais_de_nascimento:
          type: string
          example: Brasil
        endereco:
          type: object
          properties:
            endereco:
              type: string
              example: Rua das nações
            numero:
              type: string
              example: "123"
            complemento:
              type: string
              example: Casa
            cidade:
              type: string
              example: São Paulo
            estado:
              type: string
              example: SP
            cep:
              type: string
              example: 19828-123
        email:
          type: string
          example: john@email.com
        telefone_ddd:
          type: string
          example: "11"
        telefone_numero:
          type: string
          example: "934569876"
        nomeemergencia:
          type: string
          example: não possui
        cpf:
          type: string
          example: "23896587891"
        rg:
          type: string
          example: "123458862"
        estado_de_emissao:
          type: string
          example: SP
        numero_ctps:
          type: string
          example: "87654"
        serie_ctps:
          type: string
          example: "342323"
        data_de_emissao_ctps:
          type: string
          example: 10/01/2019
        inscricaopispasep:
          type: string
          example: "34323242"
        inscricao_nit:
          type: string
          example: "87654"
        numero_do_titulo:
          type: string
          example: "34534"
        zona:
          type: string
          example: "34"
        sessao:
          type: string
          example: "234"
        data_de_emissao_do_titulo:
          type: string
          example: 12/12/2015
        certificado_reservista:
          type: string
          example: "3423423"
        possui_dependentes:
          type: boolean
          example: true
        dependentes:
          type: array
          items:
            $ref: "#/components/schemas/dependents"
        data_de_chegada_ao_brasil:
          type: string
          example: 13/05/1999
        numero_do_passaporte:
          type: string
          example: "342352543"
        possui_visto:
          type: boolean
          example: true
        numero_do_visto:
          type: string
          example: "4023423534"
        possui_rne:
          type: boolean
          example: true
        numero_rne:
          type: string
          example: "634645"
        naturalizado_brasileiro:
          type: boolean
          example: false
        data_de_naturalizacao:
          type: string
          example: 20/05/2010
        casado_com_brasileiro:
          type: boolean
          example: false
        possui_filhos_brasileiros:
          type: boolean
          example: true
        possui_cnh:
          type: boolean
          example: true
        numero_cnh:
          type: string
          example: "1242352"
        validade_da_cnh:
          type: string
          example: 05/12/2029
        categoria_conta_banco:
          type: string
          example: Conta corrente
        banco:
          type: string
          example: 001 - Banco do Brasil S.A.
        numero_da_agencia:
          type: number
          example: 4321
        numero_da_conta:
          type: number
          example: 123456
        id_vaga:
          type: number
          example: 54364
        id_interno_cliente:
          type: string
          example: teste0123456
        nome_cargo:
          type: string
          example: Gerente de conta
        data_criacao_vaga:
          type: string
          example: "2022-04-12T19:43:17.803-03:00"
        data_candidato_movido_exportacao:
          type: string
          example: "2022-04-12T19:43:17.803-03:00"
    Resume:
      type: object
      properties:
        id:
          type: number
          example: 1085180
        nome_completo:
          type: string
          nullable: true
          example: José Fictício Barbosa Júnior
        data_de_nascimento:
          type: string
          nullable: true
          example: "1967-01-23"
        identidade_de_genero:
          type: string
          nullable: true
          example: homem cisgênero
        documentos:
          type: array
          items:
            type: object
            properties:
              documento:
                type: string
                description: Tipo do documento, CPF, RG, Passaporte, ...
                example: CPF (BRA)
              pais:
                type: string
                example: Brasil
              numero:
                type: string
                example: "12345678900"
        email:
          type: string
          nullable: true
          example: teste@vagas.com.br
        versao_pdf:
          type: string
          nullable: true
          example:
        pessoa_com_deficiencia:
          type: boolean
          example: false
        nacionalidade:
          type: string
          nullable: true
          example: Brasileiro
        telefone_celular:
          type: object
          properties:
            ddi:
              type: string
              nullable: true
              example: "55"
            ddd:
              type: string
              nullable: true
              example: "11"
            number:
              type: string
              nullable: true
              example: "999999999"
        telefone_residencial:
          type: string
          nullable: true
          description: Pode conter pequenas frases, não apenas números
          example: (11) 1234-5678
        endereco:
          type: object
          properties:
            bairro:
              type: string
              nullable: true
              example:
            cep:
              type: string
              nullable: true
              example: "60871680"
            complemento:
              type: string
              nullable: true
              example:
            logradouro:
              type: string
              nullable: true
              example: Rua Iraci, 123 - Apto 7
            numero:
              type: string
              nullable: true
              example:
            pais:
              type: string
              nullable: true
              example: Brasil
            estado:
              type: string
              nullable: true
              example: MG
            cidade:
              type: string
              nullable: true
              example: Belo Horizonte
            latitude:
              type: string
              nullable: true
              example: "-23.5071871"
            longitude:
              type: string
              nullable: true
              example: "-46.8965909"
        nivel_de_escolaridade:
          type: string
          nullable: true
          example: Formação superior completa
        autodeclaracao_racial:
          type: string
          nullable: true
          example:
        adendos:
          type: object
          description: Adendos podem ter N propriedades, sendo o nome do atributo definido pelo nome do adendo
          additionalProperties:
            type: object
            description: Nome dos adendos podem ter N perguntas, sendo o nome do atributo definido pelo nome identificador da pergunta
            additionalProperties:
              type: object
              properties:
                pergunta:
                  type: string
                  example: Qual a palabra certa?
                resposta:
                  type: string
                  example: A
              x-apib-key-name: identificador da pergunta
            x-apib-key-name: nome_do_adendo (string)
    dependents:
      type: object
      properties:
        nome_completo:
          type: string
          example: John Junior
        cpf:
          type: string
          example: "12345678902"
        data_de_nascimento:
          type: string
          example: 11/09/2021