Courier Partner Integrations

Supported Courier Partners

The system integrates with multiple courier partners in Indonesia:

1. JNE (Jalur Nugraha Ekakurir)

Features:

Status webhook integration

Status code mapping to internal codes

Real-time tracking updates

Controller: app/controllers/3p/jne.controller.js

2. Lion Parcel

Features:

Scheduled pickup requests via cron job

Bearer token authentication

Automatic pickup scheduling

Configuration:

// Environment variable
LIONPARCEL_PICKUP_CRON="*/30 * * * *"  // Every 30 minutes
LIONPARCEL_BEARER_TOKEN="<token>"

Controller: app/controllers/3p/lion-parcel.controller.js

3. JT Cargo (J&T Cargo)

Features:

Full API integration

Special pricing support

Database-driven pricing lookup

Fallback to JSON mapping

Special Pricing:

Primary: jnt_cargo_special_prices table

Fallback: app/maping/jntcargo-special-pricing.json

Controller: app/controllers/3p/jt-cargo.controller.js

4. AnterAja

Features:

Webhook integration

Access key authentication

Status synchronization

Authentication:

Access Key ID: ANTERAJA_ACCESS_KEY_ID

Secret Access Key: ANTERAJA_SECRET_ACCESS_KEY

Controller: app/controllers/3p/anteraja.controller.js

5. Sicepat

Features:

Status webhook support

Tracking integration

Controller: app/controllers/3p/sicepat.controller.js

6. Sap Express (SAPX)

Features:

API integration

Shipment creation

Controller: app/controllers/3p/sapx.controller.js

7. POS Indonesia

Features:

Indonesian postal service integration

Manifest generation

Token-based authentication

Routes: app/routes/pos_indo.routes.js

8. PCP Express

Features:

PCP carrier network

Manifest management

Routes: app/routes/pcp_express.routes.js

9. Laris Cargo

Features:

Regional courier integration

Routes: app/routes/laris_cargo.routes.js

Integration Pattern

All courier integrations follow a similar pattern:

// 1. Receive webhook from partner
POST /api/3p/{partner}/webhook

// 2. Validate authentication (Basic Auth or API Key)
passport.authenticate('{partner}Strategy')

// 3. Parse partner status code
parsePartnerStatus(partnerStatusCode)

// 4. Map to internal status code
const internalStatus = statusMapping[partnerStatusCode]

// 5. Update internal tracking
await updateScan(awb, internalStatus)

// 6. Trigger internal webhooks (if configured)
await triggerWebhook(waybillData)

// 7. Return acknowledgment
return { success: true }

Status Mapping

Each courier has status mappings in app/status/ directory:

Maps partner-specific status codes to internal OnDelivery codes

Ensures consistent tracking across all partners

Stored as JSON configuration files

Example Status Flow:

Partner: "DELIVERED" 
  → Internal: "DLV" 
  → Display: "Delivered to Customer"

Resi 3P Mapping

Purpose: Link internal AWB numbers to partner AWB numbers

Table: resi_3p

Fields:

internal_awb - OnDelivery waybill number

partner_awb - Partner's tracking number

partner_id - Courier partner ID

status - Current status

created_at - Mapping creation time

Usage:

// When creating shipment with partner
const mapping = await Resi3P.create({
  internal_awb: "ONX1234567890",
  partner_awb: "JNE0987654321",
  partner_id: 1  // JNE
});

// When receiving webhook
const waybill = await findWaybillByPartnerAwb(
  webhookData.awb, 
  partnerConfig.id
);

Business Workflows

Workflow 1: Waybill Creation & Booking

┌─────────────┐
│ User Input  │
└──────┬──────┘
       │
       ▼
┌────────────────────┐
│ Validate Origin/   │
│ Destination        │
└──────┬─────────────┘
       │
       ▼
┌────────────────────┐
│ Calculate Fee      │
│ (check-fee util)   │
└──────┬─────────────┘
       │
       ▼
┌────────────────────┐
│ Reserve AWB Number │
│ (from AWB Book)    │
└──────┬─────────────┘
       │
       ▼
┌────────────────────┐
│ Create Waybill     │
│ Record in DB       │
└──────┬─────────────┘
       │
       ▼
┌────────────────────┐
│ Create Initial Scan│
│ Status: BOOKED     │
└──────┬─────────────┘
       │
       ▼
┌────────────────────┐
│ Generate Label PDF │
└──────┬─────────────┘
       │
       ▼
┌────────────────────┐
│ Return AWB to User │
└────────────────────┘

Workflow 2: Package Tracking Lifecycle

Outgoing Phase:

BOOKED → PACKED → HANDOVER → DEPARTURE

Transit Phase:

DEPARTURE → [TRANSIT] → ARRIVAL

Delivery Phase:

ARRIVAL → RECEIVING → OUT_FOR_DELIVERY → DELIVERED
                                      → PROBLEM

Exception Handling:

ANY_STATUS → PROBLEM → [PROBLEM_RESOLVED]
          → RETURN → [RETURN_COMPLETE]
          → CANCEL

Status Codes:

BKD - Booked

PKD - Packed

HND - Handover

DPT - Departure

ARV - Arrival

RCV - Receiving

OFD - Out for Delivery

DLV - Delivered

PRB - Problem

RTN - Return

CNL - Cancel

Workflow 3: 3rd-Party Integration

┌──────────────────┐
│ Partner Webhook  │
└────────┬─────────┘
         │
         ▼
┌─────────────────────┐
│ Authenticate Request│
│ (Basic Auth/API Key)│
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Parse Partner AWB   │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Lookup in resi_3p   │
│ Get internal AWB    │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Map Partner Status  │
│ to Internal Status  │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Update Scan Record  │
│ in Database         │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Trigger Internal    │
│ Webhooks (optional) │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Send Acknowledgment │
│ to Partner          │
└─────────────────────┘

Workflow 4: Fee Calculation

┌─────────────────────┐
│ Origin & Destination│
│ Location Codes      │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Get Location Details│
│ (Province, City)    │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Check Service       │
│ Availability        │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Get Base Price      │
│ (by weight/distance)│
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Apply Special       │
│ Pricing (if VIP)    │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Add Surcharges      │
│ (remote area, etc.) │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Calculate Insurance │
│ (if requested)      │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Return Total Fee    │
│ with Breakdown      │
└─────────────────────┘

Workflow 5: Scanning Operations

Packing Scan:

1. Scan AWB number
2. Verify waybill exists
3. Check current status (must be BOOKED)
4. Record packing details (weight, dimensions)
5. Update status to PACKED
6. Generate packing list

Handover Scan:

1. Create handover manifest
2. Scan multiple AWBs
3. Verify all AWBs are PACKED
4. Record handover details (from/to location)
5. Update all AWBs to HANDOVER status
6. Generate handover manifest PDF
7. Print manifest for courier

Receiving Scan:

1. Scan incoming AWBs
2. Match with expected manifest
3. Record arrival time
4. Update status to RECEIVING
5. Flag any discrepancies
6. Assign to delivery driver

Delivery Scan:

1. Driver scans AWB
2. Capture POD (photo/signature)
3. Record delivery details
4. Update status to DELIVERED
5. Send customer notification
6. Update commission records

Problem Scan:

1. Scan AWB with issue
2. Select problem type (damaged, lost, refused, etc.)
3. Capture photos
4. Add notes
5. Update status to PROBLEM
6. Trigger problem resolution workflow
7. Notify relevant parties

Workflow 6: Multi-Courier Consolidation

┌─────────────────────┐
│ Multiple Couriers   │
│ Deliver to Hub      │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Receiving Scan      │
│ by Partner          │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Consolidate by      │
│ Destination         │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Create Manifest     │
│ for DC              │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Handover Scan       │
│ to Next Hub/DC      │
└────────┬────────────┘
         │
         ▼
┌─────────────────────┐
│ Final Delivery      │
│ to Customer         │
└─────────────────────┘

Workflow 7: Quality Management

Weight Discrepancy Handling:

1. Package weighed at receiving
2. Compare with declared weight
3. If difference > threshold:
   - Capture photo evidence
   - Record actual weight
   - Create alter_weight record
   - Calculate price adjustment
   - Notify customer
4. Update billing if needed

Proof of Delivery (POD):

1. Driver completes delivery
2. Capture recipient signature (digital)
3. Take delivery photo
4. Record GPS coordinates
5. Upload to server
6. Link to waybill
7. Status → DELIVERED

Proof of Pickup (POP):

1. Driver arrives at pickup location
2. Take package photos
3. Capture sender signature
4. Record GPS coordinates
5. Upload to server
6. Link to waybill
7. Status → BOOKED