order

This module provides functionality to search, retrieve, and manage orders from the Smart1 SDK API.

Overview

The order module allows you to:

Search orders with pagination
Filter orders by multiple criteria (state, priority, dates, fleet, etc.)
Sort order results by various properties
Update order states (reject, start, complete)
Retrieve specific order fields to optimize API calls
Work with complex shipment data structures

Main Components

GetAndSearchOrdersByPage

Main use case for retrieving orders from the API with advanced filtering and pagination.

UpdateOrderState

Use case for updating the state of an order (e.g., reject, start, complete).

Models

Order

Represents a complete order entity with all details.

Properties:

id: Int - Unique order identifier
routeId: Int - Related route ID
state: OrderState - Current order state
priority: Int - Order priority
totalOperators: Int - Total operators assigned
identifier: String - Order identifier
businessUnit: String - Business unit
shipment: List<Shipment> - Shipment information
dateInit: String - Initial date
hourInit: String - Initial hour
edaOrigin: String - EDA origin
etaOrigin: String - ETA origin
eddOrigin: String - EDD origin
etdOrigin: String - ETD origin
edaDestination: String - EDA destination
etaDestination: String - ETA destination
eddDestination: String - EDD destination
etdDestination: String - ETD destination
fleet: FleetType - Fleet type
loadType: LoadType - Load type
resourceIds: List<Int> - Resource IDs
truckId: Int - Truck ID
operatorIds: List<Int> - Operator IDs
objectId: Int - Related object ID
additionalInfo: JsonObject - Dynamic additional information
companyId: Int - Company ID
addedOnDate: String - Creation date
updateOnDate: String - Last update date

Shipment

Contains shipment information for an order.

Properties:

portId: Int - Port ID
empty: Boolean - Is shipment empty
pickups: List<ShipmentItem> - Pickup points
deliveries: List<ShipmentItem> - Delivery points

ShipmentItem

Represents a pickup or delivery point.

Properties:

skillIds: List<Int> - Required skill IDs
capacityInfo: List<CapacityInfo> - Capacity information

OrderFilters

Comprehensive filters for order search.

Properties: 26 different filter options including IDs, states, dates, fleet types, and more.

OrderOrderSort

Sorting configuration with 26 sortable properties.

Types

OrderProperty

Enum with 26 properties for field selection.

Values:

ID, ROUTE_ID, STATE, PRIORITY, TOTAL_OPERATORS, IDENTIFIER
BUSINESS_UNIT, SHIPMENT, DATE_INIT, HOUR_INIT
EDA_ORIGIN, ETA_ORIGIN, EDD_ORIGIN, ETD_ORIGIN
EDA_DESTINATION, ETA_DESTINATION, EDD_DESTINATION, ETD_DESTINATION
FLEET, LOAD_TYPE, RESOURCE_IDS, TRUCK_ID, OPERATOR_IDS
OBJECT_ID, ADDITIONAL_INFO, COMPANY_ID, ADDED_ON_DATE, UPDATE_ON_DATE

OrderState

Enum representing order states.

Values:

NOT_ASSIGNED - Order not assigned (use to reject)
ASSIGNED - Order assigned to operator
IN_PROGRESS - Order in progress
COMPLETED - Order completed
UNKNOWN - Unknown state (never use for updates)

PlanType

Enum for plan types.

Values:

BREAK, DRIVING, SETUP, SLEEPING, UNKNOWN

Usage Examples

Basic Search - Get All Orders

import com.servinformacion.smart1sdk.android.order.GetAndSearchOrdersByPage
import com.servinformacion.smart1sdk.android.core.ResultS1SDK

class OrderViewModel : ViewModel() {
    
    private val getOrders = GetAndSearchOrdersByPage()
    
    fun loadOrders() {
        viewModelScope.launch {
            val result = getOrders(
                page = 1,
                pageQuantity = 20
            )
            
            when (result) {
                is ResultS1SDK.Success -> {
                    val orders = result.data.data
                    val totalPages = result.data.paginationInfo.totalPages
                    // Handle success
                }
                is ResultS1SDK.Error -> {
                    // Handle error
                }
            }
        }
    }
}

Filter by Order State

import com.servinformacion.smart1sdk.android.order.model.OrderFilters
import com.servinformacion.smart1sdk.android.order.types.OrderState

suspend fun getAssignedOrders() {
    val getOrders = GetAndSearchOrdersByPage()
    
    val result = getOrders(
        filters = OrderFilters(
            states = listOf(OrderState.ASSIGNED, OrderState.IN_PROGRESS)
        ),
        page = 1
    )
    
    // Handle result
}

Filter by Date Range

suspend fun getOrdersByDateRange(startDate: String, endDate: String) {
    val getOrders = GetAndSearchOrdersByPage()
    
    val result = getOrders(
        filters = OrderFilters(
            dateInit = listOf(startDate, endDate)
        ),
        searchType = ApiSearchType.CONTAINS,
        page = 1
    )
    
    // Handle result
}

Sort Orders by Priority

import com.servinformacion.smart1sdk.android.order.model.OrderOrderSort
import com.servinformacion.smart1sdk.android.core.types.ApiSortType

