VatNumberKit

2.0.0

Star
VatNumberKit - A Swift VAT validation library for iOS & macOS
ios library macos swift validation
frederik-jacques/vatnumberkit

What's New

Version 2.0.0

2023-02-07T21:06:57Z

Added offline checksum validation

VatNumberKit Logo

VatNumberKit is a Swift library to check and validate VAT numbers (checksum based & online government services) on both iOS and macOS.

Contents

Requirements

  • iOS 14.0+ / macOS 12+
  • Xcode 11.0+
  • Swift 5.0+

Communication

  • If you found a bug, open an issue.
  • If you have a feature request, open an issue.
  • If you want to contribute, submit a pull request.

Installation

Swift Package Manager

Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system to automate the process of downloading, compiling, and linking dependencies.

Xcode 11+ is required to build VatNumberKit using Swift Package Manager.

To integrate VatNumberKit into your Xcode project using Swift Package Manager, add it to the dependencies value of your Package.swift:

dependencies: [
    .package(url: "https://github.com/frederik-jacques/vatnumberkit.git", .upToNextMajor(from: "0.1.0"))
]

Manually

If you prefer not to use Swift Package Manager, you can integrate VatNumberKit into your project manually.

Usage

Validate the VAT number format

Use the static method VatNumberKit.validateFormat(vatNumber:) to check if the VAT number format (based on regexes) is valid.

The result of this call returns a VatNumberKit.ValidationOutput object which has the following properties.

  • rawVatNumber: The original VAT number
  • vatNumber: A VatNumber object (country & number seperated)
  • isValid: Is the format valid

Example

import VatNumberKit

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        
        if let validationOutput = VatNumberKit.validateFormat(vatNumber: "BE0651634023"), validationOutput.isValid {
            print("The VAT number has a valid format")
        }
        
    }
}

Validate the VAT checksum

Use the static method VatNumberKit.validateChecksum(rawVatNumber:) to check if the checksum for the given VAT number is valid.

The result of this call returns a Boolean, indicating if the checksum is correct.

Example

import VatNumberKit

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        
        if VatNumberKit.validateChecksum(rawVatNumber: "BE0651634023"){
            print("The VAT number has a valid checksum")
        }
        
    }
}

Online VAT number validation

VatNumberKit also allows you to validate a VAT number against 2 online services.

  • European VAT numbers: Uses the VIES API of the European Union
  • Great Britain VAT numbers: Uses the API of the UK Gov

Use the static method VatNumberKit.validateOnline(vatNumber:completionHandler:) to use the online validation.

VatNumberKit will automatically select the correct service, based on the country code.

Example

VatNumberKit.validateOnline(vatNumber: "GB835145337") { result in
    switch result {
    case .success(let validation):
        if validation.isValid {
            // Retrieve the meta data for this VAT number (name & address)
            // Metadata is not always available.
            if let metaData = validation.metaData {
                print("§§ Name - \(metaData.name)")
                print("§§ Address - \(metaData.address)")
            }
        }
        else {
            print("§§ VAT number is not valid")
        }
        
    case .failure(let error):
        print("Error validating number")
        if let validationError = error as? VatNumberKit.ValidationServiceError {
            switch validationError {
            case .invalidUrl:
                print("The request url was not valid")
                
            case .invalidJsonResponse:
                print("The json returned from the service is invalid")
                
            case .invalidUrlResponse:
                print("The response returned from the service is invalid")
                
            case .validationServiceDown:
                print("The validation services is down")
                
            case .vatNumberHasIncorrectNumberOfDigits:
                print("The supplied VAT number has an incorrect number of digits (UK service only)")
                
            case .vatNumberDoesNotMatchRegisteredCompany:
                print("The supplied VAT number does not match a registered company (UK service only)")                        
            }
        }
        else {
            // Regular error
        }
    }

Search VAT numbers within a string

Use the static method VatNumberKit.searchVatNumbersInText(:applyChecksumValidation:) to find VAT numbers in a text.

This method returns a Set of VatNumberKit.ValidationOutput structs.

Example

import VatNumberKit

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        
        let validationObjects = VatNumberKit.searchVatNumbersInText(text: "This is a VAT number that is BE0651634023 somewhere in the text. \n Apple's Belgian VAT number is BE0842936235")
        // Will contain 2 VatNumberKit.ValidationOutput structs.
        
    }
}

Supported Countries

Country Offline format validation (regex) Offline checksum validation Online validation
Austria ✅ ✅ ✅
Belgium ✅ ✅ ✅
Bulgaria ✅ ✅ ✅
Croatia ✅ ✅ ✅
Cyprus ✅ ✅ ✅
Czech Republic ✅ ✅ ✅
Denmark ✅ ✅ ✅
Estonia ✅ ✅ ✅
European Entity ✅ ✅ ✅
Finland ✅ ✅ ✅
France ✅ ✅ ✅
Germany ✅ ✅ ✅
Great Britain ✅ ✅ ✅
Greece ✅ ✅ ✅
Hungary ✅ ✅ ✅
Ireland ✅ ✅ ✅
Italy ✅ ✅ ✅
Latvia ✅ ✅ ✅
Lithuania ✅ ✅ ✅
Luxembourg ✅ ✅ ✅
Malta ✅ ✅ ✅
The Netherlands ✅ ✅ ✅
Northern Ireland ✅ ✅ ✅
Poland ✅ ✅ ✅
Portugal ✅ ✅ ✅
Romania ✅ ✅ ✅
Slovakia ✅ ✅ ✅
Slovenia ✅ ✅ ✅
Spain ✅ ✅ ✅
Sweden ✅ ✅ ✅

Feel free to open a PR to add other countries!

Credits

Sources used to find more information about the checksums, as every country seems to have forgotten to document how it is being calculated :)

License

VatNumberKit is released under the MIT license. See LICENSE for details.

Description

  • Swift Tools 5.7.0
View More Packages from this Author

Dependencies

  • None
Last updated: Sat Dec 21 2024 15:06:12 GMT-1000 (Hawaii-Aleutian Standard Time)