README

English | 中文

A Symfony bundle for integrating with Cainiao pickup service, providing pickup order management, logistics tracking, and comprehensive order lifecycle management.

Features
Installation
Dependencies
Quick Start
Console Commands
Configuration
Advanced Usage
Exception Handling
Security
Contributing
Testing
License
Support
Credits

Features

🚚 Complete pickup order management (create, modify, cancel)
📦 Support for multiple item types (documents, packages, etc.)
📍 Detailed address management for senders and receivers
🔄 Real-time order status tracking (20+ status types)
📊 Logistics detail querying and tracking
🏭 Multi-configuration support for different warehouses/providers
🔒 Secure API communication with signature verification
🎯 Built-in exception handling for various API scenarios
🛠️ Symfony console commands for batch operations
📝 Comprehensive entity relationships with Doctrine ORM

Installation

composer require tourze/cainiao-pickup-bundle

After installation, register the bundle in your config/bundles.php:

return [
    // ...
    CainiaoPickupBundle\CainiaoPickupBundle::class => ['all' => true],
];

Dependencies

This bundle requires the following:

PHP Requirements

PHP 8.1 or higher
SPL, date, json, random extensions

Symfony Requirements

Symfony 7.3 or higher
Doctrine ORM 3.0+
Doctrine DBAL 4.0+
Symfony HttpClient component

Internal Dependencies

tourze/doctrine-indexed-bundle
tourze/doctrine-snowflake-bundle
tourze/doctrine-timestamp-bundle
tourze/doctrine-track-bundle
tourze/doctrine-user-bundle
tourze/enum-extra

All dependencies are automatically managed by Composer.

Quick Start

1. Configure Cainiao API Credentials

First, create a Cainiao configuration in your database:

use CainiaoPickupBundle\Entity\CainiaoConfig;

$config = new CainiaoConfig();
$config->setName('Main Warehouse')
    ->setAppKey('your_app_key')
    ->setAppSecret('your_app_secret')
    ->setAccessCode('your_access_code')
    ->setProviderId('your_provider_id')
    ->setApiGateway('https://gateway.cainiao.com/gateway/api');

$entityManager->persist($config);
$entityManager->flush();

2. Create a Pickup Order

use CainiaoPickupBundle\Service\PickupService;
use CainiaoPickupBundle\Enum\ItemTypeEnum;

$pickupService = $container->get(PickupService::class);

$orderData = [
    // Sender information
    'senderName' => 'John Doe',
    'senderPhone' => '13800138000',
    'senderFullAddress' => 'Building A, 123 Street, Beijing',
    'senderProvince' => 'Beijing',
    'senderCity' => 'Beijing',
    'senderArea' => 'Chaoyang District',
    
    // Receiver information
    'receiverName' => 'Jane Smith',
    'receiverPhone' => '13900139000',
    'receiverFullAddress' => 'Building B, 456 Avenue, Shanghai',
    'receiverProvince' => 'Shanghai',
    'receiverCity' => 'Shanghai',
    'receiverArea' => 'Pudong District',
    
    // Item details
    'itemType' => ItemTypeEnum::PACKAGE->value,
    'weight' => 2.5, // in kg
    'itemQuantity' => 1,
    'itemValue' => 100.00,
    'remark' => 'Fragile items',
    
    // Pickup time window (optional)
    'expectPickupTimeStart' => '2024-01-20 14:00:00',
    'expectPickupTimeEnd' => '2024-01-20 18:00:00',
];

$order = $pickupService->createPickupOrder($orderData);

echo "Order created: " . $order->getOrderCode();
echo "Tracking number: " . $order->getMailNo();

3. Track Order Status

// Get order by code
$order = $pickupService->getOrderDetail('PK20240120123456');

// Check current status
echo "Current status: " . $order->getStatus()->getLabel();

// Get logistics details
$cainiaoHttpClient = $container->get(CainiaoHttpClient::class);
$logistics = $cainiaoHttpClient->queryLogisticsDetail($order);

foreach ($logistics['logisticsDetails'] as $detail) {
    echo $detail['time'] . ' - ' . $detail['desc'] . PHP_EOL;
}

4. Cancel an Order

try {
    $cancelledOrder = $pickupService->cancelPickupOrder($order, 'Customer request');
    echo "Order cancelled successfully";
} catch (OrderCannotBeCancelledException $e) {
    echo "Cannot cancel order: " . $e->getMessage();
}

Console Commands

Sync Pickup Orders

Synchronize pickup order details from Cainiao API:

# Sync all unfinished orders
bin/console cainiao:pickup:sync-orders

# Sync a specific order by order code
bin/console cainiao:pickup:sync-orders --order-code="PK20240120123456"

