Contents

frederik-jacques/vatnumberkit

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 :)

  • https://github.com/DragonBe/vies
  • https://gist.github.com/svschannak/e79892f4fbc56df15bdb5496d0e67b85
  • https://github.com/arthurdejong/python-stdnum

License

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

Package Metadata

Repository: frederik-jacques/vatnumberkit

Default branch: main

README: README.md