Laravel + Exact Online: boekhouding API koppeling bouwen

// app/Models/ExactToken.php
class ExactToken extends Model
{
    protected $fillable = [
        'division',
        'access_token',
        'refresh_token',
        'expires_at',
    ];

    protected $casts = [
        'expires_at' => 'datetime',
    ];

    public function isExpired(): bool
    {
        // Buffer van 60 seconden om race conditions te voorkomen
        return $this->expires_at->subMinutes(1)->isPast();
    }
}

// app/Services/ExactOnlineService.php
class ExactOnlineService
{
    public function __construct(
        private readonly Http $http,
        private ExactToken $token,
    ) {}

    private function getValidToken(): string
    {
        if ($this->token->isExpired()) {
            $this->token = $this->refreshToken($this->token);
        }

        return $this->token->access_token;
    }

    private function refreshToken(ExactToken $token): ExactToken
    {
        $response = Http::asForm()->post(
            'https://start.exactonline.nl/api/oauth2/token',
            [
                'grant_type'    => 'refresh_token',
                'refresh_token' => $token->refresh_token,
                'client_id'     => config('services.exact.client_id'),
                'client_secret' => config('services.exact.client_secret'),
            ]
        );

        if ($response->failed()) {
            // Token is ongeldig — admin moet opnieuw autoriseren
            throw new ExactAuthorizationException(
                'Exact Online token kon niet worden vernieuwd. Herverbinding vereist.'
            );
        }

        return $token->update([
            'access_token'  => $response->json('access_token'),
            'refresh_token' => $response->json('refresh_token'),
            'expires_at'    => now()->addSeconds($response->json('expires_in')),
        ]);
    }

    public function get(string $endpoint, array $params = []): array
    {
        $response = Http::withToken($this->getValidToken())
            ->get("https://start.exactonline.nl/api/v1/{$this->token->division}/{$endpoint}", $params);

        if ($response->status() === 401) {
            // Token is verlopen ondanks refresh — gooi specifieke exception
            throw new ExactAuthorizationException('Exact Online autorisatie verlopen.');
        }

        $response->throw(); // Gooit exception bij andere HTTP-fouten

        return $response->json('d.results', []);
    }
}

// app/Services/ExactDebiteurService.php
class ExactDebiteurService
{
    public function __construct(private ExactOnlineService $exact) {}

    public function aanmakenOfUpdaten(Customer $customer): string
    {
        // Controleer of de debiteur al bestaat op basis van e-mailadres
        $bestaand = $this->exact->get('crm/Accounts', [
            '$filter' => "Email eq '{$customer->email}'",
            '$select' => 'ID,Code',
        ]);

        if (! empty($bestaand)) {
            $this->updaten($bestaand[0]['ID'], $customer);
            return $bestaand[0]['ID'];
        }

        return $this->aanmaken($customer);
    }

    private function aanmaken(Customer $customer): string
    {
        $response = Http::withToken($this->exact->getAccessToken())
            ->post("https://start.exactonline.nl/api/v1/{$this->exact->getDivision()}/crm/Accounts", [
                'Name'           => $customer->company_name ?? $customer->full_name,
                'Email'          => $customer->email,
                'Phone'          => $customer->phone,
                'AddressLine1'   => $customer->address,
                'Postcode'       => $customer->postcode,
                'City'           => $customer->city,
                'Country'        => 'NL',
                'IsSupplier'     => false,
                'IsPurchase'     => false,
                'IsSales'        => true,
            ]);

        $response->throw();

        return $response->json('d.ID');
    }
}

// app/Services/ExactFactuurService.php
class ExactFactuurService
{
    public function aanmaken(Order $order, string $exactDebiteurId): string
    {
        $entryLines = $order->items->map(fn($item) => [
            'Item'        => $this->getExactArtikelId($item->sku),
            'Quantity'    => $item->quantity,
            'UnitPrice'   => $item->price_excl_vat,
            'VATCode'     => $item->vat_rate === 21 ? '2' : '1',
            'Description' => $item->name,
        ])->toArray();

        // Voeg verzendkosten toe als aparte regel
        if ($order->shipping_cost > 0) {
            $entryLines[] = [
                'GLAccount'   => config('services.exact.shipping_gl_account'),
                'Quantity'    => 1,
                'UnitPrice'   => $order->shipping_cost_excl_vat,
                'VATCode'     => '2',
                'Description' => 'Verzendkosten',
            ];
        }

        $payload = [
            'Customer'          => $exactDebiteurId,
            'YourRef'           => $order->order_number,
            'Description'       => "Order {$order->order_number}",
            'Journal'           => config('services.exact.sales_journal'),
            'EntryDate'         => $order->created_at->format('Y-m-d') . 'T00:00:00',
            'PaymentCondition'  => $order->payment_term ?? '30',
            'SalesEntryLines'   => $entryLines,
        ];

        $response = $this->exact->post('salesentry/SalesEntries', $payload);

        return $response['EntryNumber'];
    }
}

// database/migrations/create_exact_article_mappings_table.php
Schema::create('exact_article_mappings', function (Blueprint $table) {
    $table->id();
    $table->string('sku')->unique();
    $table->string('exact_item_id', 36);
    $table->timestamps();
});

public function syncArtikel(Product $product): string
{
    $bestaand = $this->exact->get('logistics/Items', [
        '$filter' => "Code eq '{$product->sku}'",
        '$select' => 'ID',
    ]);

    if (! empty($bestaand)) {
        return $bestaand[0]['ID'];
    }

    $response = $this->exact->post('logistics/Items', [
        'Code'        => $product->sku,
        'Description' => $product->name,
        'SalesPrice'  => $product->price_excl_vat,
        'IsSalesItem' => true,
    ]);

    return $response['ID'];
}

// app/Jobs/SyncOrderToExact.php
class SyncOrderToExact implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public int $tries = 5;
    public int $backoff = 60; // Seconden tussen retries

    public function __construct(private readonly int $orderId) {}

    public function handle(ExactFactuurService $service): void
    {
        $order = Order::findOrFail($this->orderId);

        try {
            $factuurNummer = $service->aanmaken($order, $order->exact_debtor_id);

            $order->update([
                'exact_invoice_number' => $factuurNummer,
                'synced_to_exact_at'   => now(),
            ]);
        } catch (ExactRateLimitException $e) {
            // Wacht op basis van de Retry-After header van Exact
            $this->release($e->retryAfter ?? 60);
        } catch (ExactAuthorizationException $e) {
            // Stuur alert naar admin — handmatige actie nodig
            Notification::route('mail', config('services.exact.admin_email'))
                ->notify(new ExactAuthorizationAlert($e->getMessage()));

            $this->fail($e);
        }
    }
}

Order geplaatst in webshop
         ↓
SyncOrderToExact::dispatch($orderId)
         ↓
Queue worker pakt job op
         ↓
ExactOnlineService doet API-calls
         ↓
Order krijgt exact_invoice_number
         ↓
Bevestiging naar ERP/warehouse