This command will:

Update order status and details from Cainiao API
Sync all unfinished orders if no order code is specified
Handle errors gracefully for individual orders in batch operations

Sync Logistics Details

Synchronize logistics tracking information for pickup orders:

# Sync logistics for all orders with warehouse confirmed status
bin/console cainiao:pickup:sync-logistics

# Sync logistics for a specific order
bin/console cainiao:pickup:sync-logistics --order-code="PK20240120123456"

This command will:

Query and update logistics tracking details from Cainiao API
Replace existing logistics details with fresh data
Include courier information when available
Process all warehouse-confirmed orders if no order code is specified

Configuration

Entity Relationships

The bundle provides the following main entities:

CainiaoConfig: API configuration for different warehouses/providers
PickupOrder: Main order entity with full lifecycle tracking
AddressInfo: Embedded value object for sender/receiver addresses
LogisticsDetail: Tracking information for orders

Order Status Types

The bundle supports 20+ order statuses, including:

CREATE (0): Order created
WAREHOUSE_ACCEPT (100): Warehouse accepted
ACCEPT (400): Package picked up
TRANSPORT (500): In transit
DELIVERING (600): Out for delivery
SIGN (1000): Delivered
CANCELLED: Order cancelled

Item Types

Supported item types:

DOC: Documents
SPX: Small packages
PACKAGE: Standard packages
OTHER: Other items

Advanced Usage

Pre-query Service Availability

$availability = $cainiaoHttpClient->preQueryPickupService($order);

if ($availability['isFull']) {
    echo "Service is full for the requested time";
} else {
    echo "Available time slots:";
    foreach ($availability['availableTimeSlots'] as $slot) {
        echo $slot['startTime'] . ' - ' . $slot['endTime'] . PHP_EOL;
    }
}

Modify an Existing Order

$modificationData = [
    'weight' => 3.0, // Update weight
    'remark' => 'Updated: Handle with extra care',
    'expectPickupTimeStart' => '2024-01-21 09:00:00',
    'expectPickupTimeEnd' => '2024-01-21 12:00:00',
];

try {
    $modifiedOrder = $pickupService->modifyPickupOrder($order, $modificationData);
    echo "Order modified successfully";
} catch (OrderModificationFailedException $e) {
    echo "Cannot modify order: " . $e->getMessage();
}

Query Orders by Status

use CainiaoPickupBundle\Enum\OrderStatusEnum;
use CainiaoPickupBundle\Repository\PickupOrderRepository;

$orderRepository = $container->get(PickupOrderRepository::class);

// Get all orders in transit
$ordersInTransit = $orderRepository->findByStatus(OrderStatusEnum::TRANSPORT);

// Get all delivered orders
$deliveredOrders = $orderRepository->findByStatus(OrderStatusEnum::SIGN);

// Get all unfinished orders
$unfinishedOrders = $orderRepository->findUnfinishedOrders();

Exception Handling

The bundle provides specific exceptions for different scenarios:

ConfigurationException: When Cainiao API configuration is missing or invalid
CainiaoApiException: General API communication errors
InvalidResponseException: When API returns unexpected response format
OrderNotFoundException: When requested order doesn't exist
OrderCannotBeCancelledException: When order status doesn't allow cancellation
OrderCancellationFailedException: When cancellation request fails
OrderModificationFailedException: When modification request fails

Security

API Security

This bundle implements several security measures:

Signature Verification: All API requests to Cainiao are signed using HMAC-SHA256
HTTPS Communication: All API calls are made over HTTPS
Access Token Management: Secure storage and handling of API credentials
Input Validation: All user input is validated using Symfony's validator component

Data Protection

Sensitive Data: API keys and secrets are stored securely in the database
Logging: Sensitive information is excluded from logs by default
Data Encryption: Consider encrypting sensitive configuration data at rest

Best Practices

Credential Management:
- Store API credentials in environment variables or secure configuration
- Rotate API keys regularly
- Use different credentials for different environments
Network Security:
- Use HTTPS for all API communications
- Implement rate limiting to prevent API abuse
- Monitor API usage for unusual patterns
Database Security:
- Use proper database permissions
- Encrypt sensitive data columns if required
- Regular security audits of stored data

If you discover a security vulnerability, please send an e-mail to security@tourze.com instead of using the issue tracker.

Contributing

Please see CONTRIBUTING.md for details on submitting patches and the contribution workflow.

Testing

# Run all tests
./vendor/bin/phpunit packages/cainiao-pickup-bundle/tests

# Run specific test suite
./vendor/bin/phpunit packages/cainiao-pickup-bundle/tests/Service

tourze / cainiao-pickup-bundle

Maintainers

Details