PHP SDK

composer require vasbox/vasbox-php

<?php

use VasBox\VasBox;

// Initialize with API key
$vasbox = new VasBox(env('VASBOX_API_KEY'));

// Or with additional options
$vasbox = new VasBox(env('VASBOX_API_KEY'), [
    'environment' => 'sandbox', // or 'production'
    'timeout' => 30,
    'retry' => [
        'enabled' => true,
        'max_attempts' => 3,
    ],
]);

<?php

// Create an invoice
$invoice = $vasbox->invoices->create([
    'customer_id' => 'cust_123',
    'currency' => 'USD',
    'items' => [
        [
            'description' => 'Software License',
            'quantity' => 1,
            'unit_price' => 299.00,
            'tax_code' => 'STD',
        ],
    ],
    'notes' => 'Thank you for your business!',
]);

echo "Invoice ID: " . $invoice->id;
echo "Invoice Number: " . $invoice->number;

// List invoices with filters
$invoices = $vasbox->invoices->list([
    'status' => 'draft',
    'from' => '2024-01-01',
    'per_page' => 50,
]);

foreach ($invoices->data as $inv) {
    echo $inv->number . ": " . $inv->total;
}

// Get a specific invoice
$invoice = $vasbox->invoices->get('inv_abc123');

// Submit to ZIMRA
$result = $vasbox->invoices->submit('inv_abc123');
echo "Fiscal Code: " . $result->fiscal_code;

<?php

// Create a customer
$customer = $vasbox->customers->create([
    'name' => 'Acme Corporation',
    'email' => 'billing@acme.com',
    'tin' => '123456789',
    'address' => [
        'line1' => '123 Main Street',
        'city' => 'Harare',
        'country' => 'ZW',
    ],
]);

// Update a customer
$customer = $vasbox->customers->update('cust_123', [
    'email' => 'finance@acme.com',
]);

// Search customers
$customers = $vasbox->customers->list([
    'search' => 'acme',
]);

<?php

use VasBox\VasBox;
use VasBox\Exceptions\ValidationException;
use VasBox\Exceptions\AuthenticationException;
use VasBox\Exceptions\ResourceNotFoundException;
use VasBox\Exceptions\RateLimitException;
use VasBox\Exceptions\ZimraException;

try {
    $invoice = $vasbox->invoices->create([...]);
} catch (ValidationException $e) {
    // Validation failed
    echo "Validation errors:";
    foreach ($e->getErrors() as $field => $messages) {
        echo "  $field: " . implode(', ', $messages);
    }
} catch (AuthenticationException $e) {
    // Invalid API key
    echo "Authentication failed: " . $e->getMessage();
} catch (ResourceNotFoundException $e) {
    // Resource not found
    echo "Not found: " . $e->getMessage();
} catch (RateLimitException $e) {
    // Rate limit exceeded
    echo "Rate limited. Retry after: " . $e->getRetryAfter() . " seconds";
} catch (ZimraException $e) {
    // ZIMRA submission failed
    echo "ZIMRA error: " . $e->getZimraCode();
    echo "Details: " . $e->getZimraMessage();
} catch (\Exception $e) {
    // Other errors
    echo "Error: " . $e->getMessage();
}

<?php

// Auto-pagination helper
$allInvoices = $vasbox->invoices->all([
    'status' => 'submitted',
]);

foreach ($allInvoices as $invoice) {
    echo $invoice->number;
}

// Manual pagination
$page = 1;
do {
    $result = $vasbox->invoices->list([
        'page' => $page,
        'per_page' => 100,
    ]);

    foreach ($result->data as $invoice) {
        processInvoice($invoice);
    }

    $page++;
} while ($result->meta->current_page < $result->meta->last_page);

<?php

use VasBox\Webhook;

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_VASBOX_SIGNATURE'];

$event = Webhook::verify($payload, $signature, env('VASBOX_WEBHOOK_SECRET'));

switch ($event->type) {
    case 'invoice.submitted':
        handleInvoiceSubmitted($event->data);
        break;
    case 'invoice.failed':
        handleInvoiceFailed($event->data);
        break;
}