{ "openapi": "3.1.0", "info": { "title": "TouristTaxTools Developer API", "version": "2.0.0", "description": "Source-backed reference data. Names and addresses alone do not establish authoritative jurisdiction membership. No public key signup." }, "servers": [ { "url": "https://api.touristtaxtools.com" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Ordinary operator-issued ttt_live_ developer key. Server-side only." } }, "schemas": { "ResolveRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://touristtaxtools.com/schemas/resolve-request.v1.schema.json", "type": "object", "properties": { "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" }, "jurisdictionIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "maxItems": 30 }, "officialCodes": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "value": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "scheme", "value" ], "additionalProperties": false }, "maxItems": 30 }, "address": { "type": "object", "maxProperties": 12, "additionalProperties": { "type": "string", "maxLength": 500 } }, "on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "accommodationType": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "countryCode" ], "additionalProperties": false }, "ResolveRequestV2": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://touristtaxtools.com/schemas/resolve-request.v2.schema.json", "type": "object", "properties": { "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" }, "mode": { "enum": [ "policy", "quote" ] }, "address": { "type": "object", "properties": { "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" }, "street": { "type": "string", "minLength": 1, "maxLength": 500 }, "city": { "type": "string", "minLength": 1, "maxLength": 200 }, "state": { "type": "string", "maxLength": 200 }, "postalCode": { "type": "string", "maxLength": 100 } }, "required": [ "countryCode", "street", "city", "state", "postalCode" ], "additionalProperties": false }, "property": { "type": "object", "properties": { "accommodationType": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [], "additionalProperties": false }, "facts": { "type": "object", "properties": { "paidAccommodation": { "type": [ "boolean", "null" ] }, "originalContractUnderSixMonths": { "type": [ "boolean", "null" ] }, "basicHousingNeed": { "type": [ "boolean", "null" ] }, "schoolTrip": { "type": [ "boolean", "null" ] }, "registeredResidence": { "type": [ "boolean", "null" ] }, "emergencyAccommodation": { "type": [ "boolean", "null" ] }, "platformCollected": { "type": [ "boolean", "null" ] }, "passThroughChosen": { "type": [ "boolean", "null" ] } }, "required": [], "additionalProperties": false }, "stay": { "type": "object", "properties": { "checkIn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "checkOut": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "agreementOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "nights": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "netAmount": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,11})(\\.[0-9]{1,2})?$" } }, "required": [ "date", "netAmount" ], "additionalProperties": false }, "minItems": 1, "maxItems": 366 } }, "required": [], "additionalProperties": false }, "inputEvidence": { "type": "object", "properties": { "source": { "enum": [ "operator_confirmation", "booking_record", "property_record" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 500 }, "recordedAt": { "type": "string", "minLength": 20, "maxLength": 40 } }, "required": [ "source", "reference", "recordedAt" ], "additionalProperties": false }, "transaction": { "type": [ "object", "null" ], "properties": { "supplyId": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,63}$" }, "night": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "accommodatedPersonCount": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000 }, "accommodationSupplyCount": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000 }, "nightCount": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 366 }, "completeNight": { "type": [ "boolean", "null" ] }, "directlyContracted": { "type": [ "boolean", "null" ] }, "separatelyPriced": { "type": [ "boolean", "null" ] }, "considerationComplete": { "type": [ "boolean", "null" ] }, "depositReconciled": { "type": [ "boolean", "null" ] }, "components": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,63}$" }, "kind": { "type": [ "string", "null" ], "enum": [ "accommodation_net", "taxable_direct_ancillary_net", "vat", "own_tourist_levy", "excluded_service", "deposit_payment", "unknown", null ] }, "amount": { "type": [ "string", "null" ], "pattern": "^-?(0|[1-9][0-9]{0,11})(\\.[0-9]{1,2})?$" }, "supplyId": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,63}$" }, "night": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "allocation": { "type": [ "string", "null" ], "enum": [ "direct", "shared", "one_off", "indirect", null ] } }, "required": [], "additionalProperties": false }, "minItems": 0, "maxItems": 12 } }, "required": [], "additionalProperties": false } }, "required": [ "countryCode", "mode", "address" ], "additionalProperties": false }, "ResolveResponseV2": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://touristtaxtools.com/schemas/resolve-response.v2.schema.json", "type": "object", "properties": { "schemaVersion": { "const": "2.0.0" }, "status": { "enum": [ "unknown", "ambiguous", "stale", "unsupported", "needs_input", "policy_ready", "resolved" ] }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" }, "snapshotId": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "countrySnapshotSha256": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{64}$" }, "artifactSha256": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{64}$" }, "location": { "type": [ "object", "null" ], "properties": { "addressId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "addressFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "officialCode": { "type": "object", "properties": { "scheme": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "value": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "scheme", "value" ], "additionalProperties": false }, "sourceEdition": { "type": "string", "minLength": 1, "maxLength": 200 }, "scope": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "status": { "enum": [ "complete", "partial" ] }, "levyType": { "const": "tourist_accommodation" }, "summary": { "type": "string", "minLength": 1, "maxLength": 10000 }, "expectedAssessments": { "type": "integer", "minimum": 1, "maximum": 100 }, "layerSetEvidenceIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 1, "maxItems": 100 }, "assessments": { "type": "array", "items": { "type": "object", "properties": { "jurisdictionId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "membership": { "enum": [ "included", "excluded" ] }, "ownLevy": { "enum": [ "policies", "verified_none", "unknown" ] }, "policyIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 0, "maxItems": 100 }, "evidenceIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 1, "maxItems": 100 } }, "required": [ "jurisdictionId", "membership", "ownLevy", "policyIds", "evidenceIds" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 } }, "required": [ "id", "status", "levyType", "summary", "expectedAssessments", "layerSetEvidenceIds", "assessments" ], "additionalProperties": false }, "evidenceIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 1, "maxItems": 100 } }, "required": [ "addressId", "addressFingerprint", "officialCode", "sourceEdition", "scope", "evidenceIds" ], "additionalProperties": false }, "policies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "revision": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "jurisdictionId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "sourceRuleIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 1, "maxItems": 100 }, "qualification": { "type": "object", "properties": { "status": { "const": "qualified" }, "summary": { "type": "string", "minLength": 1, "maxLength": 10000 }, "evidenceIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 1, "maxItems": 100 } }, "required": [ "status", "summary", "evidenceIds" ], "additionalProperties": false }, "effectiveFrom": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "effectiveTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "currency": { "const": "EUR" }, "calculation": { "type": "object", "properties": { "kind": { "const": "net_percentage" }, "rate": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,2})(\\.[0-9]{1,8})?$" }, "rounding": { "enum": [ "half_up_per_night", "half_up_per_stay", "exact_integral_minor_unit" ] } }, "required": [ "kind", "rate", "rounding" ], "additionalProperties": false }, "conditions": { "type": "object", "properties": { "accommodationTypes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "minItems": 1, "maxItems": 100 }, "agreementFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "agreementTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "maxStayCalendarMonths": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 12 }, "factRequirements": { "type": "array", "items": { "type": "object", "properties": { "fact": { "enum": [ "paidAccommodation", "originalContractUnderSixMonths", "basicHousingNeed", "schoolTrip", "registeredResidence", "emergencyAccommodation", "platformCollected", "passThroughChosen" ] }, "equals": { "type": "boolean" }, "evidenceIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 1, "maxItems": 100 } }, "required": [ "fact", "equals", "evidenceIds" ], "additionalProperties": false }, "minItems": 0, "maxItems": 100 } }, "required": [ "accommodationTypes", "agreementFrom", "agreementTo", "maxStayCalendarMonths", "factRequirements" ], "additionalProperties": false }, "collection": { "type": "object", "properties": { "collector": { "const": "accommodation_operator" }, "passThrough": { "enum": [ "permitted", "required" ] } }, "required": [ "collector", "passThrough" ], "additionalProperties": false }, "taxTreatment": { "type": "object", "properties": { "passedThroughVatBase": { "enum": [ "accommodation", "unknown" ] }, "evidenceIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 0, "maxItems": 100 } }, "required": [ "passedThroughVatBase", "evidenceIds" ], "additionalProperties": false }, "evidenceIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 1, "maxItems": 100 } }, "required": [ "id", "revision", "name", "jurisdictionId", "sourceRuleIds", "qualification", "effectiveFrom", "effectiveTo", "currency", "calculation", "conditions", "collection", "taxTreatment", "evidenceIds" ], "additionalProperties": false }, "minItems": 0, "maxItems": 100 }, "requiredInputs": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "minItems": 0, "maxItems": 100 }, "missingInputs": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "minItems": 0, "maxItems": 100 }, "quote": { "type": [ "object", "null" ], "properties": { "calculationVersion": { "enum": [ "net-percentage.v1", "net-percentage.exact-integral-minor-unit.v1" ] }, "currency": { "const": "EUR" }, "netMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})$" }, "taxMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})$" }, "totalMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})$" }, "inputFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "inputEvidence": { "type": "object", "properties": { "source": { "enum": [ "operator_confirmation", "booking_record", "property_record" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 500 }, "recordedAt": { "type": "string", "minLength": 20, "maxLength": 40 } }, "required": [ "source", "reference", "recordedAt" ], "additionalProperties": false }, "transaction": { "type": "object", "properties": { "supplyId": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,63}$" }, "night": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "accommodatedPersonCount": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000 }, "accommodationSupplyCount": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000 }, "nightCount": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 366 }, "completeNight": { "type": [ "boolean", "null" ] }, "directlyContracted": { "type": [ "boolean", "null" ] }, "separatelyPriced": { "type": [ "boolean", "null" ] }, "considerationComplete": { "type": [ "boolean", "null" ] }, "depositReconciled": { "type": [ "boolean", "null" ] }, "components": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,63}$" }, "kind": { "type": [ "string", "null" ], "enum": [ "accommodation_net", "taxable_direct_ancillary_net", "vat", "own_tourist_levy", "excluded_service", "deposit_payment", "unknown", null ] }, "amount": { "type": [ "string", "null" ], "pattern": "^-?(0|[1-9][0-9]{0,11})(\\.[0-9]{1,2})?$" }, "supplyId": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,63}$" }, "night": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "allocation": { "type": [ "string", "null" ], "enum": [ "direct", "shared", "one_off", "indirect", null ] } }, "required": [], "additionalProperties": false }, "minItems": 0, "maxItems": 12 } }, "required": [], "additionalProperties": false }, "lines": { "type": "array", "items": { "type": "object", "properties": { "policyId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "policyRevision": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "jurisdictionId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "sourceRuleIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 1, "maxItems": 100 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "rate": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,2})(\\.[0-9]{1,8})?$" }, "rounding": { "enum": [ "half_up_per_night", "half_up_per_stay", "exact_integral_minor_unit" ] }, "netMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})$" }, "taxMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})$" } }, "required": [ "policyId", "policyRevision", "jurisdictionId", "sourceRuleIds", "name", "rate", "rounding", "netMinor", "taxMinor" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 } }, "required": [ "calculationVersion", "currency", "netMinor", "taxMinor", "totalMinor", "inputFingerprint", "inputEvidence", "lines" ], "additionalProperties": false }, "reasons": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 0, "maxItems": 100 }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "url": { "type": "string", "minLength": 8, "maxLength": 4096, "pattern": "^https://" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "retrievedAt": { "type": "string", "maxLength": 40 }, "contentType": { "type": "string", "minLength": 1, "maxLength": 10000 }, "bytes": { "type": "integer", "minimum": 1, "maximum": 268435456 } }, "required": [ "id", "url", "sha256", "retrievedAt", "contentType", "bytes" ], "additionalProperties": false }, "minItems": 0, "maxItems": 10000 } }, "required": [ "schemaVersion", "status", "countryCode", "snapshotId", "countrySnapshotSha256", "artifactSha256", "location", "policies", "requiredInputs", "missingInputs", "quote", "reasons", "evidence" ], "additionalProperties": false }, "Rule": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "jurisdictionId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 10000 }, "status": { "enum": [ "active", "verified_no_tax", "unknown", "manual_review" ] }, "combination": { "type": "object", "properties": { "mode": { "enum": [ "additive", "alternative", "unknown" ] }, "group": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 10000 }, "priority": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000 } }, "required": [ "mode", "group", "priority" ], "additionalProperties": false }, "effectiveFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "effectiveTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "effectiveDateStatus": { "enum": [ "known", "unknown" ] }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" }, "calculation": { "type": "object", "properties": { "kind": { "enum": [ "fixed", "percentage", "none", "unknown" ] }, "amount": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]{0,11})(\\.[0-9]{1,8})?$" }, "unit": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 10000 }, "base": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 10000 } }, "required": [ "kind", "amount", "unit", "base" ], "additionalProperties": false }, "conditions": { "type": "object", "properties": { "status": { "enum": [ "complete", "unknown" ] }, "accommodationTypes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 10000 }, "maxItems": 10000 }, "exemptions": { "type": "array", "items": {}, "maxItems": 10000 }, "ageBands": { "type": "array", "items": { "type": "object", "properties": { "minAgeYears": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 150 }, "maxAgeYears": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 150 }, "minInclusive": { "type": [ "boolean", "null" ] }, "maxInclusive": { "type": [ "boolean", "null" ] }, "description": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "minAgeYears", "maxAgeYears", "minInclusive", "maxInclusive", "description" ], "additionalProperties": false }, "maxItems": 10000 }, "seasons": { "type": "array", "items": {}, "maxItems": 10000 }, "nightCap": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 36600 }, "nightCapInclusive": { "type": [ "boolean", "null" ] }, "nativeText": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 10000 } }, "required": [ "status", "accommodationTypes", "exemptions", "ageBands", "seasons", "nightCap", "nightCapInclusive", "nativeText" ], "additionalProperties": false }, "collection": { "type": "object", "properties": { "collector": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 10000 }, "remittance": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 10000 } }, "required": [ "collector", "remittance" ], "additionalProperties": false }, "evidenceIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 1, "maxItems": 10000 }, "notes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 10000 }, "maxItems": 10000 } }, "required": [ "id", "jurisdictionId", "name", "status", "combination", "effectiveFrom", "effectiveTo", "effectiveDateStatus", "currency", "calculation", "conditions", "collection", "evidenceIds", "notes" ], "additionalProperties": false }, "Evidence": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "url": { "type": "string", "minLength": 8, "maxLength": 4096, "pattern": "^https://" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "retrievedAt": { "type": "string", "maxLength": 40 }, "contentType": { "type": "string", "minLength": 1, "maxLength": 10000 }, "bytes": { "type": "integer", "minimum": 1, "maximum": 268435456 } }, "required": [ "id", "url", "sha256", "retrievedAt", "contentType", "bytes" ], "additionalProperties": false }, "Jurisdiction": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 10000 }, "level": { "enum": [ "country", "state", "region", "province", "city", "municipality", "special_district" ] }, "parentId": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "officialCodes": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "value": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "scheme", "value" ], "additionalProperties": false }, "maxItems": 100 }, "aliases": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 10000 }, "maxItems": 10000 }, "evidenceIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 1, "maxItems": 10000 }, "coverage": { "type": "object", "properties": { "status": { "enum": [ "complete", "partial", "unknown", "verified_no_tax" ] }, "summary": { "type": "string", "minLength": 1, "maxLength": 10000 }, "gaps": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 10000 }, "maxItems": 10000 } }, "required": [ "status", "summary", "gaps" ], "additionalProperties": false } }, "required": [ "id", "countryCode", "name", "level", "parentId", "officialCodes", "aliases", "evidenceIds", "coverage" ], "additionalProperties": false }, "Coverage": { "type": "object", "properties": { "status": { "enum": [ "complete", "partial", "unknown", "verified_no_tax" ] }, "summary": { "type": "string", "minLength": 1, "maxLength": 10000 }, "gaps": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 10000 }, "maxItems": 10000 } }, "required": [ "status", "summary", "gaps" ], "additionalProperties": false } } }, "paths": { "/health": { "get": { "operationId": "health", "responses": { "200": { "description": "Service and schema readiness only." } } } }, "/v1/countries": { "get": { "operationId": "countries", "security": [ { "bearerAuth": [] } ], "description": "Requires countries:read.", "responses": { "200": { "description": "Published data; inspect coverage and status before use.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "const": "1.0.0" }, "countries": { "type": "array", "items": { "type": "object", "properties": { "countryCode": { "type": "string" }, "coverage": { "type": "object", "properties": { "status": { "enum": [ "complete", "partial", "unknown", "verified_no_tax" ] }, "summary": { "type": "string", "minLength": 1, "maxLength": 10000 }, "gaps": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 10000 }, "maxItems": 10000 } }, "required": [ "status", "summary", "gaps" ], "additionalProperties": false }, "collectedAt": { "type": "string" }, "publishedAt": { "type": "string" }, "snapshotId": { "type": "string" }, "stale": { "type": "boolean" } } } } } } } } }, "400": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "422": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/v1/jurisdictions": { "get": { "operationId": "jurisdictions", "security": [ { "bearerAuth": [] } ], "description": "Requires jurisdictions:read.", "responses": { "200": { "description": "Published data; inspect coverage and status before use.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "const": "1.0.0" }, "status": { "enum": [ "published", "unknown" ] }, "countryCode": { "type": "string" }, "snapshotId": { "type": "string" }, "coverage": { "type": "object", "properties": { "status": { "enum": [ "complete", "partial", "unknown", "verified_no_tax" ] }, "summary": { "type": "string", "minLength": 1, "maxLength": 10000 }, "gaps": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 10000 }, "maxItems": 10000 } }, "required": [ "status", "summary", "gaps" ], "additionalProperties": false }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 10000 }, "level": { "enum": [ "country", "state", "region", "province", "city", "municipality", "special_district" ] }, "parentId": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "officialCodes": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "value": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "scheme", "value" ], "additionalProperties": false }, "maxItems": 100 }, "aliases": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 10000 }, "maxItems": 10000 }, "evidenceIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 1, "maxItems": 10000 }, "coverage": { "type": "object", "properties": { "status": { "enum": [ "complete", "partial", "unknown", "verified_no_tax" ] }, "summary": { "type": "string", "minLength": 1, "maxLength": 10000 }, "gaps": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 10000 }, "maxItems": 10000 } }, "required": [ "status", "summary", "gaps" ], "additionalProperties": false } }, "required": [ "id", "countryCode", "name", "level", "parentId", "officialCodes", "aliases", "evidenceIds", "coverage" ], "additionalProperties": false } }, "nextOffset": { "type": [ "integer", "null" ] } } } } } }, "400": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "422": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "parameters": [ { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{2}$" } }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } } ] } }, "/v1/rules": { "get": { "operationId": "rules", "security": [ { "bearerAuth": [] } ], "description": "Requires rules:read.", "responses": { "200": { "description": "Published data; inspect coverage and status before use.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "const": "1.0.0" }, "status": { "enum": [ "published", "unknown" ] }, "countryCode": { "type": "string" }, "snapshotId": { "type": "string" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "jurisdictionId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 10000 }, "status": { "enum": [ "active", "verified_no_tax", "unknown", "manual_review" ] }, "combination": { "type": "object", "properties": { "mode": { "enum": [ "additive", "alternative", "unknown" ] }, "group": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 10000 }, "priority": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000 } }, "required": [ "mode", "group", "priority" ], "additionalProperties": false }, "effectiveFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "effectiveTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "effectiveDateStatus": { "enum": [ "known", "unknown" ] }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" }, "calculation": { "type": "object", "properties": { "kind": { "enum": [ "fixed", "percentage", "none", "unknown" ] }, "amount": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]{0,11})(\\.[0-9]{1,8})?$" }, "unit": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 10000 }, "base": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 10000 } }, "required": [ "kind", "amount", "unit", "base" ], "additionalProperties": false }, "conditions": { "type": "object", "properties": { "status": { "enum": [ "complete", "unknown" ] }, "accommodationTypes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 10000 }, "maxItems": 10000 }, "exemptions": { "type": "array", "items": {}, "maxItems": 10000 }, "ageBands": { "type": "array", "items": { "type": "object", "properties": { "minAgeYears": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 150 }, "maxAgeYears": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 150 }, "minInclusive": { "type": [ "boolean", "null" ] }, "maxInclusive": { "type": [ "boolean", "null" ] }, "description": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "minAgeYears", "maxAgeYears", "minInclusive", "maxInclusive", "description" ], "additionalProperties": false }, "maxItems": 10000 }, "seasons": { "type": "array", "items": {}, "maxItems": 10000 }, "nightCap": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 36600 }, "nightCapInclusive": { "type": [ "boolean", "null" ] }, "nativeText": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 10000 } }, "required": [ "status", "accommodationTypes", "exemptions", "ageBands", "seasons", "nightCap", "nightCapInclusive", "nativeText" ], "additionalProperties": false }, "collection": { "type": "object", "properties": { "collector": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 10000 }, "remittance": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 10000 } }, "required": [ "collector", "remittance" ], "additionalProperties": false }, "evidenceIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 1, "maxItems": 10000 }, "notes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 10000 }, "maxItems": 10000 } }, "required": [ "id", "jurisdictionId", "name", "status", "combination", "effectiveFrom", "effectiveTo", "effectiveDateStatus", "currency", "calculation", "conditions", "collection", "evidenceIds", "notes" ], "additionalProperties": false } }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "url": { "type": "string", "minLength": 8, "maxLength": 4096, "pattern": "^https://" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "retrievedAt": { "type": "string", "maxLength": 40 }, "contentType": { "type": "string", "minLength": 1, "maxLength": 10000 }, "bytes": { "type": "integer", "minimum": 1, "maximum": 268435456 } }, "required": [ "id", "url", "sha256", "retrievedAt", "contentType", "bytes" ], "additionalProperties": false } } } } } } }, "400": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "422": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "parameters": [ { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{2}$" } }, { "name": "jurisdictionId", "in": "query", "required": true, "schema": { "type": "string" } } ] } }, "/v1/resolve": { "post": { "operationId": "resolveDefaults", "security": [ { "bearerAuth": [] } ], "description": "Requires defaults:resolve.", "responses": { "200": { "description": "Published data; inspect coverage and status before use.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "const": "1.0.0" }, "status": { "enum": [ "resolved", "ambiguous", "unknown", "manual_review", "stale" ] }, "countryCode": { "type": "string" }, "snapshotId": { "type": [ "string", "null" ] }, "jurisdictions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 10000 }, "level": { "enum": [ "country", "state", "region", "province", "city", "municipality", "special_district" ] }, "parentId": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "officialCodes": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "value": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "scheme", "value" ], "additionalProperties": false }, "maxItems": 100 }, "aliases": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 10000 }, "maxItems": 10000 }, "evidenceIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 1, "maxItems": 10000 }, "coverage": { "type": "object", "properties": { "status": { "enum": [ "complete", "partial", "unknown", "verified_no_tax" ] }, "summary": { "type": "string", "minLength": 1, "maxLength": 10000 }, "gaps": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 10000 }, "maxItems": 10000 } }, "required": [ "status", "summary", "gaps" ], "additionalProperties": false } }, "required": [ "id", "countryCode", "name", "level", "parentId", "officialCodes", "aliases", "evidenceIds", "coverage" ], "additionalProperties": false } }, "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "jurisdictionId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 10000 }, "status": { "enum": [ "active", "verified_no_tax", "unknown", "manual_review" ] }, "combination": { "type": "object", "properties": { "mode": { "enum": [ "additive", "alternative", "unknown" ] }, "group": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 10000 }, "priority": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100000 } }, "required": [ "mode", "group", "priority" ], "additionalProperties": false }, "effectiveFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "effectiveTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "effectiveDateStatus": { "enum": [ "known", "unknown" ] }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" }, "calculation": { "type": "object", "properties": { "kind": { "enum": [ "fixed", "percentage", "none", "unknown" ] }, "amount": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]{0,11})(\\.[0-9]{1,8})?$" }, "unit": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 10000 }, "base": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 10000 } }, "required": [ "kind", "amount", "unit", "base" ], "additionalProperties": false }, "conditions": { "type": "object", "properties": { "status": { "enum": [ "complete", "unknown" ] }, "accommodationTypes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 10000 }, "maxItems": 10000 }, "exemptions": { "type": "array", "items": {}, "maxItems": 10000 }, "ageBands": { "type": "array", "items": { "type": "object", "properties": { "minAgeYears": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 150 }, "maxAgeYears": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 150 }, "minInclusive": { "type": [ "boolean", "null" ] }, "maxInclusive": { "type": [ "boolean", "null" ] }, "description": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "minAgeYears", "maxAgeYears", "minInclusive", "maxInclusive", "description" ], "additionalProperties": false }, "maxItems": 10000 }, "seasons": { "type": "array", "items": {}, "maxItems": 10000 }, "nightCap": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 36600 }, "nightCapInclusive": { "type": [ "boolean", "null" ] }, "nativeText": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 10000 } }, "required": [ "status", "accommodationTypes", "exemptions", "ageBands", "seasons", "nightCap", "nightCapInclusive", "nativeText" ], "additionalProperties": false }, "collection": { "type": "object", "properties": { "collector": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 10000 }, "remittance": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 10000 } }, "required": [ "collector", "remittance" ], "additionalProperties": false }, "evidenceIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 1, "maxItems": 10000 }, "notes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 10000 }, "maxItems": 10000 } }, "required": [ "id", "jurisdictionId", "name", "status", "combination", "effectiveFrom", "effectiveTo", "effectiveDateStatus", "currency", "calculation", "conditions", "collection", "evidenceIds", "notes" ], "additionalProperties": false } }, "defaults": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "ruleId": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "amount": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "unit": { "type": [ "string", "null" ] }, "base": { "type": [ "string", "null" ] } } } }, "reasons": { "type": "array", "items": { "type": "string" } }, "coverage": { "type": "object", "properties": { "status": { "enum": [ "complete", "partial", "unknown", "verified_no_tax" ] }, "summary": { "type": "string", "minLength": 1, "maxLength": 10000 }, "gaps": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 10000 }, "maxItems": 10000 } }, "required": [ "status", "summary", "gaps" ], "additionalProperties": false }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "url": { "type": "string", "minLength": 8, "maxLength": 4096, "pattern": "^https://" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "retrievedAt": { "type": "string", "maxLength": 40 }, "contentType": { "type": "string", "minLength": 1, "maxLength": 10000 }, "bytes": { "type": "integer", "minimum": 1, "maximum": 268435456 } }, "required": [ "id", "url", "sha256", "retrievedAt", "contentType", "bytes" ], "additionalProperties": false } } } } } } }, "400": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "422": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://touristtaxtools.com/schemas/resolve-request.v1.schema.json", "type": "object", "properties": { "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" }, "jurisdictionIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "maxItems": 30 }, "officialCodes": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "value": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "scheme", "value" ], "additionalProperties": false }, "maxItems": 30 }, "address": { "type": "object", "maxProperties": 12, "additionalProperties": { "type": "string", "maxLength": 500 } }, "on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "accommodationType": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "countryCode" ], "additionalProperties": false } } } } } }, "/v2/resolve": { "post": { "operationId": "resolvePolicyOrQuote", "security": [ { "bearerAuth": [] } ], "description": "Requires defaults:resolve. Matches an exact published official address. Policy review and stay quotes require complete qualified local scope. Only resolved carries a quote; unknown, ambiguous, stale, unsupported, needs_input and policy_ready carry no quote. A quote excludes VAT and is not a final booking total.", "responses": { "200": { "description": "Published data; inspect coverage and status before use.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://touristtaxtools.com/schemas/resolve-response.v2.schema.json", "type": "object", "properties": { "schemaVersion": { "const": "2.0.0" }, "status": { "enum": [ "unknown", "ambiguous", "stale", "unsupported", "needs_input", "policy_ready", "resolved" ] }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" }, "snapshotId": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "countrySnapshotSha256": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{64}$" }, "artifactSha256": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{64}$" }, "location": { "type": [ "object", "null" ], "properties": { "addressId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "addressFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "officialCode": { "type": "object", "properties": { "scheme": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "value": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "scheme", "value" ], "additionalProperties": false }, "sourceEdition": { "type": "string", "minLength": 1, "maxLength": 200 }, "scope": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "status": { "enum": [ "complete", "partial" ] }, "levyType": { "const": "tourist_accommodation" }, "summary": { "type": "string", "minLength": 1, "maxLength": 10000 }, "expectedAssessments": { "type": "integer", "minimum": 1, "maximum": 100 }, "layerSetEvidenceIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 1, "maxItems": 100 }, "assessments": { "type": "array", "items": { "type": "object", "properties": { "jurisdictionId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "membership": { "enum": [ "included", "excluded" ] }, "ownLevy": { "enum": [ "policies", "verified_none", "unknown" ] }, "policyIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 0, "maxItems": 100 }, "evidenceIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 1, "maxItems": 100 } }, "required": [ "jurisdictionId", "membership", "ownLevy", "policyIds", "evidenceIds" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 } }, "required": [ "id", "status", "levyType", "summary", "expectedAssessments", "layerSetEvidenceIds", "assessments" ], "additionalProperties": false }, "evidenceIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 1, "maxItems": 100 } }, "required": [ "addressId", "addressFingerprint", "officialCode", "sourceEdition", "scope", "evidenceIds" ], "additionalProperties": false }, "policies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "revision": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "jurisdictionId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "sourceRuleIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 1, "maxItems": 100 }, "qualification": { "type": "object", "properties": { "status": { "const": "qualified" }, "summary": { "type": "string", "minLength": 1, "maxLength": 10000 }, "evidenceIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 1, "maxItems": 100 } }, "required": [ "status", "summary", "evidenceIds" ], "additionalProperties": false }, "effectiveFrom": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "effectiveTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "currency": { "const": "EUR" }, "calculation": { "type": "object", "properties": { "kind": { "const": "net_percentage" }, "rate": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,2})(\\.[0-9]{1,8})?$" }, "rounding": { "enum": [ "half_up_per_night", "half_up_per_stay", "exact_integral_minor_unit" ] } }, "required": [ "kind", "rate", "rounding" ], "additionalProperties": false }, "conditions": { "type": "object", "properties": { "accommodationTypes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "minItems": 1, "maxItems": 100 }, "agreementFrom": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "agreementTo": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "maxStayCalendarMonths": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 12 }, "factRequirements": { "type": "array", "items": { "type": "object", "properties": { "fact": { "enum": [ "paidAccommodation", "originalContractUnderSixMonths", "basicHousingNeed", "schoolTrip", "registeredResidence", "emergencyAccommodation", "platformCollected", "passThroughChosen" ] }, "equals": { "type": "boolean" }, "evidenceIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 1, "maxItems": 100 } }, "required": [ "fact", "equals", "evidenceIds" ], "additionalProperties": false }, "minItems": 0, "maxItems": 100 } }, "required": [ "accommodationTypes", "agreementFrom", "agreementTo", "maxStayCalendarMonths", "factRequirements" ], "additionalProperties": false }, "collection": { "type": "object", "properties": { "collector": { "const": "accommodation_operator" }, "passThrough": { "enum": [ "permitted", "required" ] } }, "required": [ "collector", "passThrough" ], "additionalProperties": false }, "taxTreatment": { "type": "object", "properties": { "passedThroughVatBase": { "enum": [ "accommodation", "unknown" ] }, "evidenceIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 0, "maxItems": 100 } }, "required": [ "passedThroughVatBase", "evidenceIds" ], "additionalProperties": false }, "evidenceIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 1, "maxItems": 100 } }, "required": [ "id", "revision", "name", "jurisdictionId", "sourceRuleIds", "qualification", "effectiveFrom", "effectiveTo", "currency", "calculation", "conditions", "collection", "taxTreatment", "evidenceIds" ], "additionalProperties": false }, "minItems": 0, "maxItems": 100 }, "requiredInputs": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "minItems": 0, "maxItems": 100 }, "missingInputs": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "minItems": 0, "maxItems": 100 }, "quote": { "type": [ "object", "null" ], "properties": { "calculationVersion": { "enum": [ "net-percentage.v1", "net-percentage.exact-integral-minor-unit.v1" ] }, "currency": { "const": "EUR" }, "netMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})$" }, "taxMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})$" }, "totalMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})$" }, "inputFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "inputEvidence": { "type": "object", "properties": { "source": { "enum": [ "operator_confirmation", "booking_record", "property_record" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 500 }, "recordedAt": { "type": "string", "minLength": 20, "maxLength": 40 } }, "required": [ "source", "reference", "recordedAt" ], "additionalProperties": false }, "transaction": { "type": "object", "properties": { "supplyId": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,63}$" }, "night": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "accommodatedPersonCount": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000 }, "accommodationSupplyCount": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000 }, "nightCount": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 366 }, "completeNight": { "type": [ "boolean", "null" ] }, "directlyContracted": { "type": [ "boolean", "null" ] }, "separatelyPriced": { "type": [ "boolean", "null" ] }, "considerationComplete": { "type": [ "boolean", "null" ] }, "depositReconciled": { "type": [ "boolean", "null" ] }, "components": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,63}$" }, "kind": { "type": [ "string", "null" ], "enum": [ "accommodation_net", "taxable_direct_ancillary_net", "vat", "own_tourist_levy", "excluded_service", "deposit_payment", "unknown", null ] }, "amount": { "type": [ "string", "null" ], "pattern": "^-?(0|[1-9][0-9]{0,11})(\\.[0-9]{1,2})?$" }, "supplyId": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,63}$" }, "night": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "allocation": { "type": [ "string", "null" ], "enum": [ "direct", "shared", "one_off", "indirect", null ] } }, "required": [], "additionalProperties": false }, "minItems": 0, "maxItems": 12 } }, "required": [], "additionalProperties": false }, "lines": { "type": "array", "items": { "type": "object", "properties": { "policyId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "policyRevision": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "jurisdictionId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "sourceRuleIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "minItems": 1, "maxItems": 100 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "rate": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,2})(\\.[0-9]{1,8})?$" }, "rounding": { "enum": [ "half_up_per_night", "half_up_per_stay", "exact_integral_minor_unit" ] }, "netMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})$" }, "taxMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,17})$" } }, "required": [ "policyId", "policyRevision", "jurisdictionId", "sourceRuleIds", "name", "rate", "rounding", "netMinor", "taxMinor" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 } }, "required": [ "calculationVersion", "currency", "netMinor", "taxMinor", "totalMinor", "inputFingerprint", "inputEvidence", "lines" ], "additionalProperties": false }, "reasons": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 0, "maxItems": 100 }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,199}$" }, "url": { "type": "string", "minLength": 8, "maxLength": 4096, "pattern": "^https://" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "retrievedAt": { "type": "string", "maxLength": 40 }, "contentType": { "type": "string", "minLength": 1, "maxLength": 10000 }, "bytes": { "type": "integer", "minimum": 1, "maximum": 268435456 } }, "required": [ "id", "url", "sha256", "retrievedAt", "contentType", "bytes" ], "additionalProperties": false }, "minItems": 0, "maxItems": 10000 } }, "required": [ "schemaVersion", "status", "countryCode", "snapshotId", "countrySnapshotSha256", "artifactSha256", "location", "policies", "requiredInputs", "missingInputs", "quote", "reasons", "evidence" ], "additionalProperties": false } } } }, "400": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "403": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "422": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "503": { "description": "Request, authentication, scope, throttle or availability error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://touristtaxtools.com/schemas/resolve-request.v2.schema.json", "type": "object", "properties": { "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" }, "mode": { "enum": [ "policy", "quote" ] }, "address": { "type": "object", "properties": { "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" }, "street": { "type": "string", "minLength": 1, "maxLength": 500 }, "city": { "type": "string", "minLength": 1, "maxLength": 200 }, "state": { "type": "string", "maxLength": 200 }, "postalCode": { "type": "string", "maxLength": 100 } }, "required": [ "countryCode", "street", "city", "state", "postalCode" ], "additionalProperties": false }, "property": { "type": "object", "properties": { "accommodationType": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [], "additionalProperties": false }, "facts": { "type": "object", "properties": { "paidAccommodation": { "type": [ "boolean", "null" ] }, "originalContractUnderSixMonths": { "type": [ "boolean", "null" ] }, "basicHousingNeed": { "type": [ "boolean", "null" ] }, "schoolTrip": { "type": [ "boolean", "null" ] }, "registeredResidence": { "type": [ "boolean", "null" ] }, "emergencyAccommodation": { "type": [ "boolean", "null" ] }, "platformCollected": { "type": [ "boolean", "null" ] }, "passThroughChosen": { "type": [ "boolean", "null" ] } }, "required": [], "additionalProperties": false }, "stay": { "type": "object", "properties": { "checkIn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "checkOut": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "agreementOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "nights": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "netAmount": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,11})(\\.[0-9]{1,2})?$" } }, "required": [ "date", "netAmount" ], "additionalProperties": false }, "minItems": 1, "maxItems": 366 } }, "required": [], "additionalProperties": false }, "inputEvidence": { "type": "object", "properties": { "source": { "enum": [ "operator_confirmation", "booking_record", "property_record" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 500 }, "recordedAt": { "type": "string", "minLength": 20, "maxLength": 40 } }, "required": [ "source", "reference", "recordedAt" ], "additionalProperties": false }, "transaction": { "type": [ "object", "null" ], "properties": { "supplyId": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,63}$" }, "night": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "accommodatedPersonCount": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000 }, "accommodationSupplyCount": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000 }, "nightCount": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 366 }, "completeNight": { "type": [ "boolean", "null" ] }, "directlyContracted": { "type": [ "boolean", "null" ] }, "separatelyPriced": { "type": [ "boolean", "null" ] }, "considerationComplete": { "type": [ "boolean", "null" ] }, "depositReconciled": { "type": [ "boolean", "null" ] }, "components": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,63}$" }, "kind": { "type": [ "string", "null" ], "enum": [ "accommodation_net", "taxable_direct_ancillary_net", "vat", "own_tourist_levy", "excluded_service", "deposit_payment", "unknown", null ] }, "amount": { "type": [ "string", "null" ], "pattern": "^-?(0|[1-9][0-9]{0,11})(\\.[0-9]{1,2})?$" }, "supplyId": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,63}$" }, "night": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "allocation": { "type": [ "string", "null" ], "enum": [ "direct", "shared", "one_off", "indirect", null ] } }, "required": [], "additionalProperties": false }, "minItems": 0, "maxItems": 12 } }, "required": [], "additionalProperties": false } }, "required": [ "countryCode", "mode", "address" ], "additionalProperties": false } } } } } } } }