API-Schnellstart ┅ KRAKE

Vorbereitung

Sie benötigen ein bestätigtes Konto, einen aktiven API-Schlüssel, genügend Guthaben und curl. Die Beispiele verwenden Bash. Richten Sie KRAKE_API_KEY wie unter Authentifizierung beschrieben ein und setzen Sie die Basis-URL:

export KRAKE_API_BASE="https://api.krake.run/api/v1"

Die API verwendet JSON für einzelne Datensätze und Antworten. CSV-Uploads werden als Multipart-Anfrage gesendet. Erfolgreich angenommene Aufträge antworten mit HTTP 202 Accepted; das Ergebnis wird später abgefragt.

1. Guthaben prüfen

curl --fail-with-body "$KRAKE_API_BASE/wallet/" \
  -H "X-API-Key: $KRAKE_API_KEY"

Das Feld balance enthält den Eurobetrag als Dezimalstring. Verarbeiten Sie Geldbeträge mit Dezimalarithmetik, nicht mit gerundeten Ganzzahlen. Aufträge werden vor dem Start auf ausreichendes Guthaben geprüft.

2. Einen Datensatz einreichen

curl --fail-with-body "$KRAKE_API_BASE/enrichment/batches/" \
  -H "X-API-Key: $KRAKE_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "product": "enrichment",
    "input_data": {
      "company_domain": "beispielbusiness.de",
      "kundennummer": "K-1001"
    }
  }'

Ersetzen Sie die fiktive Domain durch ein Unternehmen, das Sie verarbeiten möchten. Ein erfolgreich angenommener Auftrag antwortet beispielsweise:

{
  "batch_id": "11111111-1111-4111-8111-111111111111",
  "record_id": "22222222-2222-4222-8222-222222222222",
  "status": "queued"
}

Speichern Sie die tatsächlich zurückgegebenen Kennungen. Setzen Sie für die nächsten Schritte zwei Variablen; die UUIDs hier sind nur Platzhalter:

BATCH_ID="11111111-1111-4111-8111-111111111111"
RECORD_ID="22222222-2222-4222-8222-222222222222"

3. Auf Abschluss warten

curl --fail-with-body "$KRAKE_API_BASE/enrichment/batches/$BATCH_ID/" \
  -H "X-API-Key: $KRAKE_API_KEY"

Wiederholen Sie den Leseaufruf beispielsweise alle fünf Sekunden. Beenden Sie das Polling bei completed, partially_completed, failed oder cancelled. Prüfen Sie zusätzlich billing_paused und uncharged_records. Der Auftragsstatus und die Freigabe bezahlter Ergebnisse sind getrennte Zustände.

4. Ergebnis abrufen

curl --fail-with-body "$KRAKE_API_BASE/enrichment/records/$RECORD_ID/" \
  -H "X-API-Key: $KRAKE_API_KEY"

Lesen Sie result, status, error und payment_pending. Das Objekt result ist null, solange der Datensatz nicht abgeschlossen ist, fehlgeschlagen ist oder auf Zahlung wartet. Die Feldreferenz steht unter Ergebnisse & Export.

5. CSV herunterladen

curl --fail-with-body "$KRAKE_API_BASE/enrichment/batches/$BATCH_ID/export/" \
  -H "X-API-Key: $KRAKE_API_KEY" \
  -H "Accept: text/csv" \
  --output ergebnisse.csv

Prüfen Sie den Exit-Code von curl und den HTTP-Status, bevor Sie die Datei weiterverwenden. Bei einem Fehler kann die Datei statt CSV einen JSON-Fehlertext enthalten. Exportieren Sie innerhalb der Aufbewahrungsfrist.

Mehrere Datensätze verarbeiten

Für eine Liste verwenden Sie den CSV-Endpunkt. Der Einzelendpunkt erwartet ein Objekt unter input_data; er akzeptiert keine Liste unter records.

curl --fail-with-body "$KRAKE_API_BASE/enrichment/batches/csv/" \
  -H "X-API-Key: $KRAKE_API_KEY" \
  -F "product=enrichment" \
  -F "file=@unternehmen.csv;type=text/csv"

Die Antwort enthält batch_id, record_count und estimated_cost_eur. Rufen Sie die Ergebnisse über /enrichment/batches/{batch_id}/records/ ab und folgen Sie der zurückgegebenen URL in next, bis sie null ist. Jeder Datensatz enthält sein Ergebnis unter result.

Weitere Parameter, Ereignisströme und Auftragsaktionen: Endpunktreferenz. Für Fehlerbehandlung und Anfragelimits: Limits & Fehler.