openapi: 3.0.0 info: version: '1.0' title: Homologations description: >- The homologations endpoint in the Nalanda API allows you to manage the certification and approval processes for workers, contractors, and subcontractors. Homologation refers to the act of validating and certifying a service provider or individual according to predefined criteria and legal regulations. This functionality is key for ensuring that only qualified personnel and contractors are engaged in various projects. **Core Functionality** - Create, update, retrieve, and delete homologation records: These actions allow you to manage the status and details of approved or certified workers and service providers. - Search homologations: Allows for filtering and retrieving homologation records based on specific criteria, such as the provider or worker’s status. - Get homologation details: Retrieve detailed information about a specific homologation, including ratings and status updates. - Get ratings for homologation: Allows you to check the ratings associated with a particular homologation record, helping assess the quality or compliance of the worker or contractor. - Invite providers: Enables inviting providers to participate in homologation processes, which is especially useful for adding new contractors or workers to your system. This endpoint also supports integration with external providers for rating and compliance checks, helping ensure all workers and contractors meet the required standards for specific projects or industries. With this API, you can ensure that your company maintains a compliant and up-to-date record of all certified workers and contractors, helping streamline legal and operational processes. termsOfService: www.nalandaglobal.com license: name: '' servers: - url: https://api.nalandaglobal.com/api description: Prod paths: /homologations: get: tags: - Homologations summary: Search homologations V2 description: >- >#### Supported Platforms: NATIONAL / INTERNATIONAL Search the main information of the homologations according to the search parameters if you have the necessary permissions. operationId: get-homologations parameters: - $ref: '#/components/parameters/Accept-V2' - $ref: '#/components/parameters/homologator_tax_id' - $ref: '#/components/parameters/provider_tax_id' - name: sort in: query description: Sort of the search required: false schema: type: string default: alias,asc example: alias,asc - name: size in: query description: Size of the page required: false schema: type: integer minimum: 0 default: 10 - $ref: '#/components/parameters/page' responses: '200': description: OK content: application/json: schema: type: object properties: content: type: array items: $ref: '#/components/schemas/ElemHomologation' page: allOf: - $ref: '#/components/schemas/Page' description: Set of elements related to the pagination of the list required: - links - content - page examples: Example 1: value: content: - id: 01HG8Q4AM7KZ5ZHWMJKCYKQQHX homologator_tax_id: C42930503 provider_tax_id: D26457788 percentage: 100 rating: A approved_at: '2024-11-19T00:00:00.000+01:00' status_group: status: APPROVED status_description: Approved substatus: NEXT_EXPIRATION substatus_description: Next expiration - id: 01HG8Q46XTXTDVME57Y2RK30KS homologator_tax_id: D97343446 provider_tax_id: D33934324 percentage: 3 rating: D status_group: status: NOT_APPROVED status_description: Not approved substatus: INCOMPLETE substatus_description: Incomplete page: size: 1 totalElements: 2 totalPages: 1 number: 1 '400': $ref: '#/components/responses/400-Bad_Request' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '406': $ref: '#/components/responses/406-Not_Acceptable' security: - NalandaToken: [] servers: - url: https://api.nalandaglobal.com/api description: Prod x-supported-platforms: - national - international /homologations/{id}: get: tags: - Homologations summary: Get homologation description: |- >#### Supported Platforms: NATIONAL / INTERNATIONAL Returns the main homologation information if it's found and has permissions. operationId: get-homologations-id parameters: - $ref: '#/components/parameters/accept' - name: id in: path description: ULID type identifier required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/HomDataExt' examples: Example 1: value: id: 01H4G5YTJ4E4HQKE3K73DTDT22 homologator_tax_id: A28854727 provider_tax_id: 43370533P type_form: BASIC data_basic: rating: null percentage: 58 registered_at: '2023-07-04' effective_at: '2024-01-13' approved_at: null non_approved_at: null state_group: documentation_state: R status: OPEN status_description: Open substatus: IN_PROGRESS substatus_description: In progress '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' security: - NalandaToken: [] servers: - url: https://api.nalandaglobal.com/api description: Prod x-supported-platforms: - national - international /homologations/{id}/ratings: get: tags: - Homologations summary: Get ratings homologation description: |- >#### Supported Platforms: NATIONAL / INTERNATIONAL Get the rating of a homologation operationId: get-homologations-id-ratings parameters: - $ref: '#/components/parameters/accept' - $ref: '#/components/parameters/id' requestBody: content: {} responses: '200': description: OK content: application/json: schema: type: object properties: total: type: string enum: - A - B - C - D description: It is an average of the ratings of the individual ratings total_percentage: type: integer description: total % rating individual_ratings: type: array description: An array whose elements represent the rating per category maxItems: 5 items: type: object properties: name: type: string enum: - RRHH - PRL - CAYMA - COMPLIANCE - SOCIAL description: Category corresponding to the rating of the element in question description: type: string description: A description of the category corresponding to the rating of the item in question points: type: number format: float description: Points for the given category value: type: string enum: - A - B - C - D - P description: Rating for the given category required: - name - description - points - value required: - total examples: Example 1: value: total: A individual_ratings: - name: RRHH description: Human resources points: 120 value: A - name: PRL description: Job safety analysis points: 80 value: A - name: CAYMA description: Quality and enviroment points: 65 value: B - name: COMPLIANCE description: Compliance points: 90 value: A - name: SOCIAL description: Enviromental social and governance points: 100 value: A Example 2: value: total: A individual_ratings: - name: RRHH description: Human resources points: 120 value: A - name: PRL description: Job safety analysis points: 80 value: A - name: CAYMA description: Quality and enviroment points: 120 value: A Example 3: value: total: A '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' security: - NalandaToken: [] servers: - url: https://api.nalandaglobal.com/api description: Prod x-supported-platforms: - national - international /homologations/{id}/providers: get: tags: - Homologations summary: Get homologation provider description: |- >#### Supported Platforms: NATIONAL / INTERNATIONAL Returns the basic information of the approval provider if the logged-in user has permissions. operationId: get-homologations-id-providers parameters: - $ref: '#/components/parameters/accept' - name: id in: path required: true schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: tax_id: type: string description: Tax id of the company company_name: type: string description: Company name trade_name: type: string description: Short description - commercial name phone: type: string description: Company phone number type: type: string description: Company type required: - tax_id - company_name - email - phone examples: Example 1: value: tax_id: E60448966 company_name: Asdf trade_name: ASD phone: '654789321' type: General '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' security: - NalandaToken: [] servers: - url: https://api.nalandaglobal.com/api description: Prod x-supported-platforms: - national - international /homologations/{id}/dragados/answers: get: tags: - Homologations summary: Search answers of the homologation description: |- >#### Supported Platforms: NATIONAL Returns the answers of one homologation of dragados if the logged-in user has permissions. operationId: get-homologations-id-dragados-generalSpecifications parameters: - name: Accept in: header description: application/vnd.nalanda.api-V1.0+json required: true schema: type: string - name: id in: path description: ULID type identifier required: true schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: specification_data: type: object properties: contact_person: type: object properties: name: type: string description: name of contact surname: type: string description: surname of contact phone: type: string description: phone of contact required: - name - surname - phone - email references_works_performed: type: object properties: references_works: type: string description: list references and list works from homologator geographic_area: type: string description: geographic area from homologator associated_companies: type: array items: $ref: '#/components/schemas/AssociatedCompany' required: - references_works - geographic_area - associated_companies activities: type: array description: list activities from homologator items: type: string required: - contact_person - references_works_performed - activities examples: Example 1: value: specification_data: contact_person: name: namePersonContact surname: surnamePersonContact phone: '11111111' references_works_performed: references_works: works realised geographic_area: my room '': - tax_id: E12066718 company_name: testCompany phone: '222222222' activities: - activities realised by company '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' security: - NalandaToken: [] servers: - url: https://api.nalandaglobal.com/api description: Prod x-supported-platforms: - national /homologations_remittances:bulk: post: tags: - Homologations summary: Upload several homologations remittances description: |- >#### Supported Platforms: NATIONAL / INTERNATIONAL To upload a set of several remittances at once (limit of 10000). The user must have permissions as homologator, associate or accessor and have the appropriate role. operationId: post-homologations_remittances-bulk parameters: - $ref: '#/components/parameters/accept' requestBody: content: multipart/form-data: schema: type: object properties: file: type: string description: The template in csv format filled in with the remittances data format: binary required: - file responses: '200': description: OK content: application/json: schema: type: array items: type: string format: byte headers: Content-Type: schema: type: string description: application/octet-stream Content-Disposition: schema: type: string description: form-data; name="attachment"; filename="remittances_report.xlsx" '400': $ref: '#/components/responses/400-Bad_Request' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '406': $ref: '#/components/responses/406-Not_Acceptable' '415': $ref: '#/components/responses/415-Unsupported_MediaType' security: - NalandaToken: [] servers: - url: https://api.nalandaglobal.com/api description: Prod x-supported-platforms: - national - international /homologations/invitations: post: tags: - Homologations summary: Invite providers description: >- >#### Supported Platforms: NATIONAL Through this access point the whole process of welcome of the supplier to the approvals will be carried out. This involves, if necessary, creating the company, the user, the remittances and the approval itself in our system, as well as sending the supplier the appropriate notifications. For a full explanation of this flow, please see: [API Invitation Documentation](../docs/Invitations.md) operationId: post-homologations:invite parameters: - $ref: '#/components/parameters/accept' requestBody: content: application/json: schema: type: object required: - homologator - provider properties: homologator: type: object description: Homologator applying for the invitation required: - tax_id properties: tax_id: type: string description: tax_id of the homologator applying for the invitation represented_tax_id: type: string x-stoplight: id: 96220khfc28be description: >- Represents the CIF of the associated company: - If provided and it belongs to a company associated with the requester, the notification files for that company will be retrieved. - If not provided, the notification files for the requester's own company will be retrieved. provider: type: object description: Provider to whom the data required for entry into the homologation system are to be registered. required: - tax_id - company_name - phone - user properties: tax_id: type: string description: >- tax_id of the provider to whom the data required for entry into the homologation system are to be registered. company_name: type: string description: >- Company name of the provider to whom the data required for entry into the homologation system are to be registered. x-stoplight: id: j71bc95af92rm phone: type: string description: Company contact telephone number format: regex pattern: ^\+?[0-9]{9,15}$ user: type: object description: User to be registered for the new provider required: - email - first_name - last_name properties: first_name: type: string description: Provider user's first name maxLength: 50 last_name: type: string description: Provider user's last name maxLength: 50 phone: type: string x-stoplight: id: x734olq6a6mqo format: regex description: User contact telephone number examples: Example 1: value: homologator: tax_id: E21785670 represented_tax_id: R15756941 provider: tax_id: U96453600 company_name: Company test phone: '+34912345678' user: first_name: nombre last_name: apellido phone: '+34685121212' responses: '201': description: Created content: application/json: schema: type: object required: - homologation_id - company_tax_id - user_email - remittance_id - links properties: homologation_id: type: string description: Identifier of the homologation created for the provider format: regex pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$ company_tax_id: type: string description: Provider's company CIF format: regex pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$ x-stoplight: id: 5sjd3l9drab7q user_email: type: string description: Email of the provider user of the company format: regex pattern: ^[_A-z0-9-]+((\.|\+)[_A-z0-9-]+)*@[A-z0-9-]+(\.[A-z0-9-]+)*(\.[A-z]{2,63})$ remittance_id: type: string description: Identifier of the provider's remittance (if not configured, returns null) format: regex pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$ examples: Example 1: value: company_tax_id: U96453600 user_email: test@testing.com remittance_id: 01JPA8RNFFJ5BH6SB1KMMMXXAD homologation_id: 01JPA8RXV5JWWZMQ06G847GG2J '400': $ref: '#/components/responses/400-Bad_Request' '401': $ref: '#/components/responses/401-Unauthorized' '403': $ref: '#/components/responses/403-Forbidden' '404': description: Not Found '409': $ref: '#/components/responses/409-Conflict' '500': description: Internal Server Error security: - NalandaToken: [] servers: - url: https://api.nalandaglobal.com/api description: Prod x-stoplight: id: bkq3bcba8ap00 x-supported-platforms: - national parameters: [] tags: - name: homologations components: parameters: page: name: page in: query description: Page number required: false schema: type: integer minimum: 0 default: 0 size: name: size in: query description: Size of the page required: false schema: type: integer minimum: 0 maximum: 500 default: 500 sort: name: sort in: query description: Sort of the search required: false schema: type: string default: business_name,asc example: business_name,asc homologator_tax_id: name: homologator_tax_id in: query description: Tax id of homologator required: false schema: type: string provider_tax_id: name: provider_tax_id in: query description: Tax id of provider required: false schema: type: string id: name: id in: path description: ULID type identifier required: true schema: type: string step_id: name: step_id in: path description: id for step required: true schema: type: string accept: name: Accept in: header description: application/vnd.nalanda.api-V1.0+json required: true schema: type: string content-type: name: Content-Type in: header description: application/json required: true schema: type: string pdf: name: Content-Type in: header description: application/pdf required: true schema: type: string excel: name: Content-Type in: header description: application/vnd.ms-excel required: false schema: type: string Accept-V2: name: Accept-V2 in: header description: application/vnd.nalanda.api-V2.0+json required: true schema: type: string requestBodies: tax_ids: description: 'Resource ' content: application/json: schema: $ref: '#/components/schemas/TaxIds' securitySchemes: NalandaToken: type: http scheme: bearer responses: 404-Not-Found: description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' application/xml: schema: $ref: '#/components/schemas/Error' 403-Forbidden: description: |- Forbidden: The company reported to be invited is a provider (it can't be a homologator or an associated company In addition, homologator tax_id must fulfil one of the following options: - It matches with the logged-in user - Is accessible by the logged-in user's tax_id - The logged-in user is an associated user content: application/json: schema: $ref: '#/components/schemas/Error' 401-Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Example 1: value: status: 401 global_error: Unauthorized field_errors: null 400-Bad_Request: description: Bad Request. The body is missing or the body parameters are incorrect. content: application/json: schema: $ref: '#/components/schemas/Error' 406-Not_Acceptable: description: Not Acceptable - Header is expected -> Accept = application/vnd.nalanda.api-vX.Y+json content: application/json: schema: $ref: '#/components/schemas/Error' 409-Conflict: description: |- Conflict. Check the following: - if the reported email already exists for a different company - if all the entities already existed previously (company, user, remittance and homologation) - if all entities except the reported user already exist (as a user already exists for that homologation) content: application/json: schema: $ref: '#/components/schemas/Error' 415-Unsupported_MediaType: description: Unsupported MediaType content: application/json: schema: $ref: '#/components/schemas/Error' headers: pdf_Response: schema: type: string description: attachment; filename=%s.pdf required: true excel_response: schema: type: string description: attachment; filename=%s.xlsx required: false schemas: Provider: type: object title: Provider description: Resource with the main information about the providers of approval properties: cif: type: string business_name: type: string Links: type: array title: Links minItems: 1 maxItems: 1 items: type: object properties: rel: type: string example: self href: type: string format: uri minProperties: 2 maxProperties: 2 example: - rel: self href: https://api.nalandaglobal.com/api/homologations/01HG8Q4AM7KZ5ZHWMJKCYKQQHX ElemHomologation: type: object title: ElemHomologation description: Describes an homologation as one of a number of items in a list required: - id - homologator_tax_id - provider_tax_id - percentage - status_group - links properties: id: type: string description: Unique identifier of type ULID for providers format: uuid homologator_tax_id: type: string description: Homologator's Tax id provider_tax_id: type: string description: Provider's Tax id percentage: type: integer description: Represents the percentage of the mandatory data that have been completed to submit the homologation minimum: 0 maximum: 100 rating: type: string enum: - A - B - C - D description: Rating assigned to the provider's homologation status_group: type: object description: The different status of the approval and its documentation required: - status - status_description - substatus - substatus_description properties: status: $ref: '#/components/schemas/Status' status_description: type: string description: Status of the homologation (attribute name from enum value) substatus: $ref: '#/components/schemas/Substatus' substatus_description: type: string description: Substatus of the homologation (attribute name from enum value) approved_at: type: string x-stoplight: id: fneposv21249b format: date-time example: '2024-11-19T00:00:00.000+01:00' description: The last date on which the provider's homologation was changed to a sub-state with approved status Status: type: string enum: - APPROVED - OPEN - NOT_APPROVED title: Status description: All possible status of a homologation Substatus: type: string enum: - APPROVED - APPROVED_TEMPORARILY - NEXT_EXPIRATION - RESOLVE_INCIDENTS_APPROVED - PENDING_REVISION_NALANDA_APPROVED - PENDING_REVISION_APPROVED - INCOMPLETE_APPROVED - RESOLVE_INCIDENTS - PENDING_REVISION_NALANDA - PENDING_REVISION - IN_PROGRESS - PENDING_CONTRACT - INCOMPLETE - PENDING_RENEWAL - ANALYSIS_INTERNAL_UNFAVORABLE - EVALUATION_UNFAVORABLE - VETOED - DECLINE title: Substatus description: |- All possible Substatus of a status Substatus included within state APPROVED: APPROVED APPROVED_TEMPORARILY NEXT_EXPIRATION RESOLVE_INCIDENTS_APPROVED PENDING_REVISION_NALANDA_APPROVED PENDING_REVISION_APPROVED INCOMPLETE_APPROVED Substatus included within state OPEN: RESOLVE_INCIDENTS PENDING_REVISION_NALANDA PENDING_REVISION IN_PROGRESS PENDING_CONTRACT Substatus included within state NOT_APPROVED: INCOMPLETE PENDING_RENEWAL ANALYSIS_INTERNAL_UNFAVORABLE EVALUATION_UNFAVORABLE VETOED DECLINE Page: type: object description: Response model for resource paging properties: size: type: integer totalElements: type: integer totalPages: type: integer number: type: integer required: - size - totalElements - totalPages - number x-examples: Example 1: size: 3 totalElements: 793 totalPages: 265 number: 0 x-tags: - page HomDataExt: type: object title: HomDataExt description: Resource with the main information about the homologation properties: id: type: string description: Unique identifier of type ULID for providers provider_tax_id: type: string description: Provider's Tax id homologator_tax_id: type: string description: Tax id of the homologator type_form: type: string enum: - UNCLASSIFIED - BASIC - STANDARD description: The type of form currently proposed for the provider state_group: type: object description: The different status of the approval and its documentation properties: documentation_state: type: string enum: - G - P - R - O description: State of the documentation status: $ref: '#/components/schemas/Status' status_description: type: string description: Status of the homologation (attribute name from enum value) substatus: $ref: '#/components/schemas/Substatus' substatus_description: type: string description: Substatus of the homologation (attribute name from enum value) required: - documentation_state - status - status_description - substatus - substatus_description data_basic: type: object description: Encapsulated in basic data properties: rating: type: string nullable: true description: Rating assigned to the provider's homologation percentage: type: integer nullable: true description: Represents the percentage of the mandatory data that have been completed to submit the homologation approved_at: type: string nullable: true description: The last date on which the provider's homologation was changed to a sub-state with approved status format: date effective_at: type: string description: Date until which the homologation contract is effective format: date non_approved_at: type: string nullable: true description: >- The last date on which the provider's homologation changed to one of the following non-approved substatus: incomplete, vetoed, pending renewal, unfavorable evaluation or unfavorable internal analysis format: date registered_at: type: string description: Date on which the provider's homologation was created format: date required: - author - rating - percentage - approved_at - effective_at - non_approved_at - registered_at required: - id - provider_tax_id - homologator_tax_id - type_form - state_group - data_basic - links example: id: 01H4G5YTJ4E4HQKE3K73DTDT22 provider_tax_id: B96361498 homologator_tax_id: A26019992 type_form: BASIC state_group: documentation_state: G status: APPROVED status_description: Approved substatus: APPROVED substatus_description: Approved data_basic: rating: B percentage: 100 approved_at: '2019-08-24' effective_at: '2019-08-24' non_approved_at: '2019-08-24' registered_at: '2019-08-24' Step: type: object title: Step description: Returns the position, name, status, and percentage of the step properties: name: type: string description: Step name state: type: string enum: - R - G - P description: Step state percentage: type: integer description: Step percentage minimum: 0 maximum: 100 url: type: string description: "relative step url homologation\r\n" required: - name - url ElemHomologator: type: object title: ElemHomologator description: Describes an homologator as one of a number of items in a list properties: tax_id: type: string description: Cif of homologator alias: type: string description: Name of homologator nombre_comercial: type: string description: Commercial (trade) name of the homologator logo: type: string description: Relative URL of the homologator's logo has_remittances: type: boolean description: Indicates whether the homologator has remittances with the logged-in provider required: - tax_id - alias - has_remittances ElemRemittance: type: object title: ElemRemittance description: >- Resource for remittance reporting. Indicates the homologator with the remittance, the supplier that is in the remittance and the respective start and end dates properties: id: type: string description: ULID type identifier format: uuid homologador_tax_id: type: string description: Tax id of the homologator provider_tax_id: type: string description: Tax id of the provider started_at: type: string description: Date of entry in the remittance format: date-time finished_at: type: string description: Date of cancellation in the remittance format: date-time required: - id - homologador_tax_id - provider_tax_id - started_at Error: type: object title: Error description: Error response model properties: status: type: integer global_error: type: string field_errors: type: object properties: key: type: string value: type: array required: - status x-tags: - error AssociatedCompany: type: object title: AssociatedCompany description: Model for associated company of step 2 of Dragados properties: tax_id: type: string description: cif of associated company company_name: type: string description: name of associated company phone: type: string description: phone of associated company required: - tax_id - company_name - contact - email - phone x-examples: Example 1: tax_id: E12066718 company_name: testCompany phone: '680326783' Example 2: - tax_id: E12066718 company_name: testCompany1 phone: '11111111' - tax_id: E12066719 company_name: testCompany2 phone: '222222222' - tax_id: E12066720 company_name: testCompany3 phone: '333333333' TaxIds: type: object title: TaxIds description: Resource with the tax ids of homologator and provider properties: homologator_tax_id: type: string description: Tax id of homologator example: V45797511 provider_tax_id: type: string description: Tax id of provider example: Q4096569A required: - homologator_tax_id - provider_tax_id PQQCompany: title: PQQCompany x-stoplight: id: bcr1ep1zsjt1v type: object x-examples: Example 1: tax_id: A35010099 name: PEREZ MORENO S.A.U. alias: PEREZ MORENO properties: tax_id: type: string x-stoplight: id: xr2256t8nanev name: type: string x-stoplight: id: xjnqzaxnhhp6l alias: type: string x-stoplight: id: c5h6iyvl9470e security: - NalandaToken: []