Authentication

The API account, its token and the provider each call acts for.

The token

The API takes the bearer token of a Superroute API account. The token comes from POST /api/v1/user/login and is valid for one week. Pass a token you already have, or sign in with the client, which keeps the token for the following calls.

// JavaScript / TypeScript
import { SLockerClient } from '@superrouteca/slocker';

const sl = new SLockerClient({ providerId: 4611 });          // or new SLockerClient({ token, providerId: 4611 })
await sl.login({ email: 'api-partner@example.com', password: process.env.SR_PASSWORD });
await sl.refreshToken();
await sl.rotateToken({ gracePeriodMinutes: 60 });
await sl.logout();

# Python
from slocker import SLockerClient

sl = SLockerClient(provider_id=4611)
sl.login('api-partner@example.com', password)

// PHP
$sl = new \Superroute\SLocker\Client(providerId: 4611);
$sl->login('api-partner@example.com', $password);

// Go
sl := slocker.New(slocker.Config{ProviderID: 4611})
_, err := sl.Login(ctx, "api-partner@example.com", password, 0)

curl -X POST 'https://api.superroute.ca/api/v1/user/login' \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  -d '{ "email": "api-partner@example.com", "password": "…" }'
# then, on every call:
#   Authorization: Bearer <token>
#   X-Third-Party-Provider-Id: 4611

Refresh the token before it expires, rotate it with a grace period during which the old token still works, or sign out when the token may have leaked.

Drivers need no Superroute account. Each task has the code the driver enters at the cabinet.

The provider

providerId is your third-party delivery provider, sent in the X-Third-Party-Provider-Id header. It may be left out when the account acts for exactly one provider. Any call can name another provider in its parameters.

// the provider of the client, or another one for one call
await sl.api.partnerLockerDeliveries({ status: 'delivered', providerId: 4612 });

A provider the account cannot access answers 403 LOCKER_PERMISSION_DENIED.

Permissions

Superroute switches on smart locker delivery, code generation and scope management for the provider. A call the provider is not allowed answers 403 LOCKER_PERMISSION_DENIED or LOCKER_ACCESS_DISABLED.

Rate limit

All partner locker calls of one account share a limit of 60 calls per minute. A call over the limit answers 429 LOCKER_RATE_LIMITED with Retry-After, and the SDK waits that long before a retry.