# Change Control
# ===============
# Version    Date        Author             Change Description
# 1.0.0      04/10/2024  Viswanathan K      Initial version
# 1.0.0      04/10/2024  Viswanathan K      Changed version from basepath to resource path and added endCustomerNameMatch in CheckVATResponseV1
# 1.0.0      25/10/2024  Viswanathan        updated enum for exceptionSystemTypeV1
# 1.0.0      22/11/2024  Viswanathan        Added allowedCountryListV1, renamed countryCode to country,
#                                           vatNumber to companyRegistrationNumber, traderName to
#                                           endCustomerName and updated request body fields
# 1.1.0      15/04/2025  Kalpana H V        Added new API: Port-In operator list
# 1.1.0      30/05/2025  Viswanathan        Added new API: Holiday Calendar

openapi: 3.0.0

info:
  title: "Common Services"
  version: "1.1.0"  
  description: "This is a common service that defines the contract for generic APIs. Check VAT number API validates the Company Registration Number (VAT ID/CIF/NIF) of Portugal, Finland and Spain"
  contact: 
    name: Colt Reseller Support Voice
    email: ResellerSupport.Voice@colt.net
    
servers:
  - url: https://apis.colt.net/common-services
    description: Production server 
  - url: https://sandbox.apis.colt.net/common-services
    description: Sandbox server 

security:
  - bearerAuth: []

tags: 
  - name: Company Registration Number (VAT ID/CIF/NIF)
  - name: Port-In operator list
  - name: Holiday Calendar
  
paths:
  /v1/check-vat-number:
    post:
      tags:
        - "Company Registration Number (VAT ID/CIF/NIF)"
      description: "Validate Company Registration Number (VAT ID/CIF/NIF) in Portugal, Finland and Spain"
      operationId: "validateVATCIFNIFNumber"
      parameters:
      - name: x-tracking-id
        in: "header"
        required: true
        description: "Unique identifier for the request"        
        schema:
          $ref: '#/components/schemas/trackingIdTypeV1'      
      requestBody:
        required: true
        content:
          application/json:        
            schema:
              $ref: '#/components/schemas/CheckVATRequestV1'
      responses:
        "200":
          description: "OK"
          headers:
            Content-Type: 
              schema:
                type: string
                enum:
                  - application/json
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'          
          content:
            application/json:          
              schema:
                $ref: "#/components/schemas/CheckVATResponseV1"
        "400":
          description: Bad Request
          headers:          
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorTypeV1'
        "401":
          description: Unauthorized
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'
        "403":
          description: Forbidden
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorTypeV1'
        "404":
          description: Not Found
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'
        "405":
          description: Method Not allowed
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'
        "406":
          description: Not Acceptable
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'                
        "413":
          description: Payload Too Large
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'                 
        "415":
          description: Unsupported Media Type
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1' 
        "429":
          description: Too Many Requests
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'                 
        "500":
          description: Internal Server Error
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'  
        "503":
          description: Service Unavailable
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorTypeV1'  
        "504":
          description: Gateway Timeout
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorTypeV1'
            
  /v1/portInOperatorList:  
    get:
      operationId: getPortInOperatorList
      tags:
        - Port-In operator list
      description: |
        API to get the list of allowed operators to submit a portIn request for all countries 
        (except DE and NL).
      parameters:
      - name: x-tracking-id
        in: "header"
        required: true
        description: "Unique identifier for the request"
        schema:
          $ref: '#/components/schemas/trackingIdTypeV1'
      - name: country
        in: query
        required: true
        schema:      
          $ref: '#/components/schemas/coltOperatingCountryListV1'

      responses:
        "200":
          description: OK
          headers:
            content-type: 
              schema:
                type: string
                enum:
                  - application/json
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'                
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/operatorListResponseTypeV1'
        "400":
          description: Bad Request
          headers:          
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'              
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorTypeV1'
        "401":
          description: Unauthorized
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'                                
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'
        "403":
          description: Forbidden
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorTypeV1'
        "404":
          description: Not Found
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'                                
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'
        "405":
          description: Method Not allowed
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'                                                  
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'
        "406":
          description: Not Acceptable
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'                                                  
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'                
        "413":
          description: Payload Too Large
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'                                                  
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'                 
        "415":
          description: Unsupported Media Type
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'                                                  
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1' 
        "429":
          description: Too Many Requests
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'                                                  
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'                 
        "500":
          description: Internal Server Error
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'                                                  
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'  
        "503":
          description: Service Unavailable
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorTypeV1'  
        "504":
          description: Gateway Timeout
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorTypeV1'

  /v1/holidayCalendar:  
    get:
      operationId: getHolidayCalendar
      tags:
        - Holiday Calendar
      description: |
        API to get the holiday calendar (list of public holidays) for specific country and year.
      parameters:
      - name: x-tracking-id
        in: "header"
        required: true
        description: "Unique identifier for the request"
        schema:
          $ref: '#/components/schemas/trackingIdTypeV1'
      - name: country
        in: query
        required: true
        schema:      
          $ref: '#/components/schemas/coltOperatingCountryListV1'
      - name: year
        in: query
        required: true
        schema:      
          $ref: '#/components/schemas/yearTypeV1'          

      responses:
        "200":
          description: OK
          headers:
            content-type: 
              schema:
                type: string
                enum:
                  - application/json
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/holidayCalendarListV1'
        "400":
          description: Bad Request
          headers:          
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'             
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorTypeV1'
        "401":
          description: Unauthorized
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'                                
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'
        "403":
          description: Forbidden
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorTypeV1'
        "404":
          description: Not Found
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'                                
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'
        "405":
          description: Method Not allowed
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'                                                  
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'
        "406":
          description: Not Acceptable
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'                                                  
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'                
        "413":
          description: Payload Too Large
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'                                                  
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'                 
        "415":
          description: Unsupported Media Type
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'                                                  
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1' 
        "429":
          description: Too Many Requests
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'                                                  
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'                 
        "500":
          description: Internal Server Error
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'                                                  
          content:
            application/json:          
              schema:
                $ref: '#/components/schemas/errorTypeV1'  
        "503":
          description: Service Unavailable
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorTypeV1'  
        "504":
          description: Gateway Timeout
          headers:
            x-exception-system: 
              schema:
                $ref: '#/components/schemas/exceptionSystemTypeV1'
            x-tracking-id:
              description: "Unique identifier for the request"
              schema: 
                $ref: '#/components/schemas/trackingIdTypeV1'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorTypeV1'               

