Βασικές έννοιες

Η παράμετρος q του fetch-organization δέχεται τρία είδη εισόδου. Τα παραδείγματα αυτής της σελίδας είναι αιτήματα για τη Hetzner Online GmbH, Ansbach HRB 6089:

Ο αριθμός μητρώου μόνος του δεν αρκεί, γιατί κάθε δικαστήριο μητρώου αποδίδει δικούς του αριθμούς. Η σειρά, αντίθετα, είναι ελεύθερη: στο παράδειγμα, το HRB 6089 Ansbach βρίσκει την ίδια εταιρεία.

Αν το API δεν βρει εταιρεία, απαντά με 404 και δεν χρεώνει τίποτα. Για ασαφή είσοδο, υπάρχει η Λειτουργία AI (ai_search=on-default): βρίσκει την εταιρεία και από μέρη της επωνυμίας και την ερευνά στο διαδίκτυο. Κοστίζει 20 επιπλέον πιστώσεις, ακόμη και αν δεν βρει εταιρεία. Για να λάβεις πολλούς υποψηφίους ταυτόχρονα, χρησιμοποίησε την Αναζήτηση & Εξαγωγή.

Κάθε προφίλ εταιρείας περιέχει τα βασικά στοιχεία, μεταξύ αυτών επωνυμία, νομική μορφή, κατάσταση, εγγραφή μητρώου, διεύθυνση, σκοπό, κλάδο, κεφάλαιο και κανόνες εκπροσώπησης. Όλα τα υπόλοιπα τα ζητάς ως feature, για παράδειγμα related_persons για τους διαχειριστές ή financial_kpi για τους Οικονομικούς δείκτες.

Πολλά features τα περνάς με επαναλαμβανόμενο feature ή ως λίστα: features=related_persons,financial_kpi. Κάθε feature εμφανίζεται στην απάντηση στο δικό του κλειδί. Μόνο το publications ονομάζεται εκεί history.

Το API αγνοεί άγνωστα ονόματα χωρίς μήνυμα σφάλματος, οπότε έλεγξε την ορθογραφία. Features που δεν περιλαμβάνει το πλάνο σου παραλείπονται και δεν χρεώνονται.

Όλα τα features με τις τιμές τους αναφέρονται στο fetch-organization, κάθε πεδίο στον Κατάλογο δεδομένων.

Τα αιτήματα δεδομένων κοστίζουν πιστώσεις. Για ένα προφίλ εταιρείας ισχύουν οι εξής κανόνες:

• Η βασική τιμή των 5 πιστώσεων ισχύει όταν το API επιστρέφει μια εταιρεία.
• Ένα feature κοστίζει πιστώσεις μόνο όταν επιστρέφει δεδομένα στην απάντηση. Ένα κενό feature είναι δωρεάν, και το insolvency_publications χωρίς καταχωρίσεις.
• Ο Πραγματικός χρόνος και η Λειτουργία AI δεν είναι features αλλά προσαυξήσεις με δικούς τους κανόνες:
  • Ο Πραγματικός χρόνος κοστίζει 10 επιπλέον πιστώσεις μόλις πετύχει η ζωντανή ανάκτηση. Αυτό ισχύει και όταν δεν δείχνει κάτι νέο.
  • Η Λειτουργία AI κοστίζει 20 επιπλέον πιστώσεις, ακόμη και αν δεν βρει εταιρεία. Η προσαύξηση δεν χρεώνεται μόνο όταν το API ακυρώνει το αίτημα με 408 επειδή διαρκεί πολύ.
• Όλα τα άλλα σφάλματα δεν κοστίζουν τίποτα.

Ο κανόνας για κάθε επιμέρους feature βρίσκεται στη Χρέωση, οι τιμές στο fetch-organization.

Ένα παράδειγμα: τα βασικά στοιχεία με related_persons και financial_kpi κοστίζουν 5 + 2 + 1 = 8 πιστώσεις αν και τα δύο features επιστρέψουν δεδομένα.

Πριν από κάθε αίτημα, το API ελέγχει αν το υπόλοιπό σου καλύπτει την υψηλότερη δυνατή τιμή. Αν όχι, το API απαντά με 402 και δεν χρεώνει τίποτα. Τι χρεώθηκε πραγματικά βρίσκεται στο meta.request_credit_cost, το υπόλοιπό σου μετά στο meta.credits_remaining.

