REST-API
TariffPilot bietet eine REST-API für den programmatischen Zugriff auf Zolltarifierungsvorschläge.
OpenAPI-Spezifikation
Die REST-API wird durch eine OpenAPI-3-Spezifikation beschrieben, die ohne Autorisierung öffentlich verfügbar ist:
curl -X GET "https://app-cloud.tariffpilot.com/api/openapi.json"
Die Spezifikation kann in Tools wie Postman, Swagger UI oder OpenAPI-Codegeneratoren importiert werden, um die API zu erkunden oder Client-Code zu erzeugen. Sie wird mit jedem Release aktualisiert.
Autorisierung
Alle folgenden Endpunkte erfordern eine Autorisierung mit einem Bearer-Zugriffsschlüssel. Ein solcher Zugriffsschlüssel kann unter cloud.tariffpilot.com in den Mandanteneinstellungen auf dem Tab API abgerufen werden. Bitte beachte, dass der Zugriffsschlüssel an das Benutzerkonto und den Mandanten gebunden ist, für die er erzeugt wurde. Das Entfernen eines Nutzers aus einem Mandanten macht den Zugriffsschlüssel daher ungültig.
Token-Bindung und Gültigkeit
- An Nutzer und Mandanten gebunden: Ein Zugriffsschlüssel ist an das Benutzerkonto und den Mandanten gebunden, für die er erzeugt wurde. Er kann nicht über Mandanten hinweg verwendet werden. Das Entfernen des Nutzers aus dem Mandanten macht den Zugriffsschlüssel sofort ungültig.
- Ablauf: Zugriffsschlüssel sind langlebig.
- Geheimhaltung: Behandle den Schlüssel wie ein Passwort. Um einen Schlüssel zu rotieren, erzeuge auf dem Tab
APIeinen neuen.
Fehler
Die API gibt kein strukturiertes Fehlerobjekt zurück.
Häufige Antworten:
| Status | Situation | Beispiel-Body |
|---|---|---|
400 Bad Request | Fehlende oder leere description (Zolltarifierungsvorschläge, Klassifizierungsvorschläge) | description must not be null in JSON |
400 Bad Request | Fehlende oder leere direction (Zolltarifierungsvorschläge) | direction must not be null in JSON |
400 Bad Request | Fehlende Vorschlags-ID im Pfad oder fehlerhafter JSON-Body | (Meldung oder leerer Body) |
403 Forbidden | Fehlendes/ungültiges Token oder unzureichende Rolle | Unauthorized |
403 Forbidden | Quota des Mandanten für Vorschläge erschöpft | Customs tariff proposals limit reached / Classification proposals limit reached |
404 Not Found | Die Vorschlags-ID existiert im Mandanten nicht | (leerer Body) |
429 Too Many Requests | Nur auf Auth-/OAuth-Endpunkten, nicht auf den Vorschlags-Endpunkten | Too Many Requests |
API für Zolltarifierungsvorschläge
Alle Zolltarifierungsvorschläge als JSON auflisten
Gibt eine JSON-Liste aller Zolltarifierungsvorschläge im Mandanten zurück.
curl -X GET "https://app-cloud.tariffpilot.com/api/customs_tariff_proposals" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"
Eine Liste aller Zolltarifierungsvorschläge nach Vendor-ID kann wie folgt abgerufen werden:
curl -X GET "https://app-cloud.tariffpilot.com/api/customs_tariff_proposals/by_vendor_id?vendor_id=123" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"
Einen Zolltarifierungsvorschlag als JSON abrufen
Gibt eine JSON-Darstellung des Zolltarifierungsvorschlags im Mandanten zurück.
curl -X GET "https://app-cloud.tariffpilot.com/api/customs_tariff_proposals/<CUSTOMS_TARIFF_PROPOSAL_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"
Einen Zolltarifierungsvorschlag als PDF abrufen
Gibt eine PDF-Darstellung des Zolltarifierungsvorschlags im Mandanten zurück.
curl -X GET "https://app-cloud.tariffpilot.com/api/customs_tariff_proposals/pdf/<CUSTOMS_TARIFF_PROPOSAL_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/pdf"
Optional kannst du die Sprache angeben. Die Standardsprache ist en. Weitere Sprachen sind de für Deutsch.
curl -X GET "https://app-cloud.tariffpilot.com/api/customs_tariff_proposals/pdf/<CUSTOMS_TARIFF_PROPOSAL_ID>?language=de" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/pdf"
Einen Zolltarifierungsvorschlag als Markdown abrufen
Gibt eine Markdown-Darstellung des Zolltarifierungsvorschlags im Mandanten zurück.
curl -X GET "https://app-cloud.tariffpilot.com/api/customs_tariff_proposals/markdown/<CUSTOMS_TARIFF_PROPOSAL_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: text/markdown"
Optional kannst du die Sprache angeben. Die Standardsprache ist en. Weitere Sprachen sind de für Deutsch.
curl -X GET "https://app-cloud.tariffpilot.com/api/customs_tariff_proposals/markdown/<CUSTOMS_TARIFF_PROPOSAL_ID>?language=de" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: text/markdown"
Einen Zolltarifierungsvorschlag als HTML abrufen
Gibt eine HTML-Darstellung des Zolltarifierungsvorschlags im Mandanten zurück.
curl -X GET "https://app-cloud.tariffpilot.com/api/customs_tariff_proposals/html/<CUSTOMS_TARIFF_PROPOSAL_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: text/html"
Optional kannst du die Sprache angeben. Die Standardsprache ist en. Weitere Sprachen sind de für Deutsch.
curl -X GET "https://app-cloud.tariffpilot.com/api/customs_tariff_proposals/html/<CUSTOMS_TARIFF_PROPOSAL_ID>?language=de" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: text/html"
Einen Zolltarifierungsvorschlag löschen
Löscht den Zolltarifierungsvorschlag im Mandanten.
curl -X DELETE "https://app-cloud.tariffpilot.com/api/customs_tariff_proposals/<CUSTOMS_TARIFF_PROPOSAL_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"
Einen Zolltarifierungsvorschlag anlegen
Sendet eine JSON-Darstellung eines Zolltarifierungsvorschlags in den Mandanten. Der Vorschlag wird in der Datenbank angelegt und asynchron verarbeitet.
curl -X POST "https://app-cloud.tariffpilot.com/api/customs_tariff_proposals" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{ "description": "Nici Einhorn 80cm", "direction": "export", "search_web": true, "vendor_id": "123" }'
Die Eigenschaft direction ist verpflichtend und kann entweder export für einen 8-stelligen oder import für einen 11-stelligen Zollcode sein. Die Eigenschaft tariff_system ist optional und standardmäßig de, z. B. ch für den Schweizer Zolltarif. Die Eigenschaft search_web ist optional und standardmäßig false. Wenn sie auf true gesetzt ist, wird das Web nach der Produktbeschreibung durchsucht. Die Eigenschaft vendor_id ist optional und kann verwendet werden, um den Zolltarifierungsvorschlag einer Vendor-ID aus deinem System zuzuordnen.
curl -X POST "https://app-cloud.tariffpilot.com/api/customs_tariff_proposals" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{ "description": "Nici Einhorn 80cm", "direction": "export", "job_id": <JOB_ID>, "search_web": true }'
Die Eigenschaft job_id ist optional und kann verwendet werden, um den Zolltarifierungsvorschlag einem Job zuzuordnen. Die job_id muss ein UUID4-String sein. Wenn der Job nicht existiert, wird er angelegt.
Zum Neue-Vorschlag-Bildschirm für Zolltarifierungsvorschläge navigieren
Sendet eine Anfrage, einen Neue-Bildschirm für Zolltarifierungsvorschläge im Mandanten zu öffnen. Der Vorschlag wird nicht in der Datenbank angelegt. Stattdessen wird ein JSON-Objekt mit einer authorize_url zurückgegeben. Die authorize_url kann verwendet werden, um den Zolltarifierungsvorschlag in der TariffPilot-Web-App zu öffnen.
curl -X POST "https://app-cloud.tariffpilot.com/api/customs_tariff_proposals/new" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{ "description": "Nici Einhorn 80cm", "reference_id": "PO-2026-0815", "vendor_id": "123" }'
Beim ersten Öffnen eines Zolltarifierungsvorschlags wird ein Service-Nutzer angelegt. Derzeit gibt es keine Option, einen Stellvertreter-Nutzer anzugeben, der als Ersteller des Zolltarifierungsvorschlags in der TariffPilot-Web-App erscheinen soll. Die Eigenschaft reference_id ist optional und füllt die Referenz-ID des Zolltarifierungsvorschlags im Neue-Bildschirm vor. Die Eigenschaft vendor_id ist optional und kann verwendet werden, um den Zolltarifierungsvorschlag einer Vendor-ID aus deinem System zuzuordnen.
Antwortfelder
Die customs_tariff_proposals-Endpunkte geben Objekte mit den folgenden Feldern zurück. Felder, die null sind, werden in der JSON-Antwort ausgelassen.
| Feld | Typ | Beschreibung |
|---|---|---|
id | UUID-String | Eindeutige ID des Vorschlags. |
state | String | Workflow-Status, siehe Vorschlagsstatus und Datenqualität. |
data_quality | String | Konfidenz des Ergebnisses: low, medium oder high. Siehe Vorschlagsstatus und Datenqualität. |
code | String | Die ermittelte Zolltarifnummer (8 Stellen für export, 11 Stellen für import; 8 oder 10 Stellen für den US-Zolltarif). |
direction | String | export (8-stelliger Code) oder import (11-stelliger Code). |
description | String | Die übermittelte Produktbeschreibung. |
tariff_system | String | Zolltarif-System: de, ch oder us. |
bti_code | String | Zollcode einer passenden verbindlichen Zolltarifauskunft (vZTA), falls vorhanden. |
bti_reference | String | Referenznummer der passenden vZTA, falls vorhanden. |
proposed_customs_description | String | Die von der KI vorgeschlagene zollrechtliche Warenbeschreibung auf Deutsch (gleicher Wert wie proposed_customs_description_de). |
proposed_customs_description_de | String | Die von der KI vorgeschlagene zollrechtliche Warenbeschreibung auf Deutsch. |
proposed_customs_description_en | String | Die von der KI vorgeschlagene zollrechtliche Warenbeschreibung auf Englisch. |
proposed_customs_description_short | String | Eine Kurzform der vorgeschlagenen zollrechtlichen Warenbeschreibung auf Deutsch (gleicher Wert wie proposed_customs_description_short_de). |
proposed_customs_description_short_de | String | Eine Kurzform der vorgeschlagenen zollrechtlichen Warenbeschreibung auf Deutsch. |
proposed_customs_description_short_en | String | Eine Kurzform der vorgeschlagenen zollrechtlichen Warenbeschreibung auf Englisch. |
reference_id | String | Surrogatschlüssel, den du zur Identifizierung des Vorschlags in deinem System angegeben hast. |
vendor_id | String | Vendor-ID, die du zur Zuordnung des Vorschlags zu einem Anbieter in deinem System angegeben hast. |
job_id | UUID-String | ID des Batch-Jobs, zu dem der Vorschlag gehört, falls vorhanden. |
test_code | String | Erwarteter Zolltarifcode eines Test-Suite-Jobs, falls vorhanden. |
created_at | Zahl | Erstellungszeit als Unix-Zeitstempel in Millisekunden. |
updated_at | Zahl | Zeitpunkt der letzten Aktualisierung als Unix-Zeitstempel in Millisekunden. |
memo_markdown_de | String | Das vollständig erzeugte Memo auf Deutsch (Markdown). Nur in Einzelvorschlags-GET/POST-Antworten, nicht in Listenantworten. |
memo_markdown_en | String | Das vollständig erzeugte Memo auf Englisch (Markdown). Nur in Einzelvorschlags-GET/POST-Antworten, nicht in Listenantworten. |
authorize_url | String | URL zum Öffnen des Vorschlags in der TariffPilot-Web-App. |
Hinweis zu Zeitstempeln: created_at und updated_at werden als Zahlen (Epochen-Millisekunden) serialisiert, nicht als ISO-8601-Strings.
Beispiel-JSON-Antworten
Unmittelbar nach POST /api/customs_tariff_proposals wird der neu angelegte Vorschlag zurückgegeben. Die Verarbeitung ist asynchron, daher ist state gleich start und Ergebnisfelder wie code sind noch nicht vorhanden:
{
"id": "3f9a2c14-8b7e-4c2a-9f1d-2e5b6a7c8d90",
"state": "start",
"description": "Nici Einhorn 80cm",
"direction": "export",
"tariff_system": "de",
"reference_id": "PO-2026-0815",
"vendor_id": "123",
"created_at": 1754737200000,
"updated_at": 1754737200000,
"authorize_url": "https://app-cloud.tariffpilot.com/auth/oauth2/api/callback?code=...&state=..."
}
Nach Abschluss der Verarbeitung gibt GET /api/customs_tariff_proposals/<CUSTOMS_TARIFF_PROPOSAL_ID> den abgeschlossenen Vorschlag zurück:
{
"id": "3f9a2c14-8b7e-4c2a-9f1d-2e5b6a7c8d90",
"state": "end",
"data_quality": "high",
"code": "95034910",
"description": "Nici Einhorn 80cm",
"direction": "export",
"tariff_system": "de",
"proposed_customs_description": "Stofftiere in Gestalt von Tieren",
"proposed_customs_description_de": "Stofftiere in Gestalt von Tieren",
"proposed_customs_description_en": "Stuffed animals in the form of animals",
"proposed_customs_description_short": "Stofftiere",
"proposed_customs_description_short_de": "Stofftiere",
"proposed_customs_description_short_en": "Stuffed animals",
"reference_id": "PO-2026-0815",
"vendor_id": "123",
"created_at": 1754737200000,
"updated_at": 1754737512000,
"memo_markdown_de": "# Zolltarifvorschlag\n\n...",
"memo_markdown_en": "# Customs Tariff Proposal\n\n...",
"authorize_url": "https://app-cloud.tariffpilot.com/auth/oauth2/api/callback?code=...&state=..."
}
Der Listen-Endpunkt GET /api/customs_tariff_proposals gibt ein JSON-Array derselben Objekte zurück, jedoch ohne direction, bti_reference und die Felder memo_markdown_de/memo_markdown_en:
[
{
"id": "3f9a2c14-8b7e-4c2a-9f1d-2e5b6a7c8d90",
"state": "end",
"data_quality": "high",
"code": "95034910",
"description": "Nici Einhorn 80cm",
"tariff_system": "de",
"reference_id": "PO-2026-0815",
"vendor_id": "123",
"created_at": 1754737200000,
"updated_at": 1754737512000,
"authorize_url": "https://app-cloud.tariffpilot.com/auth/oauth2/api/callback?code=...&state=..."
}
]
Der Endpunkt POST /api/customs_tariff_proposals/new legt keinen Vorschlag an; er gibt nur eine authorize_url zurück:
{
"authorize_url": "https://app-cloud.tariffpilot.com/auth/oauth2/api/callback?code=...&state=..."
}
Vorschlagsstatus und Datenqualität
Das Feld state spiegelt den asynchronen Workflow wider. Für Zolltarifierungsvorschläge nimmt es einen der folgenden Werte an, in dieser Reihenfolge:
state | Bedeutung |
|---|---|
start | Der Vorschlag wurde angelegt und wartet auf die Verarbeitung. |
product_done | Der Schritt der Produktanalyse ist abgeschlossen. |
code_done | Die Zolltarifnummer wurde ermittelt. |
bti_done | Der Schritt des Abgleichs mit verbindlichen Zolltarifauskünften (vZTA) ist abgeschlossen. |
ruling_done | Der Schritt des Zollentscheid-Abgleichs ist abgeschlossen. |
training_done | Der Schritt des Trainingsdaten-Abgleichs ist abgeschlossen. |
end | Die Verarbeitung ist abgeschlossen. Dies ist der Endzustand. |
Hinweise:
stateist ein einfacher String. Bevor der erste Schritt läuft, kann er kurzzeitigstartsein; in seltenen Fällen kann das Feld für ein Objekt, das überhaupt nicht verarbeitet wurde, fehlen (null).- Diese Status können in Zukunft erweitert oder geändert werden. Verlasse dich nicht auf die exakten Werte, sondern nur auf die Reihenfolge und den Endzustand
end. - Ein Vorschlag ist genau dann abgeschlossen, wenn
stategleichendist. Frage perGETab, bis dies der Fall ist. - Die API legt keinen eigenen Status „wartet auf Klarstellung" offen, und die Nachfragen der KI selbst sind nicht Teil des von diesen Endpunkten zurückgegebenen JSON. Ein Vorschlag, der über einen längeren Zeitraum in einem Nicht-
end-Status verharrt, ohne Fortschritt zu machen, ist ein Kandidat für eine manuelle Prüfung.
Das Feld data_quality gibt an, wie konfident das Ergebnis ist und ob Informationen fehlen:
data_quality | Bedeutung |
|---|---|
high | Es wurde ein Code gefunden und alle relevanten Informationen waren verfügbar. |
medium | Es wurde ein Code gefunden, aber einige Informationen fehlen – das Ergebnis kann verbesserbar sein. |
low | Es konnte kein Code gefunden werden / die Informationen sind unzureichend. |
API für Klassifizierungsvorschläge
Alle Klassifizierungsvorschläge als JSON auflisten
Gibt eine JSON-Liste aller Klassifizierungsvorschläge im Mandanten zurück.
curl -X GET "https://app-cloud.tariffpilot.com/api/classification_proposals" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"
Eine Liste aller Klassifizierungsvorschläge nach Vendor-ID kann wie folgt abgerufen werden:
curl -X GET "https://app-cloud.tariffpilot.com/api/classification_proposals/by_vendor_id?vendor_id=123" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"
Einen Klassifizierungsvorschlag als JSON abrufen
Gibt eine JSON-Darstellung des Klassifizierungsvorschlags im Mandanten zurück.
curl -X GET "https://app-cloud.tariffpilot.com/api/classification_proposals/<CLASSIFICATION_PROPOSAL_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"
Einen Klassifizierungsvorschlag als PDF abrufen
Gibt eine PDF-Darstellung des Klassifizierungsvorschlags im Mandanten zurück.
curl -X GET "https://app-cloud.tariffpilot.com/api/classification_proposals/pdf/<CLASSIFICATION_PROPOSAL_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/pdf"
Optional kannst du die Sprache angeben. Die Standardsprache ist en. Weitere Sprachen sind de für Deutsch.
curl -X GET "https://app-cloud.tariffpilot.com/api/classification_proposals/pdf/<CLASSIFICATION_PROPOSAL_ID>?language=de" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/pdf"
Einen Klassifizierungsvorschlag als Markdown abrufen
Gibt eine Markdown-Darstellung des Klassifizierungsvorschlags im Mandanten zurück.
curl -X GET "https://app-cloud.tariffpilot.com/api/classification_proposals/markdown/<CLASSIFICATION_PROPOSAL_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: text/markdown"
Optional kannst du die Sprache angeben. Die Standardsprache ist en. Weitere Sprachen sind de für Deutsch.
curl -X GET "https://app-cloud.tariffpilot.com/api/classification_proposals/markdown/<CLASSIFICATION_PROPOSAL_ID>?language=de" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: text/markdown"
Einen Klassifizierungsvorschlag als HTML abrufen
Gibt eine HTML-Darstellung des Klassifizierungsvorschlags im Mandanten zurück.
curl -X GET "https://app-cloud.tariffpilot.com/api/classification_proposals/html/<CLASSIFICATION_PROPOSAL_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: text/html"
Optional kannst du die Sprache angeben. Die Standardsprache ist en. Weitere Sprachen sind de für Deutsch.
curl -X GET "https://app-cloud.tariffpilot.com/api/classification_proposals/html/<CLASSIFICATION_PROPOSAL_ID>?language=de" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: text/html"
Einen Klassifizierungsvorschlag löschen
Löscht den Klassifizierungsvorschlag im Mandanten.
curl -X DELETE "https://app-cloud.tariffpilot.com/api/classification_proposals/<CLASSIFICATION_PROPOSAL_ID>" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"
Einen Klassifizierungsvorschlag anlegen
Sendet eine JSON-Darstellung eines Klassifizierungsvorschlags in den Mandanten. Der Vorschlag wird in der Datenbank angelegt und asynchron verarbeitet.
curl -X POST "https://app-cloud.tariffpilot.com/api/classification_proposals" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{ "description": "Nici Einhorn 80cm", "search_web": true, "vendor_id": "123" }'
Die Eigenschaft search_web ist optional und standardmäßig false. Wenn sie auf true gesetzt ist, wird das Web nach der Produktbeschreibung durchsucht. Die Eigenschaft vendor_id ist optional und kann verwendet werden, um den Klassifizierungsvorschlag einer Vendor-ID aus deinem System zuzuordnen.
Zum Neue-Vorschlag-Bildschirm für Klassifizierungsvorschläge navigieren
Sendet eine Anfrage, einen Neue-Bildschirm für Klassifizierungsvorschläge im Mandanten zu öffnen. Der Vorschlag wird nicht in der Datenbank angelegt. Stattdessen wird ein JSON-Objekt mit einer authorize_url zurückgegeben. Die authorize_url kann verwendet werden, um den Klassifizierungsvorschlag in der TariffPilot-Web-App zu öffnen.
curl -X POST "https://app-cloud.tariffpilot.com/api/classification_proposals/new" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{ "description": "Nici Einhorn 80cm", "reference_id": "PO-2026-0815", "vendor_id": "123" }'
Beim ersten Öffnen eines Klassifizierungsvorschlags wird ein Service-Nutzer angelegt. Derzeit gibt es keine Option, einen Stellvertreter-Nutzer anzugeben, der als Ersteller des Klassifizierungsvorschlags in der TariffPilot-Web-App erscheinen soll. Die Eigenschaft reference_id ist optional und füllt die Referenz-ID des Klassifizierungsvorschlags im Neue-Bildschirm vor. Die Eigenschaft vendor_id ist optional und kann verwendet werden, um den Klassifizierungsvorschlag einer Vendor-ID aus deinem System zuzuordnen.
Antwortfelder
Die classification_proposals-Endpunkte geben Objekte mit den folgenden Feldern zurück. Felder, die null sind, werden in der JSON-Antwort ausgelassen. Beachte, dass Klassifizierungsvorschläge kein Feld data_quality tragen.
| Feld | Typ | Beschreibung |
|---|---|---|
id | UUID-String | Eindeutige ID des Vorschlags. |
state | String | Workflow-Status, siehe Vorschlagsstatus. |
description | String | Die übermittelte Produktbeschreibung. |
identification_military_equipment | String | Ergebnis der Rüstungsgüterprüfung (militärische Ausrüstung). Nur in Einzelvorschlags-GET/POST-Antworten. |
identification_dual_use_eu | String | Ergebnis der EU-Dual-Use-Prüfung. Nur in Einzelvorschlags-GET/POST-Antworten. |
identification_dual_use_de | String | Ergebnis der deutschen Dual-Use-Prüfung. Nur in Einzelvorschlags-GET/POST-Antworten. |
reference_id | String | Surrogatschlüssel, den du zur Identifizierung des Vorschlags in deinem System angegeben hast. |
vendor_id | String | Vendor-ID, die du zur Zuordnung des Vorschlags zu einem Anbieter in deinem System angegeben hast. |
created_at | Zahl | Erstellungszeit als Unix-Zeitstempel in Millisekunden. |
updated_at | Zahl | Zeitpunkt der letzten Aktualisierung als Unix-Zeitstempel in Millisekunden. |
authorize_url | String | URL zum Öffnen des Vorschlags in der TariffPilot-Web-App. |
Hinweis zu Zeitstempeln: created_at und updated_at werden als Zahlen (Epochen-Millisekunden) serialisiert, nicht als ISO-8601-Strings.
Beispiel-JSON-Antworten
Unmittelbar nach POST /api/classification_proposals wird der neu angelegte Vorschlag mit state start zurückgegeben:
{
"id": "a71c0e42-3d55-4f18-9b2c-1a6d4e7f8091",
"state": "start",
"description": "Nici Einhorn 80cm",
"reference_id": "PO-2026-0815",
"vendor_id": "123",
"created_at": 1754737200000,
"updated_at": 1754737200000,
"authorize_url": "https://app-cloud.tariffpilot.com/auth/oauth2/api/callback?code=...&state=..."
}
Nach Abschluss der Verarbeitung gibt GET /api/classification_proposals/<CLASSIFICATION_PROPOSAL_ID> den abgeschlossenen Vorschlag einschließlich der Identifikationsergebnisse zurück:
{
"id": "a71c0e42-3d55-4f18-9b2c-1a6d4e7f8091",
"state": "end",
"description": "Nici Einhorn 80cm",
"identification_military_equipment": "...",
"identification_dual_use_eu": "...",
"identification_dual_use_de": "...",
"reference_id": "PO-2026-0815",
"vendor_id": "123",
"created_at": 1754737200000,
"updated_at": 1754737512000,
"authorize_url": "https://app-cloud.tariffpilot.com/auth/oauth2/api/callback?code=...&state=..."
}
Der Listen-Endpunkt GET /api/classification_proposals gibt ein JSON-Array derselben Objekte zurück, jedoch ohne die drei identification_*-Felder.
Vorschlagsstatus
Das Feld state spiegelt den asynchronen Workflow wider. Für Klassifizierungsvorschläge nimmt es einen der folgenden Werte an, in dieser Reihenfolge:
state | Bedeutung |
|---|---|
start | Der Vorschlag wurde angelegt und wartet auf die Verarbeitung. |
product_done | Der Schritt der Produktanalyse ist abgeschlossen. |
military_done | Die Rüstungsgüterprüfung (militärische Ausrüstung) ist abgeschlossen. |
dual_use_eu_done | Die EU-Dual-Use-Prüfung ist abgeschlossen. |
dual_use_de_done | Die deutsche Dual-Use-Prüfung ist abgeschlossen. |
end | Die Verarbeitung ist abgeschlossen. Dies ist der Endzustand. |
Hinweise:
stateist ein einfacher String. Bevor der erste Schritt läuft, kann er kurzzeitigstartsein; in seltenen Fällen kann das Feld für ein Objekt, das überhaupt nicht verarbeitet wurde, fehlen (null).- Diese Status können in Zukunft erweitert oder geändert werden. Verlasse dich nicht auf die exakten Werte, sondern nur auf die Reihenfolge und den Endzustand
end. - Die API legt keinen eigenen Status „wartet auf Klarstellung" offen, und die Nachfragen der KI selbst sind nicht Teil des von diesen Endpunkten zurückgegebenen JSON. Ein Vorschlag, der über einen längeren Zeitraum in einem Nicht-
end-Status verharrt, ohne Fortschritt zu machen, ist ein Kandidat für eine manuelle Prüfung.
Mandanten-API
Mandanteninformationen abrufen
Gibt eine JSON-Darstellung des Mandanten zurück.
curl -X GET "https://app-cloud.tariffpilot.com/api/tenant" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json"
Antwortfelder
Felder, die null sind, werden in der JSON-Antwort ausgelassen. Dieser Endpunkt ist schreibgeschützt; es gibt keinen API-Endpunkt zum Aktualisieren der Mandanteneinstellungen.
| Feld | Typ | Beschreibung |
|---|---|---|
id | UUID-String | Eindeutige ID des Mandanten. |
name | String | Anzeigename des Mandanten. |
classification_proposals_count | Zahl | Anzahl der im aktuellen Abrechnungszeitraum erstellten Klassifizierungsvorschläge. |
classification_proposals_limit | Zahl | Vertragliches Limit für Klassifizierungsvorschläge des Mandanten. |
customs_tariff_proposals_count | Zahl | Anzahl der im aktuellen Abrechnungszeitraum erstellten Zolltarifierungsvorschläge. |
customs_tariff_proposals_limit | Zahl | Vertragliches Limit für Zolltarifierungsvorschläge des Mandanten. |
Beispiel-JSON-Antwort
{
"id": "6b2f1a9e-4d3c-4a7b-8f21-0c9d5e7a1b34",
"name": "Acme GmbH",
"classification_proposals_count": 12,
"classification_proposals_limit": 100,
"customs_tariff_proposals_count": 348,
"customs_tariff_proposals_limit": 1000
}