واجهة برمجة حاسبة ضريبة القيمة المضافة

#What the VAT API solves

Instead of re-implementing VAT rules in every project, you send net / gross / VAT amount / rate (any two are enough), plus optional country and VAT type. The API calculates the missing numbers, applies country-specific rounding, and can even return multi-rate scenarios when you need to compare standard vs reduced rates.

#Endpoint & actions

#POST https://api.yeb.to/v1/vat

• Single endpoint with an action parameter.
• Idempotent: same input → same result; safe for caching and retries.
• Supports both: form-encoded requests (application/x-www-form-urlencoded) and JSON bodies (when valid JSON is sent from your backend).

#Quick start examples

# 1) Custom VAT rate (20%), net → gross
curl -s -X POST "https://api.yeb.to/v1/vat" ^
  -H "X-API-Key: YOUR_KEY" ^
  -H "Content-Type: application/x-www-form-urlencoded" ^
  --data "action=calculate&net=100&vat_rate=20&country_code=BG&vat_type=standard"

# 2) Use default rate from BG profile (no explicit vat_rate)
curl -s -X POST "https://api.yeb.to/v1/vat" ^
  -H "X-API-Key: YOUR_KEY" ^
  -H "Content-Type: application/x-www-form-urlencoded" ^
  --data "action=calculate&net=100&country_code=BG&vat_type=standard"

# 3) Advanced multi-rate scenarios for a country
curl -s -X POST "https://api.yeb.to/v1/vat" ^
  -H "X-API-Key: YOUR_KEY" ^
  -H "Content-Type: application/x-www-form-urlencoded" ^
  --data "action=calculate&advanced=1&net=100&country_code=DE"

#Parameters that actually matter

#Reading & acting on responses

#Single-rate scenario (scenario_type = "single_rate")

{
  "country_code": "BG",
  "vat_type": "standard",
  "scenario_type": "single_rate",
  "net": 100,
  "gross": 120,
  "vat_amount": 20,
  "vat_rate": 0.2,
  "vat_rate_percent": 20,
  "decimal_separator": ".",
  "currency": "BGN",
  "rounding": { "precision": 2, "mode": "half_up" },
  "warnings": [],
  "formatted": {
    "net": "100.00",
    "gross": "120.00",
    "vat_amount": "20.00",
    "vat_rate": "20.00%"
  },
  "response_code": 200,
  "response_time_ms": 5
}

• net, gross, vat_amount — numeric fields you can store directly in your DB.
• vat_rate, vat_rate_percent — the effective rate used (fraction and %).
• formatted — strings ready for UI/PDF output with the chosen decimal_separator.
• warnings — non-fatal hints (e.g. not enough data) that you may show to admins or logs.

#Multi-rate scenarios (scenario_type = "multi_rate")

{
  "country_code": "DE",
  "vat_type": "standard",
  "scenario_type": "multi_rate",
  "net": 100,
  "gross": null,
  "vat_amount": null,
  "decimal_separator": ".",
  "currency": "EUR",
  "rounding": { "precision": 2, "mode": "half_up" },
  "warnings": [],
  "scenarios": [
    {
      "vat_type": "standard",
      "vat_rate": 0.19,
      "vat_rate_percent": 19,
      "net": 100,
      "gross": 119,
      "vat_amount": 19,
      "formatted": { "...": "..." }
    },
    {
      "vat_type": "reduced",
      "vat_rate": 0.07,
      "vat_rate_percent": 7,
      "net": 100,
      "gross": 107,
      "vat_amount": 7,
      "formatted": { "...": "..." }
    }
  ]
}

• Use scenarios to compare different VAT types for the same net amount.
• Ideal for admin UIs where you show “standard vs reduced” on the same screen.
• Pick one scenario and persist only that to your invoice rows.

#Typical errors & how to fix them

{ "error": "Missing \"country_code\" parameter", "code": 400 }

{ "error": "Invalid API key", "code": 401 }

{
  "country_code": null,
  "scenario_type": "single_rate",
  "net": null,
  "gross": null,
  "vat_amount": null,
  "vat_rate": null,
  "warnings": [
    "Not enough information to compute VAT. Provide at least two of: net, gross, vat_amount, vat_rate (or a country_code with rates)."
  ],
  "formatted": null
}

• 401 invalid/missing key: pass api_key or X-API-Key from your backend.
• 400 missing country_code: required for country-profile and country-rates.
• Calculation warnings: if you see only a warning and no numbers, send at least two monetary inputs.

#Troubleshooting & field notes

1. Conflicting inputs: If you send net, gross and vat_amount that don’t match, the API relies on its internal math; log your raw params if you suspect rounding issues.
2. Zero-rate logic: For vat_rate = 0 or vat_type = zero, net = gross and VAT amount = 0.
3. Custom vs country rate: A provided vat_rate always wins over country_code/vat_type. Omit vat_rate if you want pure “country default” behaviour.
4. Locales & separators: You can safely accept user input with , or . — normalization is handled for you.
5. Batch use: For bulk imports, keep requests ≤ 100 rps, reuse HTTP connections, and cache stable country profiles.

#API Changelog