API Gateway Documentation

API Gateway — Overview

API ini digunakan oleh client/partner untuk mengirim data Order dan ASN (Advanced Shipping Notice) ke sistem LOZY. Semua request harus menggunakan API key untuk autentikasi.

Protocol

HTTPS

Format

JSON

Auth

API Key (Header)

Rate Limit

100 req/min

Authentication

Semua request harus menyertakan API key di header:

X-API-Key: your_api_key_here

API key diberikan oleh tim LOZY saat onboarding. Jika API key invalid atau tidak disertakan, response:

HTTP/1.1 401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Jangan share API key ke pihak lain. Jika bocor, hubungi tim LOZY untuk regenerate.

Base URL

Production	`Need Confirm`
Staging	`https://dummy-api-staging.lozy.co.id/v1`

Error Handling

Semua error response mengikuti format yang sama:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable error message",
    "details": [
      {"field": "items[0].sku", "message": "SKU is required"}
    ]
  }
}

Error Codes

HTTP Status	Code	Deskripsi
400	`VALIDATION_ERROR`	Request body invalid
401	`UNAUTHORIZED`	API key invalid/missing
404	`NOT_FOUND`	Resource tidak ditemukan
409	`DUPLICATE`	Data sudah ada (conflict)
422	`UNPROCESSABLE`	Data valid tapi tidak bisa diproses
429	`RATE_LIMITED`	Too many requests
500	`INTERNAL_ERROR`	Server error

Order API

POST `/v1/orders`

Buat order baru di sistem LOZY.

Request Headers

Content-Type: application/json
X-API-Key: your_api_key_here

Request Body

Field	Type	Required	Deskripsi
`order_id`	string	Yes	ID unik order dari sistem kamu
`marketplace`	string	Yes	`shopee`, `tiktok`, `lazada`, `zalora`, `tokopedia`, `manual`
`marketplace_order_id`	string	No	Order ID dari marketplace
`status`	string	Yes	`new`, `processing`, `packed`, `shipped`, `delivered`, `cancelled`
`customer`	object	Yes	Data customer (lihat di bawah)
`items`	array	Yes	Item order (min 1)
`shipping`	object	No	Info pengiriman
`payment`	object	No	Info pembayaran
`notes`	string	No	Catatan order
`warehouse_code`	string	No	Kode gudang tujuan

`customer` object

Field	Type	Required	Deskripsi
`name`	string	Yes	Nama penerima
`phone`	string	Yes	No. telepon
`email`	string	No	Email
`address`	object	Yes	Alamat pengiriman

`customer.address` object

Field	Type	Required
`street`	string	Yes
`district`	string	No
`city`	string	Yes
`province`	string	Yes
`postal_code`	string	Yes
`country`	string	No

`items[]` object

Field	Type	Required	Deskripsi
`sku`	string	Yes	SKU produk
`name`	string	Yes	Nama produk
`qty`	integer	Yes	Jumlah
`price`	number	Yes	Harga per item
`total`	number	No	Total (qty × price)
`weight_gram`	number	No	Berat per item (gram)
`variant`	string	No	Varian (size/color/etc)

Example Request

curl -X POST https://api.lozy.co.id/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "order_id": "ORD-2024-00123",
    "marketplace": "shopee",
    "marketplace_order_id": "240115ABCDEF",
    "status": "new",
    "customer": {
      "name": "John Doe",
      "phone": "08123456789",
      "email": "john@example.com",
      "address": {
        "street": "Jl. Sudirman No. 1, RT 01/RW 02",
        "district": "Setiabudi",
        "city": "Jakarta Selatan",
        "province": "DKI Jakarta",
        "postal_code": "12190",
        "country": "ID"
      }
    },
    "items": [
      {
        "sku": "SKU-BLK-L-001",
        "name": "Kaos Polos Hitam L",
        "qty": 2,
        "price": 75000,
        "total": 150000,
        "weight_gram": 200,
        "variant": "Hitam / L"
      },
      {
        "sku": "SKU-WHT-M-002",
        "name": "Kaos Polos Putih M",
        "qty": 1,
        "price": 70000,
        "total": 70000,
        "weight_gram": 200,
        "variant": "Putih / M"
      }
    ],
    "shipping": {
      "courier": "JNE",
      "service": "REG",
      "cost": 15000,
      "tracking_number": null
    },
    "payment": {
      "method": "marketplace",
      "total_amount": 235000,
      "currency": "IDR"
    },
    "notes": "Tolong packing bubble wrap",
    "warehouse_code": "WH-JKT-01"
  }'

Response 201 Created

{
  "success": true,
  "data": {
    "id": "lozy_ord_abc123",
    "order_id": "ORD-2024-00123",
    "marketplace": "shopee",
    "status": "new",
    "items_count": 2,
    "total_amount": 235000,
    "created_at": "2024-01-15T10:30:00Z"
  },
  "message": "Order created successfully"
}

PUT `/v1/orders/:order_id`

Update order yang sudah ada. Hanya kirim field yang berubah.

curl -X PUT https://api.lozy.co.id/v1/orders/ORD-2024-00123 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "status": "processing",
    "shipping": {
      "tracking_number": "JNE1234567890"
    }
  }'

Response 200 OK

{
  "success": true,
  "data": {
    "order_id": "ORD-2024-00123",
    "status": "processing",
    "updated_at": "2024-01-15T14:00:00Z"
  },
  "message": "Order updated successfully"
}

GET `/v1/orders/:order_id`

Ambil detail order.

curl -H "X-API-Key: your_api_key_here" \
  https://api.lozy.co.id/v1/orders/ORD-2024-00123

Response 200 OK

{
  "success": true,
  "data": {
    "id": "lozy_ord_abc123",
    "order_id": "ORD-2024-00123",
    "marketplace": "shopee",
    "marketplace_order_id": "240115ABCDEF",
    "status": "processing",
    "customer": { "name": "John Doe", "phone": "08123456789", ... },
    "items": [ ... ],
    "shipping": { "courier": "JNE", "tracking_number": "JNE1234567890" },
    "payment": { "total_amount": 235000 },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T14:00:00Z"
  }
}

GET `/v1/orders`

List orders dengan filter dan pagination.

Query Param	Type	Deskripsi
`status`	string	Filter by status
`marketplace`	string	Filter by marketplace
`date_from`	string	From date (ISO format)
`date_to`	string	To date (ISO format)
`page`	integer	Halaman (default: 1)
`limit`	integer	Per halaman (default: 20, max: 100)

curl -H "X-API-Key: your_api_key_here" \
  "https://api.lozy.co.id/v1/orders?status=new&marketplace=shopee&page=1&limit=20"

POST `/v1/orders/:order_id/cancel`

Cancel order. Hanya bisa di-cancel jika status masih new atau processing.

curl -X POST https://api.lozy.co.id/v1/orders/ORD-2024-00123/cancel \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "reason": "Customer requested cancellation",
    "cancelled_by": "customer"
  }'

Response 200 OK

{
  "success": true,
  "data": { "order_id": "ORD-2024-00123", "status": "cancelled" },
  "message": "Order cancelled successfully"
}

Order yang sudah shipped atau delivered tidak bisa di-cancel. Response: 422 Unprocessable.

ASN API (Advanced Shipping Notice)

ASN digunakan untuk memberitahu gudang LOZY bahwa akan ada barang masuk dari supplier/partner.

POST `/v1/asn`

Buat ASN baru.

Request Body

Field	Type	Required	Deskripsi
`asn_number`	string	Yes	Nomor ASN unik dari sistem kamu
`reference_number`	string	No	Nomor PO/referensi
`warehouse_code`	string	Yes	Kode gudang tujuan
`supplier`	object	Yes	Info supplier
`expected_arrival`	string	Yes	Tanggal perkiraan tiba (ISO date: `2024-01-15`)
`items`	array	Yes	Item yang dikirim (min 1)
`shipping`	object	No	Info pengiriman
`notes`	string	No	Catatan

`supplier` object

Field	Type	Required
`code`	string	Yes
`name`	string	Yes
`contact`	string	No
`phone`	string	No

`items[]` object

Field	Type	Required	Deskripsi
`sku`	string	Yes	SKU produk
`name`	string	Yes	Nama produk
`qty_expected`	integer	Yes	Jumlah yang diharapkan
`unit`	string	No	Satuan (default: `pcs`)
`batch_number`	string	No	Nomor batch
`expiry_date`	string	No	Tanggal kadaluarsa
`cost_price`	number	No	Harga beli per item

`shipping` object (opsional)

Field	Type	Deskripsi
`courier`	string	Nama kurir/ekspedisi
`tracking_number`	string	No. resi
`shipped_at`	string	Waktu pengiriman (ISO)

Example Request

curl -X POST https://api.lozy.co.id/v1/asn \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "asn_number": "ASN-2024-00045",
    "reference_number": "PO-2024-100",
    "warehouse_code": "WH-JKT-01",
    "supplier": {
      "code": "SUP-001",
      "name": "PT Supplier Utama",
      "contact": "Budi",
      "phone": "08111222333"
    },
    "expected_arrival": "2024-01-20",
    "items": [
      {
        "sku": "SKU-BLK-L-001",
        "name": "Kaos Polos Hitam L",
        "qty_expected": 200,
        "unit": "pcs",
        "batch_number": "BATCH-JAN-001",
        "cost_price": 35000
      },
      {
        "sku": "SKU-WHT-M-002",
        "name": "Kaos Polos Putih M",
        "qty_expected": 150,
        "unit": "pcs",
        "batch_number": "BATCH-JAN-001",
        "cost_price": 33000
      }
    ],
    "shipping": {
      "courier": "JNE Trucking",
      "tracking_number": "JNECARGO123456",
      "shipped_at": "2024-01-18T09:00:00Z"
    },
    "notes": "Batch produksi Januari 2024"
  }'

Response 201 Created

{
  "success": true,
  "data": {
    "id": "lozy_asn_xyz789",
    "asn_number": "ASN-2024-00045",
    "warehouse_code": "WH-JKT-01",
    "status": "pending",
    "items_count": 2,
    "total_qty_expected": 350,
    "expected_arrival": "2024-01-20",
    "created_at": "2024-01-15T08:00:00Z"
  },
  "message": "ASN created successfully"
}

PUT `/v1/asn/:asn_number`

Update ASN. Bisa update items, shipping info, expected arrival, dll.

curl -X PUT https://api.lozy.co.id/v1/asn/ASN-2024-00045 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "expected_arrival": "2024-01-22",
    "shipping": {
      "tracking_number": "JNECARGO999999",
      "shipped_at": "2024-01-19T10:00:00Z"
    },
    "notes": "Terlambat 2 hari karena cuaca"
  }'

Response 200 OK

{
  "success": true,
  "data": { "asn_number": "ASN-2024-00045", "status": "in_transit", "updated_at": "..." },
  "message": "ASN updated successfully"
}

GET `/v1/asn/:asn_number`

Ambil detail ASN termasuk status penerimaan di gudang.

curl -H "X-API-Key: your_api_key_here" \
  https://api.lozy.co.id/v1/asn/ASN-2024-00045

Response 200 OK

{
  "success": true,
  "data": {
    "id": "lozy_asn_xyz789",
    "asn_number": "ASN-2024-00045",
    "reference_number": "PO-2024-100",
    "warehouse_code": "WH-JKT-01",
    "status": "received",
    "supplier": { "code": "SUP-001", "name": "PT Supplier Utama" },
    "expected_arrival": "2024-01-22",
    "actual_arrival": "2024-01-22T09:30:00Z",
    "items": [
      {
        "sku": "SKU-BLK-L-001",
        "name": "Kaos Polos Hitam L",
        "qty_expected": 200,
        "qty_received": 198,
        "qty_damaged": 2,
        "status": "received"
      },
      {
        "sku": "SKU-WHT-M-002",
        "name": "Kaos Polos Putih M",
        "qty_expected": 150,
        "qty_received": 150,
        "qty_damaged": 0,
        "status": "received"
      }
    ],
    "shipping": { "courier": "JNE Trucking", "tracking_number": "JNECARGO999999" },
    "received_by": "Ahmad (Staff Gudang)",
    "created_at": "2024-01-15T08:00:00Z",
    "updated_at": "2024-01-22T09:30:00Z"
  }
}

ASN Status Flow

pending → in_transit → arrived → receiving → received → closed
                                                         ↘ partially_received

Status	Deskripsi
`pending`	ASN dibuat, belum dikirim
`in_transit`	Barang dalam perjalanan
`arrived`	Barang tiba di gudang, belum di-check
`receiving`	Sedang proses penerimaan/QC
`received`	Semua item diterima
`partially_received`	Sebagian item diterima (ada yang kurang/rusak)
`closed`	ASN ditutup/final

GET `/v1/asn`

List ASN dengan filter.

Query Param	Type	Deskripsi
`status`	string	Filter by status
`warehouse_code`	string	Filter by warehouse
`supplier_code`	string	Filter by supplier
`date_from`	string	Expected arrival from
`date_to`	string	Expected arrival to
`page`	integer	Halaman (default: 1)
`limit`	integer	Per halaman (max: 100)

curl -H "X-API-Key: your_api_key_here" \
  "https://api.lozy.co.id/v1/asn?status=pending&warehouse_code=WH-JKT-01"

POST `/v1/asn/:asn_number/confirm-received`

Konfirmasi penerimaan barang di gudang. Kirim qty yang benar-benar diterima per item.

curl -X POST https://api.lozy.co.id/v1/asn/ASN-2024-00045/confirm-received \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "received_by": "Ahmad - Staff Gudang",
    "received_at": "2024-01-22T09:30:00Z",
    "items": [
      {
        "sku": "SKU-BLK-L-001",
        "qty_received": 198,
        "qty_damaged": 2,
        "damage_notes": "2 pcs kotor terkena air"
      },
      {
        "sku": "SKU-WHT-M-002",
        "qty_received": 150,
        "qty_damaged": 0
      }
    ],
    "notes": "Overall kondisi baik"
  }'

Response 200 OK

{
  "success": true,
  "data": {
    "asn_number": "ASN-2024-00045",
    "status": "partially_received",
    "total_expected": 350,
    "total_received": 348,
    "total_damaged": 2,
    "discrepancy": -2
  },
  "message": "ASN receiving confirmed"
}

Jika total_received === total_expected, status otomatis jadi received.
Jika ada selisih, status jadi partially_received.

LOZY API Gateway Documentation v1.0

Webhook Docs

API Gateway — Overview

Authentication

Base URL

Error Handling

Error Codes

Order API

POST /v1/orders

Request Headers

Request Body

customer object

customer.address object

items[] object

Example Request

Response 201 Created

PUT /v1/orders/:order_id

Response 200 OK

GET /v1/orders/:order_id

Response 200 OK

GET /v1/orders

POST /v1/orders/:order_id/cancel

Response 200 OK

ASN API (Advanced Shipping Notice)

POST /v1/asn

Request Body

supplier object

items[] object

shipping object (opsional)

Example Request

Response 201 Created

PUT /v1/asn/:asn_number

Response 200 OK

GET /v1/asn/:asn_number

Response 200 OK

ASN Status Flow

GET /v1/asn

POST /v1/asn/:asn_number/confirm-received

Response 200 OK

POST `/v1/orders`

`customer` object

`customer.address` object

`items[]` object

PUT `/v1/orders/:order_id`

GET `/v1/orders/:order_id`

GET `/v1/orders`

POST `/v1/orders/:order_id/cancel`

POST `/v1/asn`

`supplier` object

`items[]` object

`shipping` object (opsional)

PUT `/v1/asn/:asn_number`

GET `/v1/asn/:asn_number`

GET `/v1/asn`

POST `/v1/asn/:asn_number/confirm-received`