Aller au contenu principal

Exemple d'intégration avec FedEx

Ce tutoriel montre comment intégrer FedEx.

1. Préparation​

1.1. Créer un compte FedEx

Créez un compte sur le portail développeur.

1.2. Créer des projets et obtenir des jetons

Créez deux projets dans la section mes projets et notez le client id et le client secret.

Le premier projet sert à gérer les expéditions.

Le second sert à suivre les expéditions.

1.3. Créer les statuts de livraison

Dans l'onglet des statuts du stockage des commandes, créez les statuts (s'ouvre dans un nouvel onglet) suivants :

  • order_delivery
  • order_delivery_started
  • ready_for_pickup

1.4. Créer un événement pour suivre les statuts

Dans le module Events (s'ouvre dans un nouvel onglet), créez un événement qui suit le changement du statut de commande order_delivery.

Événement order delivery, marqueur order_delivery : module orders, stockage test_order_storage, statut order_delivery, "Integrations" coché.

1.5. Créer une collection pour la livraison

Dans le module Integration Collections (s'ouvre dans un nouvel onglet), créez une collection pour la livraison avec les attributs suivants :

  • name (string)
  • address (string)
  • phone_number (string)
  • city (string)
  • state_code (string)
  • postal_code (string)
  • country_code (string)
  • tracking_number (string)
  • transaction_id (string)
  • ship_datestamp (string)
  • delivery_datestamp (string)

Section "Integration collections" : la collection delivery, marqueur delivery, apparaît dans la liste.

1.6. Créer une commande de test

Créez une commande, puis un enregistrement de collection pour cette commande.

Requête POST vers /api/content/orders-storage/marker/order_storage/orders avec le corps JSON d'une commande de test : formulaire order_form, paiement paypal, produit 1 × 2.

Requête POST vers /api/content/integration-collections/marker/delivery/rows : enregistrement pour la commande 1 avec le formulaire delivery_form et les données du destinataire.

2. Création d'une expédition​

2.1. Suivi de l'événement de livraison

  • Faites glisser le nœud events (s'ouvre dans un nouvel onglet) sur l'espace de travail.
  • Saisissez le nom du nœud.
  • Dans le champ "Set", remplacez la valeur par "orderEvent".
  • L'événement est enregistré dans l'objet "msg.orderEvent" et peut être utilisé dans d'autres nœuds.
  • Dans la liste, sélectionnez l'événement "order delivery" que vous avez créé, puis cliquez sur "submit".

Nœud order delivery event : "Set" vaut msg.orderEvent, order delivery sélectionné dans "Events".

2.2. Obtention d'un jeton

  • Faites glisser le nœud function (s'ouvre dans un nouvel onglet) sur l'espace de travail et reliez-le au nœud de l'étape précédente.
  • Collez le code de l'exemple dans le champ "Function".
  • Remplacez YOUR_CLIENT_ID et OUR_CLIENT_SECRET par vos valeurs.

Nœud auth body : le code du champ "Function" définit msg.payload avec client_credentials, YOUR_CLIENT_ID, YOUR_CLIENT_SECRET et un en-tête Content-Type.

msg.payload = {
    'grant_type': 'client_credentials',
    'client_id': 'YOUR_CLIENT_ID',
    'client_secret': 'YOUR_CLIENT_SECRET'
}
msg.headers = {
    'Content-Type': 'application/x-www-form-urlencoded'
}

return msg;

Pour en savoir plus sur les paramètres, consultez la documentation FedEx.

  • Faites glisser le nœud http request (s'ouvre dans un nouvel onglet) sur l'espace de travail et reliez-le au nœud de l'étape précédente.
  • Dans le champ Method, sélectionnez "POST".
  • Dans le champ Data, sélectionnez "Send as request body".
  • Dans le champ Link, collez l'URL https://apis-sandbox.fedex.com/oauth/token.
  • Dans le champ Return, sélectionnez "Object JSON".

Nœud auth request : "Method" POST, "Data" Send as request body, "Link" https://apis-sandbox.fedex.com/oauth/token, "Return" Object JSON.

Nœud set access token : le code du champ "Function" copie access_token de msg.payload vers msg.access_token.

msg.access_token = msg.payload.access_token;

return msg;

2.3. Création d'une expédition

  • Faites glisser le nœud admin-api (s'ouvre dans un nouvel onglet) sur l'espace de travail et reliez-le au nœud de l'étape précédente.
  • Sélectionnez la méthode "Receiving all records belonging to the collection" et collez le code ci-dessous dans le champ "Data".
{
  "entityType": "orders",
  "entityId": "{{orderEvent.order.id}}",
  "langCode": "en_US",
  "offset": 0,
  "limit": 1,
  "marker": "delivery"
}

Nœud find collection rows : "Type" vaut Receiving all records belonging to the collection, "Query parameters" contient un JSON avec marker delivery, entityType orders, entityId orderEvent.order.id.

Nœud shipment data : le code du champ "Function" construit les en-têtes avec un jeton Bearer et les données du destinataire à partir de l'enregistrement de collection.

// récupère le jeton enregistré précédemment
const token = msg.access_token;

// définit les en-têtes
msg.headers = {
    'Content-Type': 'application/json',
    'authorization': `Bearer ${token}`
};

// récupère les collections de l'étape précédente
const collection = msg.payload.items[0];
// convertit le tableau en objet
const formData = collection.formData.reduce((acc, item) => {
  acc[item.marker] = item.value;
  return acc;
}, {});
// définit les paramètres du destinataire à partir du formulaire
const recipient = {
  "address": {
    "streetLines": [
      formData.address
    ],
    "city": formData.city,
    "stateOrProvinceCode": formData.state_code,
    "postalCode": formData.postal_code,
    "countryCode": formData.country_code
  },
  "contact": {
    "personName": formData.name,
    "phoneNumber": formData.phone_number
  }
}
// enregistre les données de la collection dans msg pour la suite
msg.collection = collection;
// définit les paramètres de la requête FedEx
msg.payload = {
  "labelResponseOptions": "URL_ONLY",
  "accountNumber": {
    "value": "510087020"
  },
  "requestedShipment": {
    "shipper": {
      "contact": {
        "personName": "SENDER NAME",
        "phoneNumber": "9018328595"
      },
      "address": {
        "streetLines": [
          "SENDER ADDRESS 1"
        ],
        "city": "MEMPHIS",
        "stateOrProvinceCode": "TN",
        "postalCode": "38116",
        "countryCode": "US"
      }
    },
    "recipients": [
      recipient
    ],
    "serviceType": "STANDARD_OVERNIGHT",
    "packagingType": "YOUR_PACKAGING",
    "pickupType": "DROPOFF_AT_FEDEX_LOCATION",
    "shippingChargesPayment": {
      "paymentType": "SENDER",
      "payor": {
        "responsibleParty": {
          "accountNumber": {
            "value": "510087020",
            "key": ""
          }
        },
        "address": {
          "streetLines": [
            "SENDER ADDRESS 1"
          ],
          "city": "MEMPHIS",
          "stateOrProvinceCode": "TN",
          "postalCode": "38116",
          "countryCode": "US"
        }
      }
    },
    "labelSpecification": {},
    "requestedPackageLineItems": [
      {
        "customerReferences": [
          {
            "customerReferenceType": "CUSTOMER_REFERENCE",
            "value": `Collection${collection.id}`
          }
        ],
        "weight": {
          "units": "LB",
          "value": "20"
        }
      }
    ]
  }
};

return msg;

Pour en savoir plus sur les paramètres, consultez la documentation FedEx.

  • Faites glisser le nœud http request (s'ouvre dans un nouvel onglet) sur l'espace de travail et reliez-le au nœud de l'étape précédente.
  • Dans le champ Method, sélectionnez "POST".
  • Dans le champ Data, sélectionnez "Send as request body".
  • Dans le champ Link, collez l'URL https://apis-sandbox.fedex.com/ship/v1/shipments.
  • Dans le champ Return, sélectionnez "Object JSON".

Nœud shipment request : "Method" POST, "Data" Send as request body, "Link" https://apis-sandbox.fedex.com/ship/v1/shipments, "Return" Object JSON.

Nœud debug debug fedex shipment : "Output" vaut msg.payload.

Nœud update row data : le code du champ "Function" construit le nouveau formData de l'enregistrement de collection avec transaction_id et ship_datestamp issus de la réponse FedEx.

// récupère les données de l'expédition
const shipment = msg.payload.output.transactionShipments[0];
// récupère les données de la collection enregistrées précédemment
const collection = msg.collection;

// écrit les données de l'expédition dans les attributs du formulaire
const newFormData = [
  ...collection.formData
    .filter(item => !['transaction_id', 'ship_datestamp', 'delivery_datestamp', 'tracking_number'].includes(item.marker)),
  {
    marker: 'transaction_id',
    value: msg.payload.transactionId,
    type: 'string'
  },
  {
    marker: 'ship_datestamp',
    value: shipment.shipDatestamp,
    type: 'string'
  },
  {
    marker: 'delivery_datestamp',
    value: shipment.pieceResponses[0].deliveryDatestamp,
    type: 'string'
  },
  {
    marker: 'tracking_number',
    value: shipment.masterTrackingNumber,
    type: 'string'
  }
]

// définit les paramètres de mise à jour de la collection
msg.params = {
  langCode: 'en_US',
  id: collection.id,
  marker: 'delivery'
}

msg.data = {
  formIdentifier: 'delivery_form',
  formData: {
    en_US: newFormData
  },
  entityId: collection.entityId,
  entityType: collection.entityType
}

// enregistre les données de la collection pour la suite
msg.collection = collection;

return msg;

Nœud update collection row : méthode "Changing a record in the collection" sélectionnée dans "Type", "Query parameters" vide.

2.4. Mise à jour du statut de la commande

  • Faites glisser le nœud admin-api (s'ouvre dans un nouvel onglet) sur l'espace de travail et reliez-le au nœud de l'étape précédente.
  • Sélectionnez la méthode "Updating the status of an order belonging to the order storage object".
  • Collez le code ci-dessous dans le champ "Query parameters".
{
  "id": 1,
  "orderId": "{{collection.entityId}}"
}
  • Collez le code ci-dessous dans le champ "Request body".
{
  "statusIdentifier": "order_delivery_started"
}

Nœud order delivery started : type mise à jour du statut d'une commande du stockage ; paramètres id et orderId, statusIdentifier dans le corps.

Nœud debug debug status update 1 : "Output" vaut msg.payload.

3. Suivi du statut de l'expédition​

3.1. Récupération des commandes à suivre

Nœud set interval : "interval" vaut 60.

  • Faites glisser le nœud admin-api (s'ouvre dans un nouvel onglet) sur l'espace de travail et reliez-le au nœud de l'étape précédente.
  • Sélectionnez la méthode "Receiving all orders belonging to the order storage object".
  • Collez le code ci-dessous dans le champ "Query parameters".
{
  "statusIdentifier": "order_delivery_started",
  "langCode": "en_US",
  "offset": 0,
  "limit": 100,
  "id": 1
}

Nœud find orders by status : "Type" vaut Receiving all orders belonging to the order storage object, "Query parameters" contient un JSON avec statusIdentifier order_delivery_started, limit 100, id 1.

Nœud set orders : le code du champ "Function" affecte msg.payload.items à msg.payload.

msg.payload = msg.payload.items;

return msg;

Nœud split : "Property" vaut payload, "Length" vaut 1.

  • Faites glisser le nœud admin-api (s'ouvre dans un nouvel onglet) sur l'espace de travail et reliez-le au nœud de l'étape précédente.
  • Sélectionnez la méthode "Receiving all records belonging to the collection".
  • Collez le code ci-dessous dans le champ "Query parameters".
{
  "marker": "delivery",
  "entityId": "{{payload.id}}",
  "entityType": "orders",
  "langCode": "en_US",
  "limit": 1,
  "offset": 0
}

Nœud find collection rows : "Type" vaut Receiving all records belonging to the collection, "Query parameters" contient un JSON avec marker delivery, entityId payload.id, entityType orders.

Fenêtre "Node Information" du nœud function "set row" : le code du champ "Function" place le premier élément de msg.payload.items dans msg.payload

msg.payload = msg.payload.items[0]

return msg;
  • Faites glisser le nœud switch (s'ouvre dans un nouvel onglet) sur l'espace de travail et reliez-le au nœud de l'étape précédente.
  • Ajoutez une règle de vérification et sélectionnez la condition "not empty".

Fenêtre "Node Information" du nœud "switch" : propriété "payload", mode "check all rules", condition "not empty" sélectionnée dans la règle

Fenêtre "Node Information" du nœud function "set trackingNummber" : le code du champ "Function" copie dans msg.trackingNumber la valeur du champ de formData dont le marqueur est tracking_number

msg.trackingNumber = msg.payload
  .formData
  .find(item => item.marker === 'tracking_number')
  .value;

msg.collection = msg.payload;

return msg;

3.2. Obtention d'un jeton

  • Faites glisser le nœud function (s'ouvre dans un nouvel onglet) sur l'espace de travail et reliez-le au nœud de l'étape précédente.
  • Collez le code de l'exemple dans le champ "Function".
  • Remplacez YOUR_CLIENT_ID et OUR_CLIENT_SECRET par vos valeurs.

Fenêtre "Node Information" du nœud function "auth body" : le code du champ "Function" construit le corps de la requête de jeton avec grant_type, client_id et client_secret, et les valeurs à remplacer YOUR_CLIENT_ID et YOUR_CLIENT_SECRET

msg.payload = {
    'grant_type': 'client_credentials',
    'client_id': 'YOUR_CLIENT_ID',
    'client_secret': 'YOUR_CLIENT_SECRET'
}
msg.headers = {
    'Content-Type': 'application/x-www-form-urlencoded'
}

return msg;

Pour en savoir plus sur les paramètres, consultez la documentation FedEx.

  • Faites glisser le nœud http request (s'ouvre dans un nouvel onglet) sur l'espace de travail et reliez-le au nœud de l'étape précédente.
  • Dans le champ Method, sélectionnez "POST".
  • Dans le champ Data, sélectionnez "Send as request body".
  • Dans le champ Link, collez l'URL https://apis-sandbox.fedex.com/oauth/token.
  • Dans le champ Return, sélectionnez "Object JSON".

Fenêtre "Node Information" du nœud http request "auth request" : méthode "POST", "Send as request body", adresse apis-sandbox.fedex.com/oauth/token, "Return" sur "Object JSON"

3.3. Récupération du statut de l'expédition

Fenêtre "Node Information" du nœud function "tracking data" : le code du champ "Function" définit l'en-tête d'autorisation Bearer avec le jeton et un corps de requête contenant trackingNumber

const token = msg.payload.access_token;

msg.headers = {
    'content-type': 'application/json',
    'authorization': `Bearer ${token}`
};

msg.payload = {
  "trackingInfo": [
    {
      "trackingNumberInfo": {
        "trackingNumber": msg.trackingNumber
      }
    }
  ],
  "includeDetailedScans": true
}

return msg;

Pour en savoir plus sur les paramètres, consultez la documentation FedEx.

  • Faites glisser le nœud http request (s'ouvre dans un nouvel onglet) sur l'espace de travail et reliez-le au nœud de l'étape précédente.
  • Dans le champ Method, sélectionnez "POST".
  • Dans le champ Data, sélectionnez "Send as request body".
  • Dans le champ Link, collez l'URL https://apis-sandbox.fedex.com/track/v1/trackingnumbers.
  • Dans le champ Return, sélectionnez "Object JSON".

Fenêtre "Node Information" du nœud http request "tracking request" : méthode "POST", "Send as request body", adresse apis-sandbox.fedex.com/track/v1/trackingnumbers, "Return" sur "Object JSON"

Fenêtre "Node Information" du nœud function "set tracking result" : le code du champ "Function" place dans msg.payload le résultat du suivi issu de msg.payload.output

msg.payload = msg.payload.output.completeTrackResults[0].trackResults[0].latestStatusDetail.statusByLocale;

return msg;

3.4. Mise à jour du statut de la commande

  • Faites glisser le nœud switch (s'ouvre dans un nouvel onglet) sur l'espace de travail et reliez-le au nœud de l'étape précédente.
  • Ajoutez une règle de vérification : sélectionnez la condition "==" et saisissez "Ready for pickup" comme valeur.

Fenêtre "Node Information" du nœud switch "check ship status" : propriété "payload", condition "==", valeur "Ready for pickup"

  • Faites glisser le nœud admin-api (s'ouvre dans un nouvel onglet) sur l'espace de travail et reliez-le au nœud de l'étape précédente.
  • Sélectionnez la méthode "Updating the status of an order belonging to the order storage object".
  • Collez le code ci-dessous dans le champ "Query parameters".
{
  "id": 1,
  "orderId": "{{collection.entityId}}"
}
  • Collez le code ci-dessous dans le champ "Request body".
{
  "statusIdentifier": "ready_for_pickup"
}

Fenêtre "Node Information" du nœud "update status" : type mise à jour du statut de commande, "Query parameters" avec id et orderId, "Request body" avec statusIdentifier ready_for_pickup

Fenêtre "Node Information" du nœud debug "debug status update 2" : "Output" défini sur msg.payload

Dernière mise à jour le