Integrations-Dokumentation

Übersicht

myapimonitor stellt dir öffentliche HTTPS-Endpunkte bereit, die Webhooks und API-Requests in deinem Namen empfangen. Jede eingehende Anfrage wird geloggt, inspiziert und – wenn du Regeln einrichtest – validiert, bevor sie optional an dein Zielsystem weitergeleitet wird.

Dies ist keine klassische API-Dokumentation. Es ist ein Integrations-Guide, der dir zeigt, wie du deine Quellsysteme (Shops, ERPs, externe Dienste) mit myapimonitor verbindest und Validierung, Geocoding und Weiterleitung optimal nutzt.

Schnellstart

In unter zwei Minuten startklar.

1. Endpunkt anlegen

Öffne das Dashboard, gehe zu Endpunkte und klicke auf Endpunkt erstellen. Vergib einen Namen und optional einen Slug (z. B. mein-shop-bestellungen). Du erhältst eine eindeutige URL wie:

https://hooks.myapimonitor.com/my-shop-orders

2. Testdaten senden

Verwende curl, Postman oder einen beliebigen HTTP-Client, um ein JSON-Payload an deinen Endpunkt zu senden:

curl -X POST https://hooks.myapimonitor.com/my-shop-orders \
  -H "Content-Type: application/json" \
  -d '{"order_id": "12345", "customer": "Jane Doe", "total": 59.90}'

3. Request prüfen

Gehe zu Requests in der Seitenleiste. Du siehst die eingehende Anfrage mit vollständigen Headern, Body und Zeitstempel.

4. Validierungsregel hinzufügen (optional)

Navigiere zu Regeln und erstelle eine Pflichtfelder-Regel für deinen Endpunkt. Der nächste Request, dem ein Pflichtfeld fehlt, erscheint in den Alerts.

5. Weiterleitung aktivieren (optional)

Öffne die Endpunkt-Einstellungen und aktiviere die Weiterleitung. Gib die URL deines Zielsystems ein. Gültige Requests werden automatisch weitergeleitet.

Requests senden

Sende Daten an deine Endpunkt-URL mit einer beliebigen HTTP-Methode (POST, PUT, PATCH). Das gängigste Format ist JSON, aber auch XML, Formulardaten und Plaintext werden unterstützt.

JSON per curl

curl -X POST https://hooks.myapimonitor.com/my-shop-orders \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "12345",
    "customer": "Jane Doe",
    "items": [
      {"sku": "A100", "qty": 2},
      {"sku": "B200", "qty": 1}
    ],
    "total": 59.90
  }'

XML per curl (optional)

curl -X POST https://hooks.myapimonitor.com/my-shop-orders \
  -H "Content-Type: application/xml" \
  -d '<order>
    <order_id>12345</order_id>
    <customer>Jane Doe</customer>
    <total>59.90</total>
  </order>'

Postman

Setze in Postman die Request-Methode auf POST, füge deine Endpunkt-URL ein, wähle den Body-Tab, wähle raw → JSON und füge dein Payload ein. Klicke auf Send.

Adress-Payload-Beispiel

Wenn du Adressvalidierung oder Geocoding nutzt, sende die Adressfelder als flache Schlüssel oder verschachtelte Objekte. Die empfohlenen Feldnamen sind:

street, house_number, postal_code, city, country (ISO-2-Buchstaben-Code)

curl -X POST https://hooks.myapimonitor.com/my-shop-orders \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "12345",
    "customer": "Jane Doe",
    "shipping_address": {
      "street": "Hauptstraße",
      "house_number": "42",
      "postal_code": "10115",
      "city": "Berlin",
      "country": "DE"
    }
  }'

Response-Format

Jeder Request an deinen Endpunkt liefert eine JSON-Antwort mit Statusinformationen und Regel-Ergebnissen.

HTTP-Statuscodes

