Consuming SOAP Web Services in Node.js
Making a rate request to FedEx web service with node-soap
Let's be honest: nobody is ever thrilled to work with SOAP web services. If you are like most developers you will avoid SOAP at all costs and use JSON whenever you can. However, SOAP is often the only option for many important web services out there and you will eventually have to deal with them.
Luckily for us node.js developers, there is a module that makes calling SOAP web services much easier: node-soap. Node-soap lets you make SOAP calls to web services as well as setup your own SOAP service.
In this tutorial I will show how to make a call to a SOAP web service step-by-step. The web service I’m going to use as an example will be FedEx web service, where I will pass addresses and package details and get a rate quote in response.
Setting up the application
For simplicity, I will skip the basic steps of creating an Express server and setting up routes. So go ahead and do it the way you normally would and add node-soap to your dependencies:
npm install soap --save
Configuring the parameters of your SOAP request
Now in order to build your request you need to read the documents and the WSDL file provided by FedEx which list and explain all required and optional fields you can use in your request.
The first thing you have to worry about is the authentication. FedEx provides some information you need to include in the parameters of your call in order to make a successful request.
The authentication information required in rate requests are an API key, password, account number and meter number. So go ahead and register on their website and replace the fields in the parameters file with the information you will be given.
The other fields are either self-explanatory or thoroughly explained in the documentation. I suggest you play around and change some of them to see changes in quotes, expected delivery, etc.
After all this setting-up, our final parameters would look like this:
'WebAuthenticationDetail': {
'UserCredential': {
'Key': 'Your Key',
'Password': 'Your Password'
}
},
'ClientDetail': {
'AccountNumber': 'Your Account Number',
'MeterNumber': 'Your Meter Number'
},
'Version': {
'ServiceId': 'crs',
'Major': '20',
'Intermediate': '0',
'Minor': '0'
},
'ReturnTransitAndCommit': true,
'RequestedShipment': {
'ShipTimestamp': "2017-05-13T12:34:56-06:00",
'DropoffType': 'REGULAR_PICKUP',
'ServiceType': 'STANDARD_OVERNIGHT',
'PackagingType': 'YOUR_PACKAGING',
'TotalWeight': {
'Units': 'LB',
'Value': "10"
},
'Shipper': {
'Contact': {
'CompanyName': 'Company Name',
'PhoneNumber': '5555555555'
},
'Address': {
'StreetLines': [
'Address Line 1'
],
'City': 'Collierville',
'StateOrProvinceCode': 'TN',
'PostalCode': '38017',
'CountryCode': 'US'
}
},
'Recipient': {
'Contact': {
'PersonName': 'Recipient Name',
'PhoneNumber': '5555555555'
},
'Address': {
'StreetLines': [
'Address Line 1'
],
'City': 'Charlotte',
'StateOrProvinceCode': 'NC',
'PostalCode': '28202',
'CountryCode': 'US'
}
},
'ShippingChargesPayment': {
'PaymentType': 'SENDER',
'Payor': {
'ResponsibleParty': {
'AccountNumber': 'Your Account Number'
}
}
},
'RateRequestTypes': 'LIST',
'PackageCount': '1',
'RequestedPackageLineItems': {
/*SequenceNumber: 1,
GroupNumber: 1,*/
'GroupPackageCount': 1,
'Weight': {
'Units': 'LB',
'Value': "10"
},
'Dimensions': {
'Length': "4",
'Width': "6",
'Height': "10",
'Units': "IN"
}
}
}
Making a request with node-soap
Now we have finally arrived to the fun part of this tutorial: using node-soap to make a request.
First, require the path module and node-soap in your server:
var path = require(‘path’);
var soap = require('soap');
Then, add the path to the wsdl file hosted locally.
var url = path.join(__dirname, 'wsdl', 'RateService_v20.wsdl');
Creating a node-soap client
The soap client is created with soap.createClient. Note that you have to pass the url to the WSDL file here.
soap.createClient(url, function(err, client) {
// Execute methods on the soap service here
});
Using client.describe()
Inside the creatClient method, use client.describe() to get a description of services, ports and methods for the service.
soap.createClient(url, function(err, client) {
res.send(client.describe());
});
// returns:
{
"RateService": {
"RateServicePort": {
"getRates": {
"Input": {
//Input format
}
}
}
}
Calling a method on the web service
With this information in hand, we can now send our requesting calling the service, port and method specified:
client.RateService.RateServicePort.getRates(params, function(err, result) {
res.json(result);
});
Alternativelly, we can call the method without specifying the service and port
client.getRates(params, function(err, result) {
res.json(result);
});
Response
Either one of the two methods above will return the following response:
{
"HighestSeverity": "SUCCESS",
"Notifications": [
{
"Severity": "SUCCESS",
"Source": "crs",
"Code": "0",
"Message": "Request was successfully processed.",
"LocalizedMessage": "Request was successfully processed."
}
],
"Version": {
"ServiceId": "crs",
"Major": 20,
"Intermediate": 0,
"Minor": 0
},
"RateReplyDetails": [
{
"ServiceType": "STANDARD_OVERNIGHT",
"PackagingType": "YOUR_PACKAGING",
"DeliveryStation": "QWGA",
"DeliveryDayOfWeek": "MON",
"DeliveryTimestamp": "2017-05-15T15:00:00.000Z",
"CommitDetails": [
{
"ServiceType": "STANDARD_OVERNIGHT",
"CommitTimestamp": "2017-05-15T15:00:00.000Z",
"DayOfWeek": "MON",
"DestinationServiceArea": "A1",
"BrokerToDestinationDays": "0",
"DocumentContent": "NON_DOCUMENTS"
}
],
"DestinationAirportId": "CLT",
"IneligibleForMoneyBackGuarantee": false,
"OriginServiceArea": "A2",
"DestinationServiceArea": "A1",
"SignatureOption": "SERVICE_DEFAULT",
"ActualRateType": "PAYOR_ACCOUNT_PACKAGE",
"RatedShipmentDetails": [
{
"EffectiveNetDiscount": {
"Currency": "USD",
"Amount": "0.0"
},
"ShipmentRateDetail": {
"RateType": "PAYOR_ACCOUNT_PACKAGE",
"RateScale": "1327",
"RateZone": "04",
"PricingCode": "PACKAGE",
"RatedWeightMethod": "ACTUAL",
"DimDivisor": "194",
"FuelSurchargePercent": "3.25",
"TotalBillingWeight": {
"Units": "LB",
"Value": "10.0"
},
"TotalBaseCharge": {
"Currency": "USD",
"Amount": "92.73"
},
"TotalFreightDiscounts": {
"Currency": "USD",
"Amount": "0.0"
},
"TotalNetFreight": {
"Currency": "USD",
"Amount": "92.73"
},
"TotalSurcharges": {
"Currency": "USD",
"Amount": "19.53"
},
"TotalNetFedExCharge": {
"Currency": "USD",
"Amount": "112.26"
},
"TotalTaxes": {
"Currency": "USD",
"Amount": "0.0"
},
"TotalNetCharge": {
"Currency": "USD",
"Amount": "112.26"
},
"TotalRebates": {
"Currency": "USD",
"Amount": "0.0"
},
"TotalDutiesAndTaxes": {
"Currency": "USD",
"Amount": "0.0"
},
"TotalNetChargeWithDutiesAndTaxes": {
"Currency": "USD",
"Amount": "112.26"
},
"Surcharges": [
{
"SurchargeType": "SATURDAY_PICKUP",
"Description": "Saturday pickup",
"Amount": {
"Currency": "USD",
"Amount": "16.0"
}
},
{
"SurchargeType": "FUEL",
"Description": "Fuel",
"Amount": {
"Currency": "USD",
"Amount": "3.53"
}
}
]
},
"RatedPackages": [
{
"GroupNumber": "0",
"EffectiveNetDiscount": {
"Currency": "USD",
"Amount": "0.0"
},
"PackageRateDetail": {
"RateType": "PAYOR_ACCOUNT_PACKAGE",
"RatedWeightMethod": "ACTUAL",
"BillingWeight": {
"Units": "LB",
"Value": "10.0"
},
"BaseCharge": {
"Currency": "USD",
"Amount": "92.73"
},
"TotalFreightDiscounts": {
"Currency": "USD",
"Amount": "0.0"
},
"NetFreight": {
"Currency": "USD",
"Amount": "92.73"
},
"TotalSurcharges": {
"Currency": "USD",
"Amount": "19.53"
},
"NetFedExCharge": {
"Currency": "USD",
"Amount": "112.26"
},
"TotalTaxes": {
"Currency": "USD",
"Amount": "0.0"
},
"NetCharge": {
"Currency": "USD",
"Amount": "112.26"
},
"TotalRebates": {
"Currency": "USD",
"Amount": "0.0"
},
"Surcharges": [
{
"SurchargeType": "SATURDAY_PICKUP",
"Description": "Saturday pickup",
"Amount": {
"Currency": "USD",
"Amount": "16.0"
}
},
{
"SurchargeType": "FUEL",
"Description": "Fuel",
"Amount": {
"Currency": "USD",
"Amount": "3.53"
}
}
]
}
}
]
},
{
"ShipmentRateDetail": {
"RateType": "PAYOR_LIST_PACKAGE",
"RateScale": "1327",
"RateZone": "04",
"PricingCode": "PACKAGE",
"RatedWeightMethod": "ACTUAL",
"DimDivisor": "139",
"FuelSurchargePercent": "3.25",
"TotalBillingWeight": {
"Units": "LB",
"Value": "10.0"
},
"TotalBaseCharge": {
"Currency": "USD",
"Amount": "92.73"
},
"TotalFreightDiscounts": {
"Currency": "USD",
"Amount": "0.0"
},
"TotalNetFreight": {
"Currency": "USD",
"Amount": "92.73"
},
"TotalSurcharges": {
"Currency": "USD",
"Amount": "19.53"
},
"TotalNetFedExCharge": {
"Currency": "USD",
"Amount": "112.26"
},
"TotalTaxes": {
"Currency": "USD",
"Amount": "0.0"
},
"TotalNetCharge": {
"Currency": "USD",
"Amount": "112.26"
},
"TotalRebates": {
"Currency": "USD",
"Amount": "0.0"
},
"TotalDutiesAndTaxes": {
"Currency": "USD",
"Amount": "0.0"
},
"TotalNetChargeWithDutiesAndTaxes": {
"Currency": "USD",
"Amount": "112.26"
},
"Surcharges": [
{
"SurchargeType": "SATURDAY_PICKUP",
"Description": "Saturday pickup",
"Amount": {
"Currency": "USD",
"Amount": "16.0"
}
},
{
"SurchargeType": "FUEL",
"Description": "Fuel",
"Amount": {
"Currency": "USD",
"Amount": "3.53"
}
}
]
},
"RatedPackages": [
{
"GroupNumber": "0",
"PackageRateDetail": {
"RateType": "PAYOR_LIST_PACKAGE",
"RatedWeightMethod": "ACTUAL",
"BillingWeight": {
"Units": "LB",
"Value": "10.0"
},
"BaseCharge": {
"Currency": "USD",
"Amount": "92.73"
},
"TotalFreightDiscounts": {
"Currency": "USD",
"Amount": "0.0"
},
"NetFreight": {
"Currency": "USD",
"Amount": "92.73"
},
"TotalSurcharges": {
"Currency": "USD",
"Amount": "19.53"
},
"NetFedExCharge": {
"Currency": "USD",
"Amount": "112.26"
},
"TotalTaxes": {
"Currency": "USD",
"Amount": "0.0"
},
"NetCharge": {
"Currency": "USD",
"Amount": "112.26"
},
"TotalRebates": {
"Currency": "USD",
"Amount": "0.0"
},
"Surcharges": [
{
"SurchargeType": "SATURDAY_PICKUP",
"Description": "Saturday pickup",
"Amount": {
"Currency": "USD",
"Amount": "16.0"
}
},
{
"SurchargeType": "FUEL",
"Description": "Fuel",
"Amount": {
"Currency": "USD",
"Amount": "3.53"
}
}
]
}
}
]
}
]
}
]
}
Final considerations
Pay attention to your parameters because that’s where most errors are originated.
The source code for this tutorial is available on GitHub in this repository. To run it locally you just have to clone it and replace the authentication fields with the information provided by fedex.