Émettez des bons de commande, validez et payez les factures, et configurez votre espace de travail.

Référence de l’API

Webhooks

Faites envoyer par Pleaxy chaque changement à votre endpoint HTTPS dès qu’il se produit.

En savoir plus sur cette ressource

Le flux de synchronisation, poussé. Chaque événement des types auxquels un endpoint est abonné lui est envoyé en POST au format JSON - l’événement de ListSyncEvents plus workspaceId et documentPath, l’appel qui lit son document - jamais le document lui-même. Chaque requête porte Pleaxy-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>"> avec le secret de l’endpoint ; refusez-en une qui ne correspond pas ou date de plus de 5 minutes. Répondez par un 2xx sous 10 secondes ; sinon, nouvelle tentative après 1 minute, 5 minutes, 30 minutes, 2 heures, 6 heures, 12 heures et 24 heures, puis abandon. Les endpoints sont des adresses https:// sur un nom d’hôte ; les livraisons n’atteignent jamais un réseau privé et ne suivent jamais de redirection. Jusqu’à 5 par côté d’espace de travail.

Endpoints

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

Lister les webhooks

Liste vos endpoints de webhook.

GET/v1/workspaces/{regionId}/webhooks

Retour

200 OK avec l’objet présenté dans la réponse.

Plus de détails

Les endpoints de votre côté et les types d’événements qu’ils peuvent recevoir. Jamais de secret de signature : secretHint en montre le début et la fin.

Un administrateur connecté (jeton Bearer) : approvalSettings edit côté acheteur, ou un administrateur fournisseur.

Champs de la réponse

endpoints[].eventsArray<string>
Les types d’événements envoyés. Vide signifie tous les types de votre côté, y compris ceux ajoutés plus tard.
endpoints[].lastErrorCodestring
Pourquoi la dernière tentative a échoué : http_status (voir lastStatus), blocked_address, unreachable, timeout, redirect, too_large, endpoint_off ou failed.
endpoints[].failedDeliveriesnumber
Livraisons abandonnées d’affilée ; une réussite ou la reprise de l’endpoint remet le compteur à zéro.

Erreurs

403 Forbidden - Une clé API, ou un appelant qui n’est pas administrateur de ce côté de l’espace de travail.
401 Unauthorized - Aucun identifiant n’a été fourni, ou la valeur du jeton Bearer / de X-Api-Key est manquante, invalide, expirée ou révoquée.

GET /v1/workspaces/{regionId}/webhooks

Requête

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

Réponse · 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" ]
}

Créer un webhook

Ajoute un endpoint de webhook et renvoie son secret de signature, une seule fois.

POST/v1/workspaces/{regionId}/webhooks

Corps

urlstringObligatoire
Une adresse https:// sur un nom d’hôte, sans adresse IP, port, nom d’utilisateur ni mot de passe.
descriptionstring
Jusqu’à 100 caractères, pour distinguer les endpoints.
eventsArray<string>
Les types d’événements à envoyer, parmi eventTypes. Omettez-le pour les recevoir tous.

Retour

201 Created avec l’objet présenté dans la réponse.

Plus de détails

Ajoute un endpoint. La réponse contient son secret de signature, affiché uniquement cette fois : stockez-le dans votre système pour vérifier la signature de chaque requête.

Un administrateur connecté (jeton Bearer) : approvalSettings edit côté acheteur, ou un administrateur fournisseur.

Erreurs

400 Bad Request - Code WEBHOOK_URL_INVALID, WEBHOOK_EVENTS_INVALID ou WEBHOOK_LIMIT (déjà 5 endpoints).
403 Forbidden - Une clé API, ou un appelant qui n’est pas administrateur de ce côté de l’espace de travail.
401 Unauthorized - Aucun identifiant n’a été fourni, ou la valeur du jeton Bearer / de X-Api-Key est manquante, invalide, expirée ou révoquée.

POST /v1/workspaces/{regionId}/webhooks

Requête

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" ]
}

Réponse · 201 Created

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

Mettre à jour un webhook

Modifie un endpoint de webhook, ou le met en pause et le réactive.

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

Paramètres

webhookIdstringObligatoire
L’id de l’endpoint, par exemple WH-3F9A01C2.

Corps

enabledboolean
false met l’endpoint en pause ; true le réactive. url, description et events comme dans CreateWebhook.

Retour

200 OK avec l’objet présenté dans la réponse.

Plus de détails

