{"openapi":"3.0.3","info":{"title":"EU VAT & IBAN/BIC Validator API","version":"1.0.0","description":"Offline ISO 13616 IBAN MOD-97 & ISO 9362 BIC/SWIFT validation, plus 27-country EU VAT format verification and VIES lookup with KV caching and graceful degradation."},"servers":[{"url":"https://api.tinplate.dev","description":"Production Edge Gateway"}],"components":{"schemas":{"IbanCheckResponse":{"type":"object","properties":{"valid":{"type":"boolean","example":true},"iban":{"type":"string","example":"DE89370400440532013000"},"formatted":{"type":"string","example":"DE89 3704 0044 0532 0130 00"},"country_code":{"type":"string","example":"DE"},"check_digits":{"type":"string","example":"89"},"bban":{"type":"string","example":"370400440532013000"},"length_valid":{"type":"boolean","example":true},"checksum_valid":{"type":"boolean","example":true},"bic_valid":{"type":"boolean","nullable":true,"example":true},"bic_country_match":{"type":"boolean","nullable":true,"example":true},"errors":{"type":"array","items":{"type":"string"},"example":[]}},"required":["valid","iban","formatted","country_code","check_digits","bban","length_valid","checksum_valid","bic_valid","bic_country_match","errors"]},"IbanCheckRequest":{"type":"object","properties":{"iban":{"type":"string","minLength":5,"maxLength":64,"example":"DE89 3704 0044 0532 0130 00","description":"IBAN to validate (spaces allowed)."},"bic":{"type":"string","minLength":4,"maxLength":16,"example":"COBADEFFXXX","description":"Optional BIC/SWIFT code (8 or 11 characters) to validate and cross-check country."}},"required":["iban"]},"VatCheckResponse":{"type":"object","properties":{"format_valid":{"type":"boolean","example":true},"country_code":{"type":"string","example":"HU"},"vat_number":{"type":"string","example":"12345678"},"normalized":{"type":"string","example":"HU12345678"},"vies_status":{"type":"string","enum":["valid","invalid","unavailable","skipped"],"example":"valid"},"vies_valid":{"type":"boolean","nullable":true,"example":true},"cached":{"type":"boolean","example":false},"company_name":{"type":"string","nullable":true,"example":"TINPLATE KFT."},"company_address":{"type":"string","nullable":true,"example":"BUDAPEST, HU"},"errors":{"type":"array","items":{"type":"string"},"example":[]}},"required":["format_valid","country_code","vat_number","normalized","vies_status","vies_valid","cached","company_name","company_address","errors"]},"VatCheckRequest":{"type":"object","properties":{"vat_number":{"type":"string","minLength":4,"maxLength":32,"example":"HU12345678","description":"EU VAT number including 2-letter country prefix (spaces/dashes allowed)."},"verify_vies":{"type":"boolean","example":true,"description":"Whether to query EU VIES (with KV cache & graceful degradation). Defaults to true."}},"required":["vat_number"]},"ResponseMeta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","format":"uuid"},"ms":{"type":"integer","minimum":0},"version":{"type":"string","example":"1.0.0"}}},"ErrorEnvelope":{"type":"object","required":["ok","error","meta"],"properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_input"},"message":{"type":"string","example":"Request body failed validation"}}},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}}},"parameters":{}},"paths":{"/v1/eu-vat-iban/iban":{"post":{"tags":["05_EU_VAT_IBAN"],"summary":"Validate IBAN (MOD-97 & country length) and optional BIC/SWIFT","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IbanCheckRequest"}}}},"responses":{"200":{"description":"IBAN & BIC validation result","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/IbanCheckResponse"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["ok","data","meta"]}}}},"400":{"description":"Invalid input or malformed JSON request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid authentication credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request payload exceeds subscribed plan byte cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/eu-vat-iban/vat":{"post":{"tags":["05_EU_VAT_IBAN"],"summary":"Validate EU VAT format and optionally verify via VIES (with KV cache)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VatCheckRequest"}}}},"responses":{"200":{"description":"EU VAT validation result","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/VatCheckResponse"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}},"required":["ok","data","meta"]}}}},"400":{"description":"Invalid input or malformed JSON request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid authentication credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request payload exceeds subscribed plan byte cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}