Πιστώσεις λαμβάνεις ως αρχικές πιστώσεις, κάθε μήνα με μια συνδρομή πιστώσεων ή εφάπαξ ως πιστώσεις επαναφόρτισης. Χωρίς συνδρομή πιστώσεων, οι αρχικές πιστώσεις και οι πιστώσεις επαναφόρτισης ισχύουν 30 ημέρες· με ενεργή συνδρομή δεν λήγουν. Όλα τα υπόλοιπα στη Χρέωση.

Από προεπιλογή, το προφίλ εταιρείας προέρχεται από τη βάση δεδομένων μας. Πόσο επίκαιρη είναι μια πληροφορία εξαρτάται από την πηγή της.

Τα βασικά στοιχεία, τα πρόσωπα και τις ανακοινώσεις μητρώου τα διατηρούμε επίκαιρα στη βάση δεδομένων μας από το μητρώο. Αυτό είναι γρήγορο και αρκεί για τους περισσότερους σκοπούς.

Με τον Πραγματικό χρόνο (realtime_mode=handelsregister-default), το API ανακτά τον Aktueller Abdruck (AD, τρέχον απόσπασμα) ζωντανά από το Handelsregister (εμπορικό μητρώο) τη στιγμή του αιτήματός σου και τον επιστρέφει ως JSON. Λαμβάνεις επίσης τα πρόσωπα που είναι εγγεγραμμένα αυτή τη στιγμή στο related_persons.current, χωρίς να πληρώσεις για το feature.

Αν η ζωντανή ανάκτηση λειτούργησε φαίνεται στο _realtime_mode.status. Τις 10 πιστώσεις για τον Πραγματικό χρόνο τις χρεώνουμε μόνο με success.

Αν η ζωντανή ανάκτηση αποτύχει, το API επιστρέφει τα αποθηκευμένα δεδομένα από τη βάση δεδομένων μας. Το καταλαβαίνεις από το _realtime_mode.status, που τότε δεν είναι success. Ο Πραγματικός χρόνος τότε δεν χρεώνεται, όπως δείχνει και το meta.request_credit_cost.

Ο Πραγματικός χρόνος αξίζει όταν μετράει η σημερινή κατάσταση. Για παράδειγμα, ελέγχεις νέους επιχειρηματικούς εταίρους πριν από την υπογραφή ή βλέπεις ποιος μπορεί να εκπροσωπεί την εταιρεία αυτή τη στιγμή.

Αναζητούμε καθημερινά νέες δημοσιευμένες ετήσιες οικονομικές καταστάσεις. Οι εταιρείες όμως έχουν έως δώδεκα μήνες μετά το τέλος του οικονομικού έτους για να τις δημοσιεύσουν (§ 325 HGB), και πολλές αξιοποιούν όλη την προθεσμία. Ορισμένες εταιρείες χάνουν σκόπιμα τη νόμιμη προθεσμία και δημοσιεύουν ακόμη αργότερα.

Οι πιο πρόσφατες καταστάσεις αφορούν επομένως συχνά το προπροηγούμενο έτος. Περισσότερα στην Επικαιρότητα.

Τα πτωχευτικά δικαστήρια δημοσιεύουν συνήθως τις ανακοινώσεις τους την ημέρα της απόφασης ή λίγο μετά. Τις λαμβάνεις μέσω του feature insolvency_publications, την καθεμία με δικαστήριο, αριθμό υπόθεσης και ημερομηνία.

Το feature news επιστρέφει ειδήσεις για την εταιρεία από το διαδίκτυο, με τίτλο, πηγή, ημερομηνία και σύνδεσμο. Πόσο πρόσφατες είναι εξαρτάται από το πότε γράφτηκε τελευταία κάτι για την εταιρεία. Για μικρές εταιρείες υπάρχουν συχνά λίγα σχετικά δημοσιεύματα.

Πολλά στοιχεία αλλάζουν με τον χρόνο. Γι’ αυτό το API επιστρέφει την τρέχουσα κατάσταση και το ιστορικό το ένα δίπλα στο άλλο:

