Docdata Orderapi Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cleentfaar/docdata-orderapi
   

   Add the service provider to config/app.php under providers:

   Cleentfaar\DocDataOrderApi\DocDataOrderApiServiceProvider::class,
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="Cleentfaar\DocDataOrderApi\DocDataOrderApiServiceProvider" --tag="config"
   

   Update .env with your DocData API credentials (e.g., DOCDATA_API_KEY, DOCDATA_API_SECRET).

3. First Use Case: Create an Order

   use Cleentfaar\DocDataOrderApi\Facades\DocDataOrderApi;
   
   $order = DocDataOrderApi::createOrder([
       'orderNumber' => 'ORD-12345',
       'amount' => 100.00,
       'currency' => 'EUR',
       'customer' => [
           'email' => '[email protected]',
           'name' => 'John Doe',
       ],
   ]);
   

Implementation Patterns

Core Workflows

1. Order Management

   • Create: Use DocDataOrderApi::createOrder() for new orders.
   • Retrieve: Fetch by orderNumber or id:

     $order = DocDataOrderApi::getOrder('ORD-12345');
     

   • Update: Modify existing orders via DocDataOrderApi::updateOrder().
   • Cancel: Use DocDataOrderApi::cancelOrder() with a reason.

2. Payment Integration

   • Attach payments to orders:

     $payment = DocDataOrderApi::createPayment($orderId, [
         'amount' => 100.00,
         'paymentMethod' => 'ideal',
     ]);
     

   • Check payment status:

     $paymentStatus = DocDataOrderApi::getPaymentStatus($paymentId);
     

3. Webhooks

   • Register a webhook endpoint in config/docdata-orderapi.php:

     'webhook' => [
         'enabled' => true,
         'secret' => env('DOCDATA_WEBHOOK_SECRET'),
         'route' => 'docdata.webhook',
     ],
     

   • Handle events in routes/web.php:

     Route::post('/docdata/webhook', [DocDataWebhookController::class, 'handle']);
     

Integration Tips

• Laravel Events: Trigger custom events on order/payment updates:

  event(new OrderCreated($order));
  

• Queue Jobs: Offload API calls to queues for async processing:

  DocDataOrderApi::dispatchCreateOrder($data)->onQueue('docdata');
  

• Validation: Use Laravel’s validation rules for input:

  $validated = $request->validate([
      'amount' => 'required|numeric|min:0.01',
      'currency' => 'required|in:EUR,USD',
  ]);
  

Gotchas and Tips

Common Pitfalls

1. API Rate Limits

   • DocData may throttle requests. Implement exponential backoff in retries:

     try {
         $response = DocDataOrderApi::getOrder($orderId);
     } catch (RateLimitException $e) {
         sleep($e->retryAfter);
         retry();
     }
     

2. Webhook Verification

   • Always verify webhook payloads using the secret:

     $valid = hash_equals(
         env('DOCDATA_WEBHOOK_SECRET'),
         $request->header('X-DocData-Signature')
     );
     

3. Idempotency

   • Use idempotencyKey for critical operations to avoid duplicate processing:

     $order = DocDataOrderApi::createOrder($data, [
         'idempotencyKey' => 'unique-key-123',
     ]);
     

Debugging Tips

• Enable Logging Add to config/docdata-orderapi.php:

  'debug' => env('APP_DEBUG', false),
  

  Logs will appear in storage/logs/laravel.log.

• Mock API Calls Use Laravel’s HTTP client mocking for testing:

  Http::fake([
      'api.docdata.com/*' => Http::response(['success' => true], 200),
  ]);
  

Extension Points

1. Custom Responses Override default responses by binding a custom handler:

   DocDataOrderApi::extend(function ($api) {
       $api->onResponse(function ($response) {
           // Transform response data
           return $response->transform(function ($data) {
               $data['custom_field'] = 'value';
               return $data;
           });
       });
   });
   

2. Middleware Add middleware to modify requests/responses globally:

   DocDataOrderApi::middleware(function ($request) {
       $request->header('X-Custom-Header', 'value');
   });
   

3. Model Bindings Bind DocData responses to Eloquent models:

   class Order extends Model {
       public static function fromDocData(array $data) {
           return self::create([
               'docdata_id' => $data['id'],
               'amount' => $data['amount'],
           ]);
       }
   }