# VIESAC Platform Architecture & Complete Technical Specification (llms-full.txt)

## 1. Executive Summary & Legal Framework

VIESAC (https://viesac.eu) is an enterprise cloud platform and automated REST API providing European Union VAT compliance, customs EORI validation, automated company identity enrichment, statutory audit trail preservation, and official SOAP/XML evidence archiving.

### 1.1 The Legal Burden of Proof: Article 138 EU VAT Directive
Under **Article 138 of European Council Directive 2006/112/EC**, cross-border B2B supplies of goods and services within the European Union are exempt from Value Added Tax (0% Reverse Charge / Intra-Community Supply) **only if** the supplier can prove that:
1. The customer is a valid taxable person in another Member State possessing an active VAT identification number at the exact time of the transaction.
2. The supplier exercised "reasonable commercial care" and due diligence in confirming the validity of the customer's tax status.
3. According to established Court of Justice of the European Union (CJEU) jurisprudence (e.g., *Euro Tyre Holding BV, Case C-430/09*, *Mecsek-Gabona, Case C-273/11*, and *VSTR, Case C-587/10*), tax administrations routinely hold suppliers retroactively liable for uncollected 19–27% VAT plus punitive penalties if evidence of validation at the date of supply is missing.

### 1.2 How VIESAC Solves the Audit Vulnerability
Standard free web validators or basic e-commerce plugins perform ephemeral real-time checks without archiving tamper-evident proof. When tax audits occur 3–7 years later:
- The government VIES web interface cannot issue retroactive certificates for historical dates.
- VIES server outages and scheduled maintenance frequently yield false negatives.
- VIES often masks company names and addresses due to national privacy rules (e.g., Germany DE, Spain ES).

VIESAC resolves this by generating immutable **audit records** containing:
- Unique cryptographically signed `reference_number` and public validation token.
- Raw, untampered official government SOAP/XML responses with government transaction timestamps.
- Official Consultation Numbers where supported.
- Timestamped PDF Audit Certificates ready for tax authorities.
- AI-enriched corporate legal name and physical address when VIES masks data.
- Dual VAT + Customs EORI verification for international transport.

---

## 2. Supported Jurisdictions & Technical Registry Routing

VIESAC routes verification requests through dedicated adapters depending on the country code and entity type:

| Territory / System | ISO Code | Official Authority | Integration Adapter & Fallback Chain |
|---|---|---|---|
| **European Union (27 States)** | `AT, BE, BG, CY, CZ, DE, DK, EE, ES, FI, FR, GR, HR, HU, IE, IT, LT, LU, LV, MT, NL, PL, PT, RO, SE, SI, SK` | European Commission (VIES) | Primary: VIES SOAP Web Service. Fallbacks: EC REST API, National Revenue Agencies (DGFiP France, BZSt Germany, ARES Czechia, FURS Slovenia, AEAT Spain). |
| **Northern Ireland** | `XI` | HMRC / VIES Protocol | VIES Northern Ireland Special Protocol (Article 138 dual-status). |
| **United Kingdom** | `GB` | HM Revenue & Customs (HMRC) | Official HMRC VAT API (live lookups and consultation proofs). |
| **Switzerland** | `CH` | Federal Tax Administration (ESTV) | Swiss UID SOAP Registry (CHE-xxx.xxx.xxx MwSt / TVA / IVA). |
| **Norway** | `NO` | Brønnøysund Register Centre | Enhetsregisteret (BRREG) API for MVA registered enterprises. |
| **Turkey** | `TR` | Revenue Administration (GİB) | GİB VKN (Vergi Kimlik Numarası) tax identification registry. |
| **Serbia** | `RS` | Tax Administration (PURS) | PURS PDV / PIB (Poreski Identifikacioni Broj) registry. |
| **EU Customs (EORI)** | EU-wide | Directorate-General for Taxation and Customs Union (DG TAXUD) | EU EOS (Economic Operators System) customs verification database. |

---

## 3. Comprehensive REST API (v1) Specification

- **Base URL**: `https://viesac.eu/api/v1`
- **Transport**: HTTPS with TLS 1.3 enforced
- **Authentication**: `Authorization: Bearer <API_KEY>`
- **Content-Type**: `application/json`

### 3.1 Authentication & Rate Limiting
API keys are created in the VIESAC dashboard (`https://viesac.eu/app`).
- **Free Plan**: 10 requests / hour. Suitable for developer integration and testing.
- **Starter Plan**: 10 requests / minute, 50 audits / month.
- **Pro Plan**: 20 requests / minute, 250 audits / month.
- **Business Plan**: 30 requests / minute, 1,000 audits / month.
- **Enterprise Plan**: Custom dedicated concurrency, unmetered SLA.

When rate limits are exceeded, the API responds with HTTP status `429 Too Many Requests` and a standard JSON error envelope.

---

### 3.2 Endpoint: Official VAT Rates (`GET /rates`)
Free, unmetered endpoint requiring a valid API key (does not consume audit credits). Provides official standard, reduced, super-reduced, parking, regional, and special territory VAT rates across Europe.

#### Request Parameters (Query)
- `country` (string, optional): Filter by comma-separated ISO codes (e.g. `DE,FR,ES`).
- `eu_only` (boolean, optional): Restrict results strictly to the 27 EU Member States.

#### Response Example (`200 OK`)
```json
{
  "status": "success",
  "count": 30,
  "verified_at": "2026-09-16",
  "data": {
    "DE": {
      "country_code": "DE",
      "country_name": "Germany",
      "eu_member": true,
      "currency": "EUR",
      "standard_rate": 19.0,
      "reduced_rates": [7.0],
      "super_reduced_rate": null,
      "parking_rate": null,
      "special_territories": {
        "Heligoland": 0.0,
        "Busingen": 0.0
      },
      "official_source_url": "https://www.bzst.de"
    }
  }
}
```

---

### 3.3 Endpoint: Fast Ephemeral VAT Validation (`GET /validate`)
Quick check without creating a persistent audit record. Ideal for checkout validation, pre-validation form fields, and instant status verification. Consumes 1 validation check.

#### Request Parameters (Query)
- `vat` (string, required): Full VAT number with country prefix (e.g. `DE811128124`, `CHE100123456TVA`, `TR8770013406`).

#### Response Example (`200 OK`)
```json
{
  "status": "VALID",
  "valid": true,
  "country_code": "DE",
  "vat_number": "811128124",
  "name": "SIEMENS AKTIENGESELLSCHAFT",
  "address": "Werner-von-Siemens-Str. 1\n80333 München",
  "validated_at": "2026-09-25T14:30:00Z",
  "official_source": "vies",
  "cached": false
}
```

---

### 3.4 Endpoint: Fast Ephemeral EORI Validation (`GET /eori/validate`)
Quick customs verification for Economic Operators Registration and Identification numbers.

#### Request Parameters (Query)
- `eori` (string, required): Full EORI number with country prefix (e.g. `DE123456789012345`).

#### Response Example (`200 OK`)
```json
{
  "status": "VALID",
  "valid": true,
  "country_code": "DE",
  "eori_number": "123456789012345",
  "name": "LOGISTICS EUROPE GMBH",
  "address": "Hafenstrasse 12, 20457 Hamburg",
  "validated_at": "2026-09-25T14:32:00Z",
  "official_source": "eos"
}
```

---

### 3.5 Endpoint: Create Statutory Compliance Audit (`POST /audits`)
The flagship compliance endpoint. Executes official validation, archives raw SOAP XML evidence, triggers AI company enrichment when needed, creates an immutable audit trail, and generates downloadable PDF certificates.

#### Request Headers
- `Authorization: Bearer <API_KEY>`
- `Content-Type: application/json`
- `Idempotency-Key: <UUID_OR_STRING>` (optional, prevents duplicate charge on network retries)

#### Request Body (JSON Schema)
```json
{
  "type": "vat",
  "country_code": "FR",
  "vat_number": "83404833048",
  "eori_country_code": null,
  "eori_number": null,
  "requester_vat": "DE811128124",
  "company_name": null,
  "company_address": null,
  "order_number": "ORD-2026-10492",
  "invoice_number": "INV-88301",
  "customs_declaration_number": "EXP-2026-FR-0991",
  "comment": "B2B machinery delivery under 0% reverse charge",
  "method": "api",
  "monitoring": "month",
  "audit_details": {
    "erp_customer_id": "CUST-9921",
    "delivery_country": "DE"
  }
}
```

#### Field Explanations
- `type` (string, optional, default: `vat`): One of `vat`, `eori`, `vat_eori` (hybrid).
- `country_code` (string, 2 letters): Country ISO code (e.g. `FR`, `DE`, `ES`, `GB`, `CH`, `NO`, `TR`, `RS`). If omitted, automatically parsed from `vat_number`.
- `vat_number` (string): VAT/tax number with or without prefix.
- `eori_number` (string): Required when `type` is `eori` or `vat_eori`.
- `requester_vat` (string, optional): Your company's VAT number. Required by certain tax authorities (e.g. Germany, Spain) to obtain official consultation confirmation proof.
- `company_name`, `company_address` (string, optional): Optional. If omitted, VIESAC AI automatically extracts and enriches them from official registries or search evidence.
- `order_number`, `invoice_number`, `customs_declaration_number` (string, optional): Cross-reference identifiers linking the audit directly to your commercial transaction for auditors.
- `comment` (string, optional): Freeform notes for internal tax team audit log.
- `monitoring` (string, optional): Set to `day`, `week`, `month`, `quarter`, or `year` to automatically monitor this partner's validity over time.

#### Response Example (`201 Created`)
```json
{
  "reference_number": "VIES-2026-9A8F3D12",
  "audit_url": "https://viesac.eu/app/vies-audit/49210",
  "type": "vat",
  "country_code": "FR",
  "vat_number": "83404833048",
  "formatted_vat_number": "FR 83 404833048",
  "status": "valid",
  "valid": true,
  "vat_status": "valid",
  "vat_valid": true,
  "vies": 1,
  "official_source": "vies",
  "company_name": "L'OREAL",
  "company_address": "14 RUE ROYALE\n75008 PARIS",
  "consultation_number": "WAP1094827103",
  "consultation_number_status": "confirmed",
  "consultation_number_pending": false,
  "order_number": "ORD-2026-10492",
  "invoice_number": "INV-88301",
  "customs_declaration_number": "EXP-2026-FR-0991",
  "created_at": "2026-09-25T14:35:10Z",
  "certificates": {
    "vat": {
      "status": "valid",
      "pdf_url": "https://viesac.eu/cert/tok_89ab12cd34ef?locale=en",
      "xml_url": "https://viesac.eu/cert/tok_89ab12cd34ef/xml"
    }
  }
}
```

---

### 3.6 Endpoint: Audit List & Search (`GET /audits`)
Retrieve historical audits filtered by date, status, country, or customer references.

#### Query Parameters
- `page` (integer, default: 1): Pagination page.
- `limit` (integer, default: 20, max: 100): Records per page.
- `country_code` (string): Filter by 2-letter country code.
- `status` (string): Filter by `valid`, `invalid`, `pending`, `limited_valid`, `error`.
- `type` (string): Filter by `vat`, `eori`, `vat_eori`.
- `order_number`, `invoice_number`: Exact match filter.
- `search` (string): Full-text search across VAT number, company name, order number.

---

### 3.7 Endpoint: Get Single Audit (`GET /audits/{reference_number}`)
Fetch full details of a specific audit by its `reference_number`.

---

### 3.8 Endpoint: Update Audit Metadata (`PUT /audits/{reference_number}`)
Update commercial references after initial validation (e.g. after invoice issuance or customs declaration generation).

#### Request Body
```json
{
  "order_number": "ORD-2026-10492",
  "invoice_number": "INV-88301-FINAL",
  "customs_declaration_number": "MRN-26FR0000018274A0",
  "comment": "Customs cleared at Le Havre port"
}
```

---

### 3.9 Endpoints: Download Audit Evidence
- **PDF Certificate**: `GET /api/v1/audits/{reference_number}/certificate`
  - Returns `application/pdf`. Printable statutory audit certificate featuring official logos, timestamp, consultation number, and validation seals.
- **Raw SOAP/XML Evidence**: `GET /api/v1/audits/{reference_number}/certificate/xml`
  - Returns `application/xml`. The untampered XML response received directly from the national or EU government tax server, proving cryptographic veracity.

---

### 3.10 Endpoint: Account Quota & Usage (`GET /account`)
Check remaining credits, active plan, billing period, and organization limits.

#### Response Example (`200 OK`)
```json
{
  "status": "success",
  "plan": "PRO",
  "monthly_limit": 250,
  "used_this_month": 34,
  "remaining": 216,
  "organization": {
    "id": 14,
    "name": "Acme Global Tax AG",
    "org_monthly_limit": 1000,
    "org_used_this_month": 112,
    "org_remaining": 888
  },
  "period_resets_at": "2026-10-01T00:00:00Z"
}
```

---

## 4. Webhooks & Asynchronous Event Notifications

VIESAC delivers real-time webhooks for enterprise integrations. Configure endpoints in `/app/settings/webhooks`.

### 4.1 Signature Verification (HMAC-SHA256)
Every webhook delivery includes the HTTP header `X-Viesac-Signature`.
To verify authenticity in your application:
```python
import hmac, hashlib

expected_sig = hmac.new(
    WEBHOOK_SECRET.encode('utf-8'),
    request.body,
    hashlib.sha256
).hexdigest()

if not hmac.compare_digest(request.headers.get('X-Viesac-Signature'), expected_sig):
    abort(403)
```

### 4.2 Webhook Events
- `audit.created`: Triggered immediately after an audit record is generated.
- `audit.updated`: Triggered when metadata (invoice number, comment) is modified.
- `audit.status_changed`: Triggered when an asynchronous or pending audit resolves (e.g. VIES recovers from downtime).
- `monitoring.alert`: Triggered when a monitored partner's VAT registration is cancelled, invalidated, or modified in the tax registry.

---

## 5. AI-Powered Corporate Identity Enrichment

Due to privacy regulations (e.g. DSGVO / GDPR in Germany and Spain), VIES frequently returns:
```xml
<valid>true</valid>
<name>---</name>
<address>---</address>
```
When this occurs, VIESAC automatically triggers multi-tier corporate enrichment:
1. **Recent Audit Cache**: Checks if another authenticated user verified the same verified entity within 30 days.
2. **Official National Registries**: Direct queries to company registries (e.g., French Sirene API, Czech ARES, German BZSt portal).
3. **Web Search & Evidence Extraction**: Serper Google search across verified official regulatory filings and enterprise registers.
4. **LLM Verification**: Kimi, OpenAI, and Gemini models cross-reference registration numbers, legal entity suffixes (GmbH, SAS, S.L., Sp. z o.o.), and physical addresses, attaching an evidentiary provenance trail to the audit record.

---

## 6. Implementation Code Examples

### 6.1 Python (Requests)
```python
import requests

API_KEY = "viesac_live_xxxxxxxxxxxxxxxx"
BASE_URL = "https://viesac.eu/api/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json"
}

# 1. Quick validation
resp = requests.get(f"{BASE_URL}/validate", params={"vat": "NL867640765B01"}, headers=headers)
print(resp.json())

# 2. Statutory Audit Creation
payload = {
    "type": "vat",
    "vat_number": "NL867640765B01",
    "order_number": "SO-99218",
    "invoice_number": "INV-2026-001"
}
audit_resp = requests.post(f"{BASE_URL}/audits", json=payload, headers=headers)
audit = audit_resp.json()
print("Audit Reference:", audit["reference_number"])
print("PDF Certificate URL:", audit["certificates"]["vat"]["pdf_url"])
```

### 6.2 TypeScript / Node.js
```typescript
import axios from 'axios';

const client = axios.create({
  baseURL: 'https://viesac.eu/api/v1',
  headers: {
    'Authorization': `Bearer ${process.env.VIESAC_API_KEY}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  }
});

