Pleaxy

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

Riferimento API

Evasione degli ordini

I fornitori confermano gli ordini e annunciano le spedizioni; gli acquirenti vedono entrambe le cose sull’ordine.

Altro su questa risorsa

Cosa dice un fornitore di un ordine dopo che è stato emesso: se lo accetta, quando arriverà e cosa ha spedito. L’ERP di un fornitore invia le stesse informazioni in cXML: invia con POST una ConfirmationRequest o una ShipNoticeRequest (DTD Fulfill di cXML 1.2.071) a /v1/cxml/fulfillment con la chiave API in X-Api-Key o come SharedSecret del Sender, e una credenziale To con dominio PleaxyWorkspaceID che indica l’acquirente; la risposta è uno Status cXML, e un payloadID inviato di nuovo non cambia nulla. I fornitori che non hanno né l’uno né l’altro possono rispondere via email: ogni ordine inviato via email a un fornitore ha un proprio indirizzo (ListPurchaseOrderEmails), dove una risposta o un documento cXML viene conservato sull’ordine. Niente di tutto questo modifica l’ordine: spetta all’acquirente annullare un ordine rifiutato, e una spedizione non è mai un ricevimento. Il richiedente e il destinatario della merce dell’acquirente vengono avvisati, e il feed di sincronizzazione e i webhook dell’acquirente ricevono purchase_order.confirmed e purchase_order.shipped.

Endpoint

Recuperare l’evasione di un ordine d’acquisto

Restituisce le conferme e le spedizioni del fornitore per un ordine.

GET/v1/workspaces/{regionId}/purchase-orders/{poId}/fulfillment

Parametri

  • poIdstringObbligatorio

    L’identificativo dell’ordine d’acquisto.

  • buyerstring

    Chiamanti Fornitore: l’ID del workspace dell’acquirente, quando due acquirenti hanno emesso lo stesso id.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Cosa ha detto il fornitore di un ordine: la sua ultima conferma (esito accepted, backordered, changed, partial o rejected, riga per riga, con la decisione dell’acquirente sulle modifiche), quelle precedenti e le sue spedizioni (planned, shipped o canceled, con corriere e tracciamento). Ogni spedizione elenca i ricevimenti merci approvati registrati a fronte di essa. shippedByLine somma le quantità spedite; expectedDeliveryDate è la data di consegna più lontana nel tempo indicata dal fornitore. Un fornitore i cui acquirenti condividono un id di OdA aggiunge ?buyer=<ID del workspace dell’acquirente>.

Campi della risposta

  • confirmationOrderConfirmation

    L’ultima conferma, assente finché il fornitore non risponde. Il suo esito è quello dell’ordine.

  • shippedByLineArray

    Per riga, la quantità nelle spedizioni shipped. Quelle planned e canceled non vengono contate.

Errori

  • 404 Not Found - Nessun ordine d’acquisto tuo ha questo id.
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
GET /v1/workspaces/{regionId}/purchase-orders/{poId}/fulfillment
Richiesta
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/fulfillment" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 200 OK
{
   "confirmation": OrderConfirmation,
   "confirmations": [
      {
         "id": "string",
         "poId": "string",
         "outcome": "accepted" | "backordered" | "changed" | "partial" | "rejected",
         "confirmId": "string",
         "deliveryDate": "YYYY-MM-DD",
         "note": "string",
         "lines": [ { "lineNo": number, "status": "accept" | "backordered" | "change" | "reject", "qty": number, "unitPrice": number, "substitute": { "supplierPartId": "string", "name": "string", "catalogItemId": "string" }, "shipmentDate": "YYYY-MM-DD", "deliveryDate": "YYYY-MM-DD", "reason": "string" } ],
         "decision": { "decision": "applied" | "declined", "at": "string", "version": number, "reason": "string" },
         "source": "portal" | "api" | "cxml",
         "createdAt": "string"
      }
   ],
   "shipNotices": [
      {
         "shipmentId": "string",
         "status": "planned" | "shipped" | "canceled",
         "shipmentDate": "YYYY-MM-DD",
         "deliveryDate": "YYYY-MM-DD",
         "carrier": "string",
         "trackingNumber": "string",
         "trackingUrl": "string",
         "lines": [ { "lineNo": number, "qty": number } ],
         "source": "portal" | "api" | "cxml",
         "createdAt": "string",
         "updatedAt": "string",
         "receipts": [ { "id": "string", "receivedAt": "YYYY-MM-DD" } ]
      }
   ],
   "shippedByLine": [ { "lineNo": number, "qty": number } ],
   "expectedDeliveryDate": "YYYY-MM-DD"
}

Applicare le modifiche della conferma

Riporta nell’ordine le quantità e i prezzi modificati dal fornitore.

POST/v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/apply

Parametri

  • poIdstringObbligatorio

    L’identificativo dell’ordine d’acquisto.

  • confirmationIdstringObbligatorio

    L’id della conferma, da GetPurchaseOrderFulfillment.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Applica alle righe dell’ordine le modifiche dell’ultima conferma del fornitore (esito changed). È una normale modifica delle righe, come quella di UpdatePurchaseOrder: l’ordine riceve una nuova versione, torna in approvazione quando le sue regole lo prevedono e il fornitore riceve po_changed. Restituisce { purchaseOrder, confirmation } con la decisione applicata e la versione dell’ordine che ne risulta.

Errori

  • 404 Not Found - Questo ordine non esiste, oppure codice CONFIRMATION_NOT_FOUND.
  • 409 Conflict - Codice CONFIRMATION_SUPERSEDED (nel frattempo il fornitore ha confermato di nuovo), CONFIRMATION_DECIDED (modifiche già applicate o rifiutate), NO_CHANGES oppure ORDER_NOT_OPEN.
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
POST /v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/apply
Richiesta
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/apply" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 200 OK
{
   "purchaseOrder": PurchaseOrder,
   "confirmation": OrderConfirmation
}

