This project contains an UNOFFICIAL library to use the Poste Italiane Delivery Express API.
In order to use this library, you need a Poste Delivery Business contract with Poste Italiane.
This library supports .Net 6 and .Net 7.
You can hook the MLPosteDeliveryExpress.Options.VerboseOutput` event, for example:
MLPosteDeliveryExpress.Options.VerboseOutput += (object sender, MLPosteDeliveryExpress.Service.Message message) =>
{
System.Console.WriteLine(message.Data);
};
If you need to configure the HTTP Client (for instance because you need to set up a proxy), you can use some code like this:
MLPosteDeliveryExpress.Options.HttpClientInitialization += (object sender, System.Net.Http.HttpClient client) =>
{
// Configure the client here
};
You'll need the API credentials and the code of the Cost Center (it's something like CDC-...
).
In order to get these details you need to go to https://www.mypostedeliverybusiness.it/offertaunica/
Create a MLPosteDeliveryExpress.Account
instance with these details.
You can also use the account MLPosteDeliveryExpress.Account.Sandbox: in this case, the library will use the sandbox API servers (that is, a test environment).
Poste Delivery Business uses custom codes for countries (they call it ISO4
).
For example, Italy has one ISO4 code (ITA1
), whereas Germany has 3 ISO4 codes (GER1
for Germany, GER2
for Heligoland, GER3
for Busingen).
You can fetch the list of all the countries with some code like this:
var countries = (await MLPosteDeliveryExpress.Country.Fetcher.FetchAsync(account)).Countries;
For international shipments, you may need to describe the type of the product being shipped.
In order to do that, you must use a taric
code.
You can fetch all the taric codes, as well as their Italian and English descriptions, with some code like this:
var tarics = (await MLPosteDeliveryExpress.Taric.Fetcher.FetchAsync(account)).Tarics;
In order to print the labels to be applied to the packages to be shipped, you may use some code like this:
var waybill = new MLPosteDeliveryExpress.Waybill.Request.Waybill()
{
ClientReferenceId = "12312312341",
Product = MLPosteDeliveryExpress.AptusCode.PosteDeliveryBusinessExpress,
PrintFormat = MLPosteDeliveryExpress.Waybill.PrintFormat.PDF_A4,
Data = new()
{
Content = "contenuto",
Sender = new()
{
FirstLastName = "Mario Rossi",
Street = "Viale Europa",
StreetNumber = "192",
ZipCode = "00142",
City = "ROMA",
StateOrProvince = "RM",
CountryISO4 = "ITA1",
CountryName = "Italia",
Email = "[email protected]",
Phone = "37747383787287",
Notes1 = "sender note 1",
Notes2 = "sender note 2",
},
Receiver = new()
{
FirstLastName = "Ditta test",
ContactName = "Aldo Bianchi",
ZipCode = "80010",
Street = "VIALE DEL TRAMONTO 10",
StreetNumber = "27",
City = "NAPOLI",
StateOrProvince = "RM",
CountryISO4 = "ITA1",
CountryName = "Italia",
Email = "[email protected]",
Phone = "11111111111",
Notes1 = "note spedizione 1",
Notes2 = "note spedizione 2",
}
}
};
waybill.Data.Declared.Add(new()
{
Width = 25,
Height = 10,
Length = 10,
Weight = 10,
});
var request = new MLPosteDeliveryExpress.Waybill.Request.Container
{
CostCenterCode = MLPosteDeliveryExpress.Options.Sandbox ? MLPosteDeliveryExpress.Account.SANDBOX_COST_CENTER_CODE : account.CostCenterCode,
ShipmentDate = new DateTime(2020, 11, 26, 09, 2, 20, 986),
};
request.Waybills.Add(waybill);
var createdWaybill = (await MLPosteDeliveryExpress.Waybill.Creator.CreateAsync(account, request)).Waybills[0];
You can then fetch and save the waybill to a file with some code like this:
using var stream = await MLPosteDeliveryExpress.Waybill.Downloader.DownloadAsync(createdWaybill);
using var fileStream = System.IO.File.Create(@"C:\waybill.pdf");
stream.CopyTo(fileStream);
If you need to send multiple packages at once, you have to:
waybill.Data.Declared
list:
waybill.Data.Declared.Add(new()
{
Width = 25,
Height = 10,
Length = 10,
Weight = 10,
});
waybill.Data.Declared.Add(new()
{
Width = 50,
Height = 60,
Length = 70,
Weight = 80,
});
waybill.Data.Services.Add(new MLPosteDeliveryExpress.Waybill.Services.MultiPack());
CreateAsync
method, you'll have a waybill instance for every package you declared.Once you generated a waybill, you can book a pickup with some code like this:
var pickupRequest = new MLPosteDeliveryExpress.PickupBooking.Request.Pickup()
{
Operation = MLPosteDeliveryExpress.PickupBooking.Operation.Insert,
BookingType = MLPosteDeliveryExpress.PickupBooking.BookingType.Single,
ShipmentId = createdWaybill.Code,
Where = new()
{
Address = new()
{
FirstName = "Henrietta Hill",
LastName = "Gene Bowen",
StreetName = "via colonnelle",
StreetNumber = "4",
ZipCode = "00073",
City = "Castel Gandolfo",
StateOrProvince = "RM",
Country = "IT",
},
},
};
var bookingID = await MLPosteDeliveryExpress.PickupBooking.Submitter.SubmitAsync(account, pickupRequest);
You can also book a multiple pick-up, not associated to a specific waybill.
In this case, you can leave the ShipmentId
field empty, and set the BookingType
field to MLPosteDeliveryExpress.PickupBooking.BookingType.Multiple
.
You can retrieve the list of pick-up bookins with some code like this:
var filter = new MLPosteDeliveryExpress.PickupBooking.Request.Filter()
{
DateFrom: System.DateOnly.FromDateTime(System.DateTime.Today),
};
var pickupBookings = await MLPosteDeliveryExpress.PickupBooking.Finder(account, filter);
If you want to track the package identified by its waybill code, you can use some code like this:
var (tracking, messages) = await MLPosteDeliveryExpress.Tracking.Tracker.TrackAsync(account, createdWayBill.Code);
Where:
tracking
will contain the tracking datamessages
will contain any messages returned by the tracking look-upIt's possible to fetch the list of packages that failed to be delivered to the recipients:
var deposits = await MLPosteDeliveryExpress.Deposit.FindAsync(account, new() {
DepisitDateFrom = System.DateOnly.FromDateTime(System.DateTime.Today.AddDays(-5)),
DepisitDateTo = System.DateOnly.FromDateTime(System.DateTime.Today),
});
For each deposit, you can take an action:
await MLPosteDeliveryExpress.Deposit.Decisor.TakeActionAsync(
account,
deposit.ShipmentID,
MLPosteDeliveryExpress.Deposit.Action.RetryDelivery
);