API v1 / schema 1.0.0

Início rápido da API da taxa turística

Três chamadas, uma trilha de evidências.

Mantenha sua chave API no seu servidor. Comece pela cobertura de países publicada, descubra registros jurisdicionais autoritativos, depois inspecione regras ou resolva padrões compatíveis.

Obtenha uma chave específica do seu operador TouristTaxTools.
Leia a cobertura por país e suas lacunas explícitas.
Confirme a jurisdição autoritativa da propriedade antes de aplicar quaisquer padrões.

1. Inspecionar países publicados

curl 'https://api.touristtaxtools.com/v1/countries' \
  -H "Authorization: Bearer $TOURISTTAXTOOLS_API_KEY"

2. Descobrir jurisdições

curl 'https://api.touristtaxtools.com/v1/jurisdictions?country=IT&q=Rome&limit=20&offset=0' \
  -H "Authorization: Bearer $TOURISTTAXTOOLS_API_KEY"

3. Verificar um endereço — pode retornar desconhecido

curl 'https://api.touristtaxtools.com/v1/resolve' \
  -H "Authorization: Bearer $TOURISTTAXTOOLS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "countryCode": "IT",
    "address": {
      "street": "Piazza della Rotonda",
      "city": "Roma",
      "postalCode": "00186"
    },
    "on": "2026-10-26",
    "accommodationType": "hotel"
  }'

Lidar com incerteza como consequência.

Uma resposta HTTP bem-sucedida pode conter unknown, ambiguous, manual_review ou stale. Estes são estados significativos. Não os transforme em imposto zero.

JavaScript do lado do servidor · Node 24

// Run on your server. Never bundle this key into a browser.
const response = await fetch(
  'https://api.touristtaxtools.com/v1/resolve',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.TOURISTTAXTOOLS_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      countryCode: 'IT',
      // Use identifiers from authoritative property records.
      // Discovery by a place name does not prove applicability.
      officialCodes: [{ scheme: 'IT:ISTAT', value: '058091' }],
      on: '2026-10-26',
      accommodationType: 'hotel',
    }),
    signal: AbortSignal.timeout(8000),
    redirect: 'error',
  },
);
if (!response.ok) throw new Error(`API status ${response.status}`);
const result = await response.json();
if (result.status === 'resolved' && Array.isArray(result.defaults)) {
  // Offer supported defaults for review before saving.
  // Preserve manual settings and historical reservation amounts.
} else {
  // Keep existing settings. Show result.reasons for manual review.
}

Revise uma política antes de solicitar uma cotação de estadia.

POST /v2/resolve fornece um contrato separado de revisão de política e cotação para endereços oficiais exatos com cobertura local qualificada. Uma regra publicada v1 não estabelece que uma política v2 ou cotação automática esteja disponível.

Página de documentação Metodologia da fonte