@apifreaks/openapi-specs 0.1.0 → 0.1.2

package/dist/specs/financial/swift-code-lookup.yaml

@@ -0,0 +1,156 @@
+openapi: 3.1.1
+info:
+  title: SWIFT/BIC Code API - Look Up Bank Details or Find Codes by Country, Bank & City
+  version: 1.0.0
+  description: Look up a SWIFT/BIC code to retrieve bank details. Returns the bank name, address, city, country, country code, and bank code for any valid 8 or 11 character SWIFT/BIC code. Supports both headquarters and branch-level SWIFT codes.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: SWIFT/BIC Code Lookup API Server
+paths:
+  /swift-code/lookup:
+    get:
+      tags:
+        - Financial APIs
+      summary: Lookup SWIFT code details
+      description: Fetches detailed information about a SWIFT code.
+      parameters:
+        - name: format
+          in: query
+          required: false
+          schema:
+            type: string
+            enum:
+              - json
+              - xml
+            default: json
+          description: 'Specify the desired response format. Options: ''json'' (default) or ''xml''.'
+        - name: swiftCode
+          in: query
+          required: true
+          schema:
+            type: string
+          description: SWIFT/BIC code to lookup (must be 8 or 11 characters).
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SwiftCodeLookup'
+              examples:
+                typicalSuccess:
+                  summary: Typical successful response — normalized to 11-character form
+                  value:
+                    swiftCode: NWBKGB2LXXX
+                    countryCode: GB
+                    bankAddress: 250 BISHOPSGATE
+                    bankCode: NWBK
+                    bankName: NATIONAL WESTMINSTER BANK PLC
+                    city: LONDON
+                    country: United Kingdom
+        '400':
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                MissingSwiftCode:
+                  summary: Missing required swiftCode parameter
+                  value:
+                    error: Invalid Param Exception
+                    message: please pass correct parameters
+                    path: /v1.0/swift-code/lookup
+                    status: 400
+                    timestamp: '2026-07-27T11:50:49.650Z'
+                BadLength:
+                  summary: swiftCode is not 8 or 11 characters
+                  value:
+                    message: 'Bad request: SWIFT code input must be either 8 characters or 11 characters'
+        '404':
+          description: Not Found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                NotFound:
+                  summary: SWIFT code not found
+                  value:
+                    message: No bank found with the provided SWIFT code
+      operationId: lookupSwiftCode
+components:
+  securitySchemes:
+    ApiKeyAuthHeader:
+      type: apiKey
+      in: header
+      name: X-apiKey
+      description: Pass your API key via the X-apiKey request header.
+    ApiKeyAuthQuery:
+      type: apiKey
+      in: query
+      name: apiKey
+      description: Pass your API key via the apiKey query parameter.
+  schemas:
+    SwiftCodeLookup:
+      type: object
+      properties:
+        swiftCode:
+          type: string
+          description: SWIFT/BIC code, normalized to its 11-character form (an 8-character input is returned padded with XXX).
+        countryCode:
+          type: string
+          description: ISO 3166-1 alpha-2 country code where the bank is registered.
+        bankAddress:
+          type: string
+          description: Physical address of the bank branch.
+        bankCode:
+          type: string
+          description: Bank code portion of the SWIFT code (first 4 characters).
+        bankName:
+          type: string
+          description: Full name of the bank or financial institution.
+        city:
+          type: string
+          description: City where the bank branch is located.
+        country:
+          type: string
+          description: Full country name where the bank is registered.
+      required:
+        - swiftCode
+        - countryCode
+        - bankAddress
+        - bankCode
+        - bankName
+        - city
+        - country
+      description: Bank details returned for a SWIFT/BIC code lookup.
+    ErrorResponse:
+      type: object
+      required:
+        - message
+      properties:
+        error:
+          type: string
+          description: Short error category or exception type.
+        message:
+          type: string
+          description: Human-readable error message describing the failure.
+        path:
+          type: string
+          description: API endpoint path that produced the error.
+        status:
+          type: integer
+          description: HTTP status code returned with the error.
+        timestamp:
+          type: string
+          format: date-time
+          description: Timestamp when the error occurred (ISO 8601).
+      description: Standard error envelope returned by the API on failed requests.
+security:
+  - ApiKeyAuthHeader: []
+  - ApiKeyAuthQuery: []

package/dist/specs/financial/vat-number-validation.yaml

