Skip to content

Quickstart

This walkthrough uses a test key. In test mode a simulated partner carries the Shipment, nobody is billed, and no real partner sees it.

You need a tjy_test_ key from Tujyane. Put it in an environment variable:

Terminal window
export TUJYANE_API_KEY=tjy_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
export TUJYANE=https://api.tujyaneltd.com/api/v1/delivery-api

Every request below sends the key as a bearer token. Requests with a body also send Content-Type: application/json. Without that header, Tujyane ignores the body.

Terminal window
curl "$TUJYANE/client" -H "Authorization: Bearer $TUJYANE_API_KEY"
{
"id": "3f2c9a1e-5b7d-4c8e-9f10-2a3b4c5d6e7f",
"name": "Your business",
"mode": "TEST",
"webhookUrl": "https://api.example.com/tujyane/webhooks"
}

If webhookUrl is set, send yourself a test webhook:

Terminal window
curl -X POST "$TUJYANE/webhooks/test" -H "Authorization: Bearer $TUJYANE_API_KEY"

The answer { "delivered": true, "statusCode": 200, "error": null } means your receiver answered. To set or change the URL, ask your Tujyane contact.

Terminal window
curl -X POST "$TUJYANE/quote" \
-H "Authorization: Bearer $TUJYANE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"pickup": { "lat": -1.9367, "lng": 30.0866 },
"dropoff": { "lat": -1.9496, "lng": 30.1266 },
"sizeClass": "SMALL"
}'

The answer has the fee that a Shipment created now would cost, and the returnFee added if the parcel comes back.

Terminal window
curl -X POST "$TUJYANE/shipments" \
-H "Authorization: Bearer $TUJYANE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"reference": "IH-20481",
"pickup": {
"name": "Kacyiru Pharmacy",
"phone": "0788123456",
"addressText": "KG 7 Ave 14, Kacyiru",
"lat": -1.9367,
"lng": 30.0866
},
"recipient": {
"name": "Aline Uwase",
"phone": "0788654321",
"addressText": "KG 11 Ave 24, Kimironko",
"notes": "Blue gate. Call on arrival.",
"lat": -1.9496,
"lng": 30.1266
}
}'

The answer is the Shipment object with status AWAITING_CONFIRMATION. Keep its id. If your account uses Delivery Codes, it also has the deliveryCode for your customer.

Confirm when your customer has paid you. Tujyane then looks for a partner.

Terminal window
curl -X POST "$TUJYANE/shipments/<id>/confirm" \
-H "Authorization: Bearer $TUJYANE_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"

Within about a minute, the simulated partner accepts, collects the parcel and delivers it. Your webhook receives each step: shipment.searching, shipment.assigned, shipment.picked_up, and finally shipment.delivered.

To read the Shipment at any time:

Terminal window
curl "$TUJYANE/shipments/<id>" -H "Authorization: Bearer $TUJYANE_API_KEY"

To see the partner move on a map, open the event stream.

  • Try a failed delivery: put refused in the reference, for example IH-20482-refused. See Test mode.
  • Verify webhook signatures before you trust them. See Webhooks.
  • Work through the Go-live checklist before you ask for a live key.