README

This module integrates Magento 2 with the Detrack delivery management API, enabling order-based delivery creation, tracking, and management directly from the Magento admin panel.

Business Context

The core function of this module is to synchronize Magento orders with Detrack as delivery jobs, and provide a centralized UI for managing those deliveries.

Key Features:

1. Shipping Method: Provides a "Detrack" carrier option at checkout with configurable pricing and country restrictions.
2. Delivery Management UI: Admin grid listing all Detrack deliveries fetched from the API with search and filtering capabilities.
3. Order Integration: Automatically maps Magento order data (customer info, shipping address, products) to Detrack delivery fields.
4. CRUD Operations: Create, view, edit, and delete deliveries via the Detrack API directly from Magento admin.
5. Order Grid: A dedicated admin grid showing Magento orders eligible for Detrack shipment (filtered by status and shipping method).
6. Configurable Settings: API credentials, URL endpoints, order statuses, run numbers, job types, and predefined box/package templates.
7. Database Columns: Adds detrack_status, detrack_tracking_no, and detrack_sended columns to the sales_order table.

Example Scenario:

• A customer places an order selecting the "Detrack" shipping method.
• An admin user navigates to the Detrack Orders grid, selects the order, and creates a delivery job in Detrack.
• The delivery details (DO number, tracking, status, assigned vehicle) are synced back and viewable/editable from the Magento admin.

Note: This module handles the integration and data synchronization with Detrack only. Pricing, delivery zones, and vehicle assignments are managed via the Detrack platform and module configuration.

Prerequisites

Detrack Account

To use this module, you need an active Detrack account.

• Create a Detrack account
• API v1 Documentation

Required Fields in Detrack

Be sure to enable the following fields in your Detrack settings so that the integration works properly:

Installation

Composer

To install the module via Composer:

composer require aoropeza/detrackshippingmanager
bin/magento module:enable Aoropeza_DetrackShippingManager
bin/magento setup:upgrade
bin/magento setup:di:compile

Usage

Admin Configuration

1. Go to the Magento Admin Panel.
2. Navigate to Stores > Configuration > Dev Oropeza > Detrack Settings.
3. API Credentials:
   • API Key Secret: Your Detrack API key for authentication.
