Access Locker#

This is a sequence of api calls to do a complete delivery.
To integrate into a sandbox environment our base url will be: https://api.sandbox.harborlockers.com
To integrate into a production environment it will be: https://api.harborlockers.com

Tip

This Url will be referred to as {api_url} on the rest of this page. Don’t send any requests without replacing any variables in curly brackets {} with actual data

For information about locker statuses, see Locker Statuses.

Finding lockers in your tower#

In order to find what lockers are in the tower:

curl -X 'GET' \
'{api_url}/api/v1/towers/{tower_id}/lockers' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {access_token}'

Keep in mind this request will return ALL lockers and not just the available ones. So you will need some kind of filtering in your app to not show the unavailable ones to the cutomer.

[{"id":959,"name":"14","isLowLocker":false,"towerId":{tower_id},"status":{"name":"available","id":1},"type":{"name":"small","description":null,"id":1},"accessMode":"public"},

In order to access this locker you will need to use the first “id” and not the “name” In this case it is: 959.

Reserving a locker#

After finding the ID of the locker you want you can reserve the locker and give the user time to reach the location, let’s say 5 minutes.

# from the list, we select a locker_id and tower_id and make a reservation for 300 sec (5�min)
# Json request body => {'duration':300}. Number of seconds for the reservation
POST {api_url}/api/v1/towers/{tower_id}/lockers/{locker_id}/reservations

Now we want to give the user the key to open the locker. Here’s an example.

In your requests ‘client_info’ should be an empty string.

  // requests encrypted tokens to open target locker
  export async function createDropOffToken(towerId, lockerId, bearerToken) {
      try {
      const createDropOffEndpoint = `{api_url}${towerId}/lockers/${lockerId}/dropoff-locker-tokens`;
      const requestOptionsAuth = {
      headers: {
          'Content-Type': 'application/json',
          Accept: 'application/json',
          Authorization: `Bearer ${access token}`,
    },
  };
  const requestBody = {client_info: '', duration: 3000};
  const response = await axiOS.post(
    createDropOffEndpoint,
    requestBody,
    requestOptionsAuth,
  );
  return {
    payload_auth: response.data.payload_auth,
    payload: response.data.payload,
  };
} catch (error) {
  throw error;
}
  }

Warning

Don’t exaggerate your token request, the locker will be in your possession until the token expires.

This function returns payload_auth and payload You will need these to open a reserved locker.

The locker opens and then the user puts the item inside and closes the locker.

Now the locker state is ‘occupied’ and will be in your possession until someone picks up the item.

Tip

You can always check all lockers that are available to you as a build partner with: GET {api_url}/api/v1/users/me/assigned-lockers

Picking up the item#

Now the same or another user wants to pick up the item. Here are a couple of examples on how to do this. Use the payload and payload_auth from creating the drop off token to open the locker.

HarborLockersSDK.sendOpenLockerWithTokenCommand(
    payload,
    payload_auth
);

func sendOpenLockerWithTokenCommand(_ payload: String, payloadAuth: String) throws {
        guard let payloadAuthData = Data(hexString: payloadAuth),
        let payloadData = Data(hexString: payload) else {
        throw TestingError.init(.genericError,  message: "Open locker failed")
    }

    HarborSDK.shared.sendOpenLockerWithToken(payload: payloadData, payloadAuth: payloadAuthData) { lockerId, error in
        if let error = error {
            print("Error sending token: \(error)")
        } else {
            print("Locker opened with ID: \(lockerId)")
        }
    }
}

fun sendOpenLockerWithTokenCommand(payload: String, payloadAuth: String) {
    val payloadAuthData = payloadAuth.hexStringToByteArray()
    val payloadData = payload.hexStringToByteArray()

    if (payloadAuthData == null || payloadData == null) {
        throw TestingError(GenericError, "Open locker failed")
    }

HarborSDK.shared.sendOpenLockerWithToken(payload = payloadData, payloadAuth = payloadAuthData) { lockerId, error -> error?.let {
    println("Error sending token: $error")
} ?: run {
    println("Locker opened with ID: $lockerId")
        }
    }
}

The locker opens, the user removes the item and closes the locker.

Once the locker is closed, the locker will return to the Available state.

You can find information about debug logging and other tools to interact with lockers in SDK_tools

If anything has gone wrong in the test environment, you can use Harbor Console

If nothing has gone wrong: Congratulations! You have just made your first delivery!