openapi: 3.0.3
info:
  title: VAT Validation API
  version: 2.2.0
  description: |
    Unified VAT/Tax ID validation API for **54+ countries** — 27 EU via VIES plus 27+ non-EU countries.

    One API, consistent responses, complete company data.

    ---

    ## 🚀 Quick Start

    ```bash
    curl -X POST https://api.44api.dev/webhook/validate-vat \
      -H "Content-Type: application/json" \
      -H "X-API-Key: YOUR_API_KEY" \
      -d '{"vatNumber": "69838046", "countryCode": "SI"}'
    ```

    ---

    ## ✨ Features

    | Feature | Description |
    |---------|-------------|
    | 🌍 54+ Countries | 27 EU + 27+ Non-EU coverage |
    | 🔗 Unified API | One endpoint for all countries |
    | 🏢 Company Data | Name, address, registration status |
    | 💾 Smart Caching | 7-day cache, handles VIES outages |
    | 🔒 IP Whitelist | Enterprise security feature |
    | ⚡ Zapier Ready | No-code automation |

    ---

    ## 💰 Pricing

    | Plan | Requests/Month | Price |
    |------|----------------|-------|
    | Free | 250 | €0 |
    | Starter | 5,000 | €9/mo |
    | Pro | 25,000 | €29/mo |
    | Enterprise | Unlimited | €99/mo |

    **2.5x more free requests than competitors!**

    ---

    ## 🌍 Country Coverage (54+ Countries)

    ### EU Countries (27) - via VIES
    `AT` `BE` `BG` `HR` `CY` `CZ` `DK` `EE` `FI` `FR` `DE`* `EL` `HU` `IE` `IT` `LV` `LT` `LU` `MT` `NL` `PL` `PT` `RO` `SK` `SI` `ES`* `SE`

    ### Non-EU Active (27+)
    `GB` UK · `CH` Switzerland · `NO` Norway · `AU` Australia · `NZ` New Zealand · `AL` Albania · `XK` Kosovo · `TR` Turkey · `GE` Georgia · `MD` Moldova · `UA` Ukraine · `BY` Belarus · `BA` Bosnia · `IS` Iceland · `IL` Israel · `KZ` Kazakhstan · `MK` North Macedonia · `RS` Serbia · `RU` Russia + more

    > *Germany (DE) and Spain (ES) return validation status only, without company details due to data protection laws.

    ---

  contact:
    name: 44api.dev Support
    url: https://44api.dev
    email: support@44api.dev
  license:
    name: Proprietary
    url: https://44api.dev/terms

servers:
  - url: https://api.44api.dev
    description: Production API

security:
  - ApiKeyAuth: []

