API v2 / schéma 2.0.0

Politiques et devis de taxe de séjour

POST /v2/resolve · defaults:resolve · schéma 2.0.0

Commencez avec l'adresse enregistrée de la propriété.

Votre serveur fournit countryCode, mode et address: {countryCode, street, city, state, postalCode}. L'État et le code postal peuvent être des chaînes vides. La correspondance utilise uniquement les enregistrements d'adresse officiels publiés, Unicode NFC et l'élagage des espaces externes. La casse, les accents, la ponctuation et les suffixes de numéro de rue restent significatifs. Il n'y a pas de correspondance approximative, ni de recours au seul code postal ou aux coordonnées.

curl 'https://api.touristtaxtools.com/v2/resolve' \
  -H "Authorization: Bearer $TOURISTTAXTOOLS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "countryCode": "DE",
  "mode": "policy",
  "address": {
    "countryCode": "DE",
    "street": "Example Street 1",
    "city": "Example Town",
    "state": "",
    "postalCode": ""
  },
  "property": {
    "accommodationType": "hotel"
  }
}'

mode: "policy" examine l'emplacement exact et l'ensemble de sa portée fiscale locale. policy_ready identifie les politiques qualifiées ; sa quote est nul. Inspectez requiredInputs, missingInputs, preuves et dates effectives avant l'enregistrement d'une approbation explicite au niveau de la propriété. La couverture qualifiée manquante reste indisponible même lorsque le pays a publié des règles de référence.

Fournissez des données réelles de séjour.

Pour mode: "quote", indiquez le type d'hébergement, les faits requis et stay. L'enregistrement et le départ exclusif utilisent les dates du calendrier local AAAA-MM-JJ. nights doit couvrir chaque nuit exactement une fois, avec son montant réel d'hébergement net en EUR sous forme de chaîne décimale. Ne divisez pas un total de réservation arbitraire sur plusieurs nuits et n'incluez pas les services et taxes exclus par la politique.

curl 'https://api.touristtaxtools.com/v2/resolve' \
  -H "Authorization: Bearer $TOURISTTAXTOOLS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "countryCode": "DE",
  "mode": "quote",
  "address": {
    "countryCode": "DE",
    "street": "Example Street 1",
    "city": "Example Town",
    "state": "",
    "postalCode": ""
  },
  "property": {
    "accommodationType": "hotel"
  },
  "facts": {
    "paidAccommodation": true,
    "platformCollected": false,
    "passThroughChosen": true
  },
  "stay": {
    "checkIn": "2026-11-02",
    "checkOut": "2026-11-04",
    "agreementOn": "2026-10-26",
    "nights": [
      {
        "date": "2026-11-02",
        "netAmount": "100.00"
      },
      {
        "date": "2026-11-03",
        "netAmount": "120.00"
      }
    ]
  },
  "inputEvidence": {
    "source": "operator_confirmation",
    "reference": "illustrative-confirmation-reference",
    "recordedAt": "2026-10-26T12:00:00Z"
  }
}'

Les faits sont true, false ou null pour inconnu. La facturation nécessite un hébergement payé confirmé, aucune collecte antérieure par la plateforme et le choix de l'exploitant de répercuter la taxe sur le client. Une politique peut exiger d'autres faits, comme une évaluation d'exemption définie par la source. Lorsqu'elle est requise, originalContractUnderSixMonths concerne l'accord de disponibilité juridiquement contraignant initial ; le paiement effectif à la caisse ou un départ anticipé ne peut pas l'établir. L'exemple ne fournit pas toutes les entrées de politique possibles.

inputEvidence identifie votre confirmation réellement enregistrée, l'enregistrement de réservation ou l'enregistrement de propriété et son horodatage. Obtenez ceci depuis un flux de travail serveur autorisé. L'API conserve votre attestation ; elle ne vérifie pas de manière indépendante le dossier client sous-jacent.

Utilisez l'état de la réponse.

Seulement resolved contient une citation. Conserver snapshotId, countrySnapshotSha256, artifactSha256, preuve de localisation, révisions de politique et le devis avec la transaction approuvée. Vérifiez à nouveau les preuves actuelles lors de l'engagement d'une nouvelle charge. N'utilisez jamais un résultat échoué ou indisponible pour écraser des taxes manuelles ou recalculer des réservations historiques.

Maintenez la distinction entre la taxe locale et le traitement de la TVA.

Les politiques half-up existantes utilisent net-percentage.v1 en EUR, avec arrondi qualifié par source par nuit ou par séjour. Leurs requêtes et l'arithmétique restent inchangées. Calculs fixes, bruts, par paliers, par tranche d'âge, saisonniers, de remboursement et alternatifs non pris en charge. Les montants en unités mineures sont des chaînes d'entiers. netMinor est la base nette d'hébergement; taxMinor est la taxe de séjour; totalMinor est leur somme, hors TVA.

Les centimes exacts nécessitent une transaction explicite.