• Το current είναι η κατάσταση σήμερα.
• Το history απαριθμεί κάθε καταχωρισμένη κατάσταση με effective_from και effective_to. Αν το effective_to είναι null, η κατάσταση ισχύει ακόμη σήμερα.
• Τα πρόσωπα βρίσκονται στα related_persons.current και related_persons.past, το καθένα με start_date και end_date.

Κάθε στοιχείο με ιστορικό προέρχεται από τα μητρώα και τις δημοσιεύσεις, για παράδειγμα από τον Chronologischer Abdruck (CD, χρονολογικό απόσπασμα) του Handelsregister ή από όλες τις δημοσιευμένες ετήσιες οικονομικές καταστάσεις.

Έτσι φαίνεται στο παράδειγμά μας για τους κανόνες εκπροσώπησης της Hetzner Online GmbH. Στο παράδειγμα απάντησης, αναφέρουν το διοικητικό συμβούλιο έως τις 28 Ιουλίου 2015 και τους διαχειριστές από τότε:

Οι περισσότερες ημερομηνίες έρχονται στη μορφή YYYY-MM-DD. Πόσο πίσω φτάνει το ιστορικό περιγράφεται στο Παλαιότητα και ιστορικό.

Δεν έχει κάθε εταιρεία τιμή για κάθε πεδίο. Το API το δείχνει με δύο τρόπους:

• null: δεν υπάρχει τιμή για αυτό το πεδίο.
• []: η λίστα δεν έχει καταχωρίσεις, για παράδειγμα καμία ανακοίνωση αφερεγγυότητας.

Ένα feature που ζητήθηκε χωρίς δεδομένα έρχεται ως null ή [] και δεν κοστίζει τίποτα.

Στον κώδικά σου, χειρίσου ένα κλειδί που λείπει, το null και το [] με τον ίδιο τρόπο, γιατί ορισμένα κενά αντικείμενα έρχονται ως []. Διάβαζε επίσης τα πεδία με βάση τα ονόματά τους, γιατί η σειρά των κλειδιών δεν είναι σταθερή.

Αν λείπει μια τιμή, η εταιρεία συνήθως δεν υποχρεούται καν να τη δημοσιεύσει. Τι απαιτεί ο νόμος ανάλογα με τη νομική μορφή και το μέγεθος περιγράφεται στη Διαθεσιμότητα δεδομένων. Ορισμένα στοιχεία τα αποκρύπτουμε σκόπιμα· τότε φέρουν redacted: true.

Το API επεκτείνεται προσθετικά. Νέα δεδομένα και features έρχονται ως νέα πεδία. Δεν αφαιρούμε ποτέ υπάρχοντα πεδία, δεν τα μετονομάζουμε και δεν αλλάζουμε ούτε τον τύπο ούτε τη σημασία τους. Έτσι κάθε έκδοση παραμένει συμβατή προς τα πίσω.

Αλλαγές που θα έσπαγαν υπάρχοντα κώδικα έρχονται μόνο σε νέα έκδοση του API, για παράδειγμα στο /v2. Η τρέχουσα έκδοση λειτουργεί στο /v1.

Γι’ αυτό άφησε τον client σου να αγνοεί άγνωστα πεδία και χειρίσου τις άγνωστες τιμές ως γενική περίπτωση. Τα νέα πεδία και features αναφέρονται στο Changelog.

Προφίλ εταιρείας, Έγγραφα, Αναζήτηση & Εξαγωγή και Signals μπορείς να τα χρησιμοποιείς με κάθε λογαριασμό, ακόμη και χωρίς συνδρομή πιστώσεων. Μια συνδρομή πιστώσεων φέρνει νέες πιστώσεις κάθε μήνα και ξεκλειδώνει περισσότερα δεδομένα:

Το API παραλείπει features εκτός του πλάνου σου χωρίς σφάλμα και δεν τα χρεώνει. Προφίλ προσώπων και φίλτρα αναζήτησης εκτός του πλάνου σου τα απορρίπτει με 403, επίσης χωρίς κόστος. Για τα Signals, αυτό ισχύει για θέματα που ζητάς ρητά· χωρίς αυτό, λαμβάνεις απλώς όλα τα θέματα του πλάνου σου.

Τις τιμές και τις πιστώσεις των πλάνων θα τις βρεις στη σελίδα τιμών.