API Documentation - Courier Pickup Tasks

Overview

API untuk mengelola pickup tasks oleh kurir. Kurir dapat memulai, scan shipment, dan menyelesaikan pickup tasks.

Base URL

GET/PATCH /v1/courier/pickup-tasks

Authentication

Required: Bearer Token (JWT)

Endpoints

1. Update Pickup Task Status

Endpoint: PATCH /v1/courier/pickup-tasks/:taskId/status

Description: Update status pickup task oleh kurir

Request:

Available Actions:

a. START_PICKUP

Memulai pickup task dari status ASSIGNED ke PICKUP_IN_PROGRESS

Request:

{
  "action": "START_PICKUP"
}

Response:

{
  "success": true,
  "data": {
    "task": {
      "id": "1d9deddb-1ac2-40be-b124-96d661511f01",
      "previousStatus": "ASSIGNED",
      "newStatus": "PICKUP_IN_PROGRESS",
      "startedAt": "2025-10-28T07:49:05.931Z"
    },
    "action": "START_PICKUP",
    "currentLocation": {
      "vendor": "Toko ABC",
      "address": "Jl. Merdeka No. 123"
    },
    "nextActions": [
      "SCAN_SHIPMENT",
      "COMPLETE_PICKUP",
      "CANCEL_PICKUP",
      "FAIL_PICKUP"
    ]
  },
  "message": "Berhasil memulai pickup task"
}

b. SCAN_SHIPMENT

Scan tracking number untuk menandai shipment sebagai picked up

Request:

{
  "action": "SCAN_SHIPMENT",
  "trackingNumber": "BL20251027956449"
}

Response:

{
  "success": true,
  "data": {
    "scanResult": {
      "trackingNumber": "BL20251027956449",
      "productName": "Produk A",
      "quantity": 2,
      "status": "PICKED_UP"
    },
    "progress": {
      "pickedUp": 3,
      "total": 5,
      "percentage": 60
    },
    "taskStatus": "PICKUP_IN_PROGRESS",
    "action": "SCAN_SHIPMENT",
    "nextAction": "CONTINUE_SCAN"
  },
  "message": "Item berhasil di-scan"
}

Prerequisites

Authentication: User harus login sebagai kurir

Task Ownership: Kurir hanya bisa mengupdate task yang di-assign ke mereka

Valid Status Transition: Action harus sesuai dengan status current task

Example Usage Flow

Get assigned tasks → GET /v1/courier/pickup-tasks?status=active

Start pickup → PATCH /tasks/{id}/status with START_PICKUP

Scan shipments → PATCH /tasks/{id}/status with SCAN_SHIPMENT + trackingNumber

Notes

Tracking number format: BLYYYYMMDDXXXXX

Progress percentage calculated automatically

All timestamps in ISO 8601 format

Transaction ensures data consistency during updates

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location --request PATCH 'https://v1.dev.bukalombok.com/v1/courier/pickup/b0af15f9-956a-4762-88bb-5cc3c3858bc0/status' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "action": "SCAN_SHIPMENT", "trackingNumber": "BL20251028179182" }'

{ "meta": { "success": true, "status": 200, "message": "Success" }, "data": { "id": "8uCD_rwTYAQ7jE3APOjU8", "courier_id": "8e02c4f0-6733-910e-4426-5878eb5bb923", "shipping_center_id": "7dd9aaf7-1156-5450-d69d-cdf6fc8ea179", "pickup_status": "item_picked_up", "pickup_date": "2025-08-07T02:21:51.263Z", "created_at": "2025-08-07T16:02:27.840Z", "order_shipments": [ { "id": "VzfktKwsmsS6hal0t5XMV", "status": "item_picked_up", "order_id": "84069c40-e2ae-3604-793f-585d6ac4d584", "product_name": "Refined Concrete Pants", "variant_name": "Dr. Sheldon Connelly-Dibbert", "shipped_at": "2025-08-07T11:19:15.430Z", "delivered_at": "2025-08-07T21:03:49.628Z" }, { "id": "VzfktKwsmsS6hal0t5XMV", "status": "item_picked_up", "order_id": "e873cc0c-db01-4711-092d-74a880041d58", "product_name": "Gorgeous Steel Pants", "variant_name": "Ed Ratke", "shipped_at": "2025-08-07T03:40:31.936Z", "delivered_at": "2025-08-07T07:28:06.238Z" } ] } }

Update status order Couriers Pickup

API Documentation - Courier Pickup Tasks

Overview

Base URL

Authentication

Endpoints

1. Update Pickup Task Status

Available Actions:

a. START_PICKUP

b. SCAN_SHIPMENT

Prerequisites

Example Usage Flow

Notes

Request

Responses

Update status order Couriers Pickup

API Documentation - Courier Pickup Tasks#

Overview#

Base URL#

Authentication#

Endpoints#

1. Update Pickup Task Status#

Available Actions:#

a. START_PICKUP#

b. SCAN_SHIPMENT#

Prerequisites#

Example Usage Flow#

Notes#

Request

Responses

API Documentation - Courier Pickup Tasks

Overview

Base URL

Authentication

Endpoints

1. Update Pickup Task Status

Available Actions:

a. START_PICKUP

b. SCAN_SHIPMENT

Prerequisites

Example Usage Flow

Notes