4. API URL's:
   • Url Base: Base URL for the Detrack API (default: https://app.detrack.com/api/v1/).
   • Individual endpoint paths for listing, creating, editing, deleting, and viewing deliveries, as well as vehicles.
5. Settings Fields:
   • Status Order to send: Which order statuses are eligible for Detrack delivery (default: pending,processing).
   • Run No.: Route/run number configuration for grouping related deliveries.
   • Job Type: Type of job (e.g., DELIVERY, DROP OFF, PICK UP).
   • Box Settings: Predefined package/box templates with dimensions and weight.

Shipping Method Configuration

1. Navigate to Stores > Configuration > Sales > Shipping Methods > Detrack.
2. Enabled: Activate/Deactivate the carrier.
3. Method Name / Title: Display names for the shipping method.
4. Price: Flat shipping rate.
5. Ship to Applicable Countries: All or specific countries.
6. Displayed Error Message: Custom error shown when the method is unavailable.

Frontend/Admin Flow

1. Customer selects "Detrack" as the shipping method during checkout.
2. Admin views eligible orders in the Detrack Orders grid.
3. Admin creates a delivery job, which sends order data to the Detrack API.
4. Delivery details are viewable and editable in the Delivery Management grid.
5. The sales_order table is updated with detrack_status, detrack_tracking_no, and detrack_sended flag.

Magento REST API Reference

This module exposes Magento REST endpoints that wrap the Detrack API operations. All requests require admin authentication via a bearer token.

Base URL

/rest/V1/detrack

Authentication

Before calling any endpoint, obtain an admin token:

TOKEN=$(curl -s -X POST "http://yourstore.com/rest/V1/integration/admin/token" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your_password"}')

Include the token in all subsequent requests:

-H "Authorization: Bearer $TOKEN"

Endpoints

1. List All Deliveries

GET /rest/V1/detrack/deliveries?date={YYYY-MM-DD}

Fetches all deliveries for a given date (defaults to today if omitted).

curl -X GET "http://yourstore.com/rest/V1/detrack/deliveries?date=2026-04-30" \
  -H "Authorization: Bearer $TOKEN"

[
  {
    "do": "DO-20260430-001",
    "order_no": "100000001",
    "name": "John",
    "last_name": "Doe",
    "address": "123 Main St, City, State, 12345, United States",
    "phone": "+1234567890",
    "status": "pending",
    "tracking_status": "unassigned",
    "assign_to": "",
    "date": "2026-04-30",
    "start_date": "2026-04-30 08:00:00",
    "tracking_no": "TRK123456"
  }
]

2. View Delivery

POST /rest/V1/detrack/deliveries/view

Retrieves details for a specific delivery by DO number.

{
  "doNumber": "DO-20260430-001",
  "date": "2026-04-30"
}

curl -X POST "http://yourstore.com/rest/V1/detrack/deliveries/view" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "doNumber": "DO-20260430-001",
    "date": "2026-04-30"
  }'

{
  "do": "DO-20260430-001",
  "order_no": "100000001",
  "name": "John",
  "last_name": "Doe",
  "address": "123 Main St, City, State, 12345, United States",
  "phone": "+1234567890",
  "status": "pending",
  "tracking_status": "unassigned",
  "assign_to": "Vehicle-01",
  "date": "2026-04-30",
  "instructions": "Leave at front door",
  "notify_email": "john@example.com",
  "run_no": "1",
  "tracking_no": "TRK123456",
  "job_type": "delivery"
}

3. Create Delivery

POST /rest/V1/detrack/deliveries/create

Creates a new delivery job in Detrack from order data.

{
  "deliveryData": {
    "do": "DO-20260430-002",
    "date": "2026-04-30",
    "order_no": "100000002",
    "name": "Jane",
    "last_name": "Smith",
    "address": "456 Oak Ave, City, State, 67890, United States",
    "phone": "+0987654321",
    "notify_email": "jane@example.com",
    "tracking_no": "TRK654321",
    "instructions": "Call before delivery",
    "run_no": "2",
    "job_type": "delivery"
  }
}

curl -X POST "http://yourstore.com/rest/V1/detrack/deliveries/create" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryData": {
      "do": "DO-20260430-002",
      "date": "2026-04-30",
      "order_no": "100000002",
      "name": "Jane",
      "last_name": "Smith",
      "address": "456 Oak Ave, City, State, 67890, United States",
      "phone": "+0987654321",
      "notify_email": "jane@example.com",
      "tracking_no": "TRK654321",
      "instructions": "Call before delivery",
      "run_no": "2",
      "job_type": "delivery"
    }
  }'

{
  "do": "DO-20260430-002",
  "order_no": "100000002",
  "status": "ok",
  "tracking_no": "TRK654321"
}

4. Update Delivery

POST /rest/V1/detrack/deliveries/update

Updates an existing delivery's fields in Detrack.

{
  "doNumber": "DO-20260430-001",
  "fields": {
    "status": "in_transit",
    "assign_to": "Vehicle-01",
    "instructions": "Updated: Ring doorbell"
  }
}

curl -X POST "http://yourstore.com/rest/V1/detrack/deliveries/update" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "doNumber": "DO-20260430-001",
    "fields": {
      "status": "in_transit",
      "assign_to": "Vehicle-01",
      "instructions": "Updated: Ring doorbell"
    }
  }'

{
  "do": "DO-20260430-001",
  "status": "ok",
  "assign_to": "Vehicle-01"
}

5. Delete Delivery

POST /rest/V1/detrack/deliveries/delete

Deletes a delivery job from Detrack by DO number.

{
  "doNumber": "DO-20260430-001"
}

curl -X POST "http://yourstore.com/rest/V1/detrack/deliveries/delete" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"doNumber": "DO-20260430-001"}'

true

6. Get Vehicles

GET /rest/V1/detrack/vehicles

Fetches all available vehicles/drivers from Detrack for assignment.

curl -X GET "http://yourstore.com/rest/V1/detrack/vehicles" \
  -H "Authorization: Bearer $TOKEN"

[
  {
    "vehicle_id": "V001",
    "name": "Van 1",
    "status": "active",
    "driver": "Driver A"
  },
  {
    "vehicle_id": "V002",
    "name": "Truck 2",
    "status": "active",
    "driver": "Driver B"
  }
]

Detrack API Configuration

The module communicates with the Detrack REST API (v1) internally. Endpoints are configured at:

Stores > Configuration > Dev Oropeza > Detrack Settings