Practical tutorial · Step by step
Create UPS Shipping Labels with Azure Functions and C#
1. What happens when a shipping label is created?
A label results from a shipment operation with the carrier. An ERP sends sender, recipient, package details and the selected service to an API. Success may return tracking information and label content. Creating a shipment can incur charges, so repeating the request indiscriminately is unsafe.
2. Integration architecture
Business Central creates a shipping job. A protected .NET Azure Function validates input, obtains UPS authorization server-side and invokes the UPS Shipping API. It checks the response and returns tracking details and printable labels. A persistent job log tracks each operation.
3. Prerequisites
Prepare a UPS developer account, the current UPS API specifications and suitable test credentials. Confirm available services, countries, dimensions, units and label formats. Create an Azure Function in the isolated worker model and a secure test client.
4. Keep access tokens out of request data
Avoid passing a UPS access token as a regular field in client JSON. The Function should own its secure OAuth configuration and obtain tokens when needed. Separately authenticate Business Central to the Function and enforce appropriate permissions. Never log secrets or embed them in source code.
5. Define an explicit request contract
The sample JSON below illustrates the business fields. Convert it to the shipping-provider payload using the current version of the API specification.
{
"shipmentId": "SHIP-10042",
"service": "STANDARD",
"shipTo": {
"name": "Sample Recipient",
"country": "DE",
"postalCode": "10115"
},
"package": { "weightKg": 2.5 }
}6. Validate before booking
Check addresses, country codes, package weights, dimensions and permissible shipping services. Reject incomplete or invalid input early using meaningful error responses. This minimizes unnecessary carrier calls and failed transactions.
7. Do not silently substitute a shipping service
Express and standard shipping differ in price and commitments. A shipping service should not be replaced without an explicit business policy or user authorization. Parse structured carrier error codes instead of looking for arbitrary words in the response body.
8. Interpreting ZPL and labels
ZPL is a printer command language used by compatible thermal printers. Verify whether the carrier returns actual ZPL or encoded images or PDFs. Decode only supported content and test on the intended printer. Store the tracking identity and the label reference.
9. Idempotency and uncertain outcomes
A timeout does not prove that UPS failed to create a shipment. Persist a unique internal shipment operation ID. Before a retry, check whether an existing shipment can be resolved using the carrier’s supported reference or status features. Reusing your own request data does not guarantee deduplication by the carrier.
10. Monitoring and error handling
Record shipment ID, carrier references, tracking, state and safe error details. Distinguish bad addresses, unauthorized requests, invalid services, throttling and temporary server errors. Do not respond HTTP 200 while concealing a failure in an error property.
11. Test scenarios
Test domestic and international addresses, package constraints, different services, malformed inputs, interrupted requests and duplicate requests. Use the published test environment instead of accidentally creating production shipments. Include cancellation and reversal scenarios where available.
12. Conclusion
A safe shipping integration separates business logic, carrier authentication, shipment creation and label printing. Production payloads and service codes must be checked against the current UPS documentation.
Discussion (0)
No comments yet. Be the first to contribute.