Une politique qualifiée séparément peut sélectionner calculation.rounding: "exact_integral_minor_unit". Il ne s'agit pas d'une convention d'arrondi légale. Elle produit net-percentage.exact-integral-minor-unit.v1 seulement lorsque chaque taxe applicable est un nombre entier d'unités mineures en utilisant une arithmétique décimale exacte. Une taxe fractionnaire refuse l'ensemble du devis ; aucune taxe n'est supprimée, arrondie ou remplacée par zéro. À titre d'illustration, un prix de base de 80.00 EUR à 7,5 % correspond à 600 cents principal et 8600 cents net plus taxe, avant TVA. Une base de 0.01 ou 0.20 EUR est refusée. Un agrégat entier de 0.40 EUR pour deux personnes ou deux prestations n'est pas non plus pris en charge.

Fournir transaction avec supplyId, night, accommodatedPersonCount, accommodationSupplyCount et nightCount. Une personne hébergée exactement, une fourniture d'hébergement contractée directement, tarifée séparément et une nuit complète sont prises en charge. Évaluez explicitement completeNight, directlyContracted, separatelyPriced, considerationComplete et depositReconciled. Tous doivent être vrais. Un payeur, le nom d'une chambre, une ligne de facture, un départ après une seule nuit ou une somme arithmétique ne peuvent pas établir ces faits ni la durée du contrat initial.

Le complet components la liste contient au plus douze enregistrements, chacun avec un schéma borné et unique id, kind, chaîne décimale amount, correspondance supplyId/night et allocation. Exactement un accommodation_net et tous taxable_direct_ancillary_net les montants doivent s'additionner exactement au montant net de base nocturne fourni. Une chambre à 0,40 EUR plus un prix de nettoyage taxable de 0,01 EUR ne peut pas omettre ce centime pour obtenir un devis à 0,03 EUR. vat, own_tourist_levy, excluded_service et deposit_payment sont conservés mais n'augmentent pas la base. Imputez les acomptes comme paiements contre le prix, sans les compter à nouveau comme contrepartie. Seulement direct l'allocation est prise en charge ; shared, one_off, indirect, les prix négatifs, les identités conflictuelles et les différences inexpliquées sont refusés.

Réponses manquantes ou nulles et un unknown rendement de classification needs_input avec des noms de champs précis ; les cas connus incomplets ou non pris en charge donnent lieu à unsupported. Les deux ont quote: null. Les champs mal formés ou inattendus échouent à la validation. Conservez chaque entrée typée, composant et valeur réelle inputEvidence la provenance dans l'empreinte de la transaction et l'examen figé. Il s'agit d'attestations de l'appelant, pas d'une preuve indépendante de la taxation source ou du périmètre légal. L'adresse exacte, l'époque, l'actualité, l'intégralité du périmètre d'autorité ordinaire et spéciale, toutes les politiques cumulatives et les faits obligatoires concernant le but/accord restent obligatoires.

curl 'https://api.touristtaxtools.com/v2/resolve' \
  -H "Authorization: Bearer $TOURISTTAXTOOLS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "countryCode": "ZZ",
  "mode": "quote",
  "address": {
    "countryCode": "ZZ",
    "street": "1 Synthetic Street",
    "city": "Synthetic city",
    "state": "",
    "postalCode": ""
  },
  "property": {
    "accommodationType": "hotel"
  },
  "facts": {
    "paidAccommodation": true,
    "platformCollected": false,
    "passThroughChosen": true,
    "originalContractUnderSixMonths": true
  },
  "stay": {
    "checkIn": "2026-11-02",
    "checkOut": "2026-11-03",
    "agreementOn": "2026-10-26",
    "nights": [
      {
        "date": "2026-11-02",
        "netAmount": "80.00"
      }
    ]
  },
  "transaction": {
    "supplyId": "synthetic-direct-supply-1",
    "night": "2026-11-02",
    "accommodatedPersonCount": 1,
    "accommodationSupplyCount": 1,
    "nightCount": 1,
    "completeNight": true,
    "directlyContracted": true,
    "separatelyPriced": true,
    "considerationComplete": true,
    "depositReconciled": true,
    "components": [
      {
        "id": "synthetic-price-record-1",
        "kind": "accommodation_net",
        "amount": "80.00",
        "supplyId": "synthetic-direct-supply-1",
        "night": "2026-11-02",
        "allocation": "direct"
      }
    ]
  },
  "inputEvidence": {
    "source": "operator_confirmation",
    "reference": "synthetic-confirmation-only",
    "recordedAt": "2026-10-26T12:00:00Z"
  }
}'

La politique de chaque taxTreatment.passedThroughVatBase est accommodation ou unknown. Le premier établit que la taxe répercutée entre dans l'assiette de TVA de l'hébergement ; il ne choisit pas de taux de TVA et ne détermine ni l'immatriculation, ni l'exonération, ni le mode de tarification de l'entreprise. Un traitement inconnu ne peut pas autoriser un prélèvement financier. Appliquez, via votre moteur fiscal, le traitement de TVA de l'entreprise utilisatrice du logiciel (tenant), examiné séparément, et calculez la TVA une seule fois. Un devis de taxe n'est pas le montant total final de la réservation.

Le point de terminaison utilise les mêmes restrictions de pays et quotas de developer-key que v1. Les requêtes sont limitées à 32 KiB et les réponses à 2 MiB. Le proxy anonyme du site Web n'expose pas v2.

Télécharger le schéma de requête, schéma de réponse, schéma de politique et schéma de preuve de localisation, ou utilisez le Contrat OpenAPI.