@@ -0,0 +1,205 @@
+openapi: 3.1.1
+info:
+  title: VAT Number Validation API - Real-time VAT Validations across EU & UK
+  version: 1.0.0
+  description: Validate a VAT number against the VIES or HMRC databases. Supports all EU VAT numbers (validated against VIES) and UK VAT numbers (validated against HMRC). Returns validation status, consultation number, authority used, and company registration details. Optionally accepts a requester VAT number for match-based validation.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: VAT Number Validation API Server
+paths:
+  /vat/validation:
+    get:
+      tags:
+        - Financial APIs
+      summary: Validate EU and UK VAT number
+      description: Validates an EU or UK VAT number and returns registration status details.
+      parameters:
+        - name: format
+          in: query
+          required: false
+          schema:
+            type: string
+            enum:
+              - json
+              - xml
+            default: json
+          description: 'Specify the desired response format. Options: ''json'' (default) or ''xml''.'
+        - name: vatNumber
+          in: query
+          required: true
+          schema:
+            type: string
+          description: EU or UK VAT number to validate.
+        - name: requesterVatNumber
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Requester EU or UK VAT number.
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VatValidationResponse'
+              examples:
+                typicalSuccess:
+                  summary: Validation without a requester VAT number
+                  value:
+                    country_code: GB
+                    vat_number: '289111588'
+                    requested_at: '2026-07-27T11:48:43.000Z'
+                    validation:
+                      is_valid: true
+                      consultation_authority: HMRC
+                    company:
+                      company_name: EVENTURED LTD
+                      company_address: SUITE 10, BEAUFORT COURT, ADMIRALS WAY, LONDON, E14 9XL, GB
+                withRequesterVatNumber:
+                  summary: Validation with a requester VAT number (returns a consultation_number)
+                  value:
+                    country_code: GB
+                    vat_number: '289111588'
+                    requester_country_code: GB
+                    requester_vat_number: '288305674'
+                    requested_at: '2026-07-27T11:48:44.000Z'
+                    validation:
+                      is_valid: true
+                      consultation_number: YCM-VHX-WXF
+                      consultation_authority: HMRC
+                    company:
+                      company_name: EVENTURED LTD
+                      company_address: SUITE 10, BEAUFORT COURT, ADMIRALS WAY, LONDON, E14 9XL, GB
+        '400':
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                MissingVatNumber:
+                  summary: Missing required vatNumber parameter
+                  value:
+                    error: Invalid Param Exception
+                    message: please pass correct parameters
+                    path: /v1.0/vat/validation
+                    status: 400
+                    timestamp: '2026-07-27T11:48:44.845Z'
+                UnsupportedCountry:
+                  summary: Unsupported VAT country code
+                  value:
+                    message: Unsupported VAT country code. Supported prefixes are UK/GB and EU VAT country codes.
+        '404':
+          description: Not Found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                NotFound:
+                  summary: VAT number not found
+                  value:
+                    message: targetVrn does not match a registered company
+      operationId: validateVatNumber
+components:
+  securitySchemes:
+    ApiKeyAuthHeader:
+      type: apiKey
+      in: header
+      name: X-apiKey
+      description: Pass your API key via the X-apiKey request header.
+    ApiKeyAuthQuery:
+      type: apiKey
+      in: query
+      name: apiKey
+      description: Pass your API key via the apiKey query parameter.
+  schemas:
+    VatValidationResponse:
+      type: object
+      properties:
+        country_code:
+          type: string
+          description: VAT country prefix extracted from the validated VAT number (e.g., DE, GB).
+        vat_number:
+          type: string
+          description: VAT number without country prefix.
+        requester_country_code:
+          type: string
+          description: Requester VAT country prefix (present only when requesterVatNumber was provided).
+        requester_vat_number:
+          type: string
+          description: Requester VAT number without country prefix.
+        requested_at:
+          type: string
+          format: date-time
+          description: ISO 8601 timestamp of the validation request.
+        validation:
+          $ref: '#/components/schemas/VatValidationResult'
+        company:
+          $ref: '#/components/schemas/VatValidationCompany'
+      required:
+        - country_code
+        - vat_number
+        - requested_at
+        - validation
+        - company
+      description: VAT number validation response containing registration status and company details.
+    VatValidationResult:
+      type: object
+      description: Validation result block.
+      required:
+        - is_valid
+        - consultation_authority
+      properties:
+        is_valid:
+          type: boolean
+          description: Whether the VAT number is active and registered.
+        consultation_number:
+          type: string
+          description: VIES/HMRC consultation number. Only present when requesterVatNumber is provided.
+        consultation_authority:
+          type: string
+          description: Upstream authority used for validation (VIES for EU, HMRC for UK).
+    VatValidationCompany:
+      type: object
+      description: Company details block.
+      required:
+        - company_name
+        - company_address
+      properties:
+        company_name:
+          type: string
+          description: Company or trader name (may be empty string when unavailable).
+        company_address:
+          type: string
+          description: Formatted company address (may be empty string when unavailable).
+    ErrorResponse:
+      type: object
+      required:
+        - message
+      properties:
+        error:
+          type: string
+          description: Short error category or exception type.
+        message:
+          type: string
+          description: Human-readable error message describing the failure.
+        path:
+          type: string
+          description: API endpoint path that produced the error.
+        status:
+          type: integer
+          description: HTTP status code returned with the error.
+        timestamp:
+          type: string
+          format: date-time
+          description: Timestamp when the error occurred (ISO 8601).
+      description: Standard error envelope returned by the API on failed requests.
+security:
+  - ApiKeyAuthHeader: []
+  - ApiKeyAuthQuery: []

package/dist/specs/financial/vat-rates-by-ip.yaml