• 202 202 Accepted – Request wurde empfangen und erfolgreich verarbeitet.
• 401 401 Unauthorized – Authentifizierung fehlgeschlagen (falscher API-Key, fehlendes Bearer-Token usw.).
• 403 403 Forbidden – Endpunkt ist deaktiviert.
• 404 404 Not Found – Endpunkt-URL existiert nicht.

Response-Body

Die Antwort enthält immer den Endpunkt-Identifier, ein Status-Feld und ein Array mit Regel-Ergebnissen:

{
  "status": "received",
  "endpoint": "my-shop-orders",
  "rules": [
    {
      "rule_id": 1,
      "rule_name": "required_fields",
      "result": "pass",
      "errors": []
    }
  ],
  "forwarded": null
}

Wenn Validierungsregeln oder Geocoding-Prüfungen am Endpunkt hinterlegt sind, erscheinen deren Ergebnisse im rules-Array. Jeder Eintrag zeigt den Regelnamen, das Ergebnis (pass oder fail) und eventuelle Fehlermeldungen.

Wenn Weiterleitung aktiviert ist, enthält die Antwort zusätzlich ein forwarded-Objekt mit dem HTTP-Statuscode des Zielsystems und dem Response-Body (gekürzt auf 2.000 Zeichen).

Validierung & Regeln

Mit Regeln definierst du, wie ein gültiger Request aussehen soll. Jede eingehende Anfrage wird gegen alle Regeln des Endpunkts geprüft. Die Ergebnisse werden geloggt und sind in Requests und Alerts sichtbar.

Regeltypen

Wann gilt ein Request als bestanden?

Ein Request gilt als bestanden, wenn alle zugehörigen Regeln "pass" zurückgeben. Wenn eine Regel fehlschlägt, wird der Request entsprechend markiert und – wenn Benachrichtigungen auf der Regel aktiviert sind – eine Alert-E-Mail versendet.

Alerts vs. Warnungen

Jeder Regelfehler erzeugt einen Alert-Eintrag. Du findest alle Alerts in der Alerts-Ansicht, gefiltert nach Endpunkt, Regel oder Zeitraum. Wenn E-Mail-Benachrichtigungen auf einer Regel aktiviert sind, erhalten der Regelbesitzer und optional das Team sofort eine E-Mail.

Geocoding

Die Adressvalidierungsregel kann Adressen optional gegen einen Geocoding-Anbieter verifizieren. Dieser Abschnitt erklärt, wie du die besten Ergebnisse erzielst.

Empfohlene Felder

Für die genauesten Ergebnisse sende folgende Felder:

• street – Straßenname ohne Hausnummer
• house_number – Hausnummer (getrennt von der Straße für bessere Genauigkeit)
• postal_code – PLZ oder Postleitzahl
• city – Stadtname
• country – ISO-3166-1-Alpha-2-Ländercode (z. B. DE, US, FR)

Mindestanforderungen

Mindestens zwei der folgenden Felder müssen vorhanden sein: street, postal_code, city. Wenn weniger angegeben werden, wird die Adresse lokal abgelehnt, ohne einen API-Aufruf zu machen.

Ergebnisklassifizierung

Reason-Codes für verdächtige Ergebnisse

• POSTCODE_CITY_MISMATCHPostleitzahl passt nicht zur Stadt.
• HOUSE_NUMBER_UNCLEARStraße wurde gefunden, aber Hausnummer ist mehrdeutig.
• COARSE_AREA_HITNur ein Gebietstreffer, keine präzise Adresse.
• LOW_CONFIDENCETreffer vorhanden, aber Konfidenz unter dem Schwellenwert.
• ROAD_NOT_FOUNDStraßenname stimmt nicht überein.
• COUNTRY_MISMATCHLändercode stimmt nicht mit dem aufgelösten Standort überein.

Was passiert bei einem verdächtigen Ergebnis?

Ein verdächtiges Ergebnis blockiert den Request standardmäßig nicht. Es erzeugt einen Alert, damit du die Adresse manuell prüfen kannst. Du entscheidest, ob der Request weitergeleitet oder die Daten an der Quelle korrigiert werden.

Weiterleitung

