Εμπλουτισμός δεδομένων πελατών
Πρόσθεσε εταιρικά δεδομένα στη λίστα πελατών σου.
Έχεις μια λίστα με επωνυμίες, πόλεις ή αριθμούς μητρώου και θέλεις να προσθέσεις σε αυτήν επίσημα εταιρικά δεδομένα. Χρειάζεσαι μόνο το fetch-organization· δεν χρειάζεται να κάνεις πρώτα αναζήτηση.
Αντιστοίχιση εταιρειών
Στείλε ένα αίτημα ανά πελάτη με το καλύτερο στοιχείο που έχεις. Το δικαστήριο μητρώου και ο αριθμός μητρώου είναι τα καλύτερα, γιατί είναι μοναδικά. Αν δεν τα έχεις, χρησιμοποίησε την επωνυμία με νομική μορφή και πόλη. Το παράδειγμα αιτήματός μας αναζητά τη Hetzner Online GmbH, Ansbach HRB 6089, με επωνυμία και πόλη.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode 'q=Hetzner Online GmbH Gunzenhausen'
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-organization", headers={"x-api-key": "YOUR_API_KEY"}, params={ "q": "Hetzner Online GmbH Gunzenhausen", }, ) data = response.json()
const url = new URL("https://handelsregister.ai/api/v1/fetch-organization"); url.searchParams.append("q", "Hetzner Online GmbH Gunzenhausen"); const response = await fetch(url, { headers: { "x-api-key": "YOUR_API_KEY" }, }); const data = await response.json();
1{2 "entity_id": "94eb910fef13f94585c48c263fa446d4",3 "name": "Hetzner Online GmbH",4 "status": "ACTIVE",5 "registration": {6 "court": "Ansbach",7 "register_type": "HRB",8 "register_number": "6089"9 },10 "address": {11 "house_number": "25",12 "street": "Industriestraße",13 "postal_code": "91710",14 "city": "Gunzenhausen",15 "county": "Weißenburg-Gunzenhausen",16 "state": "Bayern",17 "country": "DEU",18 "coordinates": {19 "latitude": 49.12483,20 "longitude": 10.7805221 }22 },23 "meta": {24 "request_credit_cost": 5,25 "credits_remaining": 14526 }27}
Έλεγξε την απάντηση σε σχέση με τα δεδομένα σου, για παράδειγμα τον ταχυδρομικό κώδικα ή την πόλη στο address. Με συνήθεις επωνυμίες, θα μπορούσε διαφορετικά να επιστραφεί μια ομώνυμη εταιρεία.
Αποθήκευσε το entity_id μαζί με τον πελάτη σου. Όλες οι μεταγενέστερες ανακτήσεις, τα έγγραφα, τα Signals και τα monitors λειτουργούν τότε με αυτό το αναγνωριστικό.
ai_search=on-default) επιλεκτικά για ασαφείς καταχωρίσεις· κοστίζει επιπλέον 20 πιστώσεις, ακόμη και χωρίς αποτέλεσμα.
Ανάκτηση πολλών εταιρειών
Το fetch-organization επιτρέπει 60 αιτήματα ανά λεπτό. Στείλε τα αιτήματα ομοιόμορφα, το ένα μετά το άλλο. Σε HTTP 429, περίμενε τα δευτερόλεπτα από το Retry-After. Αν χρειάζεσαι περισσότερα, το Enterprise προσφέρει υψηλότερα όρια, βλ. Τιμές.
Δώσε σε κάθε αίτημα ένα Idempotency-Key, για παράδειγμα τον αριθμό πελάτη. Αν το επαναλάβεις με το ίδιο κλειδί και τις ίδιες παραμέτρους μέσα σε 24 ώρες, δεν κοστίζει τίποτα.
Σε HTTP 408 (το αίτημα διήρκεσε πολύ), το API δεν χρεώνει τίποτα, ούτε τη Λειτουργία AI. Σε σφάλμα με status 500 ή μεγαλύτερο, χρεώνεται μόνο η Λειτουργία AI, αν την επέλεξες. Δοκίμασε ξανά αργότερα με το ίδιο Idempotency-Key.
Το σενάριο διαβάζει το customers.csv με τις στήλες id, name, city και register. Η στήλη register περιέχει τον αριθμό μητρώου με το δικαστήριό του, όπως Ansbach HRB 6089, ή τίποτα. Το σενάριο γράφει ένα αντίγραφο με entity_id, δικαστήριο μητρώου και αριθμό μητρώου και μετρά τις πιστώσεις που καταναλώθηκαν.
import csv import time import requests API = "https://handelsregister.ai/api/v1/fetch-organization" HEADERS = {"x-api-key": "YOUR_API_KEY", "Accept": "application/json"} PER_MINUTE = 60 # όριο του fetch-organization def lookup(row): # Το δικαστήριο μητρώου μαζί με τον αριθμό μητρώου είναι μοναδικά· διαφορετικά επωνυμία και πόλη q = row["register"] or f'{row["name"]} {row["city"]}' headers = {**HEADERS, "Idempotency-Key": f'customer-{row["id"]}'} for attempt in range(5): response = requests.get(API, params={"q": q}, headers=headers, timeout=120) if response.status_code == 429: time.sleep(int(response.headers.get("Retry-After", "10"))) elif response.status_code in (408, 500, 502, 503, 504): time.sleep(30 * (attempt + 1)) else: break return response spent = 0 with open("customers.csv", newline="") as source, open("customers_enriched.csv", "w", newline="") as target: reader = csv.DictReader(source) writer = csv.DictWriter(target, fieldnames=reader.fieldnames + ["entity_id", "register_court", "register_number"]) writer.writeheader() for row in reader: response = lookup(row) if response.status_code == 402: print("Δεν επαρκούν οι πιστώσεις, η εκτέλεση σταμάτησε") break data = response.json() spent += data.get("meta", {}).get("request_credit_cost", 0) if response.status_code == 200: registration = data.get("registration") or {} row["entity_id"] = data["entity_id"] row["register_court"] = registration.get("court") row["register_number"] = f'{registration.get("register_type")} {registration.get("register_number")}' writer.writerow(row) time.sleep(60 / PER_MINUTE) print(f"Καταναλώθηκαν: {spent} πιστώσεις")
Μια δεύτερη εκτέλεση μέσα σε 24 ώρες δεν κοστίζει τίποτα. Η απάντηση φέρει τότε Idempotency-Status: replayed και request_credit_cost 0.
1{2 "entity_id": "94eb910fef13f94585c48c263fa446d4",3 "name": "Hetzner Online GmbH",4 "meta": {5 "request_credit_cost": 0,6 "credits_remaining": 1457 }8}
enrich, έναν έτοιμο εμπλουτισμό για αρχεία CSV, JSON και Excel.
Έλεγχος κόστους
Κάνε εκτίμηση εκ των προτέρων με τον τιμοκατάλογο: 5 πιστώσεις ανά εταιρεία για τα βασικά στοιχεία, συν την τιμή κάθε feature. Τα βασικά στοιχεία κοστίζουν σε κάθε αντιστοίχιση. Τα features χωρίς δεδομένα δεν κοστίζουν τίποτα, οπότε το πραγματικό κόστος είναι συχνά χαμηλότερο. Οι προσαυξήσεις δεν είναι features: η Λειτουργία AI κοστίζει ακόμη και χωρίς αποτέλεσμα, ο Πραγματικός χρόνος σε κάθε επιτυχή ανάκτηση.
| Τι | Πιστώσεις |
|---|---|
| Προφίλ εταιρείας με τα βασικά στοιχεία | 5 |
| Κάθε feature, μόνο όταν επιστρέφει δεδομένα | 1 έως 80 |
| Λειτουργία AI, ακόμη και χωρίς αποτέλεσμα | +20 |
| Πραγματικός χρόνος, για κάθε επιτυχή ζωντανή ανάκτηση | +10 |
Όριο: 60 αιτήματα ανά λεπτό.
Πόσο κόστισε πραγματικά ένα αίτημα αναγράφεται σε κάθε απάντηση στο meta.request_credit_cost.
Τι κόστισε ένα αίτημα βρίσκεται στο meta.request_credit_cost, το υπόλοιπο που απομένει στο meta.credits_remaining. Άθροιζε το κόστος καθώς προχωράς, όπως στο παραπάνω σενάριο.
Πριν από κάθε αίτημα, το API ελέγχει αν το υπόλοιπό σου καλύπτει την υψηλότερη δυνατή τιμή. Αν όχι, το API απαντά με HTTP 402 και δεν χρεώνει τίποτα. Το σενάριο σταματά τότε.
Το υπόλοιπο και τη χρήση σου μπορείς να τα ελέγχεις ανά πάσα στιγμή δωρεάν μέσω του account.
Συνήθεις παγίδες
- Αριθμός μητρώου χωρίς δικαστήριο: Αν τα δεδομένα σου γράφουν μόνο «HRB 6089», το API δεν βρίσκει εταιρεία. Πρόσθεσε το δικαστήριο μητρώου ή χρησιμοποίησε επωνυμία και πόλη.
- Ένα κλειδί, ένα αίτημα: Το ίδιο
Idempotency-Keyμε διαφορετικές παραμέτρους επιστρέφει HTTP 422. Για ένα τροποποιημένο αίτημα, χρησιμοποίησε νέο κλειδί. - Μορφή κλειδιού: Επιτρέπονται έως 128 χαρακτήρες από γράμματα, ψηφία και
. _ : -, με αρχή γράμμα ή ψηφίο. Το API αγνοεί ένα κλειδί σε οποιαδήποτε άλλη μορφή. Το αίτημα εκτελείται τότε χωρίς αυτή την προστασία. - Timeout: Με Πραγματικό χρόνο ή πολλά features, ένα αίτημα διαρκεί περισσότερο. Όρισε το timeout του client σου σε τουλάχιστον 120 δευτερόλεπτα.