evatr

README

go-evatr

Go client library for the eVatR API (German VAT ID validation system) of the BZSt.

Features

• Simple and qualified VAT ID validation
• EU member state information and VIES availability
• Type-safe error handling with status codes
• Context-aware API calls

Installation

go get github.com/hostwithquantum/go-evatr

Documentation

• API Reference - Full API documentation
• Examples - Working code examples
• Error codes - All status codes and their meanings

Optional Configuration

httpClient := &http.Client{
    Timeout: 30 * time.Second,
    Transport: customTransport,
}

client := evatr.NewClient(
    evatr.WithBaseURL("https://custom.api.url"),
    evatr.WithTimeout(60 * time.Second),
    evatr.WithHTTPClient(httpClient),
)

Usage

The API advertises a daily maintenance window from 23:00 - 5:00 (local). Run potential jobs during the workday to avoid issues — see our dependabot and workflow configuration for examples.

License

mpl-2.0

Links

• eVatR API Documentation
• BZSt (Federal Central Tax Office)
• VIES VAT Validation

Documentation

Index

• Constants
• func IsEvatrErr(err error) bool
• func NewDebugTransport(transport http.RoundTripper) http.RoundTripper
• type Client
  • func NewClient(opts ...Option) *Client
  • func (c *Client) GetEUMemberStates(ctx context.Context) ([]EUMemberState, error)
  • func (c *Client) GetStatusMessages(ctx context.Context) ([]StatusMessage, error)
  • func (c *Client) ValidateVAT(ctx context.Context, requestingVATID, requestedVATID string) (*ValidationResponse, error)
  • func (c *Client) ValidateVATQualified(ctx context.Context, ...) (*ValidationResponse, error)
  • func (c *Client) ValidateVATWithRequest(ctx context.Context, req *ValidationRequest) (*ValidationResponse, error)
• type EUMemberState
• type Error
  • func NewBadRequestError(status, message string) *Error
  • func NewForbiddenError(status, message string) *Error
  • func NewInternalServerError(status, message string) *Error
  • func NewNotFoundError(status, message string) *Error
  • func NewServiceUnavailableError(status, message string) *Error
  • func (e *Error) Error() string
• type ErrorResponse
• type Option
  • func WithBaseURL(baseURL string) Option
  • func WithHTTPClient(httpClient *http.Client) Option
  • func WithTimeout(timeout time.Duration) Option
• type StatusMessage
• type ValidationRequest
• type ValidationResponse
  • func (v *ValidationResponse) GetRequestTimestamp() (time.Time, error)
  • func (v *ValidationResponse) GetValidFrom() (time.Time, error)
  • func (v *ValidationResponse) GetValidUntil() (time.Time, error)
  • func (v *ValidationResponse) IsValid() bool
• type VerificationResult

Constants

const (
	// Default API endpoint for the eVatR service
	DefaultBaseURL = "https://api.evatr.vies.bzst.de/app"

	// Default HTTP client timeout
	DefaultTimeout = 30 * time.Second
)

const (
	StatusMissingRequiredField        = "evatr-0002" // At least one required field is missing
	StatusInvalidRequestingVATID      = "evatr-0004" // Requesting DE VAT ID is syntactically incorrect
	StatusInvalidRequestedVATID       = "evatr-0005" // Requested VAT ID is syntactically incorrect
	StatusMaxQualifiedRequestsReached = "evatr-0008" // Maximum qualified requests for session reached
	StatusInvalidVATIDFormat          = "evatr-0012" // Requested VAT ID doesn't match format
	StatusInvalidCountryCode          = "evatr-2003" // Country code is not valid
)

Bad Request (400) errors

const (
	StatusNotAuthorizedDE = "evatr-0006" // Requesting DE VAT ID not authorized to query DE VAT IDs
	StatusInvalidCall     = "evatr-0007" // Invalid call
)

Forbidden (403) errors

const (
	StatusVATIDNotAssigned        = "evatr-2001" // VAT ID not assigned at request time
	StatusRequestingVATIDNotValid = "evatr-2005" // Requesting DE VAT ID not valid at request time
)

