Skip to Content
Welcome to Zendera Knowledge Hub
API DocumentationCargo Carrier Accounting

Cargo Carrier Accounting API

v1

Manage cargo carrier deposits, balances, submissions, and location configurations for comprehensive cargo carrier accounting in the Zendera system.

Interactive API Explorer

Loading API Documentation...

Endpoints Overview

Core Carrier Operations

  • GET /v1/cargocarrier/carriers/list - List all cargo carriers
  • GET /v1/cargocarrier/configuration - Get organization configuration
  • POST /v1/cargocarrier/deposits - Fetch cargo carrier deposits

Product Linking

  • POST /v1/cargocarrier/link-product - Link a product as cargo carrier
  • POST /v1/cargocarrier/unlink-product - Unlink a product from cargo carrier

Balance Management

  • POST /v1/cargocarrier/overview/cargo-carriers - Get balances per cargo carrier
  • POST /v1/cargocarrier/overview/cargo-carriers/{cargoCarrierId}/locations - Get balances for specific carrier
  • POST /v1/cargocarrier/overview/locations - Get balances per location
  • POST /v1/cargocarrier/overview/locations/{locationId}/cargo-carriers - Get balances for specific location

Submission Management

  • GET /v1/cargocarrier/submission/by-id/{id} - Get submission by ID
  • POST /v1/cargocarrier/submission/create-location-submission - Create location submission
  • GET /v1/cargocarrier/submission/list - List submissions with pagination
  • GET /v1/cargocarrier/submission/list-by-location-id/{locationId} - List submissions by location
  • GET /v1/cargocarrier/submission/list-by-user-id/{userId} - List submissions by user

Location Configuration

  • POST /v1/cargocarrier/location/list-by-ids - List location accounting by IDs
  • POST /v1/cargocarrier/location/update-configurations - Update location configurations

Mobile App Endpoints

  • GET /v1/mobile-app/cargocarrier/configuration - Get mobile organization configuration
  • POST /v1/mobile-app/cargocarrier/location/batch-stop-status - Get batch stop location status
  • POST /v1/mobile-app/cargocarrier/submission/create-batch-stop-submission - Create batch stop submission
  • POST /v1/mobile-app/cargocarrier/submission/get-batch-stop-submissions - Get batch stop submissions

Authentication

Authorization: apikey YOUR_API_KEY_HERE

Base URLs

  • Production: https://app.zenderatms.com/api/
  • Staging: https://staging.zenderatms.com/api/

Key Concepts

Cargo Carriers

Cargo carriers are products that can be tracked for deposits and returns (e.g., pallets, containers, crates).

Submissions

Submissions track the movement of cargo carriers with entries recording additions and subtractions at locations.

Balances

The system maintains real-time balances of cargo carriers per location and per carrier.

Deposits

Deposits track cargo carrier transactions with details about products, locations, and quantities.

Common Request Patterns

Fetching Deposits

{
  "internalLocationNumbers": ["LOC_123", "LOC_456"],
  "internalProductNumbers": ["PROD_001", "PROD_002"]
}

Creating Location Submission

{
  "locationId": 123,
  "comment": "Daily pallet return",
  "entries": [
    {
      "cargoCarrierId": 1,
      "add": 10,
      "subtract": 0
    },
    {
      "cargoCarrierId": 2,
      "add": 0,
      "subtract": 5
    }
  ]
}

Linking Product as Cargo Carrier

{
  "productId": 456,
  "negativeBalanceAllowed": false,
  "depositInUse": true,
  "depositOnAction": "DepositAction_PICKUP",
  "depositPreserveBalanceWhenFetched": true
}

Getting Balance Overview

{
  "page": 1,
  "perPage": 50,
  "sortBy": "SORT_BY_BALANCE",
  "sortDirection": "SORT_DIRECTION_DESC",
  "cargoCarrierIds": [1, 2, 3]
}

Updating Location Configuration

