openapi: 3.1.0
x-stoplight:
  id: rhhg58l5qq706
info:
  version: '1.0'
  title: Contractors
  summary: API for contractors management
  description: >
    The Contractors API is a service designed for construction platforms to manage the relationship between a company
    and a construction project. It enables systems to register, update, and query Contractor records, which represent a
    company actively participating in a specific construction project.


    This API plays a key role in organizing project collaborators, tracking their compliance and documentation status,
    and integrating them into broader project workflows.


    **What is a Contractor?**

    In this context, a Contractor is not just a company—it’s a company linked to a specific project. This means the same
    company can be a contractor in multiple projects, each with its own context, roles, and associated documents.


    **Core Functionalities**

    - Create a Contractor

    Register a new contractor by linking a company (via its tax ID) to a project. You can also specify whether it is a
    direct contractor or a subcontractor by using the parent_contractor_id.


    - Update a Contractor

    Modify fields such as start and end dates, or update hierarchy and identification info if changes occur during the
    project.


    - Get Contractor by ID

    Retrieve detailed information about a specific contractor using its unique ID.


    - List/Search Contractors

    Filter contractors based on:


    Project (project_id)

    Company (company_tax_id)

    Hierarchical level (parent_contractor_id)
servers:
  - url: https://api.nalandaglobal.com/api
    description: Prod
paths:
  /contractors/{id}:
    get:
      summary: Get contractor
      description: |-
        <!-- BEGIN supported-platforms -->
        <!-- theme: none -->
        >#### Supported Platforms: NATIONAL / INTERNATIONAL
        <!-- END supported-platforms -->

        Get contractor by id
      operationId: get-api-contractor-id
      parameters:
        - name: Accept
          in: header
          description: application/vnd.nalanda.api-v1.0+json
          schema:
            type: string
        - name: id
          in: path
          description: unit Identificated
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contractor'
            application/xml:
              schema:
                type: object
                properties:
                  content:
                    $ref: '#/components/schemas/Contractor'
        '401':
          $ref: '#/components/responses/401-Unauthorized'
        '403':
          $ref: '#/components/responses/403-Forbidden'
        '404':
          $ref: '#/components/responses/404-Not_Found'
        '406':
          $ref: '#/components/responses/406-Not_Acceptable'
      security:
        - bearerAuth: []
      x-stoplight:
        id: 2hkbhb8bx5k32
      x-supported-platforms:
        - national
        - international
    put:
      summary: Update contractor
      operationId: update-contractor
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contractor'
        '400':
          $ref: '#/components/responses/400-Bad_Request'
        '401':
          $ref: '#/components/responses/401-Unauthorized'
        '403':
          $ref: '#/components/responses/403-Forbidden'
        '404':
          $ref: '#/components/responses/404-Not_Found'
        '406':
          $ref: '#/components/responses/406-Not_Acceptable'
      x-stoplight:
        id: h7lkoietd6phn
      description: |-
        <!-- BEGIN supported-platforms -->
        <!-- theme: none -->
        >#### Supported Platforms: NATIONAL / INTERNATIONAL
        <!-- END supported-platforms -->

        Update contractor for the company of the user logged in
      parameters:
        - $ref: '#/components/parameters/accept-v1'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contractor'
      x-supported-platforms:
        - national
        - international
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: ID of the contractor
  /contractors:
    get:
      summary: Find all contractors
      tags:
        - Search
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    x-stoplight:
                      id: 0qldfh4jy07mp
                    items:
                      $ref: '#/components/schemas/Contractor'
                      x-stoplight:
                        id: q0wrdq8259u8p
                  page:
                    $ref: ./Page.json
                    x-stoplight:
                      id: c07v0q5bfc11v
        '400':
          $ref: '#/components/responses/400-Bad_Request'
        '401':
          $ref: '#/components/responses/401-Unauthorized'
        '403':
          $ref: '#/components/responses/403-Forbidden'
        '404':
          $ref: '#/components/responses/404-Not_Found'
        '406':
          $ref: '#/components/responses/406-Not_Acceptable'
      operationId: get-contractors
      x-stoplight:
        id: 7ceyj5pibrrx9
      x-supported-platforms:
        - national
        - international
      description: |-
        <!-- BEGIN supported-platforms -->
        <!-- theme: none -->
        >#### Supported Platforms: NATIONAL / INTERNATIONAL
        <!-- END supported-platforms -->

        Search for contracts of the logged in user
      parameters:
        - schema:
            type: string
          in: header
          name: Accept
          description: application/vnd.nalanda.api-v1.0+json
        - schema:
            type: string
          in: query
          name: page
          description: Number of the current page
        - schema:
            type: string
          in: query
          name: size
          description: Size for every page
        - schema:
            type: string
          in: query
          name: sort
          description: Sort by field
        - schema:
            type: string
          in: query
          name: project_id
          description: Get all contractors for this project id
        - schema:
            type: string
          in: query
          name: company_tax_id
          description: Filter by the contractor company's tax ID (company_tax_id). Optional.
        - schema:
            type: string
          in: query
          name: status
          description: >-
            Contract vigency. active = started (started_at reached) and not finished (finished_at null or future);
            inactive = the complement; all = no filter.
      requestBody:
        content:
          application/json:
            schema:
              type: object
    post:
      summary: Create contractor
      operationId: post-contractors
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contractor'
        '400':
          $ref: '#/components/responses/400-Bad_Request'
        '401':
          $ref: '#/components/responses/401-Unauthorized'
        '403':
          $ref: '#/components/responses/403-Forbidden'
        '404':
          $ref: '#/components/responses/404-Not_Found'
        '406':
          $ref: '#/components/responses/406-Not_Acceptable'
      x-stoplight:
        id: yzss4npcyq2za
      x-supported-platforms:
        - national
        - international
      parameters:
        - schema:
            type: string
          in: header
          name: Accept
          description: application/vnd.nalanda.api-v1.0+json
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contractor'
      description: |-
        <!-- BEGIN supported-platforms -->
        <!-- theme: none -->
        >#### Supported Platforms: NATIONAL / INTERNATIONAL
        <!-- END supported-platforms -->

        Create contractor for the company of the user log in