Not Found (404) errors

const (
	StatusValid                = "evatr-0000" // VAT ID is valid at request time
	StatusNotYetValid          = "evatr-2002" // VAT ID not yet valid, see gueltigAb
	StatusNoLongerValid        = "evatr-2006" // VAT ID no longer valid, see gueltigAb and gueltigBis
	StatusValidWithSpecialCase = "evatr-2008" // VAT ID valid but special case, contact BZSt
)

Success (200) with special meanings

const (
	StatusProcessingError1 = "evatr-2004" // Processing temporarily not possible
	StatusProcessingError2 = "evatr-2011" // Processing temporarily not possible
	StatusProcessingError3 = "evatr-3011" // Processing temporarily not possible
)

Internal Server Error (500) errors

const (
	StatusServiceUnavailable1 = "evatr-0011" // Service temporarily unavailable
	StatusServiceUnavailable2 = "evatr-1001" // Service temporarily unavailable
	StatusServiceUnavailable3 = "evatr-1002" // Service temporarily unavailable
	StatusServiceUnavailable4 = "evatr-1003" // Service temporarily unavailable
	StatusServiceUnavailable5 = "evatr-1004" // Service temporarily unavailable
)

Service Unavailable (503) errors

Functions

func IsEvatrErr

func IsEvatrErr(err error) bool

IsEvatrErr returns whether the error is an eVATR error.

func NewDebugTransport

func NewDebugTransport(transport http.RoundTripper) http.RoundTripper

NewDebugTransport returns a transport that logs all requests and responses.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the eVATR API client.

func NewClient

func NewClient(opts ...Option) *Client

NewClient returns a new eVATR API client.

func (*Client) GetEUMemberStates

func (c *Client) GetEUMemberStates(ctx context.Context) ([]EUMemberState, error)

GetEUMemberStates returns EU member states and their VIES availability.

func (*Client) GetStatusMessages

func (c *Client) GetStatusMessages(ctx context.Context) ([]StatusMessage, error)

GetStatusMessages returns all status message descriptions.

func (*Client) ValidateVAT

func (c *Client) ValidateVAT(ctx context.Context, requestingVATID, requestedVATID string) (*ValidationResponse, error)

ValidateVAT validates a VAT ID without company data verification.

func (*Client) ValidateVATQualified

func (c *Client) ValidateVATQualified(ctx context.Context, requestingVATID, requestedVATID, companyName, city, street, postalCode string) (*ValidationResponse, error)

ValidateVATQualified validates a VAT ID with company data verification. Compares provided company information with registered data.

func (*Client) ValidateVATWithRequest

func (c *Client) ValidateVATWithRequest(ctx context.Context, req *ValidationRequest) (*ValidationResponse, error)

ValidateVATWithRequest validates a VAT ID with a custom request.

type EUMemberState

type EUMemberState struct {
	// Two-letter country code
	Alpha2 string `json:"alpha2"`

	// Country name
	Name string `json:"name"`

	// Whether VIES system is available for this country
	Available bool `json:"verfuegbar"`
}

EUMemberState represents an EU member state and its VIES availability.

type Error

type Error struct {
	// HTTP status code
	StatusCode int

	// eVATR status code (e.g., "evatr-0002")
	Status string

	// Human-readable error message
	Message string
}

Error represents an eVATR API error.

func NewBadRequestError

func NewBadRequestError(status, message string) *Error

NewBadRequestError returns a 400 Bad Request error.

func NewForbiddenError

func NewForbiddenError(status, message string) *Error

NewForbiddenError returns a 403 Forbidden error.

func NewInternalServerError

func NewInternalServerError(status, message string) *Error

NewInternalServerError returns a 500 Internal Server Error.

func NewNotFoundError

func NewNotFoundError(status, message string) *Error

NewNotFoundError returns a 404 Not Found error.

func NewServiceUnavailableError

func NewServiceUnavailableError(status, message string) *Error

