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:

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

Required Fields in Detrack

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

Field	Description	Required
API Key	Secret API v1 key. Obtained from the Detrack administration panel.	Yes
Run Number	Route or shift number. Used to group related deliveries for the same driver.	Yes
Job Type	Type of work (Delivery, Pickup, Installation, etc.).	Yes
Vehicle	ID of the vehicle assigned to the delivery.	No
Driver	Name or ID of the driver assigned to the job.	Yes
Tracking Number	Unique tracking number for each generated delivery.	Yes
Customer Name	Name of the customer receiving the delivery.	Yes
Customer Phone	Customer phone number for SMS notifications and updates.	No
Customer Email	Customer email for sending confirmations and tracking links.	No
Delivery Date	Scheduled delivery date.	Yes
Address	Full destination address for the delivery.	Yes
Box / Package	Type of box or package. Must be configured in the product catalog.	No

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

Go to the Magento Admin Panel.
Navigate to Stores > Configuration > Dev Oropeza > Detrack Settings.
API Credentials:
- API Key Secret: Your Detrack API key for authentication.
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.
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

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

Frontend/Admin Flow

Customer selects "Detrack" as the shipping method during checkout.
Admin views eligible orders in the Detrack Orders grid.
Admin creates a delivery job, which sends order data to the Detrack API.
Delivery details are viewable and editable in the Delivery Management grid.
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).

Example Request

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

Response Example

[
  {
    "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.

Request Payload

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

Example Request

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"
  }'

Response Example

{
  "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.

Request Payload

{
  "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"
  }
}

Example Request

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"
    }
  }'

Response Example

{
  "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.

Request Payload

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

Example Request

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"
    }
  }'

Response Example

{
  "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.

Request Payload

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

Example Request

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"}'

Response Example

true

6. Get Vehicles

GET /rest/V1/detrack/vehicles

Fetches all available vehicles/drivers from Detrack for assignment.

Example Request

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

Response Example

[
  {
    "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

Setting	Config Path	Default Value
API Key	`detrack/api/key`	(required)
Base URL	`detrack/api_url/base`	`https://app.detrack.com/api/v1/`
List Deliveries	`detrack/api_url/list`	`deliveries/view/all.json`
Create Delivery	`detrack/api_url/add`	`deliveries/create.json`
Update Delivery	`detrack/api_url/edit`	`deliveries/update.json`
Delete Delivery	`detrack/api_url/delete`	`deliveries/delete.json`
View Delivery	`detrack/api_url/view`	`deliveries/view.json`
Vehicles	`detrack/api_url/vehicles`	`vehicles/view/all.json`

aoropeza / detrackshippingmanager

Maintainers

Package info

Statistics

Security

README

Business Context

Prerequisites

Detrack Account

Required Fields in Detrack

Installation

Composer

Usage

Admin Configuration

Shipping Method Configuration

Frontend/Admin Flow

Magento REST API Reference

Base URL

Authentication

Endpoints

1. List All Deliveries

2. View Delivery

3. Create Delivery

4. Update Delivery

5. Delete Delivery

6. Get Vehicles

Detrack API Configuration