async function verifyB2BPartner(vatNumber: string, orderId: string) {
  try {
    const response = await client.post('/audits', {
      type: 'vat',
      vat_number: vatNumber,
      order_number: orderId
    });

    const audit = response.data;
    if (audit.valid) {
      console.log(`✓ VAT valid: ${audit.company_name}`);
      console.log(`Certificate: ${audit.certificates.vat.pdf_url}`);
      return { exemptFromVat: true, auditRef: audit.reference_number };
    } else {
      console.warn(`✗ VAT invalid: Charge domestic rate`);
      return { exemptFromVat: false, auditRef: audit.reference_number };
    }
  } catch (error) {
    console.error('Audit failed:', error.response?.data || error.message);
    throw error;
  }
}
```

---

## 7. Status & Error Code Reference

### HTTP Status Codes
- `200 OK`: Request succeeded.
- `201 Created`: Audit record generated successfully.
- `400 Bad Request`: Malformed parameters or unsupported country code.
- `401 Unauthorized`: Missing or invalid Bearer API key.
- `403 Forbidden`: Subscription quota exceeded or account suspended.
- `404 Not Found`: Audit reference number does not exist.
- `422 Unprocessable Entity`: Validation failed (e.g. invalid VAT checksum, invalid requester VAT).
- `429 Too Many Requests`: Rate limit exceeded.
- `500 Internal Server Error`: Upstream tax authority protocol error.

### Validation Status Values
- `valid`: Number is officially active and registered in the government database.
- `invalid`: Number does not exist or has been terminated by the tax authority.
- `limited_valid`: Valid in national registry, but EU cross-border status is restricted.
- `pending`: Government registry is temporarily offline (VIES downtime); scheduled for automatic retry.
- `error`: Upstream network timeout or national authority communication error.