@apifreaks/openapi-specs 0.1.0 → 0.1.1

package/dist/specs/financial/financial-apis-supported-countries.yaml

@@ -0,0 +1,152 @@
+openapi: 3.1.1
+info:
+  title: Financial APIs Supported Countries Reference
+  version: 1.0.0
+  description: Retrieve the countries and states supported by the VAT, IBAN, and SWIFT APIs. The response always includes all three categories — VAT_Supported_Countries_And_States, IBAN_Supported_Countries, and SWIFT_Supported_Countries — each with a different shape. VAT entries are keyed by lowercase country name and include an ISO code plus, for a handful of countries (US, Canada, Spain), a nested map of sub-national state/region codes. IBAN and SWIFT entries are flat arrays of {name, countryCode} objects.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: Financial APIs Supported Countries API Server
+paths:
+  /vat/supported-countries:
+    get:
+      tags:
+        - Financial APIs
+      summary: Get supported countries
+      description: Returns the countries and states supported by the VAT, IBAN, and SWIFT APIs.
+      operationId: getSupportedCountries
+      parameters:
+        - name: format
+          in: query
+          required: false
+          schema:
+            type: string
+            enum:
+              - json
+              - xml
+            default: json
+          description: Format of the response. Default is JSON.
+        - name: type
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Accepted by the endpoint but currently has no effect — all three categories (VAT, IBAN, SWIFT) are always returned regardless of this value.
+      responses:
+        '200':
+          description: Successful response — always returns all three categories
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SupportedCountriesResponse'
+              examples:
+                typicalSuccess:
+                  summary: Typical successful response (truncated)
+                  value:
+                    VAT_Supported_Countries_And_States:
+                      - germany:
+                          code: de
+                      - united_states:
+                          code: us
+                          states:
+                            california: us:ca
+                            new_york: us:ny
+                            texas: us:tx
+                    IBAN_Supported_Countries:
+                      - countryCode: DE
+                        name: Germany
+                      - countryCode: GB
+                        name: United Kingdom
+                    SWIFT_Supported_Countries:
+                      - name: Germany
+                        countryCode: DE
+                      - name: United States
+                        countryCode: US
+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:
+    SupportedCountriesResponse:
+      type: object
+      description: Countries and states supported by the VAT, IBAN, and SWIFT APIs.
+      required:
+        - VAT_Supported_Countries_And_States
+        - IBAN_Supported_Countries
+        - SWIFT_Supported_Countries
+      properties:
+        VAT_Supported_Countries_And_States:
+          type: array
+          description: Array of single-key objects, one per supported VAT country. Each key is the lowercase, underscore-separated country name.
+          items:
+            type: object
+            description: A single VAT-supported country, keyed by its lowercase name.
+            additionalProperties:
+              title: VatCountryEntry
+              $ref: '#/components/schemas/VatCountryEntry'
+        IBAN_Supported_Countries:
+          type: array
+          description: Array of countries supported by the IBAN Validation API.
+          items:
+            $ref: '#/components/schemas/IbanCountryEntry'
+        SWIFT_Supported_Countries:
+          type: array
+          description: Array of countries supported by the SWIFT/BIC Code Lookup and Finder APIs.
+          items:
+            $ref: '#/components/schemas/SwiftCountryEntry'
+    VatCountryEntry:
+      type: object
+      description: 'VAT country metadata: an ISO 3166-1 alpha-2 code, plus an optional map of sub-national states/regions for countries with state-level VAT (US, Canada, Spain).'
+      required:
+        - code
+      properties:
+        code:
+          type: string
+          description: ISO 3166-1 alpha-2 country code, lowercase.
+        states:
+          type: object
+          description: Map of state/region name to its combined country:state code. Only present for countries with sub-national VAT rates.
+          additionalProperties:
+            title: StateCode
+            type: string
+            description: Combined country:state identifier (e.g. us:ca).
+    IbanCountryEntry:
+      type: object
+      description: A single country supported by the IBAN Validation API.
+      required:
+        - countryCode
+        - name
+      properties:
+        countryCode:
+          type: string
+          description: ISO 3166-1 alpha-2 country code.
+        name:
+          type: string
+          description: Full country name.
+    SwiftCountryEntry:
+      type: object
+      description: A single country supported by the SWIFT/BIC Code Lookup and Finder APIs.
+      required:
+        - name
+        - countryCode
+      properties:
+        name:
+          type: string
+          description: Full country name.
+        countryCode:
+          type: string
+          description: ISO 3166-1 alpha-2 country code.
+security:
+  - ApiKeyAuthHeader: []
+  - ApiKeyAuthQuery: []

package/dist/specs/financial/iban-validation.yaml

