Entwickler-API

Authentifizierung

Erstellen Sie einen API-Schlüssel in den Einstellungen und senden Sie ihn mit jeder Anfrage. Schlüssel werden nur einmal bei der Erstellung angezeigt und können jederzeit widerrufen werden.

Authorization: Bearer tos_live_...

Aufrufe zählen zum monatlichen API-Limit Ihres Plans (Free: 500, Pro: 1.000, Business: 10.000). Jede Antwort enthält die Header X-RateLimit-Limit und X-RateLimit-Remaining; bei Überschreitung antwortet die API mit HTTP 429 und dem Code API_QUOTA_EXCEEDED.

API-Schlüssel in den Einstellungen erstellen · Plan-Limits vergleichen

Antwortstruktur

Jeder Endpunkt liefert dieselbe JSON-Struktur. Genau eines von data und error ist ungleich null; Fehler tragen einen stabilen maschinenlesbaren Code.

{ "data": { ... }, "error": null, "meta": { ... } }
{ "data": null, "error": { "code": "API_QUOTA_EXCEEDED", "message": "..." } }

POST /api/v1/resolutions

Bis zu 100 Zollanfragen pro Aufruf. Jede Anfrage benötigt einen zehnstelligen US-HTS-Code, ein ISO-Ursprungsland (wird nie abgeleitet), einen USD-Zollwert, ein Bewertungsdatum und einen Integritäts-Hash der Eingaben. Die Validierung erfolgt pro Anfrage: eine ungültige oder nicht abgedeckte Anfrage liefert ein strukturiertes blockiertes Ergebnis mit Fehlercode; der Rest des Batches wird trotzdem aufgelöst.

curl -X POST https://tariffos.com/api/v1/resolutions \
  -H "Authorization: Bearer tos_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [{
      "requestId": "req-001",
      "externalVariantRef": "sku-123",
      "destination": "US",
      "origin": "JP",
      "hsCode": "3924.10.4000",
      "evaluationDate": "2026-07-29",
      "valuationAmount": "1000.00",
      "valuationCurrency": "USD",
      "costBasis": "supplier_only",
      "costBasisVersion": "v1",
      "inputHash": "f85ceeb48558e1244fe04a44754f733d6ed53501ce8cc4e92f6993ec64cc2aa0"
    }]
  }'

Eine abgedeckte Route liefert verifizierte Zollkomponenten mit Satz, Betrag, Quell-URLs und der exakten Regierungsquellenversion:

{
  "data": {
    "results": [{
      "requestId": "req-001",
      "coverage": "supported",
      "verificationStatus": "verified",
      "calculationStatus": "calculated",
      "components": [{
        "measureId": "us-hts-column-1-general",
        "authority": "mfn",
        "rateType": "ad_valorem",
        "rateValue": "3.4",
        "amount": "34.00",
        "sourceUrls": ["https://hts.usitc.gov/search?query=3924.10.40"],
        "sourceVersion": "USITC-2026HTSRev16"
      }],
      "estimatedDutyTotal": "34.00",
      "effectiveRate": "3.4",
      "engineVersion": "tariffos-resolver-m0.2.0",
      "warnings": ["M0 covers only the listed Column 1 General base rate for this exact route."]
    }]
  },
  "error": null,
  "meta": { "engineVersion": "tariffos-resolver-m0.2.0", "requestCount": 1 }
}

Das Feld inputHash

inputHash ist der SHA-256-Hex-Hash (Kleinbuchstaben) der JSON-Serialisierung der unten aufgeführten kanonisierten Anfragefelder (Ländercodes in Großbuchstaben, HTS-Code ohne Punkte, kanonische Dezimalbeträge). Er stellt sicher, dass ein gespeichertes Ergebnis immer exakt auf die Eingaben zurückführbar ist, die es erzeugt haben. Stimmt der Hash nicht mit den Eingaben überein, wird die Anfrage abgelehnt.

destination, origin, hsCode (dots removed), evaluationDate,
valuationAmount, valuationCurrency, costBasis, costBasisVersion,
quantity, customsQuantityUnit, netWeight, netWeightUnit

GET /api/v1/measure-changes

Cursor-paginierter Feed verifizierter Änderungen an Zollmaßnahmen — die maschinenlesbare Antwort auf "sag meiner Software, wenn sich etwas ändert, das meine HTS-Codes betrifft." Fragen Sie mit Ihrem letzten Cursor ab; limit ist 1–100 pro Seite. Jeder Eintrag zitiert offizielle Quellen und enthält alten und neuen Zustand.

curl "https://tariffos.com/api/v1/measure-changes?limit=100" \
  -H "Authorization: Bearer tos_live_..."

Der Feed schlägt geschlossen fehl: Er liefert ausschließlich Einträge, die gegen offizielle Quellsnapshots verifiziert wurden. Können keine verifizierten Daten geliefert werden, antwortet er mit HTTP 503 und dem Code MEASURE_CHANGE_FEED_NOT_READY statt zu raten.

POST /api/v1/mcp

Model-Context-Protocol-Server (Streamable HTTP, zustandsloses JSON-RPC über POST). Verbinden Sie KI-Assistenten wie Claude Desktop oder Cursor direkt mit der Auflösungs-Engine, der Abdeckungsmatrix und dem Änderungs-Feed — gleicher Schlüssel, gleiche Abrechnung (ein API-Aufruf pro Anfrage). Beispiel-Client-Konfiguration:

{
  "mcpServers": {
    "tariffos": {
      "url": "https://tariffos.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer tos_live_..." }
    }
  }
}

Verfügbare Tools: resolve_tariffs (Batch-Auflösung), get_coverage (die geprüfte Matrix — zuerst aufrufen), get_measure_changes (verifizierter Änderungs-Feed).

GET /api/v1/coverage

Die vollständige maschinenlesbare Abdeckungsmatrix: unterstützte Routen, bekannt nicht unterstützte Routen, Satzarten, Quellversionen mit SHA-256-Prüfsummen der Regierungsquelldateien und der verifizierte Bewertungszeitraum. Die aktuell unterstützten Routen:

curl https://tariffos.com/api/v1/coverage \
  -H "Authorization: Bearer tos_live_..."

Abdeckungsmatrix zuletzt am 2026-08-17 gegen die zitierten Regierungsquellen verifiziert.