Bestellungen anlegen, Rechnungen freigeben und bezahlen und den Workspace einrichten.

API-Referenz

Webhooks

Lassen Sie Pleaxy jede Änderung sofort an Ihren HTTPS-Endpunkt senden.

Mehr zu dieser Ressource

Der Sync-Feed als Push. Jedes Ereignis der Typen, die ein Endpunkt abonniert, wird per POST als JSON an ihn gesendet - das Ereignis aus ListSyncEvents plus workspaceId und documentPath, der Aufruf, der sein Dokument liest -, nie das Dokument selbst. Jede Anfrage trägt Pleaxy-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>"> mit dem Secret des Endpunkts; lehnen Sie eine ab, die nicht passt oder älter als 5 Minuten ist. Antworten Sie innerhalb von 10 Sekunden mit einem 2xx; alles andere wird nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 6 Stunden, 12 Stunden und 24 Stunden wiederholt und dann aufgegeben. Endpunkte sind https://-Adressen auf einem Hostnamen; Zustellungen erreichen nie ein privates Netzwerk und folgen nie einer Weiterleitung. Bis zu 5 pro Workspace-Seite.

Endpunkte

GET…/webhooks
POST…/webhooks
PATCH…/webhooks/{webhookId}
DELETE…/webhooks/{webhookId}
POST…/webhooks/{webhookId}/secret
POST…/webhooks/{webhookId}/test
GET…/webhooks/{webhookId}/deliveries

Webhooks auflisten

Listet Ihre Webhook-Endpunkte auf.

GET/v1/workspaces/{regionId}/webhooks

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Die Endpunkte Ihrer Seite und die Ereignistypen, die sie empfangen können. Nie ein Signatur-Secret: secretHint zeigt dessen Anfang und Ende.

Ein angemeldeter Administrator (Bearer-Token): approvalSettings edit beim Käufer oder ein Lieferantenadministrator.

Antwortfelder

endpoints[].eventsArray<string>
Die gesendeten Ereignistypen. Leer bedeutet jeder Typ Ihrer Seite, auch später hinzugefügte.
endpoints[].lastErrorCodestring
Warum der letzte Versuch fehlgeschlagen ist: http_status (siehe lastStatus), blocked_address, unreachable, timeout, redirect, too_large, endpoint_off oder failed.
endpoints[].failedDeliveriesnumber
Nacheinander aufgegebene Zustellungen; ein Erfolg oder das Fortsetzen des Endpunkts setzt den Wert zurück.

Fehler

403 Forbidden - Ein API-Schlüssel oder ein Aufrufer, der kein Administrator dieser Workspace-Seite ist.
401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.

GET /v1/workspaces/{regionId}/webhooks

Anfrage

curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/webhooks" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Antwort · 200 OK

{
   "endpoints": [
      {
         "id": "string",
         "url": "string",
         "description": "string",
         "events": [ "string" ],
         "enabled": boolean,
         "secretHint": "string",
         "createdAt": "string",
         "lastAttemptAt": "string",
         "lastStatus": number,
         "lastErrorCode": "string",
         "lastSuccessAt": "string",
         "failedDeliveries": number
      }
   ],
   "eventTypes": [ "string" ]
}

Webhook anlegen

Fügt einen Webhook-Endpunkt hinzu und gibt einmalig sein Signatur-Secret zurück.

POST/v1/workspaces/{regionId}/webhooks

Body

urlstringPflicht
Eine https://-Adresse auf einem Hostnamen, ohne IP-Adresse, Port, Benutzernamen oder Passwort.
descriptionstring
Bis zu 100 Zeichen, um Endpunkte zu unterscheiden.
eventsArray<string>
Die zu sendenden Ereignistypen aus eventTypes. Weglassen für alle.

Rückgabe

201 Created mit dem in der Antwort gezeigten Objekt.

Weitere Details

Fügt einen Endpunkt hinzu. Die Antwort enthält sein Signatur-Secret, das nur dieses eine Mal angezeigt wird: Speichern Sie es in Ihrem System, um die Signatur jeder Anfrage zu prüfen.

Ein angemeldeter Administrator (Bearer-Token): approvalSettings edit beim Käufer oder ein Lieferantenadministrator.

Fehler

400 Bad Request - Code WEBHOOK_URL_INVALID, WEBHOOK_EVENTS_INVALID oder WEBHOOK_LIMIT (bereits 5 Endpunkte).
403 Forbidden - Ein API-Schlüssel oder ein Aufrufer, der kein Administrator dieser Workspace-Seite ist.
401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.

POST /v1/workspaces/{regionId}/webhooks

Anfrage

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/webhooks" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

body.json

{
   "url": "https://erp.example.com/pleaxy",
   "description": "string",
   "events": [ "invoice.paid", "invoice.remittance_sent" ]
}

Antwort · 201 Created

{
   "id": "string",
   "url": "string",
   "events": [ "string" ],
   "enabled": true,
   "secret": "string",
   "secretHint": "string",
   "createdAt": "string"
}

Webhook aktualisieren

Ändert einen Webhook-Endpunkt oder pausiert und reaktiviert ihn.

PATCH/v1/workspaces/{regionId}/webhooks/{webhookId}

Parameter

