openapi: 3.0.0
info:
  title: Companies
  version: 1.0.0
  description: >-
    The companies endpoint in the Nalanda API allows you to manage company information within your system. This includes
    creating, updating, retrieving, and deleting company records — essential for platforms that handle multiple
    organizations or clients.


    A key feature of this API is the use of the tax ID as the primary identifier for all operations. For Spanish CIFs,
    the tax ID can be used without the country code (e.g., C65434870). However, for companies based in other countries,
    the tax ID must include the country code to properly identify the origin — for example, ZW307710350 for a Zimbabwean
    company.


    The format for these country codes follows the ISO 3166-1 alpha-2 standard, ensuring consistency across
    international identifiers. This distinction is crucial for maintaining accurate and compliant company records across
    different jurisdictions.
servers:
  - url: https://api.nalandaglobal.com/api
    description: Prod
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    Company:
      type: object
      x-examples:
        Spanish tax ids:
          id: 01GSSY8TF6G8NDNZAW0CP5JPCW
          tax_id: E60448966
          company_name: Asdf
          phone: '654789321'
          type_description: General
        Other tax ids:
          tax_id: 01GSSY8TF6G8NDNZAW0CP5JPCW
          company_name: MX60472461
          phone: '654321789'
          type_description: General
      properties:
        ulid:
          type: string
          description: Ulid (unique identifier) of the company
          example: 01HSX4RKRF1HJCPKGJKQCKHM28
          readOnly: true
        tax_id:
          type: string
          description: Tax id of the company
        company_name:
          type: string
          maxLength: 100
          x-stoplight:
            id: ak8ijx25dwxld
          description: Company name
        phone:
          type: string
          maxLength: 40
          description: Company phone number
        type_description:
          x-stoplight:
            id: fuzlycf1w1rmf
          description: Company Type
          type: string
          readOnly: true
      required:
        - tax_id
        - company_name
        - email
        - phone
    CompanyProfile:
      title: CompanyProfile
      x-stoplight:
        id: zt7k1prof09ax
      allOf:
        - $ref: '#/components/schemas/Company'
        - type: object
          properties:
            self_employed:
              type: boolean
              x-stoplight:
                id: slf1mpy0dxr9a
              description: >-
                Whether the company is self-employed (autónomo). Structured, programmatically decidable flag derived
                from the company's legal nature. Omitted when it cannot be resolved.
              readOnly: true
            trading_name:
              type: string
              x-stoplight:
                id: ybd9p4vut04a5
              description: The company's trading (commercial) name. Omitted when not set.
            fiscal_address_country:
              type: string
              x-stoplight:
                id: gshdm293dmrrh
              description: Country of the company's registered fiscal address, in English (e.g. "Spain").
            tax_residence_country:
              type: string
              x-stoplight:
                id: gdt3og4ia8qgr
              description: Country of tax residence, in English. Currently mirrors the fiscal address country.
            community_and_province:
              type: string
              x-stoplight:
                id: nac4y1elwp2cs
              description: >-
                Autonomous community and province of the fiscal address, in Spanish, formatted as "Community - Province"
                (e.g. "Andalucía - Cádiz").
            fiscal_address:
              type: string
              x-stoplight:
                id: gh2vu5qio29aq
              description: First line (street) of the company's fiscal address.
            postal_code:
              type: string
              x-stoplight:
                id: 1pf4ru39ogaqt
              description: Postal code of the fiscal address.
            web_address:
              type: string
              x-stoplight:
                id: ctaxeslfia9s1
              description: Company website URL. Omitted when none is registered.
      description: >-
        Enriched company profile returned exclusively by GET /companies/{tax_id}. Extends the slim Company with
        supplier-profile attributes. Fields that cannot be resolved during enrichment are omitted from the response, so
        consumers must treat every added field as optional.
    Zone:
      title: Zone
      x-stoplight:
        id: ad3pbxyum1nmz
      type: object
      description: Zone of the company
      properties:
        code:
          type: string
          x-stoplight:
            id: 0yt6aboixllja
          example: 11W1
          description: Code of the Zone
        description:
          type: string
          x-stoplight:
            id: u2x04mmlu2c3f
          example: GAL-Galicia
          description: Description of the Zone
          readOnly: true
      required:
        - code
    CIF:
      title: CIF
      x-stoplight:
        id: mcbbnrskiss0q
      type: object
      description: Cif model
      properties:
        value:
          type: string
          x-stoplight:
            id: 5l1694u1ckcr2
          description: Raw value of Cif/Tax Id
          example: 12345678Z
        type:
          x-stoplight:
            id: cqj9937fj5bew
          enum:
            - INTERNACIONAL
            - UTE
            - EMPRESA
            - AUTONOMO
    CCC:
      title: CCC
      x-stoplight:
        id: rp9i4z90wv7to
      type: object
      description: Código cuenta cotización model
      properties:
        rawValue:
          type: string
          x-stoplight:
            id: wzuvhnxwjkna7
          description: ccc value
          example: 0111 28167037226
        valid:
          type: boolean
          x-stoplight:
            id: wsz501lz5gnbk
          description: Whether the value is valid or not
    SocialSecurityResponse:
      title: SocialSecurityResponse
      x-stoplight:
        id: v09nldsjic0fg
      type: object
      properties:
        cifProveedor:
          $ref: '#/components/schemas/CIF'
        cccProveedor:
          $ref: '#/components/schemas/CCC'
        cifConstructor:
          $ref: '#/components/schemas/CIF'
        cccConstructor:
          $ref: '#/components/schemas/CCC'
        razonSocialConstructor:
          type: string
          x-stoplight:
            id: 3kx1r74wy8le0
        ared:
          type: string
          x-stoplight:
            id: x1xt9kanp31ty
        cccEmpresa:
          $ref: '#/components/schemas/CCC'
      description: Social Security response
    REAResponse:
      title: REAResponse
      x-stoplight:
        id: b2hy7axce2exa
      type: object
      description: REA Response
      properties:
        partyId:
          type: string
          x-stoplight:
            id: q6c7iumxn9yeu
          example: '270745'
        cif:
          type: string
          x-stoplight:
            id: ngl5by88du0x7
          example: A30745772
        tipoHuella:
          type: string
          x-stoplight:
            id: ax3id662419t6
          example: CIF
        cifHuella:
          type: string
          x-stoplight:
            id: qq22kwgbrblxf
          example: A30745772
        fechaRevision:
          type: string
          x-stoplight:
            id: 4jluibuu476fu
          example: 17/01/2021
          format: date
  responses:
    500-Internal-Server-Error:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: ./Error.yaml
    409-Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: ./Error.yaml
    404-Not-Found:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: ./Error.yaml
    403-Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: ./Error.yaml
    401-Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: ./Error.yaml
    400-Bad-Request:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: ./Error.yaml
          examples: {}
    406-Not-Acceptable:
      description: Not Acceptable
      content:
        application/json:
          schema:
            $ref: ./Error.yaml
          examples: {}
  parameters:
    accept:
      name: Accept
      in: header
      required: true
      schema:
        type: string
      description: application/vnd.nalanda.api-v1.0+json
    id:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: id of ulid type
    tax_id:
      name: tax_id
      in: path
      required: true
      schema:
        type: string
      description: The tax id of the company
    status:
      name: status
      in: query
      schema:
        type: string
        enum:
          - all
          - active
          - inactive
        default: all
      description: Status of the company
    page:
      name: page
      in: query
      required: false
      schema:
        type: number
      description: Number of the current page
    size:
      name: size
      in: query
      required: false
      schema:
        type: number
      description: Size for every page
    sort:
      name: sort
      in: query
      required: false
      schema:
        type: string
      description: Sort by field
    contentType:
      name: Content-Type
      in: header
      required: false
      schema:
        type: string
      description: application/json