@@ -0,0 +1,200 @@
+openapi: 3.1.1
+info:
+  title: VAT Rates by IP API Reference
+  version: 1.0.0
+  description: Get VAT rates for a country resolved from an IP address. Returns standard and reduced VAT rates based on the geographic location of the IP.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: VAT Rates by IP API Server
+paths:
+  /vat/rates/ip-address:
+    get:
+      tags:
+        - Financial APIs
+      summary: Get VAT rate by IP address
+      description: Fetches VAT rate based on the specified or originating IP address.
+      operationId: getVatRatesByIp
+      parameters:
+        - name: format
+          in: query
+          required: false
+          schema:
+            type: string
+            enum:
+              - json
+              - xml
+            default: json
+          description: 'Specify the desired response format. Options: ''json'' (default) or ''xml''.'
+        - name: ipAddress
+          in: query
+          required: false
+          schema:
+            type: string
+          description: IPv4 or IPv6 address to look up VAT rate for. If omitted, the originating IP address will be used.
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VatIpItemArray'
+              examples:
+                typicalSuccess:
+                  summary: Country-level VAT rate
+                  value:
+                    - country: GB
+                      type: vat
+                      currency: GBP
+                      standard_rate: 0.2
+                      reduced_rate:
+                        - 0
+                        - 0.05
+                      categories:
+                        books: 0.2
+                        newspapers: 0.2
+                        periodicals: 0.2
+                        broadcasting: 0.2
+                stateLevel:
+                  summary: IP resolved to a US state with sub-national sales tax
+                  value:
+                    - country: US
+                      state: CA
+                      type: vat
+                      currency: ''
+                      standard_rate: 0.0825
+        '400':
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                InvalidIp:
+                  summary: Invalid IP address format
+                  value:
+                    message: Invalid IP address format. Please provide a valid IPv4 or IPv6 address.
+        '404':
+          description: Not Found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                NotFound:
+                  summary: VAT data not found for IP
+                  value:
+                    message: No VAT data found. Please provide a valid ipAddress.
+components:
+  securitySchemes:
+    ApiKeyAuthHeader:
+      type: apiKey
+      in: header
+      name: X-apiKey
+      description: Pass your API key via the X-apiKey request header.
+    ApiKeyAuthQuery:
+      type: apiKey
+      in: query
+      name: apiKey
+      description: Pass your API key via the apiKey query parameter.
+  schemas:
+    VatIpItemArray:
+      type: array
+      description: Array of VAT rate objects for the country resolved from the IP address.
+      items:
+        $ref: '#/components/schemas/VatIpItem'
+    VatIpItem:
+      type: object
+      required:
+        - country
+        - type
+        - currency
+        - standard_rate
+      description: Each item in the array represents a VAT rate object for the country resolved from the IP.
+      properties:
+        country:
+          type: string
+          description: Country resolved from the IP address.
+        state:
+          type: string
+          description: State or region resolved from the IP address, for countries with sub-national tax rates (e.g. US). Only present when applicable.
+        type:
+          type: string
+          description: Tax type for the resolved country (e.g., vat).
+        currency:
+          type: string
+          description: ISO 4217 currency code for the resolved country.
+        standard_rate:
+          type: number
+          format: float
+          description: Standard VAT rate as a decimal.
+        reduced_rate:
+          type: array
+          items:
+            $ref: '#/components/schemas/VatRateDecimal'
+          description: Reduced VAT rates (EU/UK only).
+        super_reduced_rate:
+          type: array
+          items:
+            $ref: '#/components/schemas/VatRateDecimal'
+          description: Super-reduced VAT rates (EU/UK only).
+        parking_rate:
+          type: number
+          format: float
+          description: Parking rate (EU/UK only).
+        categories:
+          description: Category-specific VAT rates, where defined (EU/UK only). Keys vary by country.
+          $ref: '#/components/schemas/VatCategories'
+    VatRateDecimal:
+      type: number
+      format: float
+      description: A VAT rate expressed as a decimal (e.g., 0.19 = 19%).
+    VatCategories:
+      type: object
+      description: Category-specific VAT rates, where defined (EU/UK only). Keys vary by country.
+      properties:
+        books:
+          type: number
+          format: float
+          description: VAT rate for books, as a decimal (e.g., 0.07 = 7%).
+        newspapers:
+          type: number
+          format: float
+          description: VAT rate for newspapers, as a decimal (e.g., 0.07 = 7%).
+        periodicals:
+          type: number
+          format: float
+          description: VAT rate for periodicals, as a decimal (e.g., 0.07 = 7%).
+        broadcasting:
+          type: number
+          format: float
+          description: VAT rate for broadcasting services, as a decimal (e.g., 0.19 = 19%).
+      required: []
+    ErrorResponse:
+      type: object
+      required:
+        - message
+      properties:
+        error:
+          type: string
+          description: Short error category or exception type.
+        message:
+          type: string
+          description: Human-readable error message describing the failure.
+        path:
+          type: string
+          description: API endpoint path that produced the error.
+        status:
+          type: integer
+          description: HTTP status code returned with the error.
+        timestamp:
+          type: string
+          format: date-time
+          description: Timestamp when the error occurred (ISO 8601).
+      description: Standard error envelope returned by the API on failed requests.
+security:
+  - ApiKeyAuthHeader: []
+  - ApiKeyAuthQuery: []