company

This module provides functionality to search and retrieve company information from the Smart1 SDK API.

Overview

The company module allows you to:

  • Search companies with pagination

  • Filter companies by multiple criteria

  • Sort company results

  • Retrieve specific company fields to optimize API calls

Main Components

GetAndSearchCompaniesByPage

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

Models

Company

Represents a company entity.

Properties:

  • id: Int - Unique company identifier

  • name: String - Company name

CompanyFilters

Filters to apply when searching companies.

Properties:

  • ids: List<Int>? - Filter by company IDs (optional)

  • names: List<String>? - Filter by company names (optional)

CompanyOrderSort

Sorting configuration for company results.

Properties:

  • id: ApiSortType? - Sort by ID (ASC/DESC, optional)

  • name: ApiSortType? - Sort by name (ASC/DESC, optional)

Types

CompanyProperty

Enum representing available company properties for field selection.

Values:

  • ID - Company ID field

  • NAME - Company name field

Usage Examples

Basic Search - Get All Companies

import com.servinformacion.smart1sdk.android.company.GetAndSearchCompaniesByPage
import com.servinformacion.smart1sdk.android.core.ResultS1SDK

class CompanyViewModel : ViewModel() {
    
    private val getCompanies = GetAndSearchCompaniesByPage()
    
    fun loadCompanies() {
        viewModelScope.launch {
            val result = getCompanies(
                page = 1,
                pageQuantity = 20
            )
            
            when (result) {
                is ResultS1SDK.Success -> {
                    val companies = result.data.data
                    val totalPages = result.data.paginationInfo.totalPages
                    // Handle success
                }
                is ResultS1SDK.Error -> {
                    // Handle error
                }
            }
        }
    }
}
Content copied to clipboard

Search with Filters

import com.servinformacion.smart1sdk.android.company.model.CompanyFilters
import com.servinformacion.smart1sdk.android.core.types.ApiLogicalOperator
import com.servinformacion.smart1sdk.android.core.types.ApiSearchType

suspend fun searchCompaniesByName(searchQuery: String) {
    val getCompanies = GetAndSearchCompaniesByPage()
    
    val result = getCompanies(
        filters = CompanyFilters(
            names = listOf(searchQuery)
        ),
        searchType = ApiSearchType.CONTAINS,
        logicalOperator = ApiLogicalOperator.OR,
        page = 1,
        pageQuantity = 10
    )
    
    // Handle result
}
Content copied to clipboard

Search with Sorting

import com.servinformacion.smart1sdk.android.company.model.CompanyOrderSort
import com.servinformacion.smart1sdk.android.core.types.ApiSortType

suspend fun getCompaniesSorted() {
    val getCompanies = GetAndSearchCompaniesByPage()
    
    val result = getCompanies(
        orderSort = CompanyOrderSort(
            name = ApiSortType.ASC
        ),
        page = 1
    )
    
    // Handle result
}
Content copied to clipboard

Optimized Field Selection

Request only the fields you need to reduce API response size:

import com.servinformacion.smart1sdk.android.company.types.CompanyProperty

suspend fun getCompanyIdsAndNames() {
    val getCompanies = GetAndSearchCompaniesByPage()
    
    val result = getCompanies(
        fields = listOf(
            CompanyProperty.ID,
            CompanyProperty.NAME
        ),
        page = 1,
        pageQuantity = 50
    )
    
    // Handle result
}
Content copied to clipboard

Advanced Search with Multiple Filters

suspend fun advancedCompanySearch() {
    val getCompanies = GetAndSearchCompaniesByPage()
    
    val result = getCompanies(
        fields = listOf(CompanyProperty.ID, CompanyProperty.NAME),
        filters = CompanyFilters(
            ids = listOf(1, 2, 3),
            names = listOf("Company A", "Company B")
        ),
        logicalOperator = ApiLogicalOperator.AND,
        orderSort = CompanyOrderSort(
            name = ApiSortType.ASC
        ),
        searchType = ApiSearchType.EXACT,
        page = 1,
        pageQuantity = 20
    )
    
    when (result) {
        is ResultS1SDK.Success -> {
            val dataSet = result.data
            println("Total companies: ${dataSet.paginationInfo.totalRecords}")
            println("Current page: ${dataSet.paginationInfo.currentPage}")
            println("Total pages: ${dataSet.paginationInfo.totalPages}")
            
            dataSet.data.forEach { company ->
                println("Company: ${company.name} (ID: ${company.id})")
            }
        }
        is ResultS1SDK.Error -> {
            println("Error: ${result.error}")
        }
    }
}
Content copied to clipboard

Custom Session Token

If you're managing sessions manually:

suspend fun getCompaniesWithCustomSession(token: String) {
    val getCompanies = GetAndSearchCompaniesByPage()
    
    val result = getCompanies(
        sessionToken = token,
        page = 1
    )
    
    // Handle result
}
Content copied to clipboard

Important Notes

  1. Required Field: Always include CompanyProperty.ID in the fields list. The API requires this field to function properly.

  2. Field Selection: Request only the fields you need. Less fields = faster response and less bandwidth usage.

  3. Pagination: Results are paginated. Use the DataSet.paginationInfo to navigate through pages.

  4. Logical Operators:

    • ApiLogicalOperator.AND - All filters must match

    • ApiLogicalOperator.OR - Any filter can match

  5. Search Types:

    • ApiSearchType.EXACT - Exact match

    • ApiSearchType.CONTAINS - Partial match (useful for search bars)

  6. Session Management: If you initialized the SDK with InitSDKConfig, you don't need to provide a session token. The SDK handles it automatically.

Response Structure

The response is wrapped in a DataSet<Company> which contains:

data class DataSet<T>(
    val data: List<T>,              // List of companies
    val paginationInfo: PaginationInfo,  // Pagination metadata
    val capacityInfo: CapacityInfo       // API capacity information
)
Content copied to clipboard

Error Handling

Common errors you might encounter:

  • CommonError.InvalidInputData - Invalid parameters (e.g., empty fields, page <= 0)

  • ApiError.ExpiredToken - Session token expired (handled automatically if using SDK config)

  • ApiError.Unauthorized - Invalid or missing authentication

  • ApiError.NotFound - No companies found matching criteria

Packages