components:            
  securitySchemes:
    bearerAuth:            
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    trackingIdTypeV1: 
      type: string
      description: "Unique identifier for the request"
      example: abcd456e-d45645-dfaafda-1232345667dd
      pattern: "^[a-zA-Z0-9_.~:@-]{1,255}$"
      maxLength: 255
    exceptionSystemTypeV1:
      type: string
      enum:
        - 'APIGW'
        - 'ESB'
        - 'EXT_VAT_API'
    CheckVATRequestV1:
      type: "object"
      required:
        - country
        - companyRegistrationNumber
      properties:
        country:
          $ref: '#/components/schemas/allowedCountryListV1'
        companyRegistrationNumber:
          type: "string"
        endCustomerName:
          type: "string"

    CheckVATResponseV1:
      type: "object"
      properties:
        country:
          type: "string"
        companyRegistrationNumber:
          type: "string"
        requestDate:
          type: "string"
          format: "date-time"
        valid:
          type: "boolean"
        requestIdentifier:
          type: "string"
        name:
          type: "string"
        endCustomerName:
          type: "string"
        endCustomerNameMatch:
          type: "boolean"

    allowedCountryListV1:
      type: string
      enum:
        - 'PT'
        - 'ES'
        - 'FI'

    operatorListResponseTypeV1:
      type: object
      properties:
        operatorList:
          type: array
          items:
            $ref: '#/components/schemas/operatorTypeV1' 

    operatorTypeV1:
      type: object
      properties:
        operatorName:
          type: string          
        
    coltOperatingCountryListV1:
      type: string
      enum:
        - 'GB'
        - 'ES'
        - 'FR'
        - 'DE'
        - 'AT'
        - 'BE'
        - 'NL'
        - 'IE'
        - 'IT'
        - 'SE'
        - 'DK'
        - 'PT'
        - 'CH'
        - 'CZ'
        - 'NO'
        - 'RO'
        - 'PL'
        - 'FI'
        - 'LU'
        - 'SK'
        
    holidayCalendarListV1:
      type: object
      properties:
        holidayCalendar:
          type: array
          items:
            $ref: '#/components/schemas/holidayCalendarTypeV1' 

    holidayCalendarTypeV1:
      type: object
      properties:
        holidayName:
          type: string
          example: New Year
        holidayDate:
          $ref: '#/components/schemas/dateFormatV1'          

    dateFormatV1:
      type: string
      format: date
      description: date time in ISO 8601 format      
      example: "2025-01-01"
      
    yearTypeV1:
      type: string
      description: Calendar year
      maxLength: 4
      example: "2025"     
          
    errorTypeV1:
      description: 'Used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx)'
      type: object
      required:
        - code
        - reason
      properties:
        code:
          type: string
          description: 'Application relevant detail, defined in the API or a common list.'
          example: ERR01
        reason:
          type: string
          description: Explanation of the reason for the error which can be shown to a client user.
        message:
          type: string
          description: More details and corrective actions related to the error which can be shown to a client user.