Die Weiterleitung sendet das originale Request-Payload nach der Validierung an eine externe URL. So kannst du myapimonitor als Validierungs- und Monitoring-Schicht zwischen deinem Quell- und Zielsystem einsetzen.

Wann wird ein Request weitergeleitet?

Die Weiterleitung erfolgt, wenn der Endpunkt die Weiterleitung aktiviert hat und eine Weiterleitungsregel hinterlegt ist. Das originale Payload und die Header (ohne Host und Content-Length) werden an die konfigurierte Ziel-URL gesendet.

Original- oder transformierte Daten?

Der originale Request-Body wird unverändert weitergeleitet. myapimonitor transformiert oder modifiziert das Payload nicht. Zusätzliche Header können über die Regelkonfiguration hinzugefügt werden.

Fehlerbehandlung

Wenn das Zielsystem einen HTTP-Statuscode ≥ 400 zurückgibt oder nicht erreichbar ist, wird das Weiterleitungsergebnis auf "fail" gesetzt. Der Fehler wird geloggt und ein Alert erzeugt, wenn Benachrichtigungen aktiviert sind.

Retries

Es gibt derzeit keinen automatischen Retry-Mechanismus. Ein fehlgeschlagener Weiterleitungsversuch wird geloggt und ist in Zustellungen und Alerts sichtbar. Du kannst vom Quellsystem erneut senden oder den Fehler im Dashboard untersuchen.

Timeout

Weiterleitungs-Requests haben ein Timeout von 30 Sekunden. Wenn das Zielsystem nicht innerhalb dieses Fensters antwortet, wird die Weiterleitung als fehlgeschlagen behandelt.

Fehler

Dieser Abschnitt listet häufige Fehler auf, die bei der Integration mit myapimonitor auftreten können.

Beispiele

Vollständige Request-Beispiele, die du kopieren und für deine Integration anpassen kannst.

Einfacher JSON-Request

Ein minimales Bestell-Payload an deinen Endpunkt:

curl -X POST https://hooks.myapimonitor.com/my-shop-orders \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ORD-2025-0042",
    "customer": "Jane Doe",
    "email": "jane@example.com",
    "items": [
      {"sku": "WIDGET-A", "qty": 2, "price": 19.95},
      {"sku": "GADGET-B", "qty": 1, "price": 20.00}
    ],
    "total": 59.90,
    "currency": "EUR"
  }'

Request mit Adressdaten

Eine Bestellung mit vollständiger Lieferadresse für Geocoding-Validierung:

curl -X POST https://hooks.myapimonitor.com/my-shop-orders \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ORD-2025-0043",
    "customer": "Max Mustermann",
    "email": "max@example.com",
    "shipping_address": {
      "street": "Berliner Straße",
      "house_number": "123",
      "postal_code": "10115",
      "city": "Berlin",
      "country": "DE"
    },
    "items": [{"sku": "WIDGET-A", "qty": 1}],
    "total": 19.95
  }'

XML-Request

Wenn dein Quellsystem XML sendet, setze den Content-Type auf application/xml:

curl -X POST https://hooks.myapimonitor.com/my-shop-orders \
  -H "Content-Type: application/xml" \
  -d '<order>
    <order_id>ORD-2025-0044</order_id>
    <customer>Jane Doe</customer>
    <email>jane@example.com</email>
    <items>
      <item><sku>WIDGET-A</sku><qty>2</qty></item>
    </items>
    <total>39.90</total>
  </order>'

Ergebnisse prüfen

Nach dem Senden eines Requests kannst du das Ergebnis im Dashboard überprüfen:

• 📥 Requests – Alle eingehenden Anfragen mit Headern, Body und Zeitstempel anzeigen.
• 🔔 Alerts – Regelfehler und Fehlerdetails einsehen.
• 📤 Zustellungen – Weitergeleitete Requests und Zielsystem-Antworten verfolgen.
• 🔍 Nutze die Suchleiste, um nach Endpunkt, Payload-Inhalt oder Fehlermeldung zu filtern.