{"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.\n\nThis API plays a key role in organizing project collaborators, tracking their compliance and documentation status, and integrating them into broader project workflows.\n\n**What is a Contractor?**\nIn 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.\n\n**Core Functionalities**\n- Create a Contractor\nRegister 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.\n\n- Update a Contractor\nModify fields such as start and end dates, or update hierarchy and identification info if changes occur during the project.\n\n- Get Contractor by ID\nRetrieve detailed information about a specific contractor using its unique ID.\n\n- List/Search Contractors\nFilter contractors based on:\n\nProject (project_id)\nCompany (company_tax_id)\nHierarchical level (parent_contractor_id)\n"},"servers":[{"url":"https://api.nalandaglobal.com/api","description":"Prod"}],"paths":{"/contractors/{id}":{"get":{"summary":"Get contractor","description":"<!-- BEGIN supported-platforms -->\n<!-- theme: none -->\n>#### Supported Platforms: NATIONAL / INTERNATIONAL\n<!-- END supported-platforms -->\n\nGet 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 -->\n<!-- theme: none -->\n>#### Supported Platforms: NATIONAL / INTERNATIONAL\n<!-- END supported-platforms -->\n\nUpdate 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 -->\n<!-- theme: none -->\n>#### Supported Platforms: NATIONAL / INTERNATIONAL\n<!-- END supported-platforms -->\n\nSearch 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 -->\n<!-- theme: none -->\n>#### Supported Platforms: NATIONAL / INTERNATIONAL\n<!-- END supported-platforms -->\n\nCreate 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":[]}]}