Emetti ordini d’acquisto, approva e paga le fatture e configura il tuo spazio di lavoro.

Riferimento API

Webhook

Fai inviare da Pleaxy ogni modifica al tuo endpoint HTTPS nel momento in cui avviene.

Altro su questa risorsa

Il feed di sincronizzazione, inviato a te. Ogni evento dei tipi a cui un endpoint è iscritto gli viene inviato con POST come JSON (l’evento di ListSyncEvents più workspaceId e documentPath, la chiamata che ne legge il documento), mai il documento stesso. Ogni richiesta riporta Pleaxy-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>"> con il segreto dell’endpoint; rifiuta quella che non corrisponde o che ha più di 5 minuti. Rispondi con un 2xx entro 10 secondi; qualsiasi altra risposta viene ritentata dopo 1 minuto, 5 minuti, 30 minuti, 2 ore, 6 ore, 12 ore e 24 ore, poi si rinuncia. Gli endpoint sono indirizzi https:// su un nome host; le consegne non raggiungono mai una rete privata e non seguono mai un reindirizzamento. Fino a 5 per parte del workspace.

Endpoint

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

Elencare i webhook

Elenca i tuoi endpoint webhook.

GET/v1/workspaces/{regionId}/webhooks

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Gli endpoint della tua parte e i tipi di evento che possono ricevere. Mai un segreto di firma: secretHint ne mostra l’inizio e la fine.

Un amministratore che ha effettuato l’accesso (token Bearer): approvalSettings edit per l’acquirente, oppure un amministratore fornitore.

Campi della risposta

endpoints[].eventsArray<string>
I tipi di evento inviati. Vuoto significa ogni tipo della tua parte, compresi quelli aggiunti in seguito.
endpoints[].lastErrorCodestring
Perché l’ultimo tentativo non è riuscito: http_status (vedi lastStatus), blocked_address, unreachable, timeout, redirect, too_large, endpoint_off o failed.
endpoints[].failedDeliveriesnumber
Consegne abbandonate consecutivamente; un successo o la riattivazione dell’endpoint lo azzera.

Errori

403 Forbidden - Una chiave API, oppure un chiamante che non è amministratore di questa parte del workspace.
401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.

GET /v1/workspaces/{regionId}/webhooks

Richiesta

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

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

Creare un webhook

Aggiunge un endpoint webhook e restituisce il suo segreto di firma, una sola volta.

POST/v1/workspaces/{regionId}/webhooks

Corpo

urlstringObbligatorio
Un indirizzo https:// su un nome host, senza indirizzo IP, porta, nome utente o password.
descriptionstring
Fino a 100 caratteri, per distinguere gli endpoint.
eventsArray<string>
I tipi di evento da inviare, tra quelli di eventTypes. Omettilo per inviarli tutti.

Restituisce

201 Created con l’oggetto mostrato nella risposta.

Più dettagli

Aggiunge un endpoint. La risposta riporta il suo segreto di firma, mostrato solo questa volta: conservalo nel tuo sistema per verificare la firma di ogni richiesta.

Un amministratore che ha effettuato l’accesso (token Bearer): approvalSettings edit per l’acquirente, oppure un amministratore fornitore.

Errori

400 Bad Request - Codice WEBHOOK_URL_INVALID, WEBHOOK_EVENTS_INVALID o WEBHOOK_LIMIT (già 5 endpoint).
403 Forbidden - Una chiave API, oppure un chiamante che non è amministratore di questa parte del workspace.
401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.

POST /v1/workspaces/{regionId}/webhooks

Richiesta

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

Risposta · 201 Created

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

Aggiornare un webhook

Modifica un endpoint webhook, oppure lo sospende e lo riattiva.

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

Parametri

webhookIdstringObbligatorio
L’id dell’endpoint, ad es. WH-3F9A01C2.

Corpo

enabledboolean
false sospende l’endpoint; true lo riattiva. url, description ed events come in CreateWebhook.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Modifica url, description o events di un endpoint, oppure lo sospende (enabled: false) e lo riattiva (enabled: true). Per un endpoint sospeso non viene accodato nulla. La riattivazione azzera failedDeliveries.

Un amministratore che ha effettuato l’accesso (token Bearer): approvalSettings edit per l’acquirente, oppure un amministratore fornitore.

Errori

400 Bad Request - Codice WEBHOOK_URL_INVALID o WEBHOOK_EVENTS_INVALID.
404 Not Found - Codice WEBHOOK_NOT_FOUND.
401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.

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

Richiesta

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
}

Risposta · 200 OK

The endpoint, as in ListWebhooks.

Eliminare un webhook

Rimuove un endpoint webhook.

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

Parametri

webhookIdstringObbligatorio
L’id dell’endpoint, ad es. WH-3F9A01C2.

Restituisce

204 No Content con l’oggetto mostrato nella risposta.

Più dettagli

Rimuove un endpoint. Le consegne ancora in attesa vengono abbandonate.

Un amministratore che ha effettuato l’accesso (token Bearer): approvalSettings edit per l’acquirente, oppure un amministratore fornitore.

Errori

404 Not Found - Codice WEBHOOK_NOT_FOUND.
401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.

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

Richiesta

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

Risposta · 204 No Content

(no content)

Ruotare il segreto di un webhook

Sostituisce il segreto di firma di un endpoint.

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

Parametri

webhookIdstringObbligatorio
L’id dell’endpoint, ad es. WH-3F9A01C2.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Un nuovo segreto di firma, restituito questa sola volta in secret. Quello vecchio smette subito di firmare, quindi aggiorna subito dopo il tuo sistema.

Un amministratore che ha effettuato l’accesso (token Bearer): approvalSettings edit per l’acquirente, oppure un amministratore fornitore.

Errori

404 Not Found - Codice WEBHOOK_NOT_FOUND.
401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.

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

Richiesta

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

Risposta · 200 OK

The endpoint, as in ListWebhooks, plus secret.

Testare un webhook

Invia a un endpoint un ping di test firmato.

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

Parametri

webhookIdstringObbligatorio
L’id dell’endpoint, ad es. WH-3F9A01C2.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Invia subito all’endpoint un ping firmato, una sola volta, senza nuovi tentativi, e riporta cosa ha risposto.

Un amministratore che ha effettuato l’accesso (token Bearer): approvalSettings edit per l’acquirente, oppure un amministratore fornitore.

Errori

404 Not Found - Codice WEBHOOK_NOT_FOUND.
401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.

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

Richiesta

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

Risposta · 200 OK

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

Elencare le consegne di un webhook

Elenca le consegne recenti di un endpoint.

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

Parametri

webhookIdstringObbligatorio
L’id dell’endpoint, ad es. WH-3F9A01C2.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Le ultime 50 consegne di un endpoint, dalla più recente, conservate 30 giorni: tipo, stato, tentativi di ogni evento e cosa non ha funzionato.

Un amministratore che ha effettuato l’accesso (token Bearer): approvalSettings edit per l’acquirente, oppure un amministratore fornitore.

Campi della risposta

deliveries[].statusstring
pending: in attesa del prossimo tentativo (nextAttemptAt). delivered: ha ricevuto risposta con un 2xx. failed: abbandonata.

Errori

404 Not Found - Codice WEBHOOK_NOT_FOUND.
401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.

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

Richiesta

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

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