Nepal Can Php Sdk Laravel Package

Technical Evaluation

Architecture Fit

• Microservice/API Layer Fit: Ideal for a dedicated shipping/courier service integration in a Laravel-based e-commerce or logistics platform. The SDK abstracts NCM’s API complexity, enabling clean separation between business logic and external service calls.
• Domain-Driven Design (DDD) Alignment: Immutable, type-safe resources (Shipment, Rate, Webhook) align with DDD principles, making it easier to model domain entities (e.g., Order → Shipment).
• Event-Driven Potential: Webhook support with EventDispatcher enables reactive workflows (e.g., auto-updating order statuses in real-time). Pairs well with Laravel’s event system or queues for async processing.

Integration Feasibility

• Laravel Native Support: The SDK is Laravel-ready (via pralhadstha/nepalcan-laravel wrapper) with:
  • Service provider/facade integration.
  • Config publishing (API tokens, endpoints).
  • Artisan commands for testing/webhook validation.
• Non-Laravel PHP: Works in any PHP 8.1+ app (e.g., Symfony, Lumen) with minimal boilerplate.
• API Contract Stability: NCM’s API appears stable (last release: 2026-04-01), but backward compatibility should be validated if NCM updates their API.

Technical Risk

Key Questions

1. Business Criticality:
   • Is NCM the primary courier for the product, or a secondary option? (Affects error handling depth.)
2. Real-Time Requirements:
   • Are webhooks mandatory for core workflows (e.g., inventory updates)? If yes, ensure high availability for the webhook endpoint.
3. Data Ownership:
   • How will NCM’s orderId map to internal order_id? (Use database indexes or caching layers for performance.)
4. Compliance:
   • Does NCM’s API require GDPR/PDPA compliance for customer data (e.g., phone numbers)? Audit SDK’s data handling.
5. Cost Sensitivity:
   • Are rate calculations called frequently? Optimize with local caching (e.g., cache()->remember()).

Integration Approach

Stack Fit

Migration Path

1. Phase 1: Core Integration (2-3 weeks)

   • Install SDK + Laravel wrapper.
   • Configure config/nepalcan.php with API tokens.
   • Implement shipment creation and tracking in OrderService.
   • Add webhook endpoint (/api/nepalcan/webhook) with validation.

2. Phase 2: Workflow Automation (1-2 weeks)

   • Connect webhooks to Laravel Events (e.g., OrderStatusUpdated).
   • Implement rate caching (e.g., Cache::remember()).
   • Add return/exchange flows to OrderController.

3. Phase 3: Observability (1 week)

   • Log webhook events to Laravel Logs or Sentry.
   • Add health checks for NCM API (e.g., nepalcan.ping command).
   • Monitor rate limits via Laravel Horizon or StatsD.

Compatibility

• PHP 8.1+: Ensure your Laravel app uses PHP 8.1+ (check php -v and composer.json).
• Guzzle 7.0+: No conflicts if using Laravel’s default Guzzle HTTP client.
• Laravel 9+: Test with your Laravel version (wrapper may need adjustments for older versions).
• Database: No schema changes required; SDK is stateless (except cached data).

Sequencing

1. Prerequisites:
   • Obtain NCM API tokens (sandbox + production).
   • Set up a webhook URL (e.g., https://your-app.com/api/nepalcan/webhook).
2. Critical Path:
   • Implement shipment creation → webhook handling → rate calculation.
3. Non-Critical:
   • Branch/staff listings (can be added post-MVP).
   • COD ticketing (if not core to MVP).

Operational Impact

Maintenance

• Dependencies:
  • Monitor pralhadstha/nepal-can-php-sdk for updates (check GitHub releases).
  • Pin versions in composer.json to avoid breaking changes:

    "pralhadstha/nepal-can-php-sdk": "^1.0.0"
    

• Configuration:
  • Store API tokens in Laravel Env (NEPALCAN_API_TOKEN) or Vault.
  • Use config caching (php artisan config:cache) in production.
• Logs:
  • Log SDK errors to Laravel Logs or ELK Stack:

    try {
        $client->shipments->create(...);
    } catch (ApiException $e) {
        Log::error("NCM API Error", [
            'order_id' => $orderId,
            'error' => $e->getErrorBody(),
            'status' => $e->getStatusCode(),
        ]);
    }
    

Support

• Troubleshooting:
  • Use SDK’s test suite to validate API responses locally.
  • Enable debug mode for webhooks:

    $client->webhooks->parse($payload, debug: true);
    

  • NCM’s sandbox environment for testing (no real orders).
• SLAs:
  • Define downtime policies for NCM API failures (e.g., fallback to another courier).
  • Set up alerts for webhook failures (e.g., Laravel Monitor).

Scaling

• Rate Limits:
  • Implement circuit breakers (e.g., spatie/fruitful) for NCM API calls.
  • Use queue retries for webhook processing:

    $job->retryAfter(5); // Retry after 5 seconds
    

• Performance:
  • Cache branch lists and rate calculations (TTL: 1 hour).
  • Batch bulk status checks to reduce API calls:

    $client->tracking->getBulkStatuses([$orderId1, $orderId2]);
    

• Webhooks:
  • Scale horizontally with Laravel Queues (e.g., Redis queue worker).
  • Use async processing for non-critical updates (e.g., analytics).

Failure Modes