VAT Validation API Documentation

Overview

This API provides two main endpoints:

1. VIES Status Check - Validates a VAT number against the European Commission VIES service (no calculations)
2. VAT Calculation - Validates a VAT number (if provided) and calculates VAT amounts based on the given input

Both endpoints use the VIES service to validate VAT numbers. The system includes automatic caching (5-day cache) to improve performance and reduce API calls.

API hosts: Production https://valora.spotahome.com/ (sandbox compatible); Staging / testing https://valora-testing.laravel.cloud/ (sandbox compatible). Examples below use the production host; the same paths work on the staging host.

Authentication

Endpoints

1. VIES Status Check

URL: GET https://valora.spotahome.com/api/v1/open/vat-vies/status Method: GET

Headers Required:

• Accept: application/json

Query Parameters:

Example Request:

GET https://valora.spotahome.com/api/v1/open/vat-vies/status?vat_number=12345678&vat_country=FR&client_country=ES

Note: If a POST request is sent to this endpoint, it will return a 400 Bad Request with the message: "POST method not supported for calculations. Perhaps you meant to use GET"

2. VAT Calculation

URL: https://valora.spotahome.com/api/v1/open/vat-vies/calculate Methods:

• GET → Connection check (no parameters allowed)
• POST → VAT validation and calculation (requires parameters)

Headers Required:

• Accept: application/json

Request Parameters

POST https://valora.spotahome.com/api/v1/open/vat-vies/calculate

You must send parameters in a POST request. They can be included as query string parameters or as a JSON body (recommended).

Connection Check (GET https://valora.spotahome.com/api/v1/open/vat-vies/calculate)

If no parameters are sent, the endpoint responds with the expected payload structure:

{
  "message": "You are connected!",
  "expected_payload": {
    "vat_amount": "integer, required (in cents, e.g., 2999 for €29.99)",
    "vat_rate": "integer, required (percentage, e.g., 21 for 21%)",
    "client_country": "string, required (2-letter ISO code)",
    "vat_number": "string, nullable",
    "vat_country": "string, nullable (2-letter ISO code)"
  }
}

If parameters are sent via GET, the endpoint responds with a 400 Bad Request:

{
  "error": true,
  "message": "GET method not supported for calculations. Perhaps you meant to use POST"
}

Responses

VIES Status Check - Success (200)

{
  "success": true,
  "vat_validation": {
    "is_valid": true,
    "checked": true,
    "skipped": false,
    "server_down": false,
    "vat_number": "12345678",
    "vat_country": "FR",
    "client_country": "ES",
    "trader_name": "Example Company Ltd",
    "trader_address": "123 Street, City, Country"
  }
}

Note: The vat_number and vat_country in the response represent the validated/parsed values used for the VIES check. If the input VAT number included a country prefix (e.g., "DE12345678"), the system will automatically parse it and return the cleaned number ("12345678") and extracted country code ("DE") in the response, regardless of the vat_country parameter provided.

VAT Calculation - Success (200)

{
  "success": true,
  "vat_validation": {
    "is_valid": true,
    "checked": true,
    "skipped": false,
    "vat_number": "12345678",
    "vat_country": "FR",
    "client_country": "ES"
  },
  "amounts": {
    "net": 2999,
    "gross": 2999,
    "vat_applied": 0,
    "vat_rate_applied": 0
  }
}

Notes:

• When a valid intra-community VAT number is validated, vat_rate_applied will be 0 (VAT exemption applies).
• The vat_number and vat_country in the response represent the validated/parsed values used for the VIES check. If the input VAT number included a country prefix, the system will automatically parse it and return the cleaned values.

Validation Error (422)

{
  "error": true,
  "message": "Validation failed",
  "errors": {
    "vat_amount": ["The vat_amount field is required."],
    "vat_rate": ["The vat_rate field must be between 0 and 100."]
  }
}

VIES Unavailable (503)

{
  "error": true,
  "message": "VIES service is temporarily unavailable. Please try again later."
}

Unexpected Error (500)

{
  "error": true,
  "message": "An unexpected error occurred while processing your request."
}

GET with Parameters (400) - Calculate Endpoint

{
  "error": true,
  "message": "GET method not supported for calculations. Perhaps you meant to use POST"
}

POST to Status Endpoint (400)

{
  "error": true,
  "message": "POST method not supported for calculations. Perhaps you meant to use GET"
}

POST with Missing Parameters (422)

{
  "error": true,
  "message": "Please provide valid parameters.",
  "expected_payload": {
    "vat_amount": "integer, required (in cents, e.g., 2999 for €29.99)",
    "vat_rate": "integer, required (percentage, e.g., 21 for 21%)",
    "client_country": "string, required (2-letter ISO code)",
    "vat_number": "string, nullable",
    "vat_country": "string, nullable (2-letter ISO code)"
  }
}

Important Notes

General

• VAT amounts are expected in cents for precision.
• VAT rates must be between 0 and 100.
• All country codes must be 2-letter ISO codes (e.g., ES, FR, DE).

VIES Validation

• VIES checks are only performed if both vat_number and vat_country are provided (or if vat_number includes a country prefix).
• VAT Number Parsing: The system automatically parses VAT numbers. If a VAT number includes a country prefix (e.g., "DE12345678"), the prefix is extracted and used as the country code, and the remaining digits are used as the VAT number. If no prefix is found, the provided vat_country parameter is used.
• Same-country restriction: If the validated vat_country (after parsing) matches client_country, validation will be skipped (intra-community VAT validation only works between different countries).
• The system uses automatic caching (5-day cache) to improve performance and reduce API calls to the VIES service.
• If the VAT number is validated successfully and is from a different EU country, the intra-community VAT exemption applies, setting VAT to 0%.
• Response Values: The vat_number and vat_country fields in the response always reflect the validated/parsed values that were actually used for the VIES check, not necessarily the input values.

Endpoint Usage

• Use GET https://valora.spotahome.com/api/v1/open/vat-vies/status for VAT validation only (no calculations).
• Use POST https://valora.spotahome.com/api/v1/open/vat-vies/calculate for VAT calculations with optional validation.
• Use GET https://valora.spotahome.com/api/v1/open/vat-vies/calculate (no parameters) to check connection and see expected payload.

© Valora API Documentation