Laravel Shiprocket Api Laravel Package

Getting Started

• Install with composer require seshac/laravel-shiprocket-api:^2.0. Version 2.x is PHP 8-oriented; if you are still on PHP 7.x, stay on the 1.0.x line until your runtime is upgraded.
• Publish the package config if the package exposes it, then set Shiprocket credentials in .env — typically email, password, channel ID, and pickup location. Run php artisan config:clear after changes.
• Look first at config/shiprocket.php, the package README, the registered facade/service class, and the auth/token handling. These tell you how the package expects credentials and how API calls are grouped.
• First practical use case: authenticate, create a test order, then exercise the fulfillment flow (pickup, AWB assignment, label, tracking). Start with a small non-production/test order and log the raw Shiprocket response so you can map IDs and error shapes.

Implementation Patterns

• Wrap Shiprocket calls in your own service/repository layer rather than calling the package facade directly from controllers. This keeps shipment logic testable and makes it easier to swap or mock the package.
• Centralize token handling. Authenticate once, cache the token until expiry, and reuse it across requests. Do not authenticate on every order or tracking call.
• Model the core workflow explicitly: create order → request pickup → assign AWB → generate label/manifest → track. Persist Shiprocket order IDs, shipment IDs, AWB numbers, and statuses locally so you can reconcile and retry safely.
• Map your internal order model to Shiprocket’s payload in a dedicated DTO/array builder. Validate required fields before calling the API: order ID, order date, pickup location, billing/shipping address, phone, items, SKU, quantity, price, payment method, weight, and dimensions.
• Use queued jobs for outbound API calls and webhook handlers for status updates. Keep order creation idempotent using your internal order ID as the guard against duplicate Shiprocket orders.
• Keep credentials and pickup/channel settings in config and environment variables. Avoid hard-coding pickup locations or channel IDs in application code.
• For tests, bind a fake implementation of your wrapper or use Laravel’s HTTP fake if the package uses the HTTP client. Cover the full happy path plus validation errors, expired token, and duplicate order scenarios.
• When upgrading to 2.0.0, run your integration tests against PHP 8 and exercise a full order-to-tracking flow, not just a single API call.

Gotchas and Tips

• 2.0.0 is a major release: PHP 8.x support is the headline. Treat it as a runtime upgrade checkpoint. If your CI or production host is on PHP 7.x, pin to ^1.0 until upgraded.
• Removed Psalm and updated PHP CS Fixer are development/CI changes, not runtime features. Update CI configs that still reference Psalm, and expect possible formatting diffs from the CS Fixer update.
• After changing Shiprocket credentials or pickup settings, clear Laravel config cache. Packages that read config during service-provider boot can otherwise use stale values.
• Shiprocket validation failures often return detailed field-level errors. Log the full response body for failed requests, not just the HTTP status, or debugging order creation becomes guesswork.
• Token expiry and invalid-token responses should trigger a single re-authentication and retry, not an unbounded retry loop.
• Payloads are strict: dates, pincodes, phone numbers, SKUs, weights, and dimensions must be normalized before submission. Use Laravel validation and a DTO to catch issues before the API does.
• Response shapes can vary by endpoint and error type. Centralize response parsing in your wrapper and avoid assuming every response has the same data structure.
• Queue API calls and use conservative retries with backoff. Be especially careful retrying order creation; without an idempotency guard you can create duplicate orders.
• If you consume Shiprocket webhooks, make handlers idempotent and verify any available signature/secret. Status updates may arrive more than once.
• Useful extension points: published config, package service binding overrides, and HTTP middleware/logging around the package client. Check the README for the exact facade alias and service provider registration before wiring it into your app.