wsystem-dev VAT API

openapi: 3.2.0
info:
  title: W System VAT API
  description: 'EU e-invoicing and business-data API: VAT/VIES and EORI validation, KYB, sanctions screening, EN 16931 e-invoice validation, Peppol lookup. Pay per call via x402 or use an API key; MCP server available.


    **Endpoints:** **EU VAT number validation (VIES)**, **EORI validation (EC EOS)**, **official company-registry lookup**, **sanctions screening (EU, UN, OFAC SDN, UK)**, **one-call KYB**, a **due-diligence report**, and **EU e-invoicing**: validate (EN 16931, XRechnung; UBL, CII, ZUGFeRD/Factur-X PDF), create (JSON -> UBL), ''can I e-invoice this company?'' (VIES + Peppol + mandates), and **SANDBOX send** (verify -> create -> route -> transport -> signed evidence; transport = mock, or a real submission through partner Peppol access-point sandboxes: Recommand playground or e-invoice.be sandbox). Live Peppol sending is not generally available; it opens per company once our access-point partner has activated it.


    * **No API key, no signup:** every client IP gets 20 free calls/day across all endpoints (header `X-Free-Remaining`).

    * **Beyond the free tier:** pay per call with **x402** (USDC on Base, HTTP 402 flow): $0.01 per single check, $0.10 per batch request, $0.045 per KYB check; e-invoice validate $0.03, parse $0.01, create $0.08, route $0.02; due-diligence report $0.49. Or use an API key.

    * **Live Peppol onboarding (API key):** `GET /einvoice/mandate-terms` returns the W System Peppol mandate terms (https://wsystem.dev/legal/peppol-mandate-terms, DPA: https://wsystem.dev/legal/dpa); `POST /einvoice/mandates` records the company''s click-through mandate with a signed receipt.

    * **MCP:** the same tools are available to AI agents at `https://api.wsystem.dev/mcp/` (streamable HTTP).

    * VIES/EOS are official European Commission services; this API adds retries when a member state is unavailable, caching,

    batch endpoints, audit consultation numbers and a stable JSON shape. Docs: https://wsystem.dev/llms.txt'
  contact:
    name: W System
    url: https://wsystem.dev/
  license:
    name: Proprietary API; MCP server code MIT
    url: https://github.com/wsystemdev/eu-business-data-mcp
  version: 0.3.61
  x-guidance: 'EU business verification for agents. GET /verify?vat=IE6388047V validates an EU VAT number via official VIES (name, address, consultation number as audit proof). GET /eori?eori=SE5560360793 validates an EU EORI number. GET /company?q=552032534&country=FR looks up official business registers. GET /sanctions/screen?name=... screens EU/UN/OFAC/UK lists. POST /kyb/check {"company":"FR40303265045"} returns a pass/review/fail KYB verdict. POST /einvoice/validate (raw UBL/CII XML or ZUGFeRD PDF body) checks EN 16931 + XRechnung rules; POST /einvoice/parse (same body) reads an incoming invoice into JSON (parties, totals, VAT, IBAN, lines; no validation); POST /einvoice/create turns JSON into a validated UBL invoice (example body: GET /einvoice/sample); GET /einvoice/route?id=BE0403170701 says whether/how to e-invoice a company; POST /ddreport returns a full due-diligence report. Batch POST variants take up to 100 items. First 20 calls/day per IP are free; after that pay per call with x402 (USDC on Base), or send an X-API-Key.'
servers:
- url: https://api.wsystem.dev
  description: Production
tags:
- name: Vat
  description: EU VAT number validation via VIES (27 EU states + XI Northern Ireland)
paths:
  /vies/status:
    get:
      tags:
      - Vat
      summary: VIES availability per member state (free, cached 5 min)
      description: Proxy of the European Commission VIES check-status endpoint, cached for 5 minutes. Free; does not use the free-tier quota. `national_fallback` = this API can answer from an official national source while that member state is down.
      operationId: viesStatus
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /verify:
    get:
      tags:
      - Vat
      summary: Validate one EU VAT number (VIES)
      description: 'Check whether an EU VAT number (with country prefix, e.g. IE6388047V, DE811193231, HU33119856) is valid in the official VIES system (EU-27 + XI Northern Ireland). UK (GB) VAT checks are coming soon: until HMRC live access is granted, GB numbers return `status: member_state_unavailable`, `valid: null`, `error: HMRC_LIVE_ACCESS_PENDING` and are not charged. Returns `status` (valid | invalid | invalid_format | member_state_unavailable | error), `valid`, registered `name` and `address` where the member state discloses them, and a `consultation_number` (audit proof) when `requester` is a valid EU VAT. If VIES is down for that member state, `fallback: true` answers come from an official national source (PL Biała lista, CZ ARES, FI YTJ, FR SIRENE) or the last successful VIES result with its date; fallbacks never carry a consultation number. Use for reverse-charge invoicing, customer/supplier onboarding and checkout VAT exemption. Free 20/day per IP, then x402 $0.01.'
      operationId: verifyVat
      parameters:
      - name: vat
        in: query
        required: true
        schema:
          type: string
          examples:
          - HU33119856
          title: Vat
      - name: requester
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          default: HU33119856
          title: Requester
      - name: nocache
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Nocache
      - name: fallback
        in: query
        required: false
        schema:
          type: boolean
          default: true
          title: Fallback
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '402':
          description: 'Payment Required: x402 v2 challenge (PAYMENT-REQUIRED header). Returned when the free tier is used up, or for a bare call without input.'
        '429':
          description: Free tier used up and x402 disabled
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.010000'
        protocols:
        - x402:
            network: eip155:8453
            asset: USDC
            scheme: exact
        freeTier: 20 calls/day per IP, no key
  /verify/batch:
    post:
      tags:
      - Vat
      summary: Validate up to 100 EU VAT numbers
      description: 'Batch VIES validation. Body: {"vats": [...], "requester": "optional own VAT"}. Same per-item result shape as GET /verify (GB items: member_state_unavailable until HMRC live access is granted; a batch of only GB numbers is not charged). x402 $0.10 per batch request after the free tier.'
      operationId: verifyVatBatch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Batch'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '402':
          description: 'Payment Required: x402 v2 challenge (PAYMENT-REQUIRED header). Returned when the free tier is used up, or for a bare call without input.'
        '429':
          description: Free tier used up and x402 disabled
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.100000'
        protocols:
        - x402:
            network: eip155:8453
            asset: USDC
            scheme: exact
        freeTier: 20 calls/day per IP, no key
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    Batch:
      properties:
        vats:
          items:
            type: string
          type: array
          maxItems: 100
          minItems: 1
          title: Vats
        requester:
          anyOf:
          - type: string
          - type: 'null'
          title: Requester
          default: HU33119856
      type: object
      required:
      - vats
      title: Batch
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Optional monthly-plan key. Without it: free tier, then x402 pay-per-call.'
externalDocs:
  description: Guides, prices and MCP setup
  url: https://wsystem.dev/llms-full.txt
x-discovery:
  mcp: https://api.wsystem.dev/mcp/
  serverCard: https://api.wsystem.dev/server-card
  x402: https://api.wsystem.dev/.well-known/x402