Offline Sync API Reference

API endpoints untuk batch synchronization dan conflict resolution dalam offline-first architecture.

🔐 Authentication

Semua endpoint memerlukan JWT authentication token.

Authorization: Bearer YOUR_JWT_TOKEN

📡 Endpoints

1. Batch Sync

Sync multiple transactions, payments, dan voids dalam satu request.

POST /api/v1/pos/offline/batch-sync
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "transactions": [
    {
      "offline_id": "550e8400-e29b-41d4-a716-446655440000",
      "offline_reference": "DEVICE001-20251013-001",
      "device_id": "DEVICE001",
      "created_at_device": "2025-10-13T10:30:00Z",
      "branch_code": "BRN-MST-OSK00001",
      "payment_method": "CASH",
      "id_user_apps": 5,
      "type_transaction": 1,
      "subtotal": 30000,
      "discount_total": 0,
      "tax_total": 3000,
      "grand_total": 33000,
      "status": "paid",
      "payment_status": "paid",
      "sync_status": "pending"
    }
  ],
  "payments": [],
  "voids": [],
  "device_id": "DEVICE001",
  "synced_at": "2025-10-13T11:00:00Z"
}

curl -X POST http://localhost:3002/api/v1/pos/offline/batch-sync \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "transactions": [{
      "offline_id": "550e8400-e29b-41d4-a716-446655440000",
      "offline_reference": "DEVICE001-20251013-001",
      "device_id": "DEVICE001",
      "created_at_device": "2025-10-13T10:30:00Z",
      "branch_code": "BRN-MST-OSK00001",
      "payment_method": "CASH",
      "id_user_apps": 5,
      "grand_total": 33000,
      "status": "paid"
    }],
    "payments": [],
    "voids": [],
    "device_id": "DEVICE001",
    "synced_at": "2025-10-13T11:00:00Z"
  }'

Request Body

array

required

Array of offline transactions to sync

Show Transaction Object

string

required

UUID generated by client (v4)

string

required

Unique reference: DEVICE_ID-YYYYMMDD-SEQ

string

required

Device identifier

datetime

required

ISO 8601 timestamp when created on device

string

required

Branch code (e.g., “BRN-MST-OSK00001”)

string

required

Payment method: CASH, QRIS, GOPAY, OVO, DANA, etc.

integer

required

User ID (cashier)

integer

default:"1"

Transaction type (1 = sales)

number

required

Subtotal amount

number

default:"0"

Total discount

number

default:"0"

Total tax

number

required

Grand total amount

string

required

Transaction status: draft, paid, void

string

required

Payment status: pending_payment, paid, void

array

default:"[]"

Array of offline payments to sync

array

default:"[]"

Array of offline voids to sync

string

required

Device identifier

datetime

required

ISO 8601 timestamp when sync initiated

Response (Success)

integer

HTTP status code (200)

object

Show Response Data

boolean

Overall sync success status

integer

Total items in batch

integer

Number of successful syncs

integer

Number of failed syncs

array

Array of sync results per item

Show Result Object

string

Original offline ID

string

Item type: transaction, payment, void

boolean

Sync success status

integer

Server-generated ID (if success)

string

Server-generated transaction code

string

Error message (if failed)

boolean

Whether conflict was detected

array

Array of detected conflicts

Show Conflict Object

string

Unique conflict identifier

string

Offline transaction ID

string

Conflict type: transaction, payment, void

string

duplicate, data_mismatch, constraint_violation

object

Data from offline client

object

Existing data on server

string

Suggested resolution: keep_server, keep_local, merge

string

URL to resolve conflict

datetime

Server timestamp when sync completed

Response Example

{
  "code": 200,
  "data": {
    "success": true,
    "total_items": 1,
    "success_count": 1,
    "failed_count": 0,
    "results": [
      {
        "offline_id": "550e8400-e29b-41d4-a716-446655440000",
        "type": "transaction",
        "success": true,
        "server_id": 185,
        "transaction_code": "TRX-MC01-BRN-MST-OSK00001-251013-5UJW-6SWG-7",
        "error": null,
        "conflict_detected": false
      }
    ],
    "conflicts": [],
    "synced_at": "2025-10-13T11:00:05Z"
  }
}

Response (With Conflict)

{
  "code": 200,
  "data": {
    "success": true,
    "total_items": 1,
    "success_count": 0,
    "failed_count": 1,
    "results": [
      {
        "offline_id": "550e8400-e29b-41d4-a716-446655440000",
        "type": "transaction",
        "success": false,
        "server_id": 185,
        "transaction_code": "TRX-MC01-BRN-MST-OSK00001-251013-5UJW-6SWG-7",
        "error": "Duplicate transaction detected",
        "conflict_detected": true
      }
    ],
    "conflicts": [
      {
        "conflict_id": "550e8400-e29b-41d4-a716-446655440000",
        "offline_id": "550e8400-e29b-41d4-a716-446655440000",
        "type": "transaction",
        "conflict_type": "duplicate",
        "local_data": {
          "offline_reference": "DEVICE001-20251013-001",
          "grand_total": 33000
        },
        "server_data": {
          "id": 185,
          "transaction_code": "TRX-MC01-BRN-MST-OSK00001-251013-5UJW-6SWG-7",
          "grand_total": 33000
        },
        "suggested_fix": "keep_server",
        "resolution_url": "/api/v1/pos/offline/conflicts/550e8400-e29b-41d4-a716-446655440000/resolve"
      }
    ],
    "synced_at": "2025-10-13T11:00:05Z"
  }
}

