wsystem-dev EORI API

openapi: 3.2.0
info:
  title: W System EORI 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: EORI
  description: EU EORI customs number validation via the EC EOS service
paths:
  /eori:
    get:
      tags:
      - EORI
      summary: Validate one EU EORI number (EC EOS)
      description: 'Check an EU EORI (Economic Operators Registration and Identification) number such as SE5560360793 against the official European Commission EOS service. Returns valid/invalid and name/address when the trader consented to publication. Returns status valid | invalid | invalid_format | unavailable (EC EOS down: valid null, error EOS_UNAVAILABLE, retry later; never reported as invalid) | error. Note: GB EORIs are validated by HMRC, not EOS. x402 $0.01.'
      operationId: verifyEori
      parameters:
      - name: eori
        in: query
        required: true
        schema:
          type: string
          examples:
          - SE5560360793
          title: Eori
      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
  /eori/batch:
    post:
      tags:
      - EORI
      summary: Validate up to 100 EU EORI numbers
      description: 'Body: {"eoris":[...]}. x402 $0.10.'
      operationId: verifyEoriBatch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EoriBatch'
        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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    EoriBatch:
      properties:
        eoris:
          items:
            type: string
          type: array
          maxItems: 100
          minItems: 1
          title: Eoris
          examples:
          - - SE5560360793
            - IE6388047V
      type: object
      required:
      - eoris
      title: EoriBatch
  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