Rifiutare le modifiche della conferma

Mantiene l’ordine così com’è, invece di accettare le modifiche del fornitore.

POST/v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/decline

Parametri

  • poIdstringObbligatorio

    L’identificativo dell’ordine d’acquisto.

  • confirmationIdstringObbligatorio

    L’id della conferma, da GetPurchaseOrderFulfillment.

Corpo

  • reasonstring

    Il motivo, fino a 500 caratteri. Il fornitore lo vede.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Rifiuta le modifiche dell’ultima conferma del fornitore. L’ordine non cambia; il fornitore viene avvisato, con il tuo motivo se lo indichi. Restituisce la conferma con la sua decisione.

Errori

  • 404 Not Found - Questo ordine non esiste, oppure codice CONFIRMATION_NOT_FOUND.
  • 409 Conflict - Codice CONFIRMATION_SUPERSEDED, CONFIRMATION_DECIDED o NO_CHANGES.
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
POST /v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/decline
Richiesta
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/decline" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "reason": "string"
}
Risposta · 200 OK
OrderConfirmation

Elencare le email di un ordine d’acquisto

Restituisce l’indirizzo email proprio di un ordine e le email che vi sono arrivate.

GET/v1/workspaces/{regionId}/purchase-orders/{poId}/emails

Parametri

  • poIdstringObbligatorio

    L’identificativo dell’ordine d’acquisto.

  • buyerstring

    Fornitori: l’ID del workspace dell’acquirente, quando due acquirenti hanno emesso lo stesso id.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Ogni ordine inviato via email al suo fornitore riceve un proprio indirizzo, come secondo Reply-To nell’email dell’ordine e stampato sul PDF. La risposta di un fornitore, o una ConfirmationRequest o ShipNoticeRequest cXML che il suo sistema invia lì, viene conservata sull’ordine, dalla più recente. Un documento cXML da un mittente verificato (il contatto del fornitore o il dominio della sua azienda, controllato con SPF, DKIM e DMARC) viene registrato subito (outcome applied). Pleaxy Assistant legge un’email semplice e ne ricava una bozza di conferma o di avviso di spedizione, e un documento da un mittente che Pleaxy non riesce a verificare viene trattenuto: in entrambi i casi attendono che qualcuno li registri con RecordPurchaseOrderEmail. address è assente finché l’ordine non viene emesso.

Errori

  • 404 Not Found - Questo ordine d’acquisto non esiste.
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
GET /v1/workspaces/{regionId}/purchase-orders/{poId}/emails
Richiesta
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/emails" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 200 OK
{
   "address": "string",
   "emails": [
      {
         "id": "string",
         "from": "string",
         "subject": "string",
         "receivedAt": "string",
         "trust": "verified" | "unverified",
         "kind": "cxml" | "text",
         "outcome": "applied" | "draft" | "held" | "noAction" | "test" | "failed" | "ignored",
         "reasonCode": "string",
         "summary": "string",
         "text": "string",
         "attachments": [ { "name": "string", "contentType": "string", "size": number } ],
         "draft": { "kind": "confirmation" | "shipNotice", "summary": "string", "confirmation": object, "shipNotice": object },
         "result": { "confirmationId": "string", "shipmentId": "string" },
         "decision": { "action": "recorded" | "dismissed", "by": "string", "at": "string" }
      }
   ]
}

Registrare un’email di un ordine d’acquisto

Registra la bozza di un’email come conferma o avviso di spedizione del fornitore.

POST/v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/record

Parametri

  • poIdstringObbligatorio

    L’identificativo dell’ordine d’acquisto.

  • emailIdstringObbligatorio

    L’id dell’email, da ListPurchaseOrderEmails.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Registra la bozza di un’email con outcome draft o held come conferma d’ordine o avviso di spedizione del fornitore, con origine email e gli stessi controlli di ConfirmPurchaseOrder e SendShipNotice. Risponde all’email con la sua decisione. Un acquirente deve poter modificare gli ordini d’acquisto.

Errori

  • 400 Bad Request - La bozza indica una riga sconosciuta, o una riga che non può essere spedita.
  • 404 Not Found - Questo ordine o questa email non esiste.
  • 409 Conflict - Codice EMAIL_DECIDED (già registrata o scartata), NOTHING_TO_RECORD oppure ORDER_NOT_OPEN.
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
POST /v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/record
Richiesta
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/record" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 200 OK
InboundEmail

Scartare un’email di un ordine d’acquisto

Lascia l’ordine com’è invece di registrare ciò che chiede un’email.

POST/v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/dismiss

Parametri

  • poIdstringObbligatorio

    L’identificativo dell’ordine d’acquisto.

  • emailIdstringObbligatorio

    L’id dell’email, da ListPurchaseOrderEmails.

Restituisce

200 OK con l’oggetto mostrato nella risposta.

Più dettagli

Segna un’email come scartata: non viene registrato nulla. Risponde all’email con la sua decisione.

Errori

  • 404 Not Found - Questo ordine o questa email non esiste.
  • 409 Conflict - Codice EMAIL_DECIDED: già registrata o scartata.
  • 401 Unauthorized - Non è stata presentata alcuna credenziale, oppure il token Bearer o il valore di X-Api-Key è mancante, non valido, scaduto o revocato.
  • 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
POST /v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/dismiss
Richiesta
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/dismiss" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Risposta · 200 OK
InboundEmail
Contattaci