webhookIdstringPflicht
Die ID des Endpunkts, z. B. WH-3F9A01C2.

Body

enabledboolean
false pausiert den Endpunkt; true reaktiviert ihn. url, description und events wie bei CreateWebhook.

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Ändert url, description oder events eines Endpunkts oder pausiert ihn (enabled: false) und reaktiviert ihn (enabled: true). Für einen pausierten Endpunkt wird nichts vorgehalten. Das Reaktivieren setzt failedDeliveries zurück.

Ein angemeldeter Administrator (Bearer-Token): approvalSettings edit beim Käufer oder ein Lieferantenadministrator.

Fehler

400 Bad Request - Code WEBHOOK_URL_INVALID oder WEBHOOK_EVENTS_INVALID.
404 Not Found - Code WEBHOOK_NOT_FOUND.
401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.

PATCH /v1/workspaces/{regionId}/webhooks/{webhookId}

Anfrage

curl -X PATCH "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/webhooks/{webhookId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

body.json

{
   "enabled": false
}

Antwort · 200 OK

The endpoint, as in ListWebhooks.

Webhook löschen

Entfernt einen Webhook-Endpunkt.

DELETE/v1/workspaces/{regionId}/webhooks/{webhookId}

Parameter

webhookIdstringPflicht
Die ID des Endpunkts, z. B. WH-3F9A01C2.

Rückgabe

204 No Content mit dem in der Antwort gezeigten Objekt.

Weitere Details

Entfernt einen Endpunkt. Noch ausstehende Zustellungen an ihn werden aufgegeben.

Ein angemeldeter Administrator (Bearer-Token): approvalSettings edit beim Käufer oder ein Lieferantenadministrator.

Fehler

404 Not Found - Code WEBHOOK_NOT_FOUND.
401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.

DELETE /v1/workspaces/{regionId}/webhooks/{webhookId}

Anfrage

curl -X DELETE "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/webhooks/{webhookId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Antwort · 204 No Content

(no content)

Webhook-Secret rotieren

Ersetzt das Signatur-Secret eines Endpunkts.

POST/v1/workspaces/{regionId}/webhooks/{webhookId}/secret

Parameter

webhookIdstringPflicht
Die ID des Endpunkts, z. B. WH-3F9A01C2.

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Ein neues Signatur-Secret, einmalig in secret zurückgegeben. Das alte signiert sofort nicht mehr, aktualisieren Sie Ihr System also unmittelbar danach.

Ein angemeldeter Administrator (Bearer-Token): approvalSettings edit beim Käufer oder ein Lieferantenadministrator.

Fehler

404 Not Found - Code WEBHOOK_NOT_FOUND.
401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.

POST /v1/workspaces/{regionId}/webhooks/{webhookId}/secret

Anfrage

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/webhooks/{webhookId}/secret" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Antwort · 200 OK

The endpoint, as in ListWebhooks, plus secret.

Webhook testen

Sendet einem Endpunkt einen signierten Test-Ping.

POST/v1/workspaces/{regionId}/webhooks/{webhookId}/test

Parameter

webhookIdstringPflicht
Die ID des Endpunkts, z. B. WH-3F9A01C2.

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Sendet dem Endpunkt jetzt einmalig einen signierten Ping, ohne Wiederholung, und meldet, was er geantwortet hat.

Ein angemeldeter Administrator (Bearer-Token): approvalSettings edit beim Käufer oder ein Lieferantenadministrator.

Fehler

404 Not Found - Code WEBHOOK_NOT_FOUND.
401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.

POST /v1/workspaces/{regionId}/webhooks/{webhookId}/test

Anfrage

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/webhooks/{webhookId}/test" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Antwort · 200 OK

{
   "ok": boolean,
   "status": number,
   "errorCode": "string",
   "durationMs": number
}

Webhook-Zustellungen auflisten

Listet die letzten Zustellungen eines Endpunkts auf.

GET/v1/workspaces/{regionId}/webhooks/{webhookId}/deliveries

Parameter

webhookIdstringPflicht
Die ID des Endpunkts, z. B. WH-3F9A01C2.

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Die letzten 50 Zustellungen eines Endpunkts, neueste zuerst, 30 Tage aufbewahrt: Typ, Status, Versuche und Fehler jedes Ereignisses.

Ein angemeldeter Administrator (Bearer-Token): approvalSettings edit beim Käufer oder ein Lieferantenadministrator.

Antwortfelder

deliveries[].statusstring
pending: wartet auf den nächsten Versuch (nextAttemptAt). delivered: mit einem 2xx beantwortet. failed: aufgegeben.

Fehler

404 Not Found - Code WEBHOOK_NOT_FOUND.
401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.

GET /v1/workspaces/{regionId}/webhooks/{webhookId}/deliveries

Anfrage

curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/webhooks/{webhookId}/deliveries" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Antwort · 200 OK

{
   "deliveries": [
      {
         "eventId": "string",
         "type": "string",
         "status": "pending" | "delivered" | "failed",
         "attempts": number,
         "createdAt": "string",
         "nextAttemptAt": "string",
         "lastAttemptAt": "string",
         "lastStatus": number,
         "lastErrorCode": "string",
         "deliveredAt": "string"
      }
   ]
}