NewServiceUnavailableError returns a 503 Service Unavailable error.

func (*Error) Error

func (e *Error) Error() string

type ErrorResponse

type ErrorResponse struct {
	// eVATR status code (e.g., "evatr-0002")
	Status string `json:"status"`

	// Error message in German
	Message string `json:"meldung"`
}

ErrorResponse represents the JSON error response from the API.

type Option

type Option func(*Client)

Option is a functional option for configuring the Client.

func WithBaseURL

func WithBaseURL(baseURL string) Option

WithBaseURL sets the base URL for the API.

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient sets the HTTP client.

func WithTimeout

func WithTimeout(timeout time.Duration) Option

WithTimeout sets the timeout for HTTP requests.

type StatusMessage

type StatusMessage struct {
	// Status code (e.g., "evatr-0000")
	Status string `json:"status"`

	// Category of the status
	Category string `json:"kategorie"`

	// Associated HTTP status code
	HTTPCode int `json:"httpcode"`

	// Field related to the status (if applicable)
	Field string `json:"feld,omitempty"`

	// Human-readable message
	Message string `json:"meldung"`
}

StatusMessage represents a status message for an error code.

type ValidationRequest

type ValidationRequest struct {
	// Requesting German VAT ID (required)
	RequestingVATID string `json:"anfragendeUstid"`

	// VAT ID to validate (required)
	RequestedVATID string `json:"angefragteUstid"`

	// Company name (optional, required for qualified validation)
	CompanyName string `json:"firmenname,omitempty"`

	// Street address (optional)
	Street string `json:"strasse,omitempty"`

	// Postal code (optional)
	PostalCode string `json:"plz,omitempty"`

	// City (optional, required for qualified validation)
	City string `json:"ort,omitempty"`
}

ValidationRequest represents a VAT ID validation request.

type ValidationResponse

type ValidationResponse struct {
	// Technical ID for the validation request
	ID string `json:"id,omitempty"`

	// Timestamp of the request
	RequestTimestamp string `json:"anfrageZeitpunkt"`

	// Date from when the VAT ID is/was valid
	ValidFrom string `json:"gueltigAb,omitempty"`

	// Date until when the VAT ID was valid
	ValidUntil string `json:"gueltigBis,omitempty"`

	// Status code (e.g., "evatr-0000" for valid)
	Status string `json:"status"`

	// Company name verification result (A/B/C/D)
	CompanyNameResult VerificationResult `json:"ergFirmenname,omitempty"`

	// Street verification result (A/B/C/D)
	StreetResult VerificationResult `json:"ergStrasse,omitempty"`

	// Postal code verification result (A/B/C/D)
	PostalCodeResult VerificationResult `json:"ergPlz,omitempty"`

	// City verification result (A/B/C/D)
	CityResult VerificationResult `json:"ergOrt,omitempty"`
}

ValidationResponse represents a VAT ID validation response.

func (*ValidationResponse) GetRequestTimestamp

func (v *ValidationResponse) GetRequestTimestamp() (time.Time, error)

GetRequestTimestamp parses the request timestamp.

func (*ValidationResponse) GetValidFrom

func (v *ValidationResponse) GetValidFrom() (time.Time, error)

GetValidFrom parses the valid-from date if present.

func (*ValidationResponse) GetValidUntil

func (v *ValidationResponse) GetValidUntil() (time.Time, error)

GetValidUntil parses the valid-until date if present.

func (*ValidationResponse) IsValid

func (v *ValidationResponse) IsValid() bool

IsValid returns whether the VAT ID is currently valid.

type VerificationResult

type VerificationResult string

VerificationResult represents the result of a qualified validation field comparison.

const (
	// Data matches the registered data
	VerificationMatch VerificationResult = "A"

	// Data does not match
	VerificationMismatch VerificationResult = "B"

	// Data was not requested
	VerificationNotRequested VerificationResult = "C"

	// Member state did not provide the data
	VerificationNotProvided VerificationResult = "D"
)