API v2 / schema 2.0.0

Políticas e cotações da taxa turística

POST /v2/resolve · defaults:resolve · esquema 2.0.0

Comece com o endereço salvo da propriedade.

Seu servidor fornece countryCode, mode e address: {countryCode, street, city, state, postalCode}. Estado e código postal podem ser strings vazias. A correspondência usa apenas registros oficiais de endereço publicados, Unicode NFC e remoção de espaços externos. Maiúsculas/minúsculas, acentos, pontuação e sufixos do número da casa permanecem significativos. Não há correspondência aproximada, apenas código postal ou fallback por coordenadas.

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" revisa a localização exata e seu escopo local de impostos completo. policy_ready identifica políticas qualificadas; seu quote é nulo. Inspecionar requiredInputs, missingInputs, evidência e datas efetivas antes de registrar uma aprovação explícita a nível de propriedade. Cobertura qualificada ausente permanece indisponível mesmo quando o país publicou regras de referência.

Forneça entradas reais da estadia.

Para mode: "quote", forneça o tipo de alojamento, factos exigidos e stay. O check-in e o checkout exclusivo usam datas do calendário local YYYY-MM-DD. nights deve cobrir cada noite exatamente uma vez, com o seu montante real líquido de alojamento em EUR como uma string decimal. Não divida um total arbitrário de reserva por noites nem inclua serviços e impostos excluídos pela política.

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"
  }
}'

Os factos são true, false ou null para desconhecido. A cobrança requer acomodação paga comprovada, sem recolha prévia pela plataforma e a opção do operador de repassar a taxa ao hóspede. Uma política pode exigir fatos adicionais, como uma avaliação de isenção definida pela fonte. Quando exigido, originalContractUnderSixMonths refere‑se ao acordo de disponibilidade juridicamente vinculativo original; o checkout real ou a partida antecipada não podem estabelecê‑lo. O exemplo não fornece todas as entradas de política possíveis.

inputEvidence identifica sua confirmação registrada real, registro de reserva ou registro de propriedade e seu carimbo de data/hora. Obtenha isto a partir de um fluxo de trabalho de servidor autorizado. A API preserva sua atestação; ela não verifica independentemente o registo do hóspede subjacente.

Use o estado da resposta.

Apenas resolved contém uma citação. Manter snapshotId, countrySnapshotSha256, artifactSha256, prova de localização, revisões de política e a cotação com a transação aprovada. Verifique novamente as evidências atuais ao confirmar uma nova cobrança. Nunca use um resultado falhado ou indisponível para sobrescrever impostos manuais ou recalcular reservas históricas.

Mantenha a contribuição e o tratamento do VAT distintos.

As políticas half-up existentes usam net-percentage.v1 em EUR, com arredondamento qualificado por fonte por noite ou por estadia. Os seus pedidos e a aritmética permanecem inalterados. Cálculos fixos, brutos, progressivos, por faixa etária, sazonais, de reembolso e alternativos não são suportados. Valores em unidades menores são cadeias inteiras. netMinor é a base líquida de alojamento; taxMinor é o imposto turístico; totalMinor é a sua soma, excluindo o IVA.

Centavos exatos requerem uma transação explícita.

Uma política qualificada separadamente pode selecionar calculation.rounding: "exact_integral_minor_unit". Isto não é uma convenção estatutária de arredondamento. Produz net-percentage.exact-integral-minor-unit.v1 apenas quando cada imposto aplicável for um número integral de unidades menores usando aritmética decimal exata. Um imposto fraccionário recusa toda a cotação; nenhum imposto é eliminado, arredondado ou substituído por zero. Um exemplo ilustrativo de 80.00 EUR base a 7.5% tem 600 cêntimos de principal e 8600 cêntimos líquido mais imposto, antes do IVA. Uma base de 0.01 ou 0.20 EUR é recusada. Um agregado integral de 0.40 EUR de duas pessoas ou dois fornecimentos também não é suportado.

Fornecer transaction com supplyId, night, accommodatedPersonCount, accommodationSupplyCount e nightCount. Exatamente uma pessoa acomodada, um fornecimento de acomodação contratado diretamente, com preço separado e uma noite completa são suportados. Avalie explicitamente completeNight, directlyContracted, separatelyPriced, considerationComplete e depositReconciled. Todos devem ser verdadeiros. Um pagador, nome do quarto, linha de fatura, checkout de uma noite ou soma aritmética não podem estabelecer esses factos nem a duração do contrato original.

O completo components a lista tem no máximo doze registos, cada um com um único limitado id, kind, cadeia decimal amount, correspondência supplyId/night e allocation. Exatamente um accommodation_net e tudo taxable_direct_ancillary_net os valores devem reconciliar exatamente com a base líquida noturna fornecida. Um quarto de 0,40 EUR mais um preço de limpeza tributável de 0,01 EUR não pode omitir esse centavo para obter um orçamento de 0,03. vat, own_tourist_levy, excluded_service e deposit_payment são retidos, mas não aumentam a base. Reconciliar depósitos como pagamentos contra o preço, sem contá‑los novamente como contraprestação. Apenas direct alocação é suportada; shared, one_off, indirect, preços negativos, identidades conflitantes e diferenças inexplicadas recusam.

Respostas faltando ou nulas e um unknown rendimento de classificação needs_input com nomes de campos precisos; casos conhecidos incompletos ou não suportados resultam em unsupported. Ambos têm quote: null. Campos malformados ou inesperados falham na validação. Mantenha todas as entradas digitadas, componentes e reais inputEvidence procedência na impressão digital da transação e revisão congelada. Estas são atestações do chamador, não prova independente da tributabilidade pela fonte ou do alcance legal. Endereço exato, época, atualidade, escopo completo de autoridade ordinária e especial, todas as políticas cumulativas e fatos obrigatórios de propósito/contrato permanecem mandatórios.

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"
  }
}'

A cada política taxTreatment.passedThroughVatBase é accommodation ou unknown. O primeiro estabelece que o tributo repassado entra na base de cálculo do IVA da acomodação; não seleciona uma alíquota de IVA nem determina o registro, a isenção ou a modalidade de preços da empresa. Um tratamento desconhecido não pode autorizar uma cobrança financeira. Aplique, pelo seu motor fiscal, o tratamento de IVA da empresa que utiliza o software (tenant), revisado separadamente, e calcule o IVA uma única vez. Uma cotação de tributos não é o valor total final da reserva.

O endpoint utiliza as mesmas restrições de país por developer-key e quotas que a v1. Os pedidos são limitados a 32 KiB e as respostas a 2 MiB. o proxy anónimo do website não expõe a v2.

Baixar o esquema de requisição, esquema de resposta, esquema de política e esquema de prova de localização, ou use the Contrato OpenAPI.