{
  "configurations": [
    {
      "locationId": 123,
      "setAskForAccounting": {
        "optionalValue": {
          "value": true
        }
      },
      "cargocarrierConfigurations": [
        {
          "cargoCarrierId": 1,
          "minQuantity": {
            "optional": {
              "value": 0
            }
          },
          "maxQuantity": {
            "optional": {
              "value": 100
            }
          }
        }
      ]
    }
  ]
}

Deposit Actions

The depositOnAction field in product linking supports:

  • DepositAction_UNSPECIFIED - Default/unspecified action
  • DepositAction_PICKUP - Deposit recorded at pickup
  • DepositAction_DELIVERY - Deposit recorded at delivery
  • DepositAction_BALANCE - Balance-based deposit

Sorting Options

Sort By Fields

  • SORT_BY_LOCATION_NAME - Sort by location name
  • SORT_BY_CARGO_CARRIER_NAME - Sort by cargo carrier name
  • SORT_BY_BALANCE - Sort by balance value

Sort Directions

  • SORT_DIRECTION_ASC - Ascending order
  • SORT_DIRECTION_DESC - Descending order

Pagination

Token-based Pagination

Used for submission listing:

?token={nextToken}&pageSize=100&ascending=true

Page-based Pagination

Used for balance overviews:

{
  "page": 1,
  "perPage": 50
}

Response Structure

Submission Response

{
  "submission": {
    "head": {
      "id": 123,
      "organizationId": 1,
      "createdAt": "2024-01-15T10:00:00Z",
      "createdByUserId": 456,
      "referencedLocationId": 789,
      "comment": "Daily return",
      "metadata": {},
      "internalLocationNumber": ["LOC_001"]
    },
    "entries": [
      {
        "id": 1,
        "submissionId": 123,
        "cargoCarrierId": 1,
        "delta": 10,
        "createdAt": "2024-01-15T10:00:00Z"
      }
    ]
  }
}

Balance Response

{
  "cargoCarriers": [
    {
      "cargoCarrierId": 1,
      "cargoCarrierName": "EUR Pallet",
      "balance": 150
    }
  ],
  "page": 1,
  "perPage": 50,
  "total": 3,
  "totalPages": 1
}

Error Handling

The API uses standard gRPC status codes wrapped in HTTP responses:

{
  "code": 5,
  "message": "NOT_FOUND: Cargo carrier not found",
  "details": []
}

Common error scenarios:

  • Invalid location or carrier IDs
  • Insufficient permissions
  • Invalid configuration values
  • Pagination token errors

Mobile App Integration

The mobile app endpoints provide simplified interfaces for:

  • Batch stop submissions
  • Organization configuration retrieval
  • Location status checks

These endpoints are optimized for mobile usage with reduced payload sizes and simplified request structures.

Example Usage

List All Cargo Carriers

curl -X GET "https://app.zenderatms.com/api/v1/cargocarrier/carriers/list" \
  -H "Authorization: apikey YOUR_API_KEY" \
  -H "Content-Type: application/json"

Create a Submission

curl -X POST "https://app.zenderatms.com/api/v1/cargocarrier/submission/create-location-submission" \
  -H "Authorization: apikey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": 123,
    "comment": "Pallet exchange",
    "entries": [
      {
        "cargoCarrierId": 1,
        "add": 5,
        "subtract": 3
      }
    ]
  }'

Get Location Balances

curl -X POST "https://app.zenderatms.com/api/v1/cargocarrier/overview/locations/123/cargo-carriers" \
  -H "Authorization: apikey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "perPage": 20,
    "sortBy": "SORT_BY_BALANCE",
    "sortDirection": "SORT_DIRECTION_DESC"
  }'

Best Practices

  1. Use Pagination: Always paginate when listing submissions or balances
  2. Filter Efficiently: Use location and product filters to reduce response sizes
  3. Batch Operations: Use batch stop endpoints for multiple stop submissions
  4. Configuration Caching: Cache organization configuration to reduce API calls
  5. Error Handling: Implement retry logic for transient failures
  6. Sorting: Use appropriate sort fields for your use case to improve performance
Last updated on
Atoms APINotifications Log