Modifie l’url, la description ou les events d’un endpoint, ou le met en pause (enabled: false) et le réactive (enabled: true). Rien n’est mis en file d’attente pour un endpoint en pause. La réactivation remet failedDeliveries à zéro.

Un administrateur connecté (jeton Bearer) : approvalSettings edit côté acheteur, ou un administrateur fournisseur.

Erreurs

400 Bad Request - Code WEBHOOK_URL_INVALID ou WEBHOOK_EVENTS_INVALID.
404 Not Found - Code WEBHOOK_NOT_FOUND.
401 Unauthorized - Aucun identifiant n’a été fourni, ou la valeur du jeton Bearer / de X-Api-Key est manquante, invalide, expirée ou révoquée.

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

Requête

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
}

Réponse · 200 OK

The endpoint, as in ListWebhooks.

Supprimer un webhook

Supprime un endpoint de webhook.

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

Paramètres

webhookIdstringObligatoire
L’id de l’endpoint, par exemple WH-3F9A01C2.

Retour

204 No Content avec l’objet présenté dans la réponse.

Plus de détails

Supprime un endpoint. Les livraisons encore en attente pour lui sont abandonnées.

Un administrateur connecté (jeton Bearer) : approvalSettings edit côté acheteur, ou un administrateur fournisseur.

Erreurs

404 Not Found - Code WEBHOOK_NOT_FOUND.
401 Unauthorized - Aucun identifiant n’a été fourni, ou la valeur du jeton Bearer / de X-Api-Key est manquante, invalide, expirée ou révoquée.

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

Requête

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

Réponse · 204 No Content

(no content)

Renouveler le secret d’un webhook

Remplace le secret de signature d’un endpoint.

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

Paramètres

webhookIdstringObligatoire
L’id de l’endpoint, par exemple WH-3F9A01C2.

Retour

200 OK avec l’objet présenté dans la réponse.

Plus de détails

Un nouveau secret de signature, renvoyé cette seule fois dans secret. L’ancien cesse immédiatement de signer : mettez donc votre système à jour aussitôt.

Un administrateur connecté (jeton Bearer) : approvalSettings edit côté acheteur, ou un administrateur fournisseur.

Erreurs

404 Not Found - Code WEBHOOK_NOT_FOUND.
401 Unauthorized - Aucun identifiant n’a été fourni, ou la valeur du jeton Bearer / de X-Api-Key est manquante, invalide, expirée ou révoquée.

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

Requête

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

Réponse · 200 OK

The endpoint, as in ListWebhooks, plus secret.

Tester un webhook

Envoie à un endpoint un ping de test signé.

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

Paramètres

webhookIdstringObligatoire
L’id de l’endpoint, par exemple WH-3F9A01C2.

Retour

200 OK avec l’objet présenté dans la réponse.

Plus de détails

Envoie maintenant à l’endpoint un ping signé, une seule fois, sans nouvelle tentative, et indique ce qu’il a répondu.

Un administrateur connecté (jeton Bearer) : approvalSettings edit côté acheteur, ou un administrateur fournisseur.

Erreurs

404 Not Found - Code WEBHOOK_NOT_FOUND.
401 Unauthorized - Aucun identifiant n’a été fourni, ou la valeur du jeton Bearer / de X-Api-Key est manquante, invalide, expirée ou révoquée.

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

Requête

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

Réponse · 200 OK

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

Lister les livraisons d’un webhook

Liste les livraisons récentes d’un endpoint.

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

Paramètres

webhookIdstringObligatoire
L’id de l’endpoint, par exemple WH-3F9A01C2.

Retour

200 OK avec l’objet présenté dans la réponse.

Plus de détails

Les 50 dernières livraisons d’un endpoint, de la plus récente à la plus ancienne, conservées 30 jours : pour chaque événement, son type, son statut, ses tentatives et ce qui n’a pas fonctionné.

Un administrateur connecté (jeton Bearer) : approvalSettings edit côté acheteur, ou un administrateur fournisseur.

Champs de la réponse

deliveries[].statusstring
pending : en attente de sa prochaine tentative (nextAttemptAt). delivered : a reçu une réponse 2xx. failed : abandonnée.

Erreurs

404 Not Found - Code WEBHOOK_NOT_FOUND.
401 Unauthorized - Aucun identifiant n’a été fourni, ou la valeur du jeton Bearer / de X-Api-Key est manquante, invalide, expirée ou révoquée.

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

Requête

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

Réponse · 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"
      }
   ]
}