suspend fun getOrdersSortedByPriority() {
    val getOrders = GetAndSearchOrdersByPage()
    
    val result = getOrders(
        orderSort = OrderOrderSort(
            priority = ApiSortType.DESC,
            dateInit = ApiSortType.ASC
        ),
        page = 1
    )
    
    // Handle result
}

Update Order State - Start Order

import com.servinformacion.smart1sdk.android.order.UpdateOrderState
import com.servinformacion.smart1sdk.android.order.types.OrderState

suspend fun startOrder(orderId: Int) {
    val updateOrderState = UpdateOrderState()
    
    val result = updateOrderState(
        orderId = orderId,
        newStatus = OrderState.IN_PROGRESS
    )
    
    when (result) {
        is ResultS1SDK.Success -> {
            println("Order started successfully")
        }
        is ResultS1SDK.Error -> {
            println("Failed to start order: ${result.error}")
        }
    }
}

Update Order State - Reject Order

suspend fun rejectOrder(orderId: Int) {
    val updateOrderState = UpdateOrderState()
    
    val result = updateOrderState(
        orderId = orderId,
        newStatus = OrderState.NOT_ASSIGNED
    )
    
    // Handle result
}

Optimized Field Selection

import com.servinformacion.smart1sdk.android.order.types.OrderProperty

suspend fun getOrderBasicInfo() {
    val getOrders = GetAndSearchOrdersByPage()
    
    val result = getOrders(
        fields = listOf(
            OrderProperty.ID,
            OrderProperty.IDENTIFIER,
            OrderProperty.STATE,
            OrderProperty.PRIORITY,
            OrderProperty.DATE_INIT
        ),
        page = 1,
        pageQuantity = 50
    )
    
    // Handle result
}

Advanced Search with Multiple Filters

import com.servinformacion.smart1sdk.android.core.types.FleetType
import com.servinformacion.smart1sdk.android.core.types.LoadType

suspend fun advancedOrderSearch() {
    val getOrders = GetAndSearchOrdersByPage()
    
    val result = getOrders(
        filters = OrderFilters(
            states = listOf(OrderState.ASSIGNED),
            priorities = listOf(1, 2, 3),
            fleet = listOf(FleetType.INTERNAL),
            loadTypes = listOf(LoadType.FULL),
            companyIds = listOf(1)
        ),
        logicalOperator = ApiLogicalOperator.AND,
        orderSort = OrderOrderSort(
            priority = ApiSortType.DESC,
            dateInit = ApiSortType.ASC
        ),
        searchType = ApiSearchType.EXACT,
        page = 1,
        pageQuantity = 20
    )
    
    when (result) {
        is ResultS1SDK.Success -> {
            val dataSet = result.data
            println("Total orders: ${dataSet.paginationInfo.totalRecords}")
            
            dataSet.data.forEach { order ->
                println("Order ${order.identifier} - State: ${order.state}")
            }
        }
        is ResultS1SDK.Error -> {
            println("Error: ${result.error}")
        }
    }
}

Working with Shipment Data

suspend fun analyzeOrderShipments(orderId: Int) {
    val getOrders = GetAndSearchOrdersByPage()
    
    val result = getOrders(
        filters = OrderFilters(ids = listOf(orderId)),
        fields = listOf(
            OrderProperty.ID,
            OrderProperty.SHIPMENT
        )
    )
    
    when (result) {
        is ResultS1SDK.Success -> {
            val order = result.data.data.firstOrNull()
            order?.shipment?.forEach { shipment ->
                println("Port: ${shipment.portId}")
                println("Pickups: ${shipment.pickups.size}")
                println("Deliveries: ${shipment.deliveries.size}")
                println("Empty: ${shipment.empty}")
            }
        }
        is ResultS1SDK.Error -> {
            // Handle error
        }
    }
}

Important Notes

Required Field: Always include OrderProperty.ID in the fields list.
Order States:

Use NOT_ASSIGNED to reject an order
Use IN_PROGRESS to start an order
Use COMPLETED when order is finished
Never use UNKNOWN for updates

Field Selection: Request only needed fields for better performance.
Pagination: Results are paginated. Use DataSet.paginationInfo to navigate.
Complex Data: Orders contain nested shipment data with pickups and deliveries.
Date Formats:

Dates: YYYY-MM-DD'T'HH:MM:SS
Times: HH:MM:SS

Update Restrictions: Only certain state transitions are allowed by the API.
Additional Info: Dynamic JsonObject structure that varies by object configuration.

Response Structure

data class DataSet<T>(
    val data: List<T>,                   // List of orders
    val paginationInfo: PaginationInfo,  // Pagination metadata
    val capacityInfo: CapacityInfo       // API capacity information
)

Error Handling

Common errors:

CommonError.InvalidInputData - Invalid parameters (empty fields, invalid state transitions)
ApiError.ExpiredToken - Session token expired (handled automatically)
ApiError.Unauthorized - Invalid or missing authentication
ApiError.NotFound - Order not found

Packages

com.servinformacion.smart1sdk.android.order

androidJvm

com.servinformacion.smart1sdk.android.order.model

androidJvm

com.servinformacion.smart1sdk.android.order.types

androidJvm