- How do I integrate this SDK into a Laravel e-commerce app for NCM shipping?
- Install the package via Composer (`composer require pralhadstha/nepal-can-php-sdk`), then use the Laravel wrapper (`pralhadstha/nepalcan-laravel`) for config publishing, service provider binding, and artisan commands. Initialize the client in your `AppServiceProvider` with your NCM API token, then call methods like `Client::createShipment()` in your order service.
- Does this SDK support real-time order status updates via webhooks?
- Yes, the SDK includes webhook support with an event dispatcher. For Laravel, use the `EventDispatcher` to trigger custom events (e.g., `OrderStatusUpdated`) when webhooks are received. Ensure your webhook endpoint validates signatures and processes events asynchronously via Laravel Queues for reliability.
- What Laravel versions are officially supported by this package?
- The SDK is designed for Laravel 9+ and requires PHP 8.1+. While it may work with older Laravel versions, test thoroughly, especially if using the Laravel wrapper (`pralhadstha/nepalcan-laravel`), as it relies on Laravel’s service container and config publishing features.
- How do I handle API rate limits when calculating shipping rates frequently?
- Implement caching for rate calculations using Laravel’s `Cache` facade (e.g., `Cache::remember()`). For high-volume apps, use Redis with a TTL (e.g., 5 minutes) to avoid hitting NCM’s rate limits. The SDK itself doesn’t enforce rate limiting, so you’ll need to add exponential backoff logic in your application layer.
- Can I use this SDK outside Laravel (e.g., in Symfony or Lumen)?
- Yes, the core SDK (`pralhadstha/nepal-can-php-sdk`) works in any PHP 8.1+ application. Skip the Laravel wrapper and manually initialize the `Client` with your API token and Guzzle HTTP client. The SDK’s typed resources and event dispatcher are framework-agnostic.
- How do I test webhook functionality locally before going to production?
- Use the `nepalcan:webhook:validate` artisan command (from the Laravel wrapper) to test webhook signatures. Mock webhook payloads in your tests by extending the SDK’s `EventDispatcher` or using Laravel’s HTTP test helpers to simulate incoming requests to your webhook endpoint.
- What happens if NCM changes their API endpoints or response format?
- The SDK uses immutable, type-safe resources to model NCM’s API responses, reducing breaking changes. Monitor NCM’s API changelog and update the SDK or extend it with feature flags to isolate changes. For critical apps, implement contract testing (e.g., Pact) to catch API mismatches early.
- How do I map NCM’s order IDs to my internal order IDs in the database?
- Store the mapping in a database table (e.g., `nepalcan_orders`) with columns for `nepalcan_order_id` and `internal_order_id`. Use Laravel’s `hasOne` or `belongsTo` relationships to link orders. For performance, cache the mapping in Redis with a key like `nepalcan_order:{nepalcan_id}`.
- Are there alternatives to this SDK for NCM integration in Laravel?
- This is the most comprehensive PHP SDK for NCM, but you could build a custom integration using Guzzle directly. However, the SDK provides typed resources, webhook handling, and Laravel-specific features (like config publishing) that would require significant effort to replicate. For other couriers, consider similar SDKs like `shiprocket/shiprocket-sdk` for broader regional support.
- How do I handle COD (Cash on Delivery) payments and transfers in my app?
- Use the SDK’s `createCODTransferTicket()` method to generate COD transfer requests. For tracking, listen to webhook events like `CODTransferCompleted` via the `EventDispatcher`. Store COD amounts and transfer statuses in your database and sync them with NCM’s API using the `getOrderDetails()` method.