Pleaxy

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

Référence de l’API

Exécution des commandes

Les fournisseurs confirment les commandes et annoncent les expéditions ; les acheteurs voient les deux sur la commande.

En savoir plus sur cette ressource

Ce qu’un fournisseur indique sur une commande après son émission : s’il l’accepte, quand elle arrivera et ce qu’il a expédié. L’ERP d’un fournisseur envoie la même chose en cXML : postez un ConfirmationRequest ou un ShipNoticeRequest (DTD Fulfill cXML 1.2.071) sur /v1/cxml/fulfillment avec la clé API dans X-Api-Key ou comme SharedSecret du Sender, et un identifiant To de domaine PleaxyWorkspaceID désignant l’acheteur ; la réponse est un Status cXML, et un payloadID renvoyé ne change rien. Les fournisseurs qui n’ont ni l’un ni l’autre peuvent répondre par e-mail : chaque commande envoyée par e-mail à un fournisseur a sa propre adresse (ListPurchaseOrderEmails), où une réponse ou un document cXML est conservé sur la commande. Rien ici ne modifie la commande : c’est à l’acheteur d’annuler une commande refusée, et une expédition n’est jamais une réception. Le demandeur et le réceptionnaire de l’acheteur sont prévenus, et le flux de synchronisation et les webhooks de l’acheteur reçoivent purchase_order.confirmed et purchase_order.shipped.

Endpoints

Obtenir l’exécution d’un bon de commande

Renvoie les confirmations et les expéditions du fournisseur pour une commande.

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

Paramètres

  • poIdstringObligatoire

    L’identifiant du bon de commande.

  • buyerstring

    Appelants fournisseurs : l’ID d’espace de travail de l’acheteur, quand deux acheteurs ont émis le même id.

Retour

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

Plus de détails

Ce que le fournisseur a indiqué sur une commande : sa dernière confirmation (résultat accepted, backordered, changed, partial ou rejected, ligne par ligne, avec la décision de l’acheteur sur les modifications), les précédentes, et ses expéditions (planned, shipped ou canceled, avec transporteur et suivi). Chaque expédition liste les réceptions de marchandises approuvées saisies pour elle. shippedByLine additionne les quantités expédiées ; expectedDeliveryDate est la date de livraison la plus tardive indiquée par le fournisseur. Un fournisseur dont les acheteurs partagent un id de bon de commande ajoute ?buyer=<ID d’espace de travail de l’acheteur>.

Champs de la réponse

  • confirmationOrderConfirmation

    La dernière confirmation, absente tant que le fournisseur n’a pas répondu. Son résultat est celui de la commande.

  • shippedByLineArray

    Par ligne, la quantité des expéditions au statut shipped. Celles au statut planned ou canceled ne sont pas comptées.

Erreurs

  • 404 Not Found - Aucun bon de commande avec cet id ne vous appartient.
  • 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.
  • 403 Forbidden - Le jeton Bearer ou la clé API de l’appelant ne donne pas accès à cet espace de travail (regionId), ou n’a pas le rôle requis.
GET /v1/workspaces/{regionId}/purchase-orders/{poId}/fulfillment
Requête
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/fulfillment" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Réponse · 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"
}

Appliquer les modifications de la confirmation

Reprend dans la commande les quantités et les prix modifiés par le fournisseur.

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

Paramètres

  • poIdstringObligatoire

    L’identifiant du bon de commande.

  • confirmationIdstringObligatoire

    L’id de la confirmation, issu de GetPurchaseOrderFulfillment.

Retour

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

Plus de détails

Applique aux lignes de la commande les modifications de la dernière confirmation du fournisseur (résultat changed). Il s’agit d’une modification de lignes ordinaire, comme celle que fait UpdatePurchaseOrder : la commande reçoit une nouvelle version, repasse en validation si ses règles le prévoient, et le fournisseur reçoit po_changed. Renvoie { purchaseOrder, confirmation } avec la décision appliquée et la version de la commande qui en résulte.

Erreurs

  • 404 Not Found - Aucune commande de ce type, ou code CONFIRMATION_NOT_FOUND.
  • 409 Conflict - Code CONFIRMATION_SUPERSEDED (le fournisseur a confirmé à nouveau depuis), CONFIRMATION_DECIDED (modifications déjà appliquées ou refusées), NO_CHANGES ou ORDER_NOT_OPEN.
  • 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.
  • 403 Forbidden - Le jeton Bearer ou la clé API de l’appelant ne donne pas accès à cet espace de travail (regionId), ou n’a pas le rôle requis.
POST /v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/apply
Requête
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/apply" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Réponse · 200 OK
{
   "purchaseOrder": PurchaseOrder,
   "confirmation": OrderConfirmation
}

Refuser les modifications de la confirmation

Conserve la commande telle quelle au lieu des modifications du fournisseur.

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

Paramètres

  • poIdstringObligatoire

    L’identifiant du bon de commande.

  • confirmationIdstringObligatoire

    L’id de la confirmation, issu de GetPurchaseOrderFulfillment.

