Wie kann man über die API den aktuellen Status eines Unternehmens aus dem Verzeichnis der Umsatzsteuerpflichtigen abfragen?

MGBI bietet eine umfassende API zum Abruf von Daten aus öffentlichen Registern und Verzeichnissen, darunter aus dem Verzeichnis der Umsatzsteuerpflichtigen (Weiße Liste). Eine Liste der in diesem Dienst verfügbaren Datenquellen findest du auf der Seite:
👉 Öffentliche Register API

Dieser Leitfaden bezieht sich auf die API für das Verzeichnis der Umsatzsteuerpflichtigen (Weiße Liste), die wir im Rahmen des Produkts
zur Verfügung stellen 👉 API für das Verzeichnis der Umsatzsteuerpflichtigen (Weiße Liste API)

Im Folgenden beschreiben wir, wie Sie über die API den aktuellen Status eines Unternehmens aus dem Verzeichnis der Umsatzsteuerpflichtigen anhand seiner Steueridentifikationsnummer abrufen können.

Schritt 1: Beziehen Sie einen Autorisierungsschlüssel über die API

Um den Autorisierungsschlüssel zu erhalten, der für den Aufruf der in der MGBI-API verfügbaren Endpunkte erforderlich ist, kontaktieren Sie uns bitte über das Kontaktformular auf der Produktseite:
👉 Liste der Umsatzsteuerpflichtigen (API-Weiße Liste)

Schritt 2: Rufe den Endpunkt „Create Refresh“ auf

Die im Verzeichnis der Umsatzsteuerpflichtigen verfügbaren Daten stellen wir in der MGBI-API im Datenmodell mit der Kennung „pl-wpv-record“ bereit.

Dieses Modell wird auf Anfrage synchronisiert, was bedeutet, dass wir in unseren Beständen keine vollständige Kopie der im Quellregister verfügbaren Daten dafür haben.

Um aktuelle Daten zu einem bestimmten Schuldner aus dem Modell abzurufen, musst du zunächst über den Endpunkt „Create Refresh“ einen Abrufauftrag aus dem Verzeichnis der Umsatzsteuerpflichtigen erstellen.
👉 Dokumentation zum Endpunkt „Create Refresh“

Beispiel für den Aufruf des Endpunkts „Create Refresh“ mit der Steuernummer:

POST /v1/refresh HTTP/1.1
Host: api.mgbi.pl
Authorization: [klucz autoryzacji]

{
    "query: {
        "model": "pl-wpv-record",
        "identifiers.pl_nip": [numer NIP]
    }
}

Bei korrekter Aufrufung des Endpunkts „Create Refresh“ wird als Antwort ein Dictionary zurückgegeben, das im Feld „id“ die Auftrags-ID enthält.

Schritt 3: Rufe den Endpunkt „Get Refresh“ auf

Aufträge zum Abrufen von Daten aus dem Quellregister dauern in der Regel einige bis zu mehreren Sekunden ab dem Zeitpunkt ihrer Erstellung durch den Endpunkt „Create Refresh“.

Um den aktuellen Status des Auftrags zu überprüfen, rufe den Endpunkt „Get Refresh“ auf und gib in der URL die im vorherigen Schritt erhaltene Auftrags-ID an.
👉 Dokumentation zum Endpunkt „Get Refresh“

Beispiel für den Aufruf des Endpunkts „Get Refresh“ mit der Auftrags-ID:

GET /v1/refresh/[Auftrags-ID] HTTP/1.1
Host: api.mgbi.pl
Authorization: [Autorisierungsschlüssel]

Wenn das Statusfeld im zurückgegebenen Wörterbuch den Wert „pending“ annimmt, wird der Auftrag noch ausgeführt, und der Endpunkt „Get Refresh“ sollte in einigen Sekunden erneut aufgerufen werden.

Wenn das Statusfeld den Wert „success“ annimmt, bedeutet dies, dass der Auftrag ausgeführt wurde und die Daten zum angegebenen Schuldner bereits aus dem Quellregister abgerufen wurden.

Schritt 4: Rufe den Endpunkt „Get Records“ auf

Die API für das Modell „pl-wpv-record“ stellt den Endpunkt „Get Records“ bereit, der Datensätze mit dem vollständigen Antworttext aus dem Verzeichnis der Umsatzsteuerpflichtigen für den angegebenen Schuldner zurückgibt.
👉 Dokumentation zum Endpunkt „Get Records“ für das Modell „pl-wpv-record“

Um die aus dem Quellregister abgerufenen Daten in einem zuvor erstellten Auftrag abzurufen, rufen Sie den Endpunkt „Get Records “ auf und übergeben Sie dabei die Auftrags-ID im Parameter „refresh_id“.

Beispiel für den Aufruf des Endpunkts „Get Records“ mit einer Auftrags-ID:

GET /v1/models/pl-wpv-record/records?refresh_id=[Auftrags-ID] HTTP/1.1
Host: api.mgbi.pl
Authorization: [Autorisierungsschlüssel]

Schritt 5: Entnehmen Sie der Antwort den aktuellen Status des Umsatzsteuerpflichtigen

Bei korrekter Aufrufung des Endpunkts „Get Records“ wird als Antwort eine Liste der Datensätze zurückgegeben, die den angegebenen Kriterien entsprechen.

Im obigen Beispiel sollte der Endpunkt eine Ergebnisliste mit einem Datensatz zurückgeben:

{
    "count": 1,
    "pages": 1,
    "results": [
        {
            "id": [identyfikator rekordu],
            "identifiers": [identyfikatory podmiotu],
            "version": [informacje o wersji rekordu],
            "content": [treść odpowiedzi z wyszukiwarki],
            "meta": [metadane rekordu]
        }
    ]
}

Alle Daten, die in der Suchmaschine des Verzeichnisses der Umsatzsteuerpflichtigen für das angegebene Unternehmen verfügbar sind, finden Sie im Verzeichnis „content.subject“.

Beispiel für den Inhalt des Wörterbuchs „content.subject“:

{
    "name": [nazwa podmiotu],
    "nip": [numer NIP],
    "statusVat": [status podatnika VAT],
    "regon": [numer REGON],
    "krs": [numer KRS],
    "workingAddress": [adres siedziby],
    "representatives": [dane reprezentantów],
    "authorizedClerks": [dane pełnomocników],
    "partners": [dane wspólników],
    "registrationLegalDate": [data rejestracji podanika VAT],
    "accountNumbers": [lista numerów rachunków bankowych],
    "hasVirtualAccounts": [informacja, czy podatnik posiada rachunki wirtualne]
}

Den aktuellen Umsatzsteuer-Status des angegebenen Unternehmens kannst du dem Feld „content.subject.statusVat“ entnehmen.

Weitere Informationen:
👉 Datenstruktur im Modell „pl-wpv-record“
👉 Dokumentation der Endpunkte für das Modell „pl-wpv-record“