paths:
  /webhook/validate-vat:
    post:
      operationId: validateVatNumber
      summary: Validate VAT Number
      description: |
        Validates a VAT/Tax ID number and returns company information.

        **Supports 54+ countries** — EU via VIES, plus UK, Switzerland, Norway, Australia, New Zealand, and 20+ more.

        **Caching:** Results are cached for 7 days to improve reliability and handle VIES outages.
      tags:
        - VAT Validation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VatRequest'
            examples:
              slovenia:
                summary: Slovenia (EU - full data)
                value:
                  vatNumber: "69838046"
                  countryCode: "SI"
              germany:
                summary: Germany (EU - validation only)
                value:
                  vatNumber: "123456789"
                  countryCode: "DE"
              uk:
                summary: United Kingdom
                value:
                  vatNumber: "123456789"
                  countryCode: "GB"
              switzerland:
                summary: Switzerland (Non-EU)
                value:
                  vatNumber: "CHE123456789"
                  countryCode: "CH"
              turkey:
                summary: Turkey (Non-EU)
                value:
                  vatNumber: "1234567890"
                  countryCode: "TR"
              australia:
                summary: Australia (ABN)
                value:
                  vatNumber: "51824753556"
                  countryCode: "AU"
              new_zealand:
                summary: New Zealand (NZBN)
                value:
                  vatNumber: "9429036995356"
                  countryCode: "NZ"
      responses:
        '200':
          description: Validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VatResponse'
              examples:
                valid:
                  summary: Valid VAT number
                  value:
                    success: true
                    cached: true
                    data:
                      vatNumber: "SI69838046"
                      countryCode: "SI"
                      valid: true
                      company:
                        name: "NETKO D.O.O."
                        address: "PRIMOŽIČEVA ULICA 1, 1231 LJUBLJANA - ČRNUČE"
                      verificationDate: "2025-12-26T18:07:31.685"
                invalid:
                  summary: Invalid VAT number
                  value:
                    success: true
                    cached: false
                    data:
                      vatNumber: "DE123456789"
                      countryCode: "DE"
                      valid: false
                      company:
                        name: null
                        address: null
                      verificationDate: "2025-12-26T18:13:59.074"
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /webhook/ip-whitelist:
    post:
      operationId: manageIpWhitelist
      summary: Manage IP Whitelist
      description: |
        Manage IP whitelist for enterprise security.

        **Actions:**
        - `add` - Add IP to whitelist (requires email verification)
        - `remove` - Remove IP from whitelist
        - `list` - List all whitelisted IPs
      tags:
        - IP Whitelist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IpWhitelistRequest'
            examples:
              add:
                summary: Add IP to whitelist
                value:
                  action: "add"
                  ipAddress: "203.0.113.50"
                  email: "admin@company.com"
              list:
                summary: List whitelisted IPs
                value:
                  action: "list"
              remove:
                summary: Remove IP from whitelist
                value:
                  action: "remove"
                  ipAddress: "203.0.113.50"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpWhitelistResponse'

  /webhook/core/health:
    get:
      operationId: healthCheck
      summary: Health Check
      description: Check API and upstream service status. No authentication required.
      tags:
        - System
      security: []
      responses:
        '200':
          description: Service status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "operational"
                  timestamp:
                    type: string
                    format: date-time
                  services:
                    type: object
                    properties:
                      api:
                        type: string
                        example: "up"
                      database:
                        type: string
                        example: "up"
                      vies:
                        type: string
                        example: "up"

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: |
        Get your API key at [44api.dev Dashboard](https://dashboard.44api.dev/auth)

        **Demo Key:** `0000000000000000000000000000000000000000000000000000000000000001`

  schemas:
    VatRequest:
      type: object
      required:
        - vatNumber
        - countryCode
      properties:
        vatNumber:
          type: string
          description: VAT number (with or without country prefix)
          example: "69838046"
        countryCode:
          type: string
          description: ISO 2-letter country code
          example: "SI"
          enum: [AT, BE, BG, HR, CY, CZ, DK, EE, FI, FR, DE, EL, HU, IE, IT, LV, LT, LU, MT, NL, PL, PT, RO, SK, SI, ES, SE, GB, CH, NO, AU, NZ, AL, XK, TR, GE, MD, UA, BY, BA, IS, IL, KZ, MK, RS, RU]

    VatResponse:
      type: object
      properties:
        success:
          type: boolean
        cached:
          type: boolean
          description: Whether result was from cache
        data:
          type: object
          properties:
            vatNumber:
              type: string
            countryCode:
              type: string
            valid:
              type: boolean
            company:
              type: object
              properties:
                name:
                  type: string
                  nullable: true
                address:
                  type: string
                  nullable: true
            verificationDate:
              type: string
              format: date-time

    IpWhitelistRequest:
      type: object
      required:
        - action
      properties:
        action:
          type: string
          enum: [add, remove, list]
        ipAddress:
          type: string
          description: IP address (required for add/remove)
        email:
          type: string
          description: Email for verification (required for add)

    IpWhitelistResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        data:
          type: object

    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string

tags:
  - name: VAT Validation
    description: Validate VAT/Tax ID numbers across 54+ countries
  - name: IP Whitelist
    description: Enterprise IP whitelist management
  - name: System
    description: Health checks and system status