Corps

  • reasonstring

    Motif, jusqu’à 500 caractères. Le fournisseur le voit.

Retour

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

Plus de détails

Refuse les modifications de la dernière confirmation du fournisseur. La commande ne change pas ; le fournisseur en est informé, avec votre motif si vous en donnez un. Renvoie la confirmation avec sa décision.

Erreurs

  • 404 Not Found - Aucune commande de ce type, ou code CONFIRMATION_NOT_FOUND.
  • 409 Conflict - Code CONFIRMATION_SUPERSEDED, CONFIRMATION_DECIDED ou NO_CHANGES.
  • 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.
  • 403 Forbidden - Le jeton Bearer ou la clé API de l’appelant ne donne pas accès à cet espace de travail (regionId), ou n’a pas le rôle requis.
POST /v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/decline
Requête
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"
}
Réponse · 200 OK
OrderConfirmation

Lister les e-mails d’un bon de commande

Renvoie l’adresse e-mail propre à une commande et les e-mails qui y sont arrivés.

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

Paramètres

  • poIdstringObligatoire

    L’identifiant du bon de commande.

  • buyerstring

    Fournisseurs : l’ID d’espace de travail de l’acheteur, quand deux acheteurs ont émis le même id.

Retour

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

Plus de détails

Chaque commande envoyée par e-mail à son fournisseur reçoit sa propre adresse, ajoutée comme second Reply-To de l’e-mail de la commande et imprimée sur le PDF. La réponse d’un fournisseur, ou un ConfirmationRequest ou ShipNoticeRequest cXML que son système y envoie, est conservée sur la commande, du plus récent au plus ancien. Un document cXML d’un expéditeur vérifié (le contact du fournisseur ou le domaine de son entreprise, contrôlé avec SPF, DKIM et DMARC) est enregistré immédiatement (outcome applied). Pleaxy Assistant lit un e-mail simple et en fait un brouillon de confirmation ou d’avis d’expédition, et un document d’un expéditeur que Pleaxy ne peut pas vérifier est retenu : dans les deux cas, ils attendent qu’une personne les enregistre avec RecordPurchaseOrderEmail. address est absent tant que la commande n’est pas émise.

Erreurs

  • 404 Not Found - Aucun bon de commande de ce type.
  • 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.
  • 403 Forbidden - Le jeton Bearer ou la clé API de l’appelant ne donne pas accès à cet espace de travail (regionId), ou n’a pas le rôle requis.
GET /v1/workspaces/{regionId}/purchase-orders/{poId}/emails
Requête
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/emails" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Réponse · 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" }
      }
   ]
}

Enregistrer un e-mail de bon de commande

Enregistre le brouillon d’un e-mail comme confirmation ou avis d’expédition du fournisseur.

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

Paramètres

  • poIdstringObligatoire

    L’identifiant du bon de commande.

  • emailIdstringObligatoire

    L’id de l’e-mail, issu de ListPurchaseOrderEmails.

Retour

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

Plus de détails

Enregistre le brouillon d’un e-mail dont l’outcome vaut draft ou held comme confirmation de commande ou avis d’expédition du fournisseur, avec l’e-mail pour source et les mêmes contrôles que ConfirmPurchaseOrder et SendShipNotice. Répond à l’e-mail avec sa décision. Un acheteur doit pouvoir modifier les bons de commande.

Erreurs

  • 400 Bad Request - Le brouillon cite une ligne inconnue, ou une ligne qui ne peut pas être expédiée.
  • 404 Not Found - Aucune commande ou aucun e-mail de ce type.
  • 409 Conflict - Code EMAIL_DECIDED (déjà enregistré ou écarté), NOTHING_TO_RECORD ou ORDER_NOT_OPEN.
  • 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.
  • 403 Forbidden - Le jeton Bearer ou la clé API de l’appelant ne donne pas accès à cet espace de travail (regionId), ou n’a pas le rôle requis.
POST /v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/record
Requête
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/record" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Réponse · 200 OK
InboundEmail

Écarter un e-mail de bon de commande

Laisse la commande telle quelle au lieu d’enregistrer ce que demande un e-mail.

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

Paramètres

  • poIdstringObligatoire

    L’identifiant du bon de commande.

  • emailIdstringObligatoire

    L’id de l’e-mail, issu de ListPurchaseOrderEmails.

Retour

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

Plus de détails

Marque un e-mail comme écarté : rien n’est enregistré. Répond à l’e-mail avec sa décision.

Erreurs

  • 404 Not Found - Aucune commande ou aucun e-mail de ce type.
  • 409 Conflict - Code EMAIL_DECIDED : déjà enregistré ou écarté.
  • 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.
  • 403 Forbidden - Le jeton Bearer ou la clé API de l’appelant ne donne pas accès à cet espace de travail (regionId), ou n’a pas le rôle requis.
POST /v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/dismiss
Requête
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/dismiss" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Réponse · 200 OK
InboundEmail
Nous contacter