tags:
  - name: Certificates
    description: Certificates of the contractor
  - name: Search
    description: Search
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  responses:
    401-Unauthorized:
      description: 401 Unauthorized
    404-Not_Found:
      description: 404 Not Found
      content:
        application/json:
          schema:
            $ref: ./Error.yaml
    406-Not_Acceptable:
      description: 406 Not Acceptable
      content: {}
    403-Forbidden:
      description: 403 Forbidden
      content:
        application/json:
          schema:
            $ref: ./Error.yaml
    400-Bad_Request:
      description: Example response
      content:
        application/json:
          schema:
            properties:
              id:
                type: string
  schemas:
    Contractor:
      type: object
      title: Contractor
      x-stoplight:
        id: b5mm5ald1im4g
      description: Data related to a company's contract to work on a project
      properties:
        id:
          type: string
          examples:
            - 01H3KVBK79F0B8FYD2YV85BHVF
          x-stoplight:
            id: ufciu0n526es8
          description: Identifier provided by Nalanda
          example: 01H3KVBK79F0B8FYD2YV85BHVF
          readOnly: true
        project_id:
          type: string
          examples:
            - 001m
          description: ID of the project for which the work is contracted
          example: 01HA7B8F4SW8BMRD1RKZF6WNRV
        parent_contractor_id:
          type: string
          examples:
            - mi obra es una descripción
          x-stoplight:
            id: sp27z1n5luq6t
          description: ID of the parent contractor, null in case of direct contracting
          example: 01H3KVBK79F0B8FYD2YV85BDDD
        company_tax_id:
          type: string
          examples:
            - 04339985T
          x-stoplight:
            id: wforg7spalr47
          description: 'Tax ID of the company carrying out the work '
          example: 04339985T
        started_at:
          type: string
          format: date
          examples:
            - '2001-01-01'
          x-stoplight:
            id: hig0korh0ya6w
          description: Date on which the supplier entered the project and started the work
          pattern: ^\d{4}-\d{2}-\d{2}$
          example: '2001-01-01'
        finished_at:
          type: string
          format: date
          examples:
            - '2001-01-01'
          x-stoplight:
            id: 7asaxk82lz10z
          description: Date on which the supplier completed the work and left the project
          pattern: ^\d{4}-\d{2}-\d{2}$
          example: '2001-02-13'
    ContractorWorkerState:
      title: ContractorWorkerState
      x-stoplight:
        id: qfmvk91kjpeyi
      type: object
      description: Data related to the worker state in the project
      properties:
        check_list:
          type: object
          x-stoplight:
            id: 3mguuw7atavdx
          description: Indicates whether the worker is included in the subcontractor's check lists.
          properties:
            rnt_tc2_state:
              $ref: '#/components/schemas/State'
              x-stoplight:
                id: 9hdqnm02wfdxr
              description: State of RNT/TC2 document
            payroll_state:
              $ref: '#/components/schemas/State'
              x-stoplight:
                id: cee8aui4lffcl
              description: State of Payroll document
            ita_state:
              $ref: '#/components/schemas/State'
              x-stoplight:
                id: zfk537vayi2a9
              description: State of ITA document
        accreditation:
          type: object
          x-stoplight:
            id: bq6zjqevv8x89
          description: >-
            The calculation of the worker's accreditation states, which includes some worker's and some company's
            states.
          properties:
            state:
              $ref: '#/components/schemas/State'
              x-stoplight:
                id: becgo3ucj0br1
              description: State of the acreditation
            documents:
              type: object
              x-stoplight:
                id: lfi3zbkfo49wq
              properties:
                ita_state:
                  $ref: '#/components/schemas/State'
                  x-stoplight:
                    id: qzbxsncwckq1v
                  description: Company document that informs of the workers registered in the social security system.
                specific_company_documentation_state:
                  $ref: '#/components/schemas/State'
                  x-stoplight:
                    id: d3rwn88979fnd
                  description: State of the specific company documentation
                company_documentation_state:
                  $ref: '#/components/schemas/State'
                  x-stoplight:
                    id: 5z90xf1jptwp4
                  description: State company documentation
                worker_documentation_state:
                  $ref: '#/components/schemas/State'
                  x-stoplight:
                    id: zs5oxgoudpcqa
                  description: State of worker documentation
                specific_worker_documentation_state:
                  $ref: '#/components/schemas/State'
                  x-stoplight:
                    id: oqh7218ib4byy
                  description: State of the specific worker documentation
                health_security_manager_state:
                  $ref: '#/components/schemas/State'
                  x-stoplight:
                    id: fuxyzv7ulm4nf
                  description: State for the health security manager
                security_coordinator_state:
                  $ref: '#/components/schemas/State'
                  x-stoplight:
                    id: ad3jxnm7e75ep
                  description: State of the security coordinator
        jobs:
          type: array
          x-stoplight:
            id: 523xe9u8x61ox
          description: Jobs for workers on a project
          items:
            x-stoplight:
              id: hn34ncs0689un
            type: object
            properties:
              state:
                $ref: '#/components/schemas/State'
                x-stoplight:
                  id: j886cat5389vv
                description: State of the job
              type:
                type: string
                x-stoplight:
                  id: yvyjvzazkyiow
                description: Type of the job
                example: CONSTRUCCION
              icon:
                type: string
                x-stoplight:
                  id: kzcv1q7pbet3l
                description: Uri for the icon
                example: /media/img/oficios/obra/fontanero.png
              description:
                type: string
                x-stoplight:
                  id: 7dunn4nj9qqfk
                description: Description of the job
                example: Fontanero, Gas, Tuberías
        risks:
          type: array
          x-stoplight:
            id: 0f5vdevkz9xe0
          description: Risks for workers on a project
          items:
            x-stoplight:
              id: lgae07kwzjbyc
            type: object
            properties:
              state:
                $ref: '#/components/schemas/State'
                x-stoplight:
                  id: 50thr0etphhe4
                description: State of the risk
              type:
                type: string
                x-stoplight:
                  id: rzg52bg6bqgf0
                example: Eléctrico
                description: Type of the risk
              icon:
                type: string
                x-stoplight:
                  id: 0wi9auow3a4q6
                description: Uri for the icon
                example: /media/img/riesgos/trabajador/riesgo_electrico.png
              description:
                type: string
                x-stoplight:
                  id: fnsfd484equ8t
                description: Description of the risk
                example: EPI's Riesgo Eléctrico
    State:
      title: State
      x-stoplight:
        id: t09sklo6n5ipe
      description: State of a document
      enum:
        - G
        - R
        - P
        - NO_INFORMADO
  parameters:
    accept-v1:
      name: Accept
      in: header
      required: false
      schema:
        type: string
      description: application/vnd.nalanda.api-v1.0+json
security:
  - bearerAuth: []