paths:
  /companies:
    post:
      summary: Create company
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Company'
      security:
        - bearerAuth: []
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
              examples:
                Example 1:
                  value:
                    tax_id: 12345678Y
                    company_name: My Company
                    phone: '6576542323'
            application/xml:
              schema:
                type: object
                properties: {}
          headers:
            Location:
              schema:
                type: string
              description: The location url to get the company created
        '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'
        '409':
          $ref: '#/components/responses/409-Conflict'
      description: API operation to create a company
      operationId: createCompany
      parameters:
        - $ref: '#/components/parameters/accept'
        - schema:
            type: string
          in: header
          name: Content-Type
          description: application/json
    parameters: []
  /companies/{tax_id}:
    put:
      summary: Update company
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Company'
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
            application/xml:
              schema:
                type: object
                properties: {}
          headers: {}
        '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'
      description: |-
        <!-- BEGIN supported-platforms -->
        <!-- theme: none -->
        >#### Supported Platforms: NATIONAL / INTERNATIONAL
        <!-- END supported-platforms -->

        API operation to update a company
      operationId: updateCompany
      parameters:
        - $ref: '#/components/parameters/accept'
        - schema:
            type: string
          in: header
          name: Content-Type
          description: application/json
      x-supported-platforms:
        - national
        - international
    parameters:
      - schema:
          type: string
        name: tax_id
        description: The tax id of the company
        in: path
        required: true
  /companies/{tax_id}/subcontractors:
    get:
      summary: Get subcontractors
      security:
        - bearerAuth: []
      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
        - $ref: '#/components/parameters/status'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    x-stoplight:
                      id: vh3wbwsx3gmxx
                    items:
                      $ref: '#/components/schemas/Company'
                  page:
                    $ref: ./Page.json
        '401':
          description: Unauthorized
        '403':
          $ref: '#/components/responses/403-Forbidden'
        '404':
          $ref: '#/components/responses/404-Not-Found'
        '406':
          $ref: '#/components/responses/406-Not-Acceptable'
      operationId: getSubcontractorsByTaxId
      description: >-
        <!-- BEGIN supported-platforms -->

        <!-- theme: none -->

        >#### Supported Platforms: NATIONAL / INTERNATIONAL

        <!-- END supported-platforms -->


        The endpoint returns a list of companies that have a contractual relationship with the company associated to the
        tax id, i.e. it will return the companies that are directly associated through a work.
      x-stoplight:
        id: 0vlcmi0mw66zv
      x-supported-platforms:
        - national
        - international
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties: {}
    parameters:
      - schema:
          type: string
        name: tax_id
        description: The tax id of the company
        in: path
        required: true
  /companies/{tax_id}/zones:
    parameters:
      - schema:
          type: string
        name: tax_id
        in: path
        required: true
        description: Tax id of the company
    get:
      summary: Find all zones for the company
      tags:
        - zones
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    x-stoplight:
                      id: hiifh9liutc1u
                    items:
                      $ref: '#/components/schemas/Zone'
                  page:
                    $ref: ./Page.json
        '401':
          $ref: '#/components/responses/401-Unauthorized'
        '403':
          $ref: '#/components/responses/403-Forbidden'
        '404':
          $ref: '#/components/responses/404-Not-Found'
        '500':
          $ref: '#/components/responses/500-Internal-Server-Error'
      operationId: get-companies-tax_id-zones
      x-stoplight:
        id: ykbgqictxbtht
      description: |-
        <!-- BEGIN supported-platforms -->
        <!-- theme: none -->
        >#### Supported Platforms: NATIONAL / INTERNATIONAL
        <!-- END supported-platforms -->

        Get all the zones from the company by tax id
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/contentType'
        - $ref: '#/components/parameters/accept'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/size'
        - $ref: '#/components/parameters/sort'
      x-supported-platforms:
        - national
        - international
    post:
      summary: Create zone for the company
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Zone'
        '400':
          $ref: '#/components/responses/400-Bad-Request'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: ./Error.yaml
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: ./Error.yaml
        '406':
          description: Not Acceptable
          content:
            application/json:
              schema:
                $ref: ./Error.yaml
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: ./Error.yaml
      operationId: post-companies-tax_id-zones
      x-stoplight:
        id: p1hedhijvk3hz
      description: |-
        <!-- BEGIN supported-platforms -->
        <!-- theme: none -->
        >#### Supported Platforms: NATIONAL / INTERNATIONAL
        <!-- END supported-platforms -->

        Create a new zone for the company 
      x-supported-platforms:
        - national
        - international
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/contentType'
        - $ref: '#/components/parameters/accept'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Zone'
      tags:
        - zones
tags:
  - name: Logos
    description: Logos of the company
  - name: Zones
    description: Zone of the company