Exemplo de integração com a FedEx

Este tutorial mostra como integrar a FedEx.

1. Preparação

1.1. Crie uma conta na FedEx

Crie uma conta no portal do desenvolvedor.

1.2. Crie os projetos e obtenha os tokens

Crie 2 projetos na seção meus projetos e salve o client id e o client secret de cada um.

O primeiro projeto é para gerenciar envios:

O segundo é para rastrear envios:

1.3. Crie os status de entrega

Na aba de status do armazenamento de pedidos, crie os status (abre em uma nova aba):

order_delivery
order_delivery_started
ready_for_pickup

1.4. Crie um evento para rastrear os status

No módulo Events (abre em uma nova aba), crie um evento que rastreie a mudança do status do pedido para order_delivery.

Evento order delivery com marcador order_delivery: módulo orders, armazenamento test_order_storage, status order_delivery, "Integrations" marcado.

1.5. Crie uma coleção para entregas

No módulo Integration Collections (abre em uma nova aba), crie uma coleção para entregas com os atributos:

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)

Seção "Integration collections": a coleção delivery, com marcador delivery, criada na lista.

1.6. Crie um pedido de teste

Crie um pedido e um registro na coleção para esse pedido.

Requisição POST para /api/content/orders-storage/marker/order_storage/orders com o corpo JSON do pedido de teste: formulário order_form, pagamento paypal, produto 1 × 2.

Requisição POST para /api/content/integration-collections/marker/delivery/rows: registro do pedido 1 com o formulário delivery_form e os dados do destinatário.

2. Criação do envio

2.1. Rastreamento do evento de entrega

Arraste o nó events (abre em uma nova aba) para o espaço de trabalho.
Insira o nome do nó.
Altere o valor do campo "Set" para "orderEvent".
O evento fica salvo no objeto "msg.orderEvent", e você pode usá-lo em outros nós.
Selecione na lista o evento criado, "order delivery", e clique em "submit".

Nó order delivery event: "Set" é msg.orderEvent, order delivery selecionado em "Events".

2.2. Obtenção do token