@@ -0,0 +1,270 @@
+openapi: 3.1.1
+info:
+  title: IBAN Validation API - Validate Format, Check SEPA & Return Bank Details
+  version: 1.0.0
+  description: Validate an IBAN number against country-specific format, length, and checksum rules. Supports IBANs from all SEPA and IBAN-compliant countries. Returns detailed validation results for each check — alphanumeric, supported country, length, structure, and check digit. Includes bank data such as BIC/SWIFT code, bank name, branch details, and SEPA eligibility when available.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: IBAN Validation API Server
+paths:
+  /iban/validation:
+    get:
+      tags:
+        - Financial APIs
+      summary: Validate IBAN
+      description: Checks an IBAN for structural validity, checksum accuracy, and bank metadata.
+      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: iban
+          in: query
+          required: true
+          schema:
+            type: string
+          description: IBAN to validate.
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IbanValidationResponse'
+              examples:
+                validIban:
+                  summary: Valid IBAN with full bank data
+                  value:
+                    valid: true
+                    iban: GB29NWBK60161331926819
+                    validation:
+                      is_alpha_numeric: true
+                      is_iban_supported_country: true
+                      is_valid_length: true
+                      is_valid_structure: true
+                      is_iban_check_digit_valid: true
+                      bban: valid
+                    bank_data:
+                      bic: NWBKGB2LBHM
+                      bank: NATIONAL WESTMINSTER BANK PLC
+                      bank_code: NWBK
+                      branch_code: '601613'
+                      country: United Kingdom
+                      country_iso2: GB
+                      city: BIRMINGHAM
+                      address: 6 BRINDLEY PLACE - BIRMINGHAM, B1
+                      account: '31926819'
+                      sepa: true
+                invalidIban:
+                  summary: Structurally invalid IBAN — still a 200, not an error, with the failing checks flagged
+                  value:
+                    valid: false
+                    iban: NOTANIBAN123
+                    validation:
+                      is_alpha_numeric: true
+                      is_iban_supported_country: true
+                      is_valid_length: false
+                      is_valid_structure: false
+                      is_iban_check_digit_valid: false
+                      bban: unknown
+                    bank_data:
+                      bic: null
+                      bank: null
+                      bank_code: null
+                      branch_code: ''
+                      country: Norway
+                      country_iso2: 'NO'
+                      city: null
+                      address: null
+                      account: N123
+                      sepa: true
+                unsupportedCountry:
+                  summary: Country prefix not covered by IBAN — bank_data fields are null
+                  value:
+                    valid: false
+                    iban: US29NWBK60161331926819
+                    validation:
+                      is_alpha_numeric: true
+                      is_iban_supported_country: false
+                      is_valid_length: false
+                      is_valid_structure: false
+                      is_iban_check_digit_valid: false
+                      bban: unknown
+                    bank_data:
+                      bic: null
+                      bank: null
+                      bank_code: null
+                      branch_code: ''
+                      country: null
+                      country_iso2: US
+                      city: null
+                      address: null
+                      account: null
+                      sepa: null
+        '400':
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                MissingIban:
+                  summary: Missing required iban parameter
+                  value:
+                    error: Invalid Param Exception
+                    message: please pass correct parameters
+                    path: /v1.0/iban/validation
+                    status: 400
+                    timestamp: '2026-07-27T11:49:29.286Z'
+      operationId: validateIban
+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:
+    IbanValidationResponse:
+      type: object
+      properties:
+        valid:
+          type: boolean
+          description: True if the IBAN passes all validation checks.
+        iban:
+          type: string
+          description: The IBAN number provided in the request.
+        validation:
+          $ref: '#/components/schemas/IbanValidationResult'
+        bank_data:
+          $ref: '#/components/schemas/IbanBankData'
+      required:
+        - valid
+        - iban
+        - validation
+        - bank_data
+      description: IBAN validation response containing validation results and bank data.
+    IbanValidationResult:
+      type: object
+      description: Object contains IBAN validation details.
+      required:
+        - is_alpha_numeric
+        - is_iban_supported_country
+        - is_valid_length
+        - is_valid_structure
+        - is_iban_check_digit_valid
+      properties:
+        is_alpha_numeric:
+          type: boolean
+          description: Whether the IBAN contains only alphanumeric characters.
+        is_iban_supported_country:
+          type: boolean
+          description: Whether the country extracted from the IBAN supports IBAN standards.
+        is_valid_length:
+          type: boolean
+          description: Whether the IBAN length matches the expected length for its country.
+        is_valid_structure:
+          type: boolean
+          description: Whether the IBAN structure matches the pattern for its country.
+        is_iban_check_digit_valid:
+          type: boolean
+          description: Whether the IBAN check digit is valid.
+        bban:
+          type: string
+          enum:
+            - valid
+            - invalid
+            - unknown
+          description: BBAN checksum status. "unknown" means BBAN checksum validation isn't supported for this country.
+    IbanBankData:
+      type: object
+      description: Object contains Bank and BIC details. Most fields are null when the IBAN is structurally invalid or the country's bank data isn't resolvable.
+      required:
+        - country_iso2
+      properties:
+        bic:
+          type:
+            - string
+            - 'null'
+          description: SWIFT/BIC code extracted from the IBAN. Null when not available for this country or IBAN.
+        bank:
+          type:
+            - string
+            - 'null'
+          description: Bank name extracted from the IBAN. Null when not resolvable.
+        bank_code:
+          type:
+            - string
+            - 'null'
+          description: Bank code extracted from the IBAN. Null when not resolvable.
+        branch_code:
+          type: string
+          description: Branch code extracted from the IBAN. Can be an empty string when not available.
+        country:
+          type:
+            - string
+            - 'null'
+          description: Country name extracted from the IBAN. Null when the country prefix isn't a supported IBAN country.
+        country_iso2:
+          type: string
+          description: ISO 3166-1 alpha-2 country code extracted from the IBAN's prefix.
+        city:
+          type:
+            - string
+            - 'null'
+          description: City or branch name for the bank. Null when not resolvable.
+        address:
+          type:
+            - string
+            - 'null'
+          description: Bank branch address. Null when not resolvable.
+        account:
+          type:
+            - string
+            - 'null'
+          description: Account number extracted from the IBAN. Null when the country prefix isn't a supported IBAN country.
+        sepa:
+          type:
+            - boolean
+            - 'null'
+          description: Whether the country supports Single Euro Payments Area (SEPA). Null when the country prefix isn't a supported IBAN country.
+    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/swift-code-finder.yaml

@@ -0,0 +1,146 @@
+openapi: 3.1.1
+info:
+  title: SWIFT/BIC Code Finder API Reference
+  version: 1.0.0
+  description: Progressively drill down from all supported countries to a specific bank's SWIFT/BIC codes. With no parameters, returns the list of all supported countries. Adding country returns the list of bank names in that country. Adding bank returns the list of cities that bank operates in. Adding city as well returns the matching SWIFT/BIC codes. Parameters must be supplied in order (country, then bank, then city) — supplying bank without country, for example, returns a 400. An unmatched country/bank/city combination returns a 200 with an empty array, not an error.
+  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 Finder API Server
+paths:
+  /swift-code/finder:
+    get:
+      tags:
+        - Financial APIs
+      summary: Find SWIFT codes
+      description: Drills down from countries to banks to cities to SWIFT/BIC codes, one parameter level at a time.
+      operationId: findSwiftCode
+      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: country
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Country name (accepts full name, e.g., Pakistan, United States). If supplied alone, returns the list of bank names in that country. If omitted entirely, returns the list of all supported countries.
+        - name: bank
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Bank name (upper case) to drill into. Requires country to also be set. If supplied without city, returns the list of cities that bank operates in.
+        - name: city
+          in: query
+          required: false
+          schema:
+            type: string
+          description: City (upper case) to narrow results to. Requires country and bank to also be set. Returns the matching SWIFT/BIC codes for that bank in that city.
+      responses:
+        '200':
+          description: Successful response. The array's contents depend on which parameters were supplied — see the examples for each drill-down level.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SwiftCodeFinderResponse'
+              examples:
+                allCountries:
+                  summary: No parameters — all supported countries
+                  value:
+                    - Albania
+                    - Algeria
+                    - Andorra
+                    - Germany
+                    - United States
+                banksInCountry:
+                  summary: country only — bank names in that country
+                  value:
+                    - 1NCE GMBH
+                    - AAREAL BANK AG
+                    - DEUTSCHE BANK AG
+                citiesForBank:
+                  summary: country + bank — cities that bank operates in
+                  value:
+                    - AACHEN
+                    - BERLIN
+                    - FRANKFURT AM MAIN
+                    - MUENCHEN
+                swiftCodes:
+                  summary: country + bank + city — matching SWIFT/BIC codes
+                  value:
+                    - DEUTDEBB101
+                    - DEUTDEBB162
+                    - DEUTDEBB165
+                    - DEUTDEBBXXX
+                    - DEUTDEDB101
+                noMatch:
+                  summary: Unmatched country/bank/city — empty array, not an error
+                  value: []
+        '400':
+          description: Bad Request — Parameters supplied out of order
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                OutOfOrder:
+                  summary: bank supplied without country
+                  value:
+                    message: 'Invalid query parameters. Provide parameters in sequence: country → bank → city'
+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:
+    SwiftCodeFinderResponse:
+      type: array
+      description: 'Array of strings whose meaning depends on the supplied parameters: country names, bank names, city names, or SWIFT/BIC codes.'
+      items:
+        $ref: '#/components/schemas/SwiftCodeString'
+    SwiftCodeString:
+      type: string
+      description: A single result value — a country name, bank name, city name, or SWIFT/BIC code depending on the drill-down level.
+    ErrorResponse:
+      type: object
+      description: Standard error envelope returned by the API on failed requests.
+      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).
+security:
+  - ApiKeyAuthHeader: []
+  - ApiKeyAuthQuery: []