openapi: 3.0.3
info:
  title: Applicants Export API
  version: 1.0.0
  description: |
    The Applicants Export API allows Vagas for Business customers to export all candidates of a vacancy in the export phase or
    who entered the export phase in the given date range, so that they can import the data into their systems via an HTTP call in JSON format.

    ## Authentication

    The authentication for using this API can be done in two ways:

    + Client Credencials
        + The job will be created with user identification of _admin_ as responsible
    + Autorization Code (3-legged)
        + The job will be created with the given user in the authorization steps as responsible

    ### Client Credencials

    This process consists of a direct POST call to the gateway indicating the credentials to obtain the access token.

    Considering that the credentials were created in the gateway, just make a call according to the example:

    ```
    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'
    ```

    The return will be:

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

    For all other requests below, the __access\_token__ must be
    included in the request as a Authorization HEADER attribute in BEARER token format

    Remembering that __access\_token__ has a time limit for use, the information returned in the key
    __expires\_in__ indicates the number of seconds that the token will expire from its generation date.

    __Exemple request using the __access\_token__:__

    ```shell
    # Example token the must be added in the Authorization HEADER:
    # Authorization: Bearer asd23sde12e123sd
    CURL example:
    curl -XGET <URL TBD>
        --header “Authorization: Bearer asd23sde12e123sd”
    ```


    ### Autorization Code (3-legged)

    This process implements the OAuth 2.0 specification for authentication and authorization.

    This authentication follows the "three leg" approach:

    + The __remote service__ requests __user__ (Jobs For Business employee)
      to authenticate to a __VAGAS API__ server

    #### How to get the token

    The remote service starts the process by calling the PATH /oauth/authorize
    from the VAGAS API server, sending as parameters:

    + __client_id__: Application ID (Provided by VAGAS team)
    + __login_type__: Type of login ID (must send the value "empresa")
    + __response_type__: Type of response ID (must send "code")
    + __redirect_uri__: URI that will be redirected when login action succeeds or fails

    __Exemple:__
    ```
    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
    ```

    The user will authenticate with their credentials and authorize the use of their information
    by the remote service.

    When the user accepts the authorization, the VAGAS API server will redirect back
    to the remote service using the address indicated by the redirect_uri parameter
    with an authorization code.

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

    In case of unauthorized request, the call will be to the same URI
    informed in the redirect_uri parameter with the error parameter.

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

    Using the code returned above, the remote service must request
    an access token that will be used for all other requests.

    Making a new request via an HTTP POST to the route
    /oauth/token using the "application/x-www-form-urlencoded" format with the following parameters:
    + __code__: The authorization code (received in the previous request)
    + __grant_type__: Should have the value: "authorization_code"

    It must also be included in the request HEADER an attribute with the client\_id and client\_secret information concatenated
    by a colon (:) and encoded in Base64

    __Example:__

    + Having the client\_id equal to `<client_id>` and a client\_secret equal to `<client_secret>`
    + Must be concatenated: `<client_id>:<client_secret>`
    + Applied Base64 on above value: `<base64(client_id:client_secret)>`
    + Included in the HEADER of the request: `Authorization: Basic <base64(client_id:client_secret)>`

    __Exemple Curl:__

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

    __The return of the request, if successful will be:__
    ```json
     {
       "access_token": "asd23sde12e123sd",
       "expired_in": 2591999
     }
    ```

    For all other requests below, the __access\_token__ must be
    included in the request as a HEADER attribute in BEARER format

    Remembering that __access\_token__ has a time limit for use, the information returned
    in the key __expires\_in__ indicates the number of seconds that the token will expire from its generation date.

    __Example call using __access\_token__:__

    ``` shell
    # Example value that must be included in the request HEADER:
    # 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: Applicants resumes
paths:
  /jobs/pproved-applicants.json:
    get:
      summary: Applicants to export
      description: |
        The request can be made through the following parameters, which are mandatory:
         * Job ID (job_id); or
         * Date range (export_date_start e export_date_end)

        Important:
         * The date range will fetch applicants based on the date they were moved to the export phase
         * The maximum range between date is 12(twelve) months
      operationId: get_jobs_pproved_applicants_json
      parameters:
        - name: job_id
          in: query
          required: false
          description: Job ID to fetch the applicants
          schema:
            type: string
          example: "123"
        - name: export_date_start
          in: query
          required: false
          description: Start date to fetch candidates.
          schema:
            type: string
            format: date
          example: "2023-01-10"
        - name: export_date_end
          in: query
          required: false
          description: End dateto fetch candidates.
          schema:
            type: string
            format: date
          example: "2023-02-05"
        - name: page
          in: query
          required: false
          description: Page number.
          schema:
            type: number
            default: 1
          example: 1
        - name: per_page
          in: query
          required: false
          description: Per page record limit
          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: |
            Response given when any of the parameters are invalid, the return can be one or more of the values
            defined in the example answer
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/precondition_failed"
  /jobs/resumes.json:
    get:
      tags:
        - Applicants resumes
      summary: Resumes
      description: |
        The request can be made through the following parameters, which are mandatory:
         * Job ID (job_id); or
         * Date range (export_date_start e export_date_end)

        Important:
         * The date range will fetch applicants based on the date they were moved to the export phase
         * The maximum range between date is 12(twelve) months
      operationId: get_jobs_resumes_json
      parameters:
        - name: job_id
          in: query
          required: false
          description: Job ID.
          schema:
            type: string
          example: "123"
        - name: export_date_start
          in: query
          required: false
          description: Start date of applicants search.
          schema:
            type: string
            format: date
          example: "2023-01-10"
        - name: export_date_end
          in: query
          required: false
          description: End date of applicants search.
          schema:
            type: string
            format: date
          example: "2023-02-05"
        - name: page
          in: query
          required: false
          description: requested page
          schema:
            type: number
            default: 1
          example: 1
        - name: per_page
          in: query
          required: false
          description: per page limit
          schema:
            type: number
            default: 10
          example: 10
        - name: include_additions
          in: query
          required: false
          description: Parameter to indicate if additions will be included in the return.
          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: Response for when any of the parameters are invalid, the return can be one or more of the values defined in the example answer
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/precondition_failed"
  /jobs/resumes/{resume_id}.pdf:
    get:
      tags:
        - Applicants resumes
      summary: PDF Resume
      operationId: get_jobs_resumes_resume_id_pdf
      parameters:
        - name: resume_id
          in: path
          required: true
          schema:
            type: string
          example: "123"
      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
          description: Full name
          example: John Sousa
        data_de_nascimento:
          type: string
          description: Date of birth
          example: 05/11/1980
        identidade_de_genero:
          type: string
          description: Gender identity
          example: Homem Cisgenero
        genero:
          type: string
          description: Gender
          example: M
        estado_civil:
          type: object
          description: Marital status
          properties:
            codigo:
              type: number
              description: Code
              example: 1
            estado:
              type: string
              description: State
              example: Solteiro(a)
        raca:
          type: object
          description: Race
          properties:
            codigo:
              type: number
              description: Code
              example: 1
            classificacao:
              type: string
              description: Classification
              example: Branco(a)
        pessoa_com_deficiencia:
          type: boolean
          description: Person with a disability
          example: true
        tipo_da_deficiencia:
          type: string
          description: Type of disability
          example: Visual
        nome_da_mae:
          type: string
          description: Mother name
          example: Maria Sousa
        nivel_de_escolaridade:
          type: string
          description: Education level
          example: Superior completo
        pais_de_nascimento:
          type: string
          description: Country of birth
          example: Brasil
        endereco:
          type: object
          properties:
            endereco:
              type: string
              description: Address
              example: Rua das nações
            numero:
              type: string
              description: Address number
              example: "123"
            complemento:
              type: string
              description: Complement
              example: Casa
            cidade:
              type: string
              description: City
              example: São Paulo
            estado:
              type: string
              description: State
              example: SP
            cep:
              type: string
              description: ZIP code
              example: 19828-123
        email:
          type: string
          example: john@email.com
        telefone_ddd:
          type: string
          description: Phone area code
          example: "11"
        telefone_numero:
          type: string
          description: Phone number
          example: "934569876"
        nomeemergencia:
          type: string
          description: Emergency name
          example: não possui
        cpf:
          type: string
          example: "23896587891"
        rg:
          type: string
          example: "123458862"
        estado_de_emissao:
          type: string
          description: Emission state of RG
          example: SP
        numero_ctps:
          type: string
          description: CTPS number
          example: "87654"
        serie_ctps:
          type: string
          description: CTPS serie
          example: "342323"
        data_de_emissao_ctps:
          type: string
          description: Emission date of CTPS
          example: 10/01/2019
        inscricaopispasep:
          type: string
          description: Inscription pis pasep
          example: "34323242"
        inscricao_nit:
          type: string
          description: Inscription NIT
          example: "87654"
        numero_do_titulo:
          type: string
          description: Voting title
          example: "34534"
        zona:
          type: string
          description: Voting zone
          example: "34"
        sessao:
          type: string
          description: Voting session
          example: "234"
        data_de_emissao_do_titulo:
          type: string
          description: Emission date of title
          example: 12/12/2015
        certificado_reservista:
          type: string
          description: Army certificate
          example: "3423423"
        possui_dependentes:
          type: boolean
          description: Has dependants
          example: true
        dependentes:
          type: array
          items:
            $ref: "#/components/schemas/dependents"
          description: Dependants
        data_de_chegada_ao_brasil:
          type: string
          description: Date of arrival in Brazil
          example: 13/05/1999
        numero_do_passaporte:
          type: string
          description: Passport number
          example: "342352543"
        possui_visto:
          type: boolean
          description: Has visa
          example: true
        numero_do_visto:
          type: string
          description: Visa number
          example: "4023423534"
        possui_rne:
          type: boolean
          description: Has RNE
          example: true
        numero_rne:
          type: string
          description: RNE number
          example: "634645"
        naturalizado_brasileiro:
          type: boolean
          description: Brazilian naturalized
          example: false
        data_de_naturalizacao:
          type: string
          description: Date of naturalization
          example: 20/05/2010
        casado_com_brasileiro:
          type: boolean
          description: Married with brazilian
          example: false
        possui_filhos_brasileiros:
          type: boolean
          description: Has brazilian children
          example: true
        possui_cnh:
          type: boolean
          description: Has CNH
          example: true
        numero_cnh:
          type: string
          description: CNH number
          example: "1242352"
        validade_da_cnh:
          type: string
          description: CNH expire date
          example: 05/12/2029
        categoria_conta_banco:
          type: string
          description: Bank account category
          example: Conta corrente
        banco:
          type: string
          description: Bank
          example: 001 - Banco do Brasil S.A.
        numero_da_agencia:
          type: number
          description: Bank agency number
          example: 4321
        numero_da_conta:
          type: number
          description: Bank account number
          example: 123456
        id_vaga:
          type: number
          description: Job ID
          example: 54364
        id_interno_cliente:
          type: string
          description: Internal Client ID
          example: teste0123456
        nome_cargo:
          type: string
          description: Job title
          example: Gerente de conta
        data_criacao_vaga:
          type: string
          description: Date of job creation
          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
          description: Full name
          example: José Fictício Barbosa Júnior
        data_de_nascimento:
          type: string
          nullable: true
          description: Date of birth
          example: "1967-01-23"
        identidade_de_genero:
          type: string
          nullable: true
          description: gender identification
          example: homem cisgênero
        cpf:
          type: string
          nullable: true
          example: "01234500100"
        email:
          type: string
          nullable: true
          example: teste@vagas.com.br
        versao_pdf:
          type: string
          nullable: true
          description: Resume PDF version
          example:
        pessoa_com_deficiencia:
          type: boolean
          description: Person with disability
          example: false
        nacionalidade:
          type: string
          nullable: true
          description: nationality
          example: Brasileiro
        telefone_celular:
          type: object
          description: Cellphone
          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: |
            Home phone
            It might also have small text with the number
          example: (11) 1234-5678
        endereco:
          type: object
          description: Address
          properties:
            bairro:
              type: string
              nullable: true
              description: Neightborhood
              example:
            cep:
              type: string
              nullable: true
              description: ZIP code
              example: "60871680"
            complemento:
              type: string
              nullable: true
              description: complement
              example:
            logradouro:
              type: string
              nullable: true
              description: address street
              example: Rua Iraci, 123 - Apto 7
            numero:
              type: string
              nullable: true
              description: number
              example:
            pais:
              type: string
              nullable: true
              description: country
              example: Brasil
            estado:
              type: string
              nullable: true
              description: state
              example: MG
            cidade:
              type: string
              nullable: true
              description: city
              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
          description: Education level
          example: Formação superior completa
        autodeclaracao_racial:
          type: string
          nullable: true
          description: self racial declaration
          example:
        adendos:
          type: object
          description: Additions can have N properties, where the attribute name defined by the addition name
          additionalProperties:
            type: object
            description: Addition names can have N questions, with the attribute name defined by the question identifier name
            additionalProperties:
              type: object
              properties:
                pergunta:
                  type: string
                  description: question
                  example: What is the correct answer?
                resposta:
                  type: string
                  description: answer
                  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
          description: Full name
          example: John Junior
        cpf:
          type: string
          example: "12345678902"
        data_de_nascimento:
          type: string
          description: Date of birth
          example: 11/09/2021