{ "openapi": "3.1.0", "info": { "title": "Veriport API", "version": "2026-10-28.1", "summary": "The EU counterparty check and compliant e-invoices", "description": "One REST API for the checks every invoicing, billing and payout system needs, and for the e-invoices it must now issue: EU VAT number validation on top of the Commission’s VIES service with a dated cache when a member state is down, French company data from the public registries, IBAN validation from the SWIFT registry with a SEPA flag, compliant e-invoices from JSON (XRechnung, ZUGFeRD / Factur-X, Peppol BIS Billing 3.0) with the official check of any e-invoice, EU VAT rates by country and category from a sourced table, OSS and IOSS return lines, and US sales-tax rates from public state tables. Deterministic answers, documented errors, a free tier without a card.\n\nAuthenticate with `Authorization: Bearer `. Without a key, 20 calls a day per address are allowed on the validation and rates endpoints (no consultation number, no bulk). Every error is an RFC 9457 problem document whose `type` links to the errors page. Dates are ISO 8601 in UTC.", "termsOfService": "https://veriport.io/legal/terms", "contact": { "name": "Veriport support", "email": "hello@veriport.io", "url": "https://veriport.io/contact" }, "license": { "name": "Proprietary; the OpenAPI document itself may be copied", "url": "https://veriport.io/legal/terms" } }, "servers": [ { "url": "https://veriport.io/api/v1", "description": "Production (functions and database in the EU, Paris)" } ], "tags": [ { "name": "VAT numbers", "description": "EU VAT number validation on top of the Commission’s VIES service." }, { "name": "VAT rates", "description": "EU VAT rates by member state with category hints, from a dated and sourced table." }, { "name": "IBAN", "description": "IBAN structure, length, mod 97-10 and BBAN pattern per country, with the SEPA flag." }, { "name": "OSS return", "description": "OSS return validator (lines only; dispatch-country breakdown not implemented): OSS / IOSS return lines from a sales export, per member state of consumption, supply type and rate, validated against the dated rates table, with a generic CSV. Not a filable return for sellers dispatching goods from more than one member state." }, { "name": "French companies", "description": "French company-registry enrichment (SIREN / SIRET) from the open Recherche d’entreprises API and, with a key, the INSEE Sirene API; cached, normalised, sourced." }, { "name": "US sales tax", "description": "US sales-tax rates from public data: state rates for the 50 states + DC, ZIP-level combined averages where a revenue department publishes a ZIP file; coverage stated per answer." }, { "name": "E-invoices", "description": "Compliant e-invoices from invoice JSON (XRechnung 3.0 UBL and CII, ZUGFeRD 2.x / Factur-X EN 16931, Peppol BIS Billing 3.0 with the Belgian rules), the official check of any e-invoice (XML schema plus the published CEN, XRechnung and Peppol schematron, run in-process), and the reading of a received one as JSON or a PDF. Nothing is sent on a network and no document is stored." }, { "name": "Account", "description": "Your key, tier and usage." }, { "name": "Status", "description": "Self-reported status and upstream availability." } ], "paths": { "/vat/validate": { "get": { "operationId": "validateVatNumber", "summary": "Validate an EU VAT number", "description": "Normalises the country code and the number (spaces, punctuation, a repeated prefix, GR → EL), checks the national structure and check digit, then asks VIES (REST first, SOAP fallback). Returns the registered name and address where the member state publishes them, and a consultation number when `requester` is supplied (prepaid credits or the monthly plan). When VIES or the member state is down, the last answer we hold for that number is returned with `source.kind = \"cache\"` and `source.stale = true`; it is never presented as live. A structurally impossible number answers `valid: false` without calling VIES and is not counted.", "tags": [ "VAT numbers" ], "security": [ { "apiKey": [] }, {} ], "x-tiers": [ "anonymous", "free", "credits", "plan" ], "x-cost": "1 call when VIES or the cache answered; 0 when the structure already fails or when a 5xx is returned", "parameters": [ { "name": "country", "in": "query", "required": false, "description": "ISO 3166-1 alpha-2 of the member state; Greece is `EL` (GR accepted), Northern Ireland `XI`. May be omitted when `number` carries the prefix.", "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "example": "DE" }, { "name": "number", "in": "query", "required": true, "description": "The VAT number, with or without the country prefix, spaces or punctuation.", "schema": { "type": "string", "minLength": 2, "maxLength": 20 }, "example": "136695976" }, { "name": "requester", "in": "query", "required": false, "description": "Your own EU VAT number (with prefix). VIES then issues a consultation number, the evidence a tax audit accepts. Prepaid credits or the monthly plan.", "schema": { "type": "string", "minLength": 4, "maxLength": 20 }, "example": "FR40303265045" }, { "name": "record", "in": "query", "required": false, "description": "`true` keeps this validation as a record on your account for 10 years (or until you delete it), and the answer gains `record`. A structure-only answer is not kept (`record` is null), since VIES was not consulted. A record is our dated copy of the answer; only the consultation number is issued by VIES. Prepaid credits or the monthly plan.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The validation result, live or from the dated cache.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Tier": { "$ref": "#/components/headers/X-Tier" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatValidation" }, "example": { "valid": true, "countryCode": "DE", "vatNumber": "136695976", "full": "DE136695976", "structure": { "valid": true, "checksum": "passed", "expected": "9 digits" }, "name": null, "address": null, "requestDate": "2026-10-24", "consultationNumber": null, "source": { "kind": "live", "checkedAt": "2026-10-24T09:14:03Z", "cacheAgeSeconds": 0, "stale": false }, "upstream": { "service": "vies", "transport": "rest", "status": "ok", "memberStateAvailable": true }, "tableVersion": null } } } }, "400": { "description": "`invalid_parameter` — A parameter is missing or malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#invalid_parameter", "title": "A parameter is missing or malformed", "status": 400, "detail": "Read `detail` and `errors[]`: each entry names the parameter and the rule it broke. Nothing was counted against your quota.", "instance": "req_01HZX…", "code": "invalid_parameter" } } } }, "401": { "description": "`unauthorized` — The API key is missing, unknown or revoked.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#unauthorized", "title": "The API key is missing, unknown or revoked", "status": 401, "detail": "Send `Authorization: Bearer vp_live_…`. Keys are shown once at sign-up; a revoked key cannot be restored, create a new one.", "instance": "req_01HZX…", "code": "unauthorized" } } } }, "402": { "description": "`quota_exceeded` — Monthly allowance and credits are used up.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#quota_exceeded", "title": "Monthly allowance and credits are used up", "status": 402, "detail": "The free allowance resets on the first of the month (UTC). Buy a credit pack or the monthly plan at /pricing; the key stays the same.", "instance": "req_01HZX…", "code": "quota_exceeded" } } } }, "403": { "description": "`forbidden_for_tier` — This option is not included in your tier.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#forbidden_for_tier", "title": "This option is not included in your tier", "status": 403, "detail": "The `requester` option (consultation number) and the `record` option (a stored validation record) need prepaid credits or the monthly plan; the bulk endpoints need the monthly plan. See /pricing.", "instance": "req_01HZX…", "code": "forbidden_for_tier" } } } }, "429": { "description": "`rate_limited` — Too many requests per second.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#rate_limited", "title": "Too many requests per second", "status": 429, "detail": "Honour `Retry-After` and the `RateLimit-*` headers. Free keys may send 2 requests a second; the monthly plan 10. Use the bulk endpoint for lists.", "instance": "req_01HZX…", "code": "rate_limited" } } } }, "503": { "description": "`vies_unavailable` — VIES or the member state is unavailable and no cached answer exists. `vies_blocked` — VIES refused the request (concurrency or blocking).", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#vies_blocked", "title": "VIES refused the request (concurrency or blocking)", "status": 503, "detail": "VIES answered MS_MAX_CONCURRENT_REQ, GLOBAL_MAX_CONCURRENT_REQ or a blocking code. Retry after `Retry-After` seconds; the call was not counted.", "instance": "req_01HZX…", "code": "vies_blocked" } } } } } } }, "/vat/validate/bulk": { "post": { "operationId": "validateVatNumbersBulk", "summary": "Validate up to 100 EU VAT numbers in one request", "description": "Monthly plan only. Each item is processed as `GET /vat/validate` would, with a bounded concurrency towards VIES; items are answered in order. Each item counts one call. Up to 100 items.", "tags": [ "VAT numbers" ], "security": [ { "apiKey": [] } ], "x-tiers": [ "plan" ], "x-cost": "1 call per item", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "number" ], "properties": { "country": { "type": "string" }, "number": { "type": "string" } } } }, "requester": { "type": "string", "description": "Applied to every item." } } }, "example": { "items": [ { "country": "DE", "number": "136695976" }, { "number": "FR40303265045" } ] } } } }, "responses": { "200": { "description": "One result per item, in order.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Tier": { "$ref": "#/components/headers/X-Tier" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/VatValidation" }, { "$ref": "#/components/schemas/Problem" } ] } }, "counted": { "type": "integer" } } } } } }, "400": { "description": "`invalid_parameter` — A parameter is missing or malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#invalid_parameter", "title": "A parameter is missing or malformed", "status": 400, "detail": "Read `detail` and `errors[]`: each entry names the parameter and the rule it broke. Nothing was counted against your quota.", "instance": "req_01HZX…", "code": "invalid_parameter" } } } }, "401": { "description": "`unauthorized` — The API key is missing, unknown or revoked.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#unauthorized", "title": "The API key is missing, unknown or revoked", "status": 401, "detail": "Send `Authorization: Bearer vp_live_…`. Keys are shown once at sign-up; a revoked key cannot be restored, create a new one.", "instance": "req_01HZX…", "code": "unauthorized" } } } }, "402": { "description": "`quota_exceeded` — Monthly allowance and credits are used up.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#quota_exceeded", "title": "Monthly allowance and credits are used up", "status": 402, "detail": "The free allowance resets on the first of the month (UTC). Buy a credit pack or the monthly plan at /pricing; the key stays the same.", "instance": "req_01HZX…", "code": "quota_exceeded" } } } }, "403": { "description": "`forbidden_for_tier` — This option is not included in your tier.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#forbidden_for_tier", "title": "This option is not included in your tier", "status": 403, "detail": "The `requester` option (consultation number) and the `record` option (a stored validation record) need prepaid credits or the monthly plan; the bulk endpoints need the monthly plan. See /pricing.", "instance": "req_01HZX…", "code": "forbidden_for_tier" } } } }, "429": { "description": "`rate_limited` — Too many requests per second.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#rate_limited", "title": "Too many requests per second", "status": 429, "detail": "Honour `Retry-After` and the `RateLimit-*` headers. Free keys may send 2 requests a second; the monthly plan 10. Use the bulk endpoint for lists.", "instance": "req_01HZX…", "code": "rate_limited" } } } } } } }, "/vat/validations": { "get": { "operationId": "listVatValidationRecords", "summary": "List the validation records kept on your account", "description": "The records made with `record=true`, newest first, on every key of the account (a rotated key keeps them). Open to every key, a lapsed plan included, and not counted. `format=csv` returns the same page as CSV with the next cursor in `X-Next-Cursor`.", "tags": [ "VAT numbers" ], "security": [ { "apiKey": [] } ], "x-tiers": [ "free", "credits", "plan" ], "x-cost": "free", "parameters": [ { "name": "number", "in": "query", "required": false, "description": "Only this VAT number, with or without its prefix (`country` supplies a missing prefix).", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "Two-letter prefix when `number` has none.", "schema": { "type": "string", "maxLength": 2 } }, { "name": "from", "in": "query", "required": false, "description": "Records made at or after this ISO 8601 date or instant.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "Records made before this ISO 8601 date or instant.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Records per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` of the previous page.", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "The answer format.", "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" } } ], "responses": { "200": { "description": "One page of records.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Tier": { "$ref": "#/components/headers/X-Tier" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "records", "nextCursor" ], "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationRecord" } }, "nextCursor": { "type": [ "string", "null" ] } } } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "`invalid_parameter` — A parameter is missing or malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#invalid_parameter", "title": "A parameter is missing or malformed", "status": 400, "detail": "Read `detail` and `errors[]`: each entry names the parameter and the rule it broke. Nothing was counted against your quota.", "instance": "req_01HZX…", "code": "invalid_parameter" } } } }, "401": { "description": "`unauthorized` — The API key is missing, unknown or revoked.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#unauthorized", "title": "The API key is missing, unknown or revoked", "status": 401, "detail": "Send `Authorization: Bearer vp_live_…`. Keys are shown once at sign-up; a revoked key cannot be restored, create a new one.", "instance": "req_01HZX…", "code": "unauthorized" } } } }, "429": { "description": "`rate_limited` — Too many requests per second.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#rate_limited", "title": "Too many requests per second", "status": 429, "detail": "Honour `Retry-After` and the `RateLimit-*` headers. Free keys may send 2 requests a second; the monthly plan 10. Use the bulk endpoint for lists.", "instance": "req_01HZX…", "code": "rate_limited" } } } } } } }, "/vat/validations/{id}": { "get": { "operationId": "getVatValidationRecord", "summary": "Get one validation record", "description": "One record of your account, as it was kept. Open to every key and not counted.", "tags": [ "VAT numbers" ], "security": [ { "apiKey": [] } ], "x-tiers": [ "free", "credits", "plan" ], "x-cost": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The record id (`vr_…`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The record.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Tier": { "$ref": "#/components/headers/X-Tier" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationRecord" } } } }, "401": { "description": "`unauthorized` — The API key is missing, unknown or revoked.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#unauthorized", "title": "The API key is missing, unknown or revoked", "status": 401, "detail": "Send `Authorization: Bearer vp_live_…`. Keys are shown once at sign-up; a revoked key cannot be restored, create a new one.", "instance": "req_01HZX…", "code": "unauthorized" } } } }, "404": { "description": "`not_found` — No such resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#not_found", "title": "No such resource", "status": 404, "detail": "Check the path against /openapi.json. Country codes are ISO 3166-1 alpha-2 (Greece is `EL` for VAT, `GR` for IBAN).", "instance": "req_01HZX…", "code": "not_found" } } } }, "429": { "description": "`rate_limited` — Too many requests per second.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#rate_limited", "title": "Too many requests per second", "status": 429, "detail": "Honour `Retry-After` and the `RateLimit-*` headers. Free keys may send 2 requests a second; the monthly plan 10. Use the bulk endpoint for lists.", "instance": "req_01HZX…", "code": "rate_limited" } } } } } }, "delete": { "operationId": "deleteVatValidationRecord", "summary": "Delete one validation record", "description": "Deletes the record for good. Records cannot be edited, only deleted. Open to every key and not counted.", "tags": [ "VAT numbers" ], "security": [ { "apiKey": [] } ], "x-tiers": [ "free", "credits", "plan" ], "x-cost": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The record id (`vr_…`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Tier": { "$ref": "#/components/headers/X-Tier" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "deleted" ], "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } }, "401": { "description": "`unauthorized` — The API key is missing, unknown or revoked.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#unauthorized", "title": "The API key is missing, unknown or revoked", "status": 401, "detail": "Send `Authorization: Bearer vp_live_…`. Keys are shown once at sign-up; a revoked key cannot be restored, create a new one.", "instance": "req_01HZX…", "code": "unauthorized" } } } }, "404": { "description": "`not_found` — No such resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#not_found", "title": "No such resource", "status": 404, "detail": "Check the path against /openapi.json. Country codes are ISO 3166-1 alpha-2 (Greece is `EL` for VAT, `GR` for IBAN).", "instance": "req_01HZX…", "code": "not_found" } } } }, "429": { "description": "`rate_limited` — Too many requests per second.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#rate_limited", "title": "Too many requests per second", "status": 429, "detail": "Honour `Retry-After` and the `RateLimit-*` headers. Free keys may send 2 requests a second; the monthly plan 10. Use the bulk endpoint for lists.", "instance": "req_01HZX…", "code": "rate_limited" } } } } } } }, "/vat/rates": { "get": { "operationId": "listVatRates", "summary": "EU VAT rates for all member states", "description": "The 27 rows of the rates table: standard, reduced, super-reduced and parking rates with category hints, each with its `verifiedOn` date and sources. Table verified on 2026-10-24; reviewed monthly. Optional `category` filter returns, for each country, the hint for that category.", "tags": [ "VAT rates" ], "security": [ { "apiKey": [] }, {} ], "x-tiers": [ "anonymous", "free", "credits", "plan" ], "x-cost": "1 call", "parameters": [ { "name": "category", "in": "query", "required": false, "description": "One of digital_services, ebooks, printed_books, foodstuffs, hotel_accommodation, restaurant, newspapers.", "schema": { "type": "string", "enum": [ "digital_services", "ebooks", "printed_books", "foodstuffs", "hotel_accommodation", "restaurant", "newspapers" ] }, "example": "ebooks" } ], "responses": { "200": { "description": "The table.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Tier": { "$ref": "#/components/headers/X-Tier" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "verifiedOn": { "type": "string", "format": "date" }, "nextReview": { "type": "string", "format": "date" }, "rates": { "type": "array", "items": { "$ref": "#/components/schemas/VatRates" } } } }, "example": { "verifiedOn": "2026-10-24", "nextReview": "2026-11-24", "rates": [ { "country": "FR", "name": "France", "currency": "EUR", "standard": 20, "reduced": [ 5.5, 10 ], "superReduced": 2.1, "parking": null, "hints": [ { "category": "digital_services", "rate": 20, "kind": "standard" }, { "category": "ebooks", "rate": 5.5, "kind": "reduced" }, { "category": "newspapers", "rate": 2.1, "kind": "super_reduced" } ], "verifiedOn": "2026-10-24", "sources": [ { "title": "VAT rates applied in the Member States of the European Union", "url": "https://taxation-customs.ec.europa.eu/taxation/vat/vat-rates_en", "consulted": "2026-10-24" } ], "note": "Corsica and the overseas departments apply other rates (not in this table)." } ] } } } }, "400": { "description": "`invalid_parameter` — A parameter is missing or malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#invalid_parameter", "title": "A parameter is missing or malformed", "status": 400, "detail": "Read `detail` and `errors[]`: each entry names the parameter and the rule it broke. Nothing was counted against your quota.", "instance": "req_01HZX…", "code": "invalid_parameter" } } } }, "401": { "description": "`unauthorized` — The API key is missing, unknown or revoked.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#unauthorized", "title": "The API key is missing, unknown or revoked", "status": 401, "detail": "Send `Authorization: Bearer vp_live_…`. Keys are shown once at sign-up; a revoked key cannot be restored, create a new one.", "instance": "req_01HZX…", "code": "unauthorized" } } } }, "402": { "description": "`quota_exceeded` — Monthly allowance and credits are used up.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#quota_exceeded", "title": "Monthly allowance and credits are used up", "status": 402, "detail": "The free allowance resets on the first of the month (UTC). Buy a credit pack or the monthly plan at /pricing; the key stays the same.", "instance": "req_01HZX…", "code": "quota_exceeded" } } } }, "429": { "description": "`rate_limited` — Too many requests per second.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#rate_limited", "title": "Too many requests per second", "status": 429, "detail": "Honour `Retry-After` and the `RateLimit-*` headers. Free keys may send 2 requests a second; the monthly plan 10. Use the bulk endpoint for lists.", "instance": "req_01HZX…", "code": "rate_limited" } } } } } } }, "/vat/rates/{country}": { "get": { "operationId": "getVatRates", "summary": "EU VAT rates for one member state", "description": "One row of the rates table with its category hints, `verifiedOn` date and sources. Greece is `EL` (GR accepted).", "tags": [ "VAT rates" ], "security": [ { "apiKey": [] }, {} ], "x-tiers": [ "anonymous", "free", "credits", "plan" ], "x-cost": "1 call", "parameters": [ { "name": "country", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2 of the member state.", "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "example": "FR" } ], "responses": { "200": { "description": "The row.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Tier": { "$ref": "#/components/headers/X-Tier" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatRates" }, "example": { "country": "FR", "name": "France", "currency": "EUR", "standard": 20, "reduced": [ 5.5, 10 ], "superReduced": 2.1, "parking": null, "hints": [ { "category": "digital_services", "rate": 20, "kind": "standard" }, { "category": "ebooks", "rate": 5.5, "kind": "reduced" }, { "category": "newspapers", "rate": 2.1, "kind": "super_reduced" } ], "verifiedOn": "2026-10-24", "sources": [ { "title": "VAT rates applied in the Member States of the European Union", "url": "https://taxation-customs.ec.europa.eu/taxation/vat/vat-rates_en", "consulted": "2026-10-24" } ], "note": "Corsica and the overseas departments apply other rates (not in this table)." } } } }, "401": { "description": "`unauthorized` — The API key is missing, unknown or revoked.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#unauthorized", "title": "The API key is missing, unknown or revoked", "status": 401, "detail": "Send `Authorization: Bearer vp_live_…`. Keys are shown once at sign-up; a revoked key cannot be restored, create a new one.", "instance": "req_01HZX…", "code": "unauthorized" } } } }, "402": { "description": "`quota_exceeded` — Monthly allowance and credits are used up.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#quota_exceeded", "title": "Monthly allowance and credits are used up", "status": 402, "detail": "The free allowance resets on the first of the month (UTC). Buy a credit pack or the monthly plan at /pricing; the key stays the same.", "instance": "req_01HZX…", "code": "quota_exceeded" } } } }, "404": { "description": "`not_found` — No such resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#not_found", "title": "No such resource", "status": 404, "detail": "Check the path against /openapi.json. Country codes are ISO 3166-1 alpha-2 (Greece is `EL` for VAT, `GR` for IBAN).", "instance": "req_01HZX…", "code": "not_found" } } } }, "429": { "description": "`rate_limited` — Too many requests per second.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#rate_limited", "title": "Too many requests per second", "status": 429, "detail": "Honour `Retry-After` and the `RateLimit-*` headers. Free keys may send 2 requests a second; the monthly plan 10. Use the bulk endpoint for lists.", "instance": "req_01HZX…", "code": "rate_limited" } } } } } } }, "/iban/validate": { "get": { "operationId": "validateIban", "summary": "Validate an IBAN", "description": "Normalises the input (case, spaces, dashes), then checks: allowed characters, known country, country length, the ISO 7064 mod 97-10 check digits, and the country’s BBAN pattern from the SWIFT IBAN Registry. Returns the bank and branch identifiers where the registry defines them and whether the country is in the SEPA geographical scope (EPC list). BIC lookup is not part of v1 (the BIC directory is licensed data); see the roadmap.", "tags": [ "IBAN" ], "security": [ { "apiKey": [] }, {} ], "x-tiers": [ "anonymous", "free", "credits", "plan" ], "x-cost": "1 call", "parameters": [ { "name": "iban", "in": "query", "required": true, "description": "The IBAN, electronic or paper form.", "schema": { "type": "string", "minLength": 5, "maxLength": 42 }, "example": "DE89 3704 0044 0532 0130 00" } ], "responses": { "200": { "description": "The result, valid or not (an invalid IBAN is a 200 with `valid: false` and `failures[]`).", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Tier": { "$ref": "#/components/headers/X-Tier" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IbanResult" }, "example": { "valid": true, "iban": "DE89370400440532013000", "formatted": "DE89 3704 0044 0532 0130 00", "countryCode": "DE", "countryName": "Germany", "checkDigits": "89", "bban": "370400440532013000", "bankIdentifier": "37040044", "branchIdentifier": null, "expectedLength": 22, "sepa": true, "sepaSince": null, "checks": { "characters": true, "country": true, "length": true, "mod97": true, "bbanPattern": true }, "failures": [], "registry": { "source": "SWIFT IBAN Registry (ISO 13616)", "verifiedOn": "2026-10-24" } } } } }, "400": { "description": "`invalid_parameter` — A parameter is missing or malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#invalid_parameter", "title": "A parameter is missing or malformed", "status": 400, "detail": "Read `detail` and `errors[]`: each entry names the parameter and the rule it broke. Nothing was counted against your quota.", "instance": "req_01HZX…", "code": "invalid_parameter" } } } }, "401": { "description": "`unauthorized` — The API key is missing, unknown or revoked.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#unauthorized", "title": "The API key is missing, unknown or revoked", "status": 401, "detail": "Send `Authorization: Bearer vp_live_…`. Keys are shown once at sign-up; a revoked key cannot be restored, create a new one.", "instance": "req_01HZX…", "code": "unauthorized" } } } }, "402": { "description": "`quota_exceeded` — Monthly allowance and credits are used up.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#quota_exceeded", "title": "Monthly allowance and credits are used up", "status": 402, "detail": "The free allowance resets on the first of the month (UTC). Buy a credit pack or the monthly plan at /pricing; the key stays the same.", "instance": "req_01HZX…", "code": "quota_exceeded" } } } }, "429": { "description": "`rate_limited` — Too many requests per second.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#rate_limited", "title": "Too many requests per second", "status": 429, "detail": "Honour `Retry-After` and the `RateLimit-*` headers. Free keys may send 2 requests a second; the monthly plan 10. Use the bulk endpoint for lists.", "instance": "req_01HZX…", "code": "rate_limited" } } } } } } }, "/iban/validate/bulk": { "post": { "operationId": "validateIbansBulk", "summary": "Validate up to 100 IBANs in one request", "description": "Monthly plan only. Each IBAN is answered in order; each counts one call. Up to 100 items.", "tags": [ "IBAN" ], "security": [ { "apiKey": [] } ], "x-tiers": [ "plan" ], "x-cost": "1 call per item", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ibans" ], "properties": { "ibans": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" } } } }, "example": { "ibans": [ "DE89370400440532013000", "FR7630006000011234567890189", "GB82WEST12345698765432" ] } } } }, "responses": { "200": { "description": "One result per IBAN, in order.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Tier": { "$ref": "#/components/headers/X-Tier" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/IbanResult" } }, "counted": { "type": "integer" } } } } } }, "400": { "description": "`invalid_parameter` — A parameter is missing or malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#invalid_parameter", "title": "A parameter is missing or malformed", "status": 400, "detail": "Read `detail` and `errors[]`: each entry names the parameter and the rule it broke. Nothing was counted against your quota.", "instance": "req_01HZX…", "code": "invalid_parameter" } } } }, "401": { "description": "`unauthorized` — The API key is missing, unknown or revoked.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#unauthorized", "title": "The API key is missing, unknown or revoked", "status": 401, "detail": "Send `Authorization: Bearer vp_live_…`. Keys are shown once at sign-up; a revoked key cannot be restored, create a new one.", "instance": "req_01HZX…", "code": "unauthorized" } } } }, "402": { "description": "`quota_exceeded` — Monthly allowance and credits are used up.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#quota_exceeded", "title": "Monthly allowance and credits are used up", "status": 402, "detail": "The free allowance resets on the first of the month (UTC). Buy a credit pack or the monthly plan at /pricing; the key stays the same.", "instance": "req_01HZX…", "code": "quota_exceeded" } } } }, "403": { "description": "`forbidden_for_tier` — This option is not included in your tier.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#forbidden_for_tier", "title": "This option is not included in your tier", "status": 403, "detail": "The `requester` option (consultation number) and the `record` option (a stored validation record) need prepaid credits or the monthly plan; the bulk endpoints need the monthly plan. See /pricing.", "instance": "req_01HZX…", "code": "forbidden_for_tier" } } } }, "429": { "description": "`rate_limited` — Too many requests per second.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#rate_limited", "title": "Too many requests per second", "status": 429, "detail": "Honour `Retry-After` and the `RateLimit-*` headers. Free keys may send 2 requests a second; the monthly plan 10. Use the bulk endpoint for lists.", "instance": "req_01HZX…", "code": "rate_limited" } } } } } } }, "/vat/oss/return": { "post": { "operationId": "buildOssReturn", "summary": "OSS return validator (lines only; dispatch-country breakdown not implemented)", "description": "OSS return validator (lines only; dispatch-country breakdown not implemented): the output is the set of return lines per member state of consumption, supply type and rate, checked against the rates table, not a filable return. Implementing Regulation (EU) 2020/194 Annex III also requires goods to be split by member state of dispatch or fixed establishment; the row model carries no dispatch country, so a seller shipping from stock in several member states cannot file from this output (assessment 2026-10-28). Send the quarter's (OSS) or month's (IOSS) B2C sales as JSON rows or as a CSV export (`Content-Type: text/csv`, header row in English, French or German; or JSON `{period, scheme, csv}`). Each row names the member state of consumption, the rate (or a rates-table category), the net amount, optionally the VAT amount, the supply date and the supply type. The service aggregates per member state, supply type and rate; validates every row against the dated rates table (the rate must be one the member state applies; a rate changed inside the table's window is accepted with a warning when the supply predates the change), reconciles VAT with net × rate, checks the dates against the period, and nets credit notes; rows marked `correctionOfPeriod` become the corrections section. Returns the per-country summary and the upload file. On 2026-10-24 no national portal format could be fetched (the BZSt publishes its CSV record layout only inside the logged-in form; the DGFiP publishes none), so the file is a clearly labelled generic CSV and `portals[]` says so per member state. Up to 50000 rows or 4.5 MB. Add `?output=csv` to receive the file itself instead of JSON. Send an `Idempotency-Key` header (1–128 characters, unique per request) and a retry after a dropped response replays the stored answer for 24 hours without a second charge (`Idempotent-Replayed: true`); the same key with a different body or query is refused with 409 `idempotency_conflict`.", "tags": [ "OSS return" ], "security": [ { "apiKey": [] } ], "x-tiers": [ "free", "credits", "plan" ], "x-cost": "25 calls per accepted return (0 when the rows are refused with 422; 0 on an Idempotency-Key replay)", "parameters": [ { "name": "output", "in": "query", "required": false, "description": "`json` (default): summary, files and portal notes. `csv`: the generic CSV file alone, with `Content-Disposition`.", "schema": { "type": "string", "enum": [ "json", "csv" ] }, "example": "json" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique per request (a UUID will do; `^[A-Za-z0-9_.:-]{1,128}$`). A retry with the same key, query and body replays the stored answer for 24 hours (`Idempotent-Replayed: true`) instead of building and charging a second return; another body under the same key is 409.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "period", "rows" ], "properties": { "period": { "type": "string", "description": "`2026-Q3` for OSS (quarterly), `2026-09` for IOSS (monthly)." }, "scheme": { "type": "string", "enum": [ "union", "non_union", "import" ], "description": "Default `union`." }, "rows": { "type": "array", "maxItems": 50000, "items": { "$ref": "#/components/schemas/OssSaleRow" } }, "csv": { "type": "string", "description": "Alternative to `rows`: the CSV text of the export." } } }, "example": { "period": "2026-Q3", "scheme": "union", "rows": [ { "country": "DE", "rate": 19, "net": 1250, "vat": 237.5, "date": "2026-07-14", "supplyType": "goods" }, { "country": "DE", "rate": 7, "net": 310, "vat": 21.7, "date": "2026-08-02", "supplyType": "goods" }, { "country": "FR", "category": "digital_services", "net": 980, "date": "2026-09-21" }, { "country": "IT", "rate": 22, "net": -45, "vat": -9.9, "date": "2026-05-30", "correctionOfPeriod": "2026-Q2" } ] } } } }, "responses": { "200": { "description": "The return: lines, corrections, totals, the file, and what each portal accepts.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Tier": { "$ref": "#/components/headers/X-Tier" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OssReturn" }, "example": { "scheme": "union", "period": { "label": "2026-Q3", "kind": "quarter", "start": "2026-07-01", "end": "2026-09-30", "dueDate": "2026-10-31" }, "currency": "EUR", "lines": [ { "country": "DE", "countryName": "Germany", "supplyType": "goods", "rateKind": "standard", "rate": 19, "rows": 1, "net": 1250, "vat": 237.5, "vatComputed": 237.5 }, { "country": "DE", "countryName": "Germany", "supplyType": "goods", "rateKind": "reduced", "rate": 7, "rows": 1, "net": 310, "vat": 21.7, "vatComputed": 21.7 }, { "country": "FR", "countryName": "France", "supplyType": "services", "rateKind": "standard", "rate": 20, "rows": 1, "net": 980, "vat": 196, "vatComputed": 196 } ], "corrections": [ { "period": "2026-Q2", "country": "IT", "countryName": "Italy", "rows": 1, "vat": -9.9, "net": -45 } ], "totals": { "rows": 4, "countries": 2, "net": 2540, "vat": 455.2, "correctionsVat": -9.9, "vatPayable": 445.3 }, "byCountry": [ { "country": "DE", "countryName": "Germany", "net": 1560, "vat": 259.2 }, { "country": "FR", "countryName": "France", "net": 980, "vat": 196 } ], "rates": { "verifiedOn": "2026-10-24" }, "warnings": [], "files": [ { "id": "generic_csv", "filename": "oss-return-union-2026-Q3-generic.csv", "contentType": "text/csv; charset=utf-8", "portal": null, "content": "period,scheme,member_state,member_state_name,supply_type,rate_kind,rate_percent,taxable_amount_eur,vat_amount_eur,rows,correction_of_period\r\n2026-Q3,union,DE,Germany,goods,standard,19,1250.00,237.50,1,\r\n…" } ], "portals": [ { "memberState": "FR", "portal": "impots.gouv.fr — guichet unique TVA (espace professionnel)", "status": "generic", "note": "No public file-import specification was found; key the lines in." }, { "memberState": "DE", "portal": "BZStOnline-Portal (Mein BOP)", "status": "generic", "note": "CSV import exists; its record layout is published only inside the logged-in form." } ] } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "`invalid_parameter` — A parameter is missing or malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#invalid_parameter", "title": "A parameter is missing or malformed", "status": 400, "detail": "Read `detail` and `errors[]`: each entry names the parameter and the rule it broke. Nothing was counted against your quota.", "instance": "req_01HZX…", "code": "invalid_parameter" } } } }, "401": { "description": "`unauthorized` — The API key is missing, unknown or revoked.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#unauthorized", "title": "The API key is missing, unknown or revoked", "status": 401, "detail": "Send `Authorization: Bearer vp_live_…`. Keys are shown once at sign-up; a revoked key cannot be restored, create a new one.", "instance": "req_01HZX…", "code": "unauthorized" } } } }, "402": { "description": "`quota_exceeded` — Monthly allowance and credits are used up.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#quota_exceeded", "title": "Monthly allowance and credits are used up", "status": 402, "detail": "The free allowance resets on the first of the month (UTC). Buy a credit pack or the monthly plan at /pricing; the key stays the same.", "instance": "req_01HZX…", "code": "quota_exceeded" } } } }, "409": { "description": "`idempotency_conflict` — The Idempotency-Key is in use.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#idempotency_conflict", "title": "The Idempotency-Key is in use", "status": 409, "detail": "The same `Idempotency-Key` was sent with a different body or query (a key is bound to one request), or a request with that key is still being processed. Send a new key for a new request; retry the same request after `Retry-After` seconds when it was still in progress. Nothing was counted.", "instance": "req_01HZX…", "code": "idempotency_conflict" } } } }, "413": { "description": "`payload_too_large` — Too many rows or too many bytes.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#payload_too_large", "title": "Too many rows or too many bytes", "status": 413, "detail": "A request body is limited to 4.5 MB (4,500,000 bytes, the hosting platform’s limit); one OSS return to 50,000 rows. Aggregate per country and rate before sending, or split the quarter by month; for an e-invoice, send the XML rather than a PDF carrying large attachments.", "instance": "req_01HZX…", "code": "payload_too_large" } } } }, "422": { "description": "`unprocessable_file` — The uploaded rows cannot be turned into a return.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#unprocessable_file", "title": "The uploaded rows cannot be turned into a return", "status": 422, "detail": "Read `errors[]`: each entry names the row (1-based, header excluded) and the rule it broke (unknown country, rate not in the table for the period, VAT does not equal net × rate, date outside the period). Fix the export and resend; nothing was counted.", "instance": "req_01HZX…", "code": "unprocessable_file" } } } }, "429": { "description": "`rate_limited` — Too many requests per second.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#rate_limited", "title": "Too many requests per second", "status": 429, "detail": "Honour `Retry-After` and the `RateLimit-*` headers. Free keys may send 2 requests a second; the monthly plan 10. Use the bulk endpoint for lists.", "instance": "req_01HZX…", "code": "rate_limited" } } } } } } }, "/fr/company/{id}": { "get": { "operationId": "getFrenchCompany", "summary": "French company by SIREN or SIRET", "description": "Looks the identifier up (spaces and dots removed; a French VAT number is accepted and its SIREN used), checks its Luhn key, then asks the open Recherche d'entreprises API (INSEE Sirene + INPI RNE data, 7 requests a second shared by everyone) and, when the operator has configured an INSEE key, the INSEE Sirene API for the unité légale. Answers are cached 7 days (served marked `stale` up to 30 days when the registries are down) and normalised: legal form, NAF code and section, status, address, headcount band, company category, establishments, the computed VAT number, officers where the open RNE data gives them. Every answer carries `source` (which APIs answered, cache hit and age) and `fetchedOn`. A SIRET answers the company with that establishment under `establishment`.", "tags": [ "French companies" ], "security": [ { "apiKey": [] }, {} ], "x-tiers": [ "anonymous", "free", "credits", "plan" ], "x-cost": "1 call (cached or live); 0 on 404 or 503", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "SIREN (9 digits), SIRET (14 digits) or a French VAT number; spaces and dots allowed.", "schema": { "type": "string", "minLength": 9, "maxLength": 20 }, "example": "356000000" } ], "responses": { "200": { "description": "The company.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Tier": { "$ref": "#/components/headers/X-Tier" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FrCompany" }, "example": { "siren": "356000000", "name": "LA POSTE", "legalName": "LA POSTE", "acronym": null, "legalForm": { "code": "5510", "label": "SA nationale à conseil d’administration" }, "naf": { "code": "53.10Z", "section": "H", "sectionLabel": "Transportation and storage" }, "status": "active", "createdOn": "1991-01-01", "ceasedOn": null, "headcountBand": { "code": "53", "label": "10,000 employees or more", "year": "2023" }, "companyCategory": { "code": "GE", "label": "Large enterprise (GE)", "year": "2023" }, "employer": true, "diffusion": "O", "address": { "street": "9 RUE DU COLONEL PIERRE AVIA", "postalCode": "75015", "city": "PARIS", "cityCode": "75115", "country": "FR", "full": "9 RUE DU COLONEL PIERRE AVIA 75015 PARIS" }, "headquarters": { "siret": "35600000000048", "isHeadquarters": true, "status": "active", "naf": "53.10Z", "address": { "street": "9 RUE DU COLONEL PIERRE AVIA", "postalCode": "75015", "city": "PARIS", "cityCode": "75115", "country": "FR", "full": "9 RUE DU COLONEL PIERRE AVIA 75015 PARIS" }, "createdOn": "2014-01-01", "closedOn": null, "tradeName": null, "headcountBand": null }, "establishment": null, "establishments": { "total": 12345, "open": 9876 }, "vatNumber": { "computed": "FR39356000000", "activeNumbers": [ "FR39356000000" ], "note": "computed from the SIREN; validate it with GET /vat/validate before relying on it." }, "officers": [ { "type": "person", "name": "EXEMPLE", "firstNames": "PRÉNOM", "role": "Président du conseil d’administration", "birthYear": null, "nationality": "Française", "siren": null } ], "updatedOn": { "registry": "2026-10-20", "insee": "2026-10-19", "rne": "2026-10-18" }, "source": { "primary": "recherche_entreprises", "insee": false, "openData": [ "recherche_entreprises", "inpi_rne" ], "fetchedOn": "2026-10-24T09:14:03Z", "cache": { "hit": false, "ageSeconds": 0, "stale": false } } } } } }, "400": { "description": "`invalid_parameter` — A parameter is missing or malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#invalid_parameter", "title": "A parameter is missing or malformed", "status": 400, "detail": "Read `detail` and `errors[]`: each entry names the parameter and the rule it broke. Nothing was counted against your quota.", "instance": "req_01HZX…", "code": "invalid_parameter" } } } }, "401": { "description": "`unauthorized` — The API key is missing, unknown or revoked.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#unauthorized", "title": "The API key is missing, unknown or revoked", "status": 401, "detail": "Send `Authorization: Bearer vp_live_…`. Keys are shown once at sign-up; a revoked key cannot be restored, create a new one.", "instance": "req_01HZX…", "code": "unauthorized" } } } }, "402": { "description": "`quota_exceeded` — Monthly allowance and credits are used up.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#quota_exceeded", "title": "Monthly allowance and credits are used up", "status": 402, "detail": "The free allowance resets on the first of the month (UTC). Buy a credit pack or the monthly plan at /pricing; the key stays the same.", "instance": "req_01HZX…", "code": "quota_exceeded" } } } }, "404": { "description": "`not_found` — No such resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#not_found", "title": "No such resource", "status": 404, "detail": "Check the path against /openapi.json. Country codes are ISO 3166-1 alpha-2 (Greece is `EL` for VAT, `GR` for IBAN).", "instance": "req_01HZX…", "code": "not_found" } } } }, "429": { "description": "`rate_limited` — Too many requests per second.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#rate_limited", "title": "Too many requests per second", "status": 429, "detail": "Honour `Retry-After` and the `RateLimit-*` headers. Free keys may send 2 requests a second; the monthly plan 10. Use the bulk endpoint for lists.", "instance": "req_01HZX…", "code": "rate_limited" } } } }, "503": { "description": "`upstream_unavailable` — The public registry did not answer and no cached answer exists.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#upstream_unavailable", "title": "The public registry did not answer and no cached answer exists", "status": 503, "detail": "The French company-registry APIs (recherche-entreprises.api.gouv.fr, INSEE Sirene) did not answer in time or refused the request. Retry after `Retry-After` seconds; the call was not counted.", "instance": "req_01HZX…", "code": "upstream_unavailable" } } } } } } }, "/fr/company/bulk": { "post": { "operationId": "getFrenchCompaniesBulk", "summary": "Up to 100 French companies in one request", "description": "Monthly plan only. Each identifier is answered as `GET /fr/company/{id}` would, in order; the upstream calls are paced inside the shared 7 requests a second of the open API (and 30 a minute for INSEE when configured), with cached answers served first. Each answered item counts one call; refused items are problem documents in place and cost nothing.", "tags": [ "French companies" ], "security": [ { "apiKey": [] } ], "x-tiers": [ "plan" ], "x-cost": "1 call per answered item", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" } } } }, "example": { "ids": [ "356000000", "35600000000048", "FR40303265045" ] } } } }, "responses": { "200": { "description": "One result per identifier, in order.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Tier": { "$ref": "#/components/headers/X-Tier" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/FrCompany" }, { "$ref": "#/components/schemas/Problem" } ] } }, "counted": { "type": "integer" } } } } } }, "400": { "description": "`invalid_parameter` — A parameter is missing or malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#invalid_parameter", "title": "A parameter is missing or malformed", "status": 400, "detail": "Read `detail` and `errors[]`: each entry names the parameter and the rule it broke. Nothing was counted against your quota.", "instance": "req_01HZX…", "code": "invalid_parameter" } } } }, "401": { "description": "`unauthorized` — The API key is missing, unknown or revoked.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#unauthorized", "title": "The API key is missing, unknown or revoked", "status": 401, "detail": "Send `Authorization: Bearer vp_live_…`. Keys are shown once at sign-up; a revoked key cannot be restored, create a new one.", "instance": "req_01HZX…", "code": "unauthorized" } } } }, "402": { "description": "`quota_exceeded` — Monthly allowance and credits are used up.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#quota_exceeded", "title": "Monthly allowance and credits are used up", "status": 402, "detail": "The free allowance resets on the first of the month (UTC). Buy a credit pack or the monthly plan at /pricing; the key stays the same.", "instance": "req_01HZX…", "code": "quota_exceeded" } } } }, "403": { "description": "`forbidden_for_tier` — This option is not included in your tier.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#forbidden_for_tier", "title": "This option is not included in your tier", "status": 403, "detail": "The `requester` option (consultation number) and the `record` option (a stored validation record) need prepaid credits or the monthly plan; the bulk endpoints need the monthly plan. See /pricing.", "instance": "req_01HZX…", "code": "forbidden_for_tier" } } } }, "429": { "description": "`rate_limited` — Too many requests per second.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#rate_limited", "title": "Too many requests per second", "status": 429, "detail": "Honour `Retry-After` and the `RateLimit-*` headers. Free keys may send 2 requests a second; the monthly plan 10. Use the bulk endpoint for lists.", "instance": "req_01HZX…", "code": "rate_limited" } } } } } } }, "/us/sales-tax": { "get": { "operationId": "getUsSalesTax", "summary": "US sales-tax rate for a ZIP code", "description": "State rate and, where the state's revenue department publishes an open ZIP-keyed file (OH, WA on 2026-10-24), the combined state + local rate averaged across the jurisdictions in the ZIP with its minimum and maximum. `coverage` says what you got: `zip_average`, `state_only` (state rate plus the statewide population-weighted average and maximum local rates, from the dated 51-row table), or `none` (unknown prefix, territory, military mail). Address-level jurisdiction assignment is not offered. Table verified 2026-10-24; next review 2027-01-15.", "tags": [ "US sales tax" ], "security": [ { "apiKey": [] }, {} ], "x-tiers": [ "anonymous", "free", "credits", "plan" ], "x-cost": "1 call", "parameters": [ { "name": "zip", "in": "query", "required": true, "description": "Five-digit ZIP; ZIP+4 accepted, the +4 is ignored.", "schema": { "type": "string", "minLength": 5, "maxLength": 10 }, "example": "98101" } ], "responses": { "200": { "description": "The lookup, with its coverage.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Tier": { "$ref": "#/components/headers/X-Tier" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsSalesTax" }, "example": { "zip": "98101", "state": "WA", "stateName": "Washington", "coverage": "zip_average", "stateRate": 6.5, "combined": { "average": 10.55, "min": 10.55, "max": 10.55, "jurisdictions": 1, "period": "2026Q4", "fetchedOn": "2026-10-24", "method": "Average of the combined rates of the ZIP+4 ranges in the ZIP, weighted by range width; min and max over those ranges." }, "statewide": null, "verifiedOn": "2026-10-24", "nextReview": "2027-01-15", "sources": [ { "title": "Washington State Department of Revenue — downloadable database", "url": "https://dor.wa.gov/taxes-rates/sales-use-tax-rates/downloadable-database", "consulted": "2026-10-24" } ], "notes": [ "Address-level jurisdiction assignment is not offered: a ZIP is a postal route, not a tax boundary." ] } } } }, "400": { "description": "`invalid_parameter` — A parameter is missing or malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#invalid_parameter", "title": "A parameter is missing or malformed", "status": 400, "detail": "Read `detail` and `errors[]`: each entry names the parameter and the rule it broke. Nothing was counted against your quota.", "instance": "req_01HZX…", "code": "invalid_parameter" } } } }, "401": { "description": "`unauthorized` — The API key is missing, unknown or revoked.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#unauthorized", "title": "The API key is missing, unknown or revoked", "status": 401, "detail": "Send `Authorization: Bearer vp_live_…`. Keys are shown once at sign-up; a revoked key cannot be restored, create a new one.", "instance": "req_01HZX…", "code": "unauthorized" } } } }, "402": { "description": "`quota_exceeded` — Monthly allowance and credits are used up.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#quota_exceeded", "title": "Monthly allowance and credits are used up", "status": 402, "detail": "The free allowance resets on the first of the month (UTC). Buy a credit pack or the monthly plan at /pricing; the key stays the same.", "instance": "req_01HZX…", "code": "quota_exceeded" } } } }, "429": { "description": "`rate_limited` — Too many requests per second.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#rate_limited", "title": "Too many requests per second", "status": 429, "detail": "Honour `Retry-After` and the `RateLimit-*` headers. Free keys may send 2 requests a second; the monthly plan 10. Use the bulk endpoint for lists.", "instance": "req_01HZX…", "code": "rate_limited" } } } } } } }, "/einvoice/create": { "post": { "operationId": "createEInvoice", "summary": "Create an e-invoice (XRechnung, ZUGFeRD / Factur-X, Peppol BIS)", "description": "Send the invoice as JSON (the InvoiceInput schema: seller, buyer, lines, VAT, allowances and charges, payment, references) and `format`: `xrechnung-ubl` (XRechnung 3.0, UBL 2.1), `xrechnung-cii` (XRechnung 3.0, CII D16B), `zugferd` (ZUGFeRD 2.x / Factur-X 1.0, profile EN 16931: a PDF/A-3 with the CII embedded as factur-x.xml) or `peppol-bis` (Peppol BIS Billing 3.0, UBL 2.1, with the Belgian rules). The answer is the file itself, with its validation summary in the `Veriport-Validation` header; `?envelope=json` returns { file (base64), contentType, validation, defaults } instead.\n\nNothing is ever dropped silently: every field of the input is written, or the request is refused with 422 `einvoice_unsupported` naming the feature and its path (`feature`, `path`, `unsupported[]`). The input is checked against the engine's rules first (422 `einvoice_invalid` with the published rule ids and the JSON paths), the arithmetic is computed (line nets, VAT per breakdown, totals), the file is written, and the file is then run through the XML schema and the official schematron (CEN EN 16931 1.3.16, XRechnung 3.0.2, Peppol BIS 3.0.21); a fatal finding there withholds the file. Every value the engine adds (a VATEX code for reverse charge, the § 19 UStG mention, a 0208 Peppol address, a due date from paymentTermsDays) is listed in `defaults` and counted in the `Veriport-Defaults` header.\n\nv1 writes: EUR; a seller in Germany (XRechnung, ZUGFeRD) or Belgium (Peppol BIS); a buyer in any EU member state; VAT categories S, Z, E, AE and K; invoice 380, credit note 381, corrected invoice 384; SEPA credit transfer or credit transfer; up to 500 lines; document-level allowances and charges. It does not send the invoice (no Peppol access point), does not store it, and gives no tax advice. Up to 4.5 MB (4500000 bytes) per request. Send an `Idempotency-Key` (1–128 characters): a retry replays the same file without a second charge for 24 hours; nothing of the invoice is kept for that, only the time of the first build.", "tags": [ "E-invoices" ], "security": [ { "apiKey": [] } ], "x-tiers": [ "free", "credits", "plan" ], "x-cost": "20 calls per produced file; 0 when refused (400, 413, 422) and on an Idempotency-Key replay", "parameters": [ { "name": "envelope", "in": "query", "required": false, "description": "`json`: { format, filename, contentType, size, file (base64), validation, defaults } instead of the file.", "schema": { "type": "string", "enum": [ "json" ] } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique per request (`^[A-Za-z0-9_.:-]{1,128}$`). The same key, query and body within 24 hours replays the same file (`Idempotent-Replayed: true`), rebuilt from the request, not stored; another body under the key is 409.", "schema": { "type": "string", "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceInput" }, "example": { "number": "2026-017", "issueDate": "2026-10-20", "paymentTermsDays": 14, "buyerReference": "EK-2026-0345", "deliveryDate": "2026-10-15", "seller": { "name": "Lena Hartmann — Webdesign", "address": { "street": "Lindenstraße 14", "postalCode": "10969", "city": "Berlin", "countryCode": "DE" }, "vatId": "DE136695976", "contact": { "name": "Lena Hartmann", "phone": "+49 30 1234567", "email": "rechnung@hartmann-webdesign.example" } }, "buyer": { "name": "Mustermann Maschinenbau GmbH", "address": { "street": "Industrieweg 7", "postalCode": "70565", "city": "Stuttgart", "countryCode": "DE" }, "contact": { "email": "buchhaltung@mustermann.example" } }, "payment": { "iban": "DE02120300000000202051" }, "lines": [ { "name": "Relaunch Website, Konzeption und Umsetzung", "quantity": 24, "unitCode": "HUR", "unitPrice": 95, "vat": { "category": "S", "rate": 19 } }, { "name": "Lizenz Bildmaterial", "quantity": 1, "unitCode": "C62", "unitPrice": 128.4, "vat": { "category": "S", "rate": 19 } } ], "format": "xrechnung-ubl" } } } }, "responses": { "200": { "description": "The e-invoice file (or, with ?envelope=json, the envelope).", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Tier": { "$ref": "#/components/headers/X-Tier" }, "Veriport-Validation": { "description": "`valid; profile=; errors=0; warnings=`: the official check of the produced file.", "schema": { "type": "string" } }, "Veriport-Defaults": { "description": "How many values the engine added (listed in the envelope).", "schema": { "type": "integer" } }, "Content-Disposition": { "description": "`attachment; filename=\"…\"`", "schema": { "type": "string" } } }, "content": { "application/xml": { "schema": { "type": "string", "description": "XRechnung (UBL or CII) or Peppol BIS XML, UTF-8." } }, "application/pdf": { "schema": { "type": "string", "format": "binary", "description": "ZUGFeRD / Factur-X PDF/A-3b with factur-x.xml embedded." } }, "application/json": { "schema": { "$ref": "#/components/schemas/EInvoiceEnvelope" } } } }, "400": { "description": "`invalid_parameter` — A parameter is missing or malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#invalid_parameter", "title": "A parameter is missing or malformed", "status": 400, "detail": "Read `detail` and `errors[]`: each entry names the parameter and the rule it broke. Nothing was counted against your quota.", "instance": "req_01HZX…", "code": "invalid_parameter" } } } }, "401": { "description": "`unauthorized` — The API key is missing, unknown or revoked.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#unauthorized", "title": "The API key is missing, unknown or revoked", "status": 401, "detail": "Send `Authorization: Bearer vp_live_…`. Keys are shown once at sign-up; a revoked key cannot be restored, create a new one.", "instance": "req_01HZX…", "code": "unauthorized" } } } }, "402": { "description": "`quota_exceeded` — Monthly allowance and credits are used up.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#quota_exceeded", "title": "Monthly allowance and credits are used up", "status": 402, "detail": "The free allowance resets on the first of the month (UTC). Buy a credit pack or the monthly plan at /pricing; the key stays the same.", "instance": "req_01HZX…", "code": "quota_exceeded" } } } }, "409": { "description": "`idempotency_conflict` — The Idempotency-Key is in use.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#idempotency_conflict", "title": "The Idempotency-Key is in use", "status": 409, "detail": "The same `Idempotency-Key` was sent with a different body or query (a key is bound to one request), or a request with that key is still being processed. Send a new key for a new request; retry the same request after `Retry-After` seconds when it was still in progress. Nothing was counted.", "instance": "req_01HZX…", "code": "idempotency_conflict" } } } }, "413": { "description": "`payload_too_large` — Too many rows or too many bytes.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#payload_too_large", "title": "Too many rows or too many bytes", "status": 413, "detail": "A request body is limited to 4.5 MB (4,500,000 bytes, the hosting platform’s limit); one OSS return to 50,000 rows. Aggregate per country and rate before sending, or split the quarter by month; for an e-invoice, send the XML rather than a PDF carrying large attachments.", "instance": "req_01HZX…", "code": "payload_too_large" } } } }, "422": { "description": "`einvoice_unsupported` — The invoice uses a feature the e-invoice writers do not produce. `einvoice_invalid` — The invoice breaks the rules of its format.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#einvoice_invalid", "title": "The invoice breaks the rules of its format", "status": 422, "detail": "Read `violations[]`: each names the published rule (BR-*, BR-DE-*, PEPPOL-*, or VP-* for Veriport’s own checks of national practice), its path in your JSON (or the XPath in the produced file) and what it requires. No file was produced and nothing was counted.", "instance": "req_01HZX…", "code": "einvoice_invalid" } } } }, "429": { "description": "`rate_limited` — Too many requests per second.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#rate_limited", "title": "Too many requests per second", "status": 429, "detail": "Honour `Retry-After` and the `RateLimit-*` headers. Free keys may send 2 requests a second; the monthly plan 10. Use the bulk endpoint for lists.", "instance": "req_01HZX…", "code": "rate_limited" } } } } } } }, "/einvoice/validate": { "post": { "operationId": "validateEInvoice", "summary": "Validate an e-invoice against the official rules", "description": "Send an XRechnung, Peppol BIS or EN 16931 XML (UBL 2.1 Invoice or CreditNote, UN/CEFACT CII D16B) or a ZUGFeRD / Factur-X hybrid PDF, as the raw body (Content-Type application/xml or application/pdf) or as the `file` field of multipart/form-data. The XML schema and the official schematron of the document's profile run in-process: CEN EN 16931 1.3.16 always, XRechnung 3.0.2 (2.6.0) for an XRechnung, Peppol BIS Billing 3.0.21 for a Peppol document, with the severities of the KoSIT XRechnung configuration. Rule ids and messages are the published ones (CEN and Peppol in English, the XRechnung BR-DE rules in German); Veriport's own checks of national practice (VP-DE-*, VP-BE-*, VP-EU-*) come as warnings only. The evidence that this check names the same rules as the KoSIT validator, file by file, is at /einvoice-api. Not checked: PDF/A-3 conformance of a hybrid PDF (`checks.pdfa`: not_checked), Factur-X MINIMUM, BASIC WL and EXTENDED profiles (422 einvoice_unsupported). Without a key, 4 checks a day per address. The document is not stored.", "tags": [ "E-invoices" ], "security": [ { "apiKey": [] }, {} ], "x-tiers": [ "anonymous", "free", "credits", "plan" ], "x-cost": "5 calls per report (valid or not); 0 for an unreadable file or an unsupported profile", "requestBody": { "required": true, "description": "The e-invoice file.", "content": { "application/xml": { "schema": { "type": "string" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "The validation report (`valid: false` with the errors when the document breaks a rule).", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Tier": { "$ref": "#/components/headers/X-Tier" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EInvoiceValidation" }, "example": { "valid": true, "profile": "xrechnung", "format": "xrechnung-ubl", "syntax": "ubl", "container": "xml", "attachment": null, "errors": [], "warnings": [], "checks": { "schema": { "status": "passed", "name": "UBL 2.1 (OASIS) and UN/CEFACT CII D16B XML schemas, from the KoSIT XRechnung validator configuration v2026-08-31" }, "ruleSets": [ { "id": "cen-ubl", "name": "CEN EN 16931 validation artefacts (UBL)", "release": "1.3.16", "sha256": "bafada015efbc5248bf5e05ad2191e1d9833ef96e9dd5f4bce420a747342da85", "fatal": 0, "warnings": 0 }, { "id": "xrechnung-ubl", "name": "XRechnung 3.0.2 schematron (UBL)", "release": "2.6.0", "sha256": "ca5e07afd04e72cd283d581590ffff3a15f4aac9d2f40c993345d78e67ea22b4", "fatal": 0, "warnings": 0 } ], "pdfa": null, "veriport": 0 }, "ms": 84 } } } }, "400": { "description": "`invalid_parameter` — A parameter is missing or malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#invalid_parameter", "title": "A parameter is missing or malformed", "status": 400, "detail": "Read `detail` and `errors[]`: each entry names the parameter and the rule it broke. Nothing was counted against your quota.", "instance": "req_01HZX…", "code": "invalid_parameter" } } } }, "401": { "description": "`unauthorized` — The API key is missing, unknown or revoked.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#unauthorized", "title": "The API key is missing, unknown or revoked", "status": 401, "detail": "Send `Authorization: Bearer vp_live_…`. Keys are shown once at sign-up; a revoked key cannot be restored, create a new one.", "instance": "req_01HZX…", "code": "unauthorized" } } } }, "402": { "description": "`quota_exceeded` — Monthly allowance and credits are used up.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#quota_exceeded", "title": "Monthly allowance and credits are used up", "status": 402, "detail": "The free allowance resets on the first of the month (UTC). Buy a credit pack or the monthly plan at /pricing; the key stays the same.", "instance": "req_01HZX…", "code": "quota_exceeded" } } } }, "413": { "description": "`payload_too_large` — Too many rows or too many bytes.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#payload_too_large", "title": "Too many rows or too many bytes", "status": 413, "detail": "A request body is limited to 4.5 MB (4,500,000 bytes, the hosting platform’s limit); one OSS return to 50,000 rows. Aggregate per country and rate before sending, or split the quarter by month; for an e-invoice, send the XML rather than a PDF carrying large attachments.", "instance": "req_01HZX…", "code": "payload_too_large" } } } }, "422": { "description": "`einvoice_unreadable` — The file is not an e-invoice the API can read. `einvoice_unsupported` — The invoice uses a feature the e-invoice writers do not produce.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#einvoice_unsupported", "title": "The invoice uses a feature the e-invoice writers do not produce", "status": 422, "detail": "Nothing is ever dropped silently: a field the writers cannot put in the file is refused. Read `feature` and `path` (the first one) and `unsupported[]` (all of them), remove or change those fields, and resend. The list of what v1 does not write is on /einvoice-api. Nothing was counted.", "instance": "req_01HZX…", "code": "einvoice_unsupported" } } } }, "429": { "description": "`rate_limited` — Too many requests per second.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#rate_limited", "title": "Too many requests per second", "status": 429, "detail": "Honour `Retry-After` and the `RateLimit-*` headers. Free keys may send 2 requests a second; the monthly plan 10. Use the bulk endpoint for lists.", "instance": "req_01HZX…", "code": "rate_limited" } } } } } } }, "/einvoice/parse": { "post": { "operationId": "parseEInvoice", "summary": "Read an e-invoice as invoice JSON or a readable PDF", "description": "Send an XML or hybrid PDF e-invoice (raw body or the `file` field of multipart/form-data). The answer is the invoice in the create model (the same JSON POST /einvoice/create accepts), its format and profile, and `notInJson`: everything the document holds that the JSON does not (attachments, line periods, a paid amount, other payment means, totals that differ from the recomputation…), so nothing is dropped silently. A file the API wrote parses with an empty list and writes the same file again. `?as=pdf` returns a readable PDF/A-3 copy instead (`?lang=de|en|fr|nl`). The document is not stored.", "tags": [ "E-invoices" ], "security": [ { "apiKey": [] } ], "x-tiers": [ "free", "credits", "plan" ], "x-cost": "5 calls per answer; 0 for an unreadable file", "parameters": [ { "name": "as", "in": "query", "required": false, "description": "`json` (default) or `pdf` (a readable copy).", "schema": { "type": "string", "enum": [ "json", "pdf" ] } }, { "name": "lang", "in": "query", "required": false, "description": "Labels of the readable PDF: de, en, fr, nl (default from the seller’s country).", "schema": { "type": "string", "enum": [ "de", "en", "fr", "nl" ] } } ], "requestBody": { "required": true, "description": "The e-invoice file.", "content": { "application/xml": { "schema": { "type": "string" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "The invoice JSON (or the PDF with ?as=pdf).", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "X-Quota-Remaining": { "$ref": "#/components/headers/X-Quota-Remaining" }, "X-Tier": { "$ref": "#/components/headers/X-Tier" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EInvoiceParse" }, "example": { "invoice": { "format": "xrechnung-ubl", "type": "invoice", "number": "2026-017", "issueDate": "2026-10-20", "dueDate": "2026-11-03", "currency": "EUR", "buyerReference": "EK-2026-0345", "deliveryDate": "2026-10-15", "seller": { "name": "Lena Hartmann — Webdesign", "address": { "street": "Lindenstraße 14", "city": "Berlin", "postalCode": "10969", "countryCode": "DE" }, "vatId": "DE136695976", "electronicAddress": { "scheme": "EM", "id": "rechnung@hartmann-webdesign.example" }, "contact": { "name": "Lena Hartmann", "phone": "+49 30 1234567", "email": "rechnung@hartmann-webdesign.example" }, "vatScheme": "standard" }, "buyer": { "name": "Mustermann Maschinenbau GmbH", "address": { "street": "Industrieweg 7", "city": "Stuttgart", "postalCode": "70565", "countryCode": "DE" }, "electronicAddress": { "scheme": "EM", "id": "buchhaltung@mustermann.example" }, "contact": { "email": "buchhaltung@mustermann.example" } }, "payment": { "means": "sepa_credit_transfer", "iban": "DE02120300000000202051" }, "lines": [ { "id": "1", "name": "Relaunch Website, Konzeption und Umsetzung", "quantity": 24, "unitCode": "HUR", "unitPrice": 95, "vat": { "category": "S", "rate": 19 } }, { "id": "2", "name": "Lizenz Bildmaterial", "quantity": 1, "unitCode": "C62", "unitPrice": 128.4, "vat": { "category": "S", "rate": 19 } } ] }, "format": "xrechnung-ubl", "formatLabel": "XRechnung 3.0 (UBL 2.1)", "profile": "xrechnung", "syntax": "ubl", "container": "xml", "attachment": null, "notInJson": [] } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "`invalid_parameter` — A parameter is missing or malformed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#invalid_parameter", "title": "A parameter is missing or malformed", "status": 400, "detail": "Read `detail` and `errors[]`: each entry names the parameter and the rule it broke. Nothing was counted against your quota.", "instance": "req_01HZX…", "code": "invalid_parameter" } } } }, "401": { "description": "`unauthorized` — The API key is missing, unknown or revoked.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#unauthorized", "title": "The API key is missing, unknown or revoked", "status": 401, "detail": "Send `Authorization: Bearer vp_live_…`. Keys are shown once at sign-up; a revoked key cannot be restored, create a new one.", "instance": "req_01HZX…", "code": "unauthorized" } } } }, "402": { "description": "`quota_exceeded` — Monthly allowance and credits are used up.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#quota_exceeded", "title": "Monthly allowance and credits are used up", "status": 402, "detail": "The free allowance resets on the first of the month (UTC). Buy a credit pack or the monthly plan at /pricing; the key stays the same.", "instance": "req_01HZX…", "code": "quota_exceeded" } } } }, "413": { "description": "`payload_too_large` — Too many rows or too many bytes.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#payload_too_large", "title": "Too many rows or too many bytes", "status": 413, "detail": "A request body is limited to 4.5 MB (4,500,000 bytes, the hosting platform’s limit); one OSS return to 50,000 rows. Aggregate per country and rate before sending, or split the quarter by month; for an e-invoice, send the XML rather than a PDF carrying large attachments.", "instance": "req_01HZX…", "code": "payload_too_large" } } } }, "422": { "description": "`einvoice_unreadable` — The file is not an e-invoice the API can read.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#einvoice_unreadable", "title": "The file is not an e-invoice the API can read", "status": 422, "detail": "Send a UBL 2.1 Invoice or CreditNote, a UN/CEFACT CII D16B CrossIndustryInvoice, or a ZUGFeRD / Factur-X PDF with its XML embedded; as the raw body (Content-Type application/xml or application/pdf) or as the `file` part of multipart/form-data. Nothing was counted.", "instance": "req_01HZX…", "code": "einvoice_unreadable" } } } }, "429": { "description": "`rate_limited` — Too many requests per second.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#rate_limited", "title": "Too many requests per second", "status": 429, "detail": "Honour `Retry-After` and the `RateLimit-*` headers. Free keys may send 2 requests a second; the monthly plan 10. Use the bulk endpoint for lists.", "instance": "req_01HZX…", "code": "rate_limited" } } } } } } }, "/me": { "get": { "operationId": "getMe", "summary": "Your key, tier, usage and credits", "description": "Does not count as a call. Shows the calendar month’s usage against the allowance, the credit balance and its earliest expiry, and the plan status.", "tags": [ "Account" ], "security": [ { "apiKey": [] } ], "x-tiers": [ "free", "credits", "plan" ], "x-cost": "0", "responses": { "200": { "description": "The account view.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" }, "example": { "keyPrefix": "vp_live_3f9a", "tier": "free", "createdAt": "2026-10-24T09:00:00Z", "month": "2026-10", "usage": { "calls": 12, "allowance": 100, "remaining": 88, "byEndpoint": { "vat/validate": 9, "iban/validate": 3 } }, "credits": { "remaining": 0, "earliestExpiry": null }, "plan": null, "limits": { "rps": 2, "bulk": false, "consultationNumber": false } } } } }, "401": { "description": "`unauthorized` — The API key is missing, unknown or revoked.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#unauthorized", "title": "The API key is missing, unknown or revoked", "status": 401, "detail": "Send `Authorization: Bearer vp_live_…`. Keys are shown once at sign-up; a revoked key cannot be restored, create a new one.", "instance": "req_01HZX…", "code": "unauthorized" } } } } } } }, "/status": { "get": { "operationId": "getStatus", "summary": "Service status and upstream availability", "description": "Self-reported component status plus the Commission’s VIES availability per member state (`check-status`, cached five minutes). Does not count as a call and needs no key; it takes no parameter, so the only refusal is the per-address pace (one request a second, the anonymous rate), answered 429 with the RateLimit-* headers like every other endpoint.", "tags": [ "Status" ], "security": [ {} ], "x-tiers": [ "anonymous", "free", "credits", "plan" ], "x-cost": "0", "responses": { "200": { "description": "Status.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } }, "429": { "description": "`rate_limited` — Too many requests per second.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://veriport.io/docs/errors#rate_limited", "title": "Too many requests per second", "status": 429, "detail": "Honour `Retry-After` and the `RateLimit-*` headers. Free keys may send 2 requests a second; the monthly plan 10. Use the bulk endpoint for lists.", "instance": "req_01HZX…", "code": "rate_limited" } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "vp_live_<32 chars>", "description": "The API key shown once after e-mail confirmation. Send it as `Authorization: Bearer vp_live_…`. Keys can be revoked from the account page; they are stored hashed." } }, "headers": { "RateLimit-Limit": { "description": "Requests per second allowed for this key (or address), counted on a sliding one-second window shared by every server instance.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window (0 on a 429).", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window opens again (at least 1).", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "The policy, `;w=1` (one-second window), per draft-ietf-httpapi-ratelimit-headers.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying; sent with every 429 and 503.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Calls left this month on the allowance, plus credits (free: 100 a month). `unlimited` never appears: the plan has 5,000.", "schema": { "type": "integer" } }, "X-Tier": { "description": "anonymous | free | credits | plan.", "schema": { "type": "string" } } }, "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details.", "required": [ "type", "title", "status", "detail", "instance", "code" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "invalid_parameter", "unauthorized", "forbidden_for_tier", "not_found", "quota_exceeded", "rate_limited", "vies_unavailable", "vies_blocked", "checkout_closed", "store_unavailable", "upstream_unavailable", "unprocessable_file", "payload_too_large", "einvoice_unsupported", "einvoice_invalid", "einvoice_unreadable", "idempotency_conflict", "internal" ] }, "errors": { "type": "array", "items": { "type": "object", "properties": { "parameter": { "type": "string" }, "message": { "type": "string" } } } }, "retryAfter": { "type": "integer", "description": "Seconds; also sent as the Retry-After header." }, "feature": { "type": "string", "description": "einvoice_unsupported: the first feature refused (attachments, prepaid_amount, currency, vat_category_g, unknown_field…)." }, "path": { "type": "string", "description": "einvoice_unsupported: its path in the input JSON." }, "unsupported": { "type": "array", "description": "einvoice_unsupported: every field or value refused.", "items": { "type": "object", "properties": { "feature": { "type": "string" }, "path": { "type": "string" }, "detail": { "type": "string" } } } }, "violations": { "type": "array", "description": "einvoice_invalid: the rules broken.", "items": { "$ref": "#/components/schemas/EInvoiceFinding" } } } }, "InvoiceInput": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "xrechnung-ubl", "xrechnung-cii", "zugferd", "peppol-bis" ], "description": "The file to write: xrechnung-ubl (XRechnung 3.0, UBL 2.1), xrechnung-cii (XRechnung 3.0, CII D16B), zugferd (ZUGFeRD 2.x / Factur-X 1.0 EN 16931, a PDF/A-3 with the CII embedded), peppol-bis (Peppol BIS Billing 3.0, UBL 2.1)." }, "type": { "default": "invoice", "description": "BT-3: invoice 380, credit_note 381, corrected_invoice 384 (amounts stay positive; the type says what it is).", "type": "string" }, "number": { "type": "string", "minLength": 1, "maxLength": 100, "description": "BT-1 Invoice number." }, "issueDate": { "type": "string", "format": "date", "description": "BT-2 Issue date, YYYY-MM-DD." }, "dueDate": { "description": "BT-9; or give paymentTermsDays", "type": "string", "format": "date" }, "paymentTermsDays": { "description": "Days from the issue date to the due date (writes BT-9).", "type": "integer", "minimum": 0, "maximum": 365 }, "paymentTerms": { "description": "BT-20 Payment terms, free text (the XRechnung #SKONTO# lines are written as given).", "type": "string", "maxLength": 1000 }, "currency": { "default": "EUR", "description": "BT-5: EUR in v1", "type": "string" }, "buyerReference": { "description": "BT-10: XRechnung requires it (BR-DE-15); for a public body the Leitweg-ID", "type": "string", "maxLength": 200 }, "orderReference": { "description": "BT-13 Purchase order reference.", "type": "string", "maxLength": 200 }, "contractReference": { "description": "BT-12 Contract reference.", "type": "string", "maxLength": 200 }, "precedingInvoice": { "description": "BG-3 Preceding invoice: its number (BT-25) and date (BT-26), for credit notes and corrected invoices.", "type": "object", "properties": { "number": { "type": "string", "minLength": 1, "maxLength": 100 }, "issueDate": { "type": "string", "format": "date" } }, "required": [ "number" ], "additionalProperties": false }, "deliveryDate": { "description": "BT-72 Actual delivery date, YYYY-MM-DD.", "type": "string", "format": "date" }, "deliverToAddress": { "description": "BG-15 deliver-to address: an intra-Community supply (K) needs its country (BR-IC-12), XRechnung also city and post code (BR-DE-10, BR-DE-11); defaults to the buyer's address for K lines", "type": "object", "properties": { "street": { "type": "string", "maxLength": 200 }, "additionalStreet": { "type": "string", "maxLength": 200 }, "city": { "type": "string", "maxLength": 100 }, "postalCode": { "type": "string", "maxLength": 20 }, "countryCode": { "pattern": "^[A-Za-z]{2}$", "description": "ISO 3166-1 alpha-2 (GR for Greece in an address).", "type": "string" } }, "required": [ "countryCode" ], "additionalProperties": false }, "period": { "description": "BG-14 Invoicing period (start and end, YYYY-MM-DD).", "type": "object", "properties": { "start": { "type": "string", "format": "date" }, "end": { "type": "string", "format": "date" } }, "required": [ "start", "end" ], "additionalProperties": false }, "notes": { "description": "BT-22 (Peppol admits one, PEPPOL-EN16931-R002)", "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "language": { "description": "The language of the texts the engine adds (statutory mentions, the visible page of the ZUGFeRD PDF): de, en, fr, nl. Defaults to the seller's country (de for DE, fr for BE).", "type": "string", "enum": [ "de", "en", "fr", "nl" ] }, "seller": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "BT-27 Seller name (legal registration name)." }, "tradingName": { "description": "BT-28 Seller trading name.", "type": "string", "maxLength": 200 }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "BT-35 / BT-50 Street and number." }, "additionalStreet": { "description": "BT-36 / BT-51 Additional street line.", "type": "string", "maxLength": 200 }, "city": { "type": "string", "minLength": 1, "maxLength": 100, "description": "BT-37 / BT-52 City." }, "postalCode": { "type": "string", "minLength": 1, "maxLength": 20, "description": "BT-38 / BT-53 Post code." }, "countryCode": { "pattern": "^[A-Za-z]{2}$", "description": "BT-40 / BT-55 Country code.", "type": "string" } }, "required": [ "street", "city", "postalCode", "countryCode" ], "additionalProperties": false }, "vatId": { "description": "BT-31, with the country prefix", "type": "string", "maxLength": 30 }, "taxNumber": { "description": "BT-32 Seller tax registration identifier: the German Steuernummer (written under scheme FC). Without a VAT identifier it is also repeated as BT-29 (BR-CO-26).", "type": "string", "maxLength": 30 }, "legalRegistration": { "description": "BT-30 Seller legal registration identifier and its ISO 6523 scheme (BT-30-1), e.g. a Belgian enterprise number under 0208.", "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 100 }, "scheme": { "description": "ISO 6523 ICD scheme (0208 Belgian enterprise number, 0002 SIREN…); optional.", "type": "string", "pattern": "^[0-9]{4}$" } }, "required": [ "id" ], "additionalProperties": false }, "electronicAddress": { "description": "BT-34; defaults: 0208 + enterprise number for a Belgian seller on peppol-bis, EM + the contact e-mail otherwise", "type": "object", "properties": { "scheme": { "type": "string", "pattern": "^[A-Z0-9]{2,4}$", "description": "BT-34-1 / BT-49-1: a code of the CEF Electronic Address Scheme list (EM e-mail, 0204 Leitweg-ID, 0208 Belgian enterprise number, 9930 German VAT number…)." }, "id": { "type": "string", "minLength": 1, "maxLength": 254 } }, "required": [ "scheme", "id" ], "additionalProperties": false }, "contact": { "description": "BG-6: BT-41, BT-42, BT-43 (XRechnung requires all three, BR-DE-2 … 7)", "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "phone": { "type": "string", "maxLength": 50 }, "email": { "type": "string", "maxLength": 254 } }, "additionalProperties": false }, "vatScheme": { "default": "standard", "description": "`small_business`: § 19 UStG (Kleinunternehmer) or the Belgian franchise (art. 56bis): every line is category E, the statutory mention is written.", "type": "string", "enum": [ "standard", "small_business" ] } }, "required": [ "name", "address" ], "additionalProperties": false, "description": "BG-4 Seller: in Germany for the XRechnung and ZUGFeRD formats, in Belgium for peppol-bis (v1)." }, "buyer": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "BT-44 Buyer name." }, "tradingName": { "description": "BT-45 Buyer trading name.", "type": "string", "maxLength": 200 }, "address": { "type": "object", "properties": { "street": { "type": "string", "minLength": 1, "maxLength": 200, "description": "BT-35 / BT-50 Street and number." }, "additionalStreet": { "description": "BT-36 / BT-51 Additional street line.", "type": "string", "maxLength": 200 }, "city": { "type": "string", "minLength": 1, "maxLength": 100, "description": "BT-37 / BT-52 City." }, "postalCode": { "type": "string", "minLength": 1, "maxLength": 20, "description": "BT-38 / BT-53 Post code." }, "countryCode": { "pattern": "^[A-Za-z]{2}$", "description": "BT-40 / BT-55 Country code.", "type": "string" } }, "required": [ "street", "city", "postalCode", "countryCode" ], "additionalProperties": false }, "vatId": { "description": "BT-48, with the country prefix; required for reverse charge (BR-AE-02) and intra-Community supplies (BR-IC-02)", "type": "string", "maxLength": 30 }, "legalRegistration": { "description": "BT-47 Buyer legal registration identifier and its ISO 6523 scheme (BT-47-1).", "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 100 }, "scheme": { "description": "ISO 6523 ICD scheme (0208 Belgian enterprise number, 0002 SIREN…); optional.", "type": "string", "pattern": "^[0-9]{4}$" } }, "required": [ "id" ], "additionalProperties": false }, "electronicAddress": { "description": "BT-49: XRechnung and Peppol require it (PEPPOL-EN16931-R010); for a public body in Germany the Leitweg-ID under 0204. Defaults: 0208 + enterprise number for a Belgian buyer on peppol-bis, EM + the contact e-mail otherwise", "type": "object", "properties": { "scheme": { "type": "string", "pattern": "^[A-Z0-9]{2,4}$", "description": "BT-34-1 / BT-49-1: a code of the CEF Electronic Address Scheme list (EM e-mail, 0204 Leitweg-ID, 0208 Belgian enterprise number, 9930 German VAT number…)." }, "id": { "type": "string", "minLength": 1, "maxLength": 254 } }, "required": [ "scheme", "id" ], "additionalProperties": false }, "contact": { "description": "BG-9: BT-56, BT-57, BT-58", "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "phone": { "type": "string", "maxLength": 50 }, "email": { "type": "string", "maxLength": 254 } }, "additionalProperties": false } }, "required": [ "name", "address" ], "additionalProperties": false, "description": "BG-7 Buyer: in any EU member state." }, "payment": { "description": "BG-16 Payment instructions (XRechnung requires them, BR-DE-1).", "type": "object", "properties": { "means": { "default": "sepa_credit_transfer", "description": "BT-81: SEPA credit transfer (58) or credit transfer (30).", "type": "string" }, "iban": { "type": "string", "minLength": 1, "maxLength": 34, "description": "BT-84 IBAN of the payee account." }, "bic": { "description": "BT-86 BIC of the payee account (optional for SEPA).", "type": "string", "maxLength": 11 }, "accountName": { "description": "BT-85 Account name.", "type": "string", "maxLength": 200 }, "reference": { "description": "BT-83 remittance information; a Belgian structured communication « +++123/4567/89002+++ » is checked (VP-BE-002).", "type": "string", "maxLength": 140 } }, "required": [ "iban" ], "additionalProperties": false }, "lines": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "BT-126; numbered 1… when absent", "type": "string", "maxLength": 50 }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "BT-153 Item name." }, "description": { "description": "BT-154 Item description.", "type": "string", "maxLength": 1000 }, "quantity": { "type": "number", "description": "BT-129: positive (a negative quantity is refused as `negative_line`)" }, "unitCode": { "type": "string", "pattern": "^[A-Z0-9]{1,3}$", "description": "BT-130, UN/ECE Recommendation 20 or 21 (C62 piece, HUR hour, DAY, MON, KGM, MTR, LTR, LS lump sum…)" }, "unitPrice": { "type": "number", "description": "BT-146, net price per unit, four decimals at most, never negative (BR-27)" }, "vat": { "type": "object", "properties": { "category": { "type": "string", "description": "BT-151: S, Z, E, AE or K." }, "rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "BT-152 VAT rate in percent (0 for Z, E, AE, K)." }, "exemptionReason": { "description": "BT-120 VAT exemption reason text, written on the VAT breakdown of this category and rate (one reason per breakdown).", "type": "string", "maxLength": 1000 }, "exemptionReasonCode": { "description": "BT-121 VAT exemption reason code (VATEX), e.g. VATEX-EU-132; defaults to VATEX-EU-AE for AE and VATEX-EU-IC for K.", "type": "string", "maxLength": 30 } }, "required": [ "category", "rate" ], "additionalProperties": false, "description": "BG-30 The line VAT: category (S, Z, E, AE, K), rate, and the exemption reason of the breakdown." } }, "required": [ "name", "quantity", "unitCode", "unitPrice", "vat" ], "additionalProperties": false }, "description": "BG-25 Invoice lines, 1 to 500; the line net amount is quantity × unit price, rounded to cents." }, "allowances": { "description": "BG-20 Document-level allowances (discounts), each with its VAT category and rate.", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "amount": { "description": "BT-92 / BT-99; or give `percent` and `baseAmount`", "type": "number" }, "percent": { "description": "BT-94 / BT-101 Percentage applied to baseAmount.", "type": "number", "minimum": 0, "maximum": 100 }, "baseAmount": { "description": "BT-93 / BT-100 Base amount the percentage applies to.", "type": "number" }, "reason": { "description": "BT-97 / BT-104 (BR-33, BR-38: a reason or a code)", "type": "string", "maxLength": 500 }, "reasonCode": { "description": "BT-98 / BT-105: UNCL5189 for allowances (95 discount…), UNCL7161 for charges (FC freight…)", "type": "string", "maxLength": 10 }, "vat": { "type": "object", "properties": { "category": { "type": "string" }, "rate": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "category", "rate" ], "additionalProperties": false } }, "required": [ "vat" ], "additionalProperties": false } }, "charges": { "description": "BG-21 Document-level charges (freight, packaging…), each with its VAT category and rate.", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "amount": { "description": "BT-92 / BT-99; or give `percent` and `baseAmount`", "type": "number" }, "percent": { "description": "BT-94 / BT-101 Percentage applied to baseAmount.", "type": "number", "minimum": 0, "maximum": 100 }, "baseAmount": { "description": "BT-93 / BT-100 Base amount the percentage applies to.", "type": "number" }, "reason": { "description": "BT-97 / BT-104 (BR-33, BR-38: a reason or a code)", "type": "string", "maxLength": 500 }, "reasonCode": { "description": "BT-98 / BT-105: UNCL5189 for allowances (95 discount…), UNCL7161 for charges (FC freight…)", "type": "string", "maxLength": 10 }, "vat": { "type": "object", "properties": { "category": { "type": "string" }, "rate": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "category", "rate" ], "additionalProperties": false } }, "required": [ "vat" ], "additionalProperties": false } } }, "required": [ "format", "number", "issueDate", "seller", "buyer", "lines" ], "additionalProperties": false, "description": "The invoice (EN 16931 business terms named in each field). Strict: an unknown field is refused, never ignored." }, "EInvoiceFinding": { "type": "object", "required": [ "rule", "severity", "path", "message" ], "properties": { "rule": { "type": "string", "description": "As published (BR-CO-17, BR-DE-15, PEPPOL-EN16931-R010, BR-CL-23), `XSD` for the schema, or Veriport’s own (VP-DE-001…)." }, "severity": { "type": "string", "enum": [ "fatal", "warning", "information" ] }, "path": { "type": "string", "description": "An XPath into the document (official rules), `line N` (schema), or the input path (create)." }, "message": { "type": "string" }, "source": { "type": "string", "enum": [ "schema", "cen-ubl", "cen-cii", "xrechnung-ubl", "xrechnung-cii", "peppol-ubl", "peppol-cii", "veriport" ] } } }, "EInvoiceValidation": { "type": "object", "required": [ "valid", "profile", "syntax", "errors", "warnings", "checks" ], "properties": { "valid": { "type": "boolean", "description": "No fatal finding of the schema or the official rules." }, "profile": { "type": "string", "enum": [ "xrechnung", "peppol-bis", "en16931", "factur-x-basic" ], "description": "What the document claims (BT-24)." }, "format": { "type": [ "string", "null" ], "enum": [ "xrechnung-ubl", "xrechnung-cii", "zugferd", "peppol-bis", null ], "description": "The create format of this kind of document." }, "syntax": { "type": "string", "enum": [ "ubl", "cii" ] }, "container": { "type": "string", "enum": [ "xml", "pdf" ] }, "attachment": { "type": [ "string", "null" ], "description": "The embedded file’s name in a hybrid PDF (factur-x.xml)." }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/EInvoiceFinding" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/EInvoiceFinding" } }, "checks": { "type": "object", "properties": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "passed", "failed" ] }, "name": { "type": "string" } } }, "ruleSets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "release": { "type": "string" }, "sha256": { "type": "string" }, "fatal": { "type": "integer" }, "warnings": { "type": "integer" } } } }, "pdfa": { "type": [ "string", "null" ], "enum": [ "not_checked", null ] }, "veriport": { "type": "integer", "description": "Veriport practice checks reported as warnings." } } }, "ms": { "type": "integer" } } }, "EInvoiceEnvelope": { "type": "object", "required": [ "format", "filename", "contentType", "file", "validation", "defaults" ], "properties": { "format": { "type": "string", "enum": [ "xrechnung-ubl", "xrechnung-cii", "zugferd", "peppol-bis" ] }, "filename": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "integer" }, "file": { "type": "string", "contentEncoding": "base64" }, "validation": { "$ref": "#/components/schemas/EInvoiceValidation" }, "defaults": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "value": { "type": "string" }, "reason": { "type": "string" } } } } } }, "EInvoiceParse": { "type": "object", "required": [ "invoice", "profile", "syntax", "container", "notInJson" ], "properties": { "invoice": { "$ref": "#/components/schemas/InvoiceInput" }, "format": { "type": [ "string", "null" ], "enum": [ "xrechnung-ubl", "xrechnung-cii", "zugferd", "peppol-bis", null ] }, "formatLabel": { "type": [ "string", "null" ] }, "profile": { "type": "string" }, "syntax": { "type": "string", "enum": [ "ubl", "cii" ] }, "container": { "type": "string", "enum": [ "xml", "pdf" ] }, "attachment": { "type": [ "string", "null" ] }, "notInJson": { "type": "array", "description": "What the document holds that the JSON does not.", "items": { "type": "object", "properties": { "feature": { "type": "string" }, "path": { "type": "string" }, "detail": { "type": "string" } } } } } }, "VatValidation": { "type": "object", "required": [ "valid", "countryCode", "vatNumber", "full", "structure", "source", "upstream" ], "properties": { "valid": { "type": "boolean", "description": "True when VIES (or the cached VIES answer) says the number is registered for intra-EU transactions on `requestDate`." }, "countryCode": { "type": "string" }, "vatNumber": { "type": "string", "description": "The national part, normalised." }, "full": { "type": "string", "description": "Prefix + number." }, "structure": { "type": "object", "properties": { "valid": { "type": "boolean" }, "checksum": { "type": "string", "enum": [ "passed", "failed", "not_checked" ] }, "expected": { "type": "string" } } }, "name": { "type": [ "string", "null" ], "description": "Registered name, when the member state publishes it (some answer \"---\")." }, "address": { "type": [ "string", "null" ] }, "requestDate": { "type": [ "string", "null" ], "format": "date", "description": "The date VIES stamped the answer with." }, "record": { "type": [ "object", "null" ], "description": "Present when `record=true` was sent: the kept record, or null for a structure-only answer.", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "digest": { "type": "string" } } }, "consultationNumber": { "type": [ "string", "null" ], "description": "VIES request identifier, issued only when `requester` is supplied and accepted. Keep it with the invoice." }, "source": { "type": "object", "required": [ "kind", "checkedAt", "stale" ], "properties": { "kind": { "type": "string", "enum": [ "live", "cache", "structure_only" ] }, "checkedAt": { "type": "string", "format": "date-time" }, "cacheAgeSeconds": { "type": "integer" }, "stale": { "type": "boolean", "description": "True whenever the answer did not come from VIES during this request." } } }, "upstream": { "type": "object", "properties": { "service": { "type": "string", "enum": [ "vies" ] }, "transport": { "type": [ "string", "null" ], "enum": [ "rest", "soap", null ] }, "status": { "type": "string", "enum": [ "ok", "member_state_unavailable", "service_unavailable", "timeout", "blocked", "not_called" ] }, "memberStateAvailable": { "type": [ "boolean", "null" ] } } }, "tableVersion": { "type": [ "string", "null" ], "description": "Unused for validation; present for symmetry with the rates endpoints." } } }, "VatRates": { "type": "object", "required": [ "country", "standard", "reduced", "verifiedOn", "sources" ], "properties": { "country": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" }, "standard": { "type": "number" }, "standardSince": { "type": "string", "format": "date" }, "reduced": { "type": "array", "items": { "type": "number" } }, "superReduced": { "type": [ "number", "null" ] }, "parking": { "type": [ "number", "null" ] }, "hints": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "rate": { "type": "number" }, "kind": { "type": "string", "enum": [ "standard", "reduced", "super_reduced", "parking", "zero" ] }, "since": { "type": "string", "format": "date" }, "note": { "type": "string" } } } }, "verifiedOn": { "type": "string", "format": "date" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "consulted": { "type": "string", "format": "date" } } } }, "note": { "type": "string" } } }, "IbanResult": { "type": "object", "required": [ "valid", "iban", "checks", "failures" ], "properties": { "valid": { "type": "boolean" }, "iban": { "type": "string" }, "formatted": { "type": "string" }, "countryCode": { "type": [ "string", "null" ] }, "countryName": { "type": [ "string", "null" ] }, "checkDigits": { "type": [ "string", "null" ] }, "bban": { "type": [ "string", "null" ] }, "bankIdentifier": { "type": [ "string", "null" ] }, "branchIdentifier": { "type": [ "string", "null" ] }, "expectedLength": { "type": [ "integer", "null" ] }, "sepa": { "type": [ "boolean", "null" ] }, "sepaSince": { "type": [ "string", "null" ], "format": "date" }, "checks": { "type": "object", "properties": { "characters": { "type": "boolean" }, "country": { "type": "boolean" }, "length": { "type": "boolean" }, "mod97": { "type": "boolean" }, "bbanPattern": { "type": "boolean" } } }, "failures": { "type": "array", "items": { "type": "string", "enum": [ "empty", "characters", "country_unknown", "length", "check_digits", "bban_pattern" ] } }, "registry": { "type": "object", "properties": { "source": { "type": "string" }, "verifiedOn": { "type": "string", "format": "date" } } } } }, "OssSaleRow": { "type": "object", "required": [ "country", "net", "date" ], "properties": { "country": { "type": "string", "description": "Member state of consumption, ISO alpha-2 (EL or GR for Greece)." }, "rate": { "type": [ "number", "null" ], "description": "Rate in percent; or give `category`." }, "category": { "type": [ "string", "null" ], "description": "A rates-table category: digital_services, ebooks, printed_books, foodstuffs, hotel_accommodation, restaurant, newspapers." }, "net": { "type": "number", "description": "Taxable amount in euro; negative for a credit note." }, "vat": { "type": [ "number", "null" ], "description": "VAT amount in euro; computed when absent, reconciled when present." }, "date": { "type": "string", "format": "date" }, "supplyType": { "type": [ "string", "null" ], "enum": [ "services", "goods", null ] }, "currency": { "type": [ "string", "null" ], "description": "EUR or absent." }, "correctionOfPeriod": { "type": [ "string", "null" ], "description": "The earlier period this row corrects." } } }, "OssReturn": { "type": "object", "required": [ "scheme", "period", "currency", "lines", "corrections", "totals", "files", "portals" ], "properties": { "scheme": { "type": "string", "enum": [ "union", "non_union", "import" ] }, "period": { "type": "object", "properties": { "label": { "type": "string" }, "kind": { "type": "string", "enum": [ "quarter", "month" ] }, "start": { "type": "string", "format": "date" }, "end": { "type": "string", "format": "date" }, "dueDate": { "type": "string", "format": "date", "description": "Last day of the month following the period." } } }, "currency": { "type": "string", "enum": [ "EUR" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "countryName": { "type": "string" }, "supplyType": { "type": "string", "enum": [ "services", "goods" ] }, "rateKind": { "type": "string", "enum": [ "standard", "reduced", "super_reduced", "parking", "zero", "unverified" ] }, "rate": { "type": "number" }, "rows": { "type": "integer" }, "net": { "type": "number" }, "vat": { "type": "number" }, "vatComputed": { "type": "number", "description": "net × rate, for the reconciliation." } } } }, "corrections": { "type": "array", "items": { "type": "object", "properties": { "period": { "type": "string" }, "country": { "type": "string" }, "countryName": { "type": "string" }, "rows": { "type": "integer" }, "vat": { "type": "number" }, "net": { "type": "number" } } } }, "totals": { "type": "object", "properties": { "rows": { "type": "integer" }, "countries": { "type": "integer" }, "net": { "type": "number" }, "vat": { "type": "number" }, "correctionsVat": { "type": "number" }, "vatPayable": { "type": "number" } } }, "byCountry": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "countryName": { "type": "string" }, "net": { "type": "number" }, "vat": { "type": "number" } } } }, "rates": { "type": "object", "properties": { "verifiedOn": { "type": "string", "format": "date" } } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": [ "integer", "null" ] }, "message": { "type": "string" } } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "generic_csv" ] }, "filename": { "type": "string" }, "contentType": { "type": "string" }, "portal": { "type": [ "string", "null" ], "description": "Null: no national format was available; the file is the labelled generic CSV." }, "content": { "type": "string" } } } }, "portals": { "type": "array", "items": { "type": "object", "properties": { "memberState": { "type": "string" }, "portal": { "type": "string" }, "status": { "type": "string", "enum": [ "generic" ] }, "note": { "type": "string" } } } } } }, "FrAddress": { "type": "object", "properties": { "street": { "type": [ "string", "null" ] }, "postalCode": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "cityCode": { "type": [ "string", "null" ], "description": "INSEE commune code." }, "country": { "type": "string" }, "full": { "type": [ "string", "null" ] } } }, "FrEstablishment": { "type": "object", "properties": { "siret": { "type": "string" }, "isHeadquarters": { "type": "boolean" }, "status": { "type": [ "string", "null" ], "enum": [ "active", "closed", null ] }, "naf": { "type": [ "string", "null" ] }, "address": { "$ref": "#/components/schemas/FrAddress" }, "createdOn": { "type": [ "string", "null" ] }, "closedOn": { "type": [ "string", "null" ] }, "tradeName": { "type": [ "string", "null" ] }, "headcountBand": { "type": [ "object", "null" ] } } }, "FrCompany": { "type": "object", "required": [ "siren", "legalForm", "naf", "status", "address", "vatNumber", "source" ], "properties": { "siren": { "type": "string" }, "name": { "type": [ "string", "null" ], "description": "Full name as the registry shows it." }, "legalName": { "type": [ "string", "null" ] }, "acronym": { "type": [ "string", "null" ] }, "legalForm": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "INSEE catégorie juridique." }, "label": { "type": [ "string", "null" ], "description": "Null for codes outside the carried list; the code is still returned." } } }, "naf": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "NAF rév. 2 (APE) code." }, "section": { "type": [ "string", "null" ] }, "sectionLabel": { "type": [ "string", "null" ] } } }, "status": { "type": [ "string", "null" ], "enum": [ "active", "ceased", null ] }, "createdOn": { "type": [ "string", "null" ], "format": "date" }, "ceasedOn": { "type": [ "string", "null" ], "format": "date" }, "headcountBand": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "year": { "type": [ "string", "null" ] } } }, "companyCategory": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "enum": [ "PME", "ETI", "GE" ] }, "label": { "type": [ "string", "null" ] }, "year": { "type": [ "string", "null" ] } } }, "employer": { "type": [ "boolean", "null" ] }, "diffusion": { "type": [ "string", "null" ], "description": "`O` full publication, `P` partial (opposition): individuals’ addresses are then withheld by the sources." }, "address": { "$ref": "#/components/schemas/FrAddress" }, "headquarters": { "oneOf": [ { "$ref": "#/components/schemas/FrEstablishment" }, { "type": "null" } ] }, "establishment": { "oneOf": [ { "$ref": "#/components/schemas/FrEstablishment" }, { "type": "null" } ], "description": "The establishment asked for when the query was a SIRET." }, "establishments": { "type": "object", "properties": { "total": { "type": [ "integer", "null" ] }, "open": { "type": [ "integer", "null" ] } } }, "vatNumber": { "type": "object", "properties": { "computed": { "type": "string", "description": "FR + key + SIREN, computed; not a registration check." }, "activeNumbers": { "type": [ "array", "null" ], "items": { "type": "string" } }, "note": { "type": "string" } } }, "officers": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "person", "company" ] }, "name": { "type": [ "string", "null" ] }, "firstNames": { "type": [ "string", "null" ] }, "role": { "type": [ "string", "null" ] }, "birthYear": { "type": [ "string", "null" ] }, "nationality": { "type": [ "string", "null" ] }, "siren": { "type": [ "string", "null" ] } } }, "description": "From the open INPI RNE data as re-served by the search API; null when the source gives none." }, "updatedOn": { "type": "object", "properties": { "registry": { "type": [ "string", "null" ] }, "insee": { "type": [ "string", "null" ] }, "rne": { "type": [ "string", "null" ] } } }, "source": { "type": "object", "required": [ "primary", "insee", "fetchedOn", "cache" ], "properties": { "primary": { "type": "string", "enum": [ "recherche_entreprises", "insee" ], "description": "`insee` when the open search API failed and the answer was built from the INSEE Sirene API alone (officers are then null)." }, "insee": { "type": "boolean", "description": "True when the INSEE Sirene API was also consulted (operator key configured)." }, "openData": { "type": "array", "items": { "type": "string" } }, "fetchedOn": { "type": "string", "format": "date-time", "description": "When the registry was asked (the cache fill time for a cached answer)." }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean" }, "ageSeconds": { "type": "integer" }, "stale": { "type": "boolean", "description": "True when the answer is older than 7 days and was served because the registries did not answer (never older than 30 days)." } } } } } } }, "UsSalesTax": { "type": "object", "required": [ "zip", "coverage", "verifiedOn", "sources", "notes" ], "properties": { "zip": { "type": "string" }, "state": { "type": [ "string", "null" ] }, "stateName": { "type": [ "string", "null" ] }, "coverage": { "type": "string", "enum": [ "zip_average", "state_only", "none" ] }, "stateRate": { "type": [ "number", "null" ], "description": "Percent. CA, UT and VA include their mandatory statewide local add-on (source convention, said in `notes`)." }, "combined": { "type": [ "object", "null" ], "properties": { "average": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" }, "jurisdictions": { "type": "integer" }, "period": { "type": "string" }, "fetchedOn": { "type": "string", "format": "date" }, "method": { "type": "string" } }, "description": "With `zip_average`: the combined rate across the ZIP." }, "statewide": { "type": [ "object", "null" ], "properties": { "averageLocalRate": { "type": [ "number", "null" ] }, "maxLocalRate": { "type": "number" }, "averageCombinedRate": { "type": [ "number", "null" ] }, "localRates": { "type": "boolean" } }, "description": "With `state_only`: statewide figures to estimate with." }, "verifiedOn": { "type": "string", "format": "date" }, "nextReview": { "type": "string", "format": "date" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "consulted": { "type": "string" } } } }, "notes": { "type": "array", "items": { "type": "string" } } } }, "ValidationRecord": { "type": "object", "required": [ "id", "createdAt", "full", "valid", "source", "upstream", "digest" ], "properties": { "id": { "type": "string", "description": "The record id (`vr_…`)." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the record was made." }, "keyPrefix": { "type": "string", "description": "The prefix of the key that made it." }, "countryCode": { "type": "string" }, "vatNumber": { "type": "string" }, "full": { "type": "string", "description": "The normalised number with its prefix." }, "valid": { "type": "boolean" }, "name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "requestDate": { "type": [ "string", "null" ] }, "consultationNumber": { "type": [ "string", "null" ], "description": "Issued by VIES when `requester` was supplied." }, "requester": { "type": [ "string", "null" ] }, "source": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "live", "cache" ] }, "checkedAt": { "type": "string", "format": "date-time" }, "stale": { "type": "boolean" } } }, "upstream": { "type": "object", "properties": { "service": { "type": "string", "enum": [ "vies" ] }, "status": { "type": "string" }, "transport": { "type": [ "string", "null" ], "enum": [ "rest", "soap", null ] } } }, "digest": { "type": "string", "description": "SHA-256 (hex) of the JSON array [id, createdAt, full, valid, name, address, requestDate, consultationNumber, requester, source.kind, source.checkedAt, source.stale, upstream.status, upstream.transport]. Store it to compare the record later." } } }, "Me": { "type": "object", "properties": { "keyPrefix": { "type": "string" }, "tier": { "type": "string", "enum": [ "free", "credits", "plan" ] }, "createdAt": { "type": "string", "format": "date-time" }, "month": { "type": "string" }, "usage": { "type": "object", "properties": { "calls": { "type": "integer" }, "allowance": { "type": "integer" }, "remaining": { "type": "integer" }, "byEndpoint": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "credits": { "type": "object", "properties": { "remaining": { "type": "integer" }, "earliestExpiry": { "type": [ "string", "null" ], "format": "date" } } }, "plan": { "type": [ "object", "null" ], "properties": { "status": { "type": "string" }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time" } } }, "limits": { "type": "object", "properties": { "rps": { "type": "integer" }, "bulk": { "type": "boolean" }, "consultationNumber": { "type": "boolean" } } } } }, "Status": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "operational", "degraded", "outage" ] }, "checkedAt": { "type": "string", "format": "date-time" }, "components": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "note": { "type": "string" } } } }, "vies": { "type": "object", "properties": { "available": { "type": [ "boolean", "null" ] }, "mode": { "type": "string", "enum": [ "live", "mock" ] }, "memberStates": { "type": "array", "items": { "type": "object", "properties": { "countryCode": { "type": "string" }, "available": { "type": "boolean" } } } } } }, "incidents": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "text": { "type": "string" } } } } } } } } }