# 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
#
openapi: 3.0.0

info:
  title: "Common Services"
  version: "1.0.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 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)
  
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 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'
            
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'
    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.