Arraste o nó function (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
Cole o código do exemplo no campo "Function".
Substitua YOUR_CLIENT_ID e OUR_CLIENT_SECRET pelos seus valores.

Nó auth body: o código no campo "Function" define msg.payload com client_credentials, YOUR_CLIENT_ID, YOUR_CLIENT_SECRET e o cabeçalho 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;

Os parâmetros estão descritos na documentação da FedEx.

Arraste o nó http request (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
No campo Method, selecione "POST".
No campo Data, selecione "Send as request body".
No campo Link, cole https://apis-sandbox.fedex.com/oauth/token.
No campo Return, selecione "Object JSON".

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

Arraste o nó function (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
Cole o código do exemplo no campo "Function".

Nó set access token: o código no campo "Function" copia access_token de msg.payload para msg.access_token.

msg.access_token = msg.payload.access_token;

return msg;

2.3. Criação do envio

Arraste o nó admin-api (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
Selecione o método "Receiving all records belonging to the collection" e cole o código abaixo no campo "Data".

{
  "entityType": "orders",
  "entityId": "{{orderEvent.order.id}}",
  "langCode": "en_US",
  "offset": 0,
  "limit": 1,
  "marker": "delivery"
}

Nó find collection rows: "Type" é Receiving all records belonging to the collection; "Query parameters" contém JSON com marker delivery, entityType orders, entityId orderEvent.order.id.

Arraste o nó function (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
Cole o código do exemplo no campo "Function".

Nó shipment data: o código no campo "Function" monta os cabeçalhos com o token Bearer e os dados do destinatário a partir do registro da coleção.

// obtém o token salvo anteriormente
const token = msg.access_token;

// define os cabeçalhos
msg.headers = {
    'Content-Type': 'application/json',
    'authorization': `Bearer ${token}`
};

// obtém as coleções da etapa anterior
const collection = msg.payload.items[0];
// converte o array em um objeto
const formData = collection.formData.reduce((acc, item) => {
  acc[item.marker] = item.value;
  return acc;
}, {});
// define os dados do destinatário a partir do formulário
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
  }
}
// salva os dados da coleção em msg para uso posterior
msg.collection = collection;
// define os parâmetros da requisição para a 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;

Os parâmetros estão descritos na documentação da FedEx.

Arraste o nó http request (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
No campo Method, selecione "POST".
No campo Data, selecione "Send as request body".
No campo Link, cole https://apis-sandbox.fedex.com/ship/v1/shipments.
No campo Return, selecione "Object JSON".

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

Arraste o nó debug (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.

Nó debug debug fedex shipment: "Output" é msg.payload.

Arraste o nó function (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
Cole o código do exemplo no campo "Function".

Nó update row data: o código no campo "Function" monta o novo formData do registro da coleção com os campos transaction_id e ship_datestamp da resposta da FedEx.

// obtém os dados do envio
const shipment = msg.payload.output.transactionShipments[0];
// obtém os dados da coleção salvos anteriormente
const collection = msg.collection;

// grava os dados do envio nos atributos do formulário
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'
  }
]

// define os parâmetros para atualizar a coleção
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
}

// salva os dados da coleção para uso posterior
msg.collection = collection;

return msg;

Arraste o nó admin-api (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
Selecione o método "Changing a record in the collection".

Nó update collection row: método "Changing a record in the collection" selecionado em "Type", campo "Query parameters" vazio.

2.4. Atualização do status do pedido

Arraste o nó admin-api (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
Selecione o método "Updating the status of an order belonging to the order storage object".
Cole o código abaixo no campo "Query parameters".

{
  "id": 1,
  "orderId": "{{collection.entityId}}"
}

Cole o código abaixo no campo "Request body".

{
  "statusIdentifier": "order_delivery_started"
}

Nó order delivery started: tipo atualização do status de um pedido no armazenamento; parâmetros id e orderId, statusIdentifier no corpo.

Arraste o nó debug (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.

Nó debug debug status update 1: "Output" é msg.payload.

3. Rastreamento do status do envio

3.1. Obtenção dos pedidos a rastrear

Arraste o nó interval (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
Insira o intervalo em minutos.

Nó set interval: o campo "interval" contém 60.

Arraste o nó admin-api (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
Selecione o método "Receiving all orders belonging to the order storage object".
Cole o código abaixo no campo "Query parameters".

{
  "statusIdentifier": "order_delivery_started",
  "langCode": "en_US",
  "offset": 0,
  "limit": 100,
  "id": 1
}

Nó find orders by status: "Type" é Receiving all orders belonging to the order storage object; "Query parameters" contém JSON com statusIdentifier order_delivery_started, limit 100, id 1.

Arraste o nó function (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
Cole o código do exemplo no campo "Function".

Nó set orders: o código no campo "Function" grava msg.payload.items em msg.payload.

msg.payload = msg.payload.items;

return msg;

Arraste o nó split (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
Insira o comprimento.

Nó split: "Property" é payload, "Length" é 1.

Arraste o nó admin-api (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
Selecione o método "Receiving all records belonging to the collection".
Cole o código abaixo no campo "Query parameters".

{
  "marker": "delivery",
  "entityId": "{{payload.id}}",
  "entityType": "orders",
  "langCode": "en_US",
  "limit": 1,
  "offset": 0
}

Nó find collection rows: "Type" é Receiving all records belonging to the collection; "Query parameters" contém JSON com marker delivery, entityId payload.id, entityType orders.

Arraste o nó function (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
Cole o código do exemplo no campo "Function".

Janela "Node Information" do nó function "set row": o código no campo "Function" grava em msg.payload o primeiro elemento de msg.payload.items

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

return msg;

Arraste o nó switch (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
Adicione uma regra de verificação e selecione a condição "not empty".

Janela "Node Information" do nó "switch": propriedade "payload", modo "check all rules", condição "not empty" selecionada na regra

Arraste o nó function (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
Cole o código do exemplo no campo "Function".

Janela "Node Information" do nó function "set trackingNummber": o código no campo "Function" copia de formData o valor do campo com marcador tracking_number para msg.trackingNumber

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

msg.collection = msg.payload;

return msg;

3.2. Obtenção do token

Arraste o nó function (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
Cole o código do exemplo no campo "Function".
Substitua YOUR_CLIENT_ID e OUR_CLIENT_SECRET pelos seus valores.

Janela "Node Information" do nó function "auth body": o código no campo "Function" monta o corpo da requisição de token com grant_type, client_id e client_secret, com os placeholders YOUR_CLIENT_ID e 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;

Os parâmetros estão descritos na documentação da FedEx.

Arraste o nó http request (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
No campo Method, selecione "POST".
No campo Data, selecione "Send as request body".
No campo Link, cole https://apis-sandbox.fedex.com/oauth/token.
No campo Return, selecione "Object JSON".

Janela "Node Information" do nó http request "auth request": método "POST", "Send as request body", endereço apis-sandbox.fedex.com/oauth/token, "Return" em "Object JSON"

3.3. Obtenção do status do envio

Arraste o nó function (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
Cole o código do exemplo no campo "Function".

Janela "Node Information" do nó function "tracking data": o código no campo "Function" define o cabeçalho de autorização Bearer com o token e o corpo da requisição com 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;

Os parâmetros estão descritos na documentação da FedEx.

Arraste o nó http request (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
No campo Method, selecione "POST".
No campo Data, selecione "Send as request body".
No campo Link, cole https://apis-sandbox.fedex.com/track/v1/trackingnumbers.
No campo Return, selecione "Object JSON".

Janela "Node Information" do nó http request "tracking request": método "POST", "Send as request body", endereço apis-sandbox.fedex.com/track/v1/trackingnumbers, "Return" em "Object JSON"

Arraste o nó function (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
Cole o código do exemplo no campo "Function".

Janela "Node Information" do nó function "set tracking result": o código no campo "Function" grava em msg.payload o resultado do rastreamento obtido de msg.payload.output

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

return msg;

3.4. Atualização do status do pedido

Arraste o nó switch (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
Adicione uma regra de verificação: selecione a condição "==" e, como valor, insira "Ready for pickup".

Janela "Node Information" do nó switch "check ship status": propriedade "payload", condição "==", valor "Ready for pickup"

Arraste o nó admin-api (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.
Selecione o método "Updating the status of an order belonging to the order storage object".
Cole o código abaixo no campo "Query parameters".

{
  "id": 1,
  "orderId": "{{collection.entityId}}"
}

Cole o código abaixo no campo "Request body".

{
  "statusIdentifier": "ready_for_pickup"
}

Janela "Node Information" do nó "update status": tipo atualização do status do pedido, "Query parameters" com id e orderId, "Request body" com statusIdentifier ready_for_pickup

Arraste o nó debug (abre em uma nova aba) para o espaço de trabalho e conecte-o ao nó da etapa anterior.

Janela "Node Information" do nó debug "debug status update 2": msg.payload selecionado no campo "Output"

1. Preparação​

2. Criação do envio​

3. Rastreamento do status do envio​

1. Preparação

2. Criação do envio

3. Rastreamento do status do envio