Error Responses

{
  "code": 400,
  "message": "Invalid request body",
  "errors": [
    {
      "field": "transactions[0].offline_reference",
      "message": "offline_reference is required"
    }
  ]
}

{
  "code": 401,
  "message": "Unauthorized",
  "error": "Invalid or expired token"
}

{
  "code": 500,
  "message": "Internal server error",
  "error": "Database connection failed"
}

2. Resolve Conflict

Resolve detected conflict dengan strategy tertentu.

POST /api/v1/pos/offline/conflicts/550e8400-e29b-41d4-a716-446655440000/resolve
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "strategy": "keep_server"
}

curl -X POST http://localhost:3002/api/v1/pos/offline/conflicts/550e8400-e29b-41d4-a716-446655440000/resolve \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "strategy": "keep_server"
  }'

Path Parameters

string

required

Conflict ID from batch sync response

Request Body

string

required

Resolution strategy:

keep_server: Keep server data, discard local
keep_local: Keep local data, overwrite server (not yet implemented)
merge: Merge both data (not yet implemented)

object

Required if strategy is “merge”

Response (Success)

{
  "code": 200,
  "data": {
    "conflict_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "resolved",
    "message": "Conflict resolved successfully",
    "resolved_at": "2025-10-13T11:05:00Z"
  }
}

Error Responses

{
  "code": 404,
  "message": "Conflict not found",
  "error": "No conflict with ID: 550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": 400,
  "message": "Invalid strategy",
  "error": "Strategy 'keep_local' not yet implemented"
}

🔄 Sync Flow Diagram

📊 Rate Limiting

Endpoint	Rate Limit	Window
Batch Sync	10 requests	1 minute
Resolve Conflict	30 requests	1 minute

💡 Best Practices

Batch Size

Limit batch size to 50 transactions per request untuk optimal performance.

Retry Logic

Implement exponential backoff untuk retry:

1st retry: 5 seconds
2nd retry: 10 seconds
3rd retry: 30 seconds
Max retries: 3

Idempotency

Gunakan offline_reference sebagai idempotency key. Server akan detect duplicate dan return existing data.

Error Handling

try {
  final response = await apiService.batchSync(request);
  
  // Handle success
  for (final result in response.results) {
    if (result.success) {
      await updateLocalTransaction(result);
    } else {
      await markAsFailed(result);
    }
  }
  
  // Handle conflicts
  if (response.conflicts.isNotEmpty) {
    await showConflictDialog(response.conflicts);
  }
  
} on DioException catch (e) {
  if (e.response?.statusCode == 401) {
    // Token expired, refresh and retry
    await refreshToken();
    return retry();
  } else if (e.type == DioExceptionType.connectionTimeout) {
    // Network timeout, queue for retry
    await queueForRetry();
  } else {
    // Other errors
    await logError(e);
  }
}

🧪 Testing

Postman Collection

Download Postman collection: offline-sync-api.postman_collection.json

REST Client Examples

See complete examples in: api/pos/offline-sync.http

Backend Implementation

Complete backend guide

Flutter Implementation

Step-by-step Flutter guide

Transaction Flow

Transaction state machine

Error Codes

Complete error codes reference

🆘 Support

Need Help?

Backend Team: [email protected]
Documentation: GitHub Wiki
Issues: GitHub Issues

Getting Started

Offline Sync API

Raw API

Offline Sync API Reference

Offline Sync API Reference

🔐 Authentication

📡 Endpoints

1. Batch Sync

Request Body

Response (Success)

Response Example

Response (With Conflict)

Error Responses

2. Resolve Conflict

Path Parameters

Request Body

Response (Success)

Error Responses

🔄 Sync Flow Diagram

📊 Rate Limiting

💡 Best Practices

Batch Size

Retry Logic

Idempotency

Error Handling

🧪 Testing

Postman Collection

REST Client Examples

Backend Implementation

Flutter Implementation

Transaction Flow

Error Codes

🆘 Support

​Offline Sync API Reference

​🔐 Authentication

​📡 Endpoints

​1. Batch Sync

​Request Body

​Response (Success)

​Response Example

​Response (With Conflict)

​Error Responses

​2. Resolve Conflict

​Path Parameters

​Request Body

​Response (Success)

​Error Responses

​🔄 Sync Flow Diagram

​📊 Rate Limiting

​💡 Best Practices

​Batch Size

​Retry Logic

​Idempotency

​Error Handling

​🧪 Testing

​Postman Collection

​REST Client Examples

​📚 Related Documentation

Backend Implementation

Flutter Implementation

Transaction Flow

Error Codes

​🆘 Support

Offline Sync API Reference

🔐 Authentication

📡 Endpoints

1. Batch Sync

Request Body

Response (Success)

Response Example

Response (With Conflict)

Error Responses

2. Resolve Conflict

Path Parameters

Request Body

Response (Success)

Error Responses

🔄 Sync Flow Diagram

📊 Rate Limiting

💡 Best Practices

Batch Size

Retry Logic

Idempotency

Error Handling

🧪 Testing

Postman Collection

REST Client Examples

📚 Related Documentation

🆘 Support