sLocker
The SDK for Superroute smart lockers: for carriers that deliver to them and for customer apps
sLocker is the SDK for Superroute smart lockers. Its carrier side serves carriers and delivery partners that put parcels into the lockers, with a mock cabinet that runs the whole flow without hardware. Its customer side serves apps and websites whose people collect parcels, store bags, buy from cabinets and hand items over at the lockers.
Version 0.2.1. Every package of a release has the same version and the same operations. 40 operations of the partner locker delivery API, each a method in every language. 38 smart-locker operations of the partner app API for customer apps.
Two sides
Carrier side
For carriers and delivery partners: delivery tasks, opening the doors for the driver, confirming the deposit, following the pickup and verifying the webhooks. It signs in with a Superroute API account and does not use sApp.
Customer side
For apps and websites of a service provider's customers: pickups, locker locations, locker storage, the locker shop and second-hand handover. It is built on the sApp core and signs people in the same way as sApp.
Installation
The sLocker packages for nine languages and the first call in each.
Authentication
The API account, its token and the provider each call acts for.
Sandbox
A mock cabinet runs the same steps as a real cabinet without hardware.
A deposit, end to end
From the delivery task to the pickup by the recipient.
Webhooks
Verifying the events Superroute sends about deposits and pickups.
Delivery API reference
The partner locker delivery API that the carrier side calls, read only.
Customer apps
The smart-locker operations for apps and websites of a service provider's customers.
UI kit
The pickup list and the locker map on seven platforms, inside the sApp UI kit.
Customer API reference
The smart-locker operations of the partner app API that the customer side calls.
What the carrier side covers
Delivery tasks
Create a task with an idempotency key, list, read and cancel tasks, and replace a code.
At the cabinet
Open the doors with the delivery code, confirm all or part of a deposit, abort, move a package to another compartment, cancel the placement, reopen after the confirmation and open for pickup.
Scopes and locations
Read the grants and sub-scopes, create, update or disable a sub-scope, and list the locations of a scope or near an address or a point.
Usage
A summary, daily figures and figures by location.
Carriers
The carrier profile, intake locations and receiving warehouses, pre-advice of packages, the carrier packages, cancelling, rerouting and resetting a pickup code.
Mock cabinet
Create and delete mock cabinets, force doors open or closed, take a cabinet offline, change its features and compartment sizes, and seed, clear or take parcels.
What the customer side covers
Pickups
Parcels waiting in lockers with their pickup codes: collect and open the door, hand a pickup to another person and take it back.
Locker locations
The service provider's locker locations, directions to the lockers inside a building, and the person's preferred locations.
Locker storage
Bags stored in lockers: add one by its code, keep it, change the return time, collect it at another cabinet, or have it delivered or shipped.
Locker shop
Buying from locker cabinets: the catalogue of a location, orders, opening the next door and asking for a refund; for merchant staff, the items in cells and staff codes.
Second-hand handover
A seller and a buyer hand an item over through a locker: the terms, opening a handover, sending and revoking the pickup code, calling it off and reporting a problem.
Languages
Carrier side: Python, PHP, Java, Go, C# and JavaScript / TypeScript on the server; Kotlin (Android), Swift (iOS and macOS) and Dart (Flutter) in apps.
- Python
- PHP
- Java
- Go
- C# / .NET
- JavaScript / TypeScript
- Kotlin / Android
- Swift (iOS, macOS)
- Dart / Flutter
Customer side: JavaScript and TypeScript, Dart, Swift, Kotlin, Java, C#, Python, PHP and Go, with UI kits for Flutter, the web, React, React Native, SwiftUI, Jetpack Compose, WPF and WinForms.
License: Superroute SDK License
Errors and retries
Every failed call raises one error type with the HTTP status, the stable error code of the server, its message, the field errors and the wait the server asked for. Act on the status and the code, never on the message.
Only repeatable calls are retried: reads, deletes and the two create calls that carry an idempotency key. Opening doors, confirming and every other change are never repeated by the SDK. After a timeout, read the task before the next step.
Getting started on the carrier side
- Ask Superroute for an API account and a third-party delivery provider with smart locker delivery switched on.
- Install the package for your language.
- Create a mock cabinet and run a deposit end to end.
- Add a webhook endpoint and verify every event.
- Create tasks without mock to deliver to real cabinets.
Getting started on the customer side
- Register the app under Open Platform → Apps with the locker capabilities it needs, and submit it for review.
- Request access to a service provider, which approves it under My Apps → Developers and switches the capabilities on.
- Install the sLocker package of your language.
- Sign the person in, with sLocker alone or with the sign-in of your sApp client.