Partner API

Partner Integration Documentation

Create delivery orders, manage contacts, calculate prices, and track shipments through the Tawasil partner API. This page exposes only the partner integration flow, not the internal Swagger documentation.

Overview

Partners use Tawasil APIs to create delivery orders and follow delivery status from their own system or partner portal.

Current version: partner accounts use the existing CLIENT role. Dedicated PARTNER_ADMIN and PARTNER_STAFF roles can be added later for multi-user partner companies.
Create ordersUse saved contacts, price calculation, and order creation APIs.
Track deliveryUse polling first, then WebSocket when real-time tracking is required.

Authentication

All protected partner APIs require a JWT access token.

POST/login
{
  "email": "partner@example.com",
  "password": "********"
}

Send the returned token in the Authorization header.

Authorization: Bearer <access_token>
POST/refresh

Use refresh when the access token expires. If refresh fails, login again.

Recommended Flow

  1. Login using POST /login.
  2. Calculate the delivery price.
  3. Create the order.
  4. List orders.
  5. Track the order.

Pricing

Calculate the delivery price before creating the order.

POST/partners/orders/pricing
{
  "vehicle_type": "motorcycle",
  "distance_km": 162.649
}

Orders

Create an order

POST/orders/

Create the order after preparing sender contact, receiver contact, vehicle type, and calculated price.

List partner orders

GET/clients/clients_get_orders

Useful query params: status_filter, page, and size.

Order details

GET/orders/{order_id}

Tracking

Polling

GET/tracking/orders/{order_id}/live

Recommended polling interval: 10 to 30 seconds while the order is active.

WebSocket

GET/tracking/ws/protocol
WS/tracking/ws?token=<jwt>
{
  "action": "subscribe",
  "channel": "order:<order_id>"
}

Dashboard

GET/clients/statistics

Optional query params: start_date, end_date.

Show total orders, orders by status, delivered orders, active orders, and date-filtered activity.

Restricted APIs

Do not show admin, manager, or driver endpoints in the partner documentation page.
POST /orders/{order_id}/assign-manual
POST /orders/{order_id}/start_of_delivery
POST /orders/{order_id}/finish_delivering
PATCH /orders/orders/{order_id}/cancel
GET /clients/getallpartner
POST /contacts/admin
GET /contacts/admin