tombroucke/wefact-php-client

There is no license information available for the latest version (dev-main) of this package.

dev-main 2025-10-05 09:40 UTC

Requires

• fansipan/fansipan: ^1.4
• guzzlehttp/guzzle: ^7.10

Requires (Dev)

• laravel/pint: ^1.25
• pestphp/pest: ^4.1
• phpstan/phpstan: ^2.1
• vlucas/phpdotenv: ^5.6

Unknown License

• Tom Broucke

README

A modern PHP client library for the WeFact API, providing a simple and elegant way to interact with WeFact's online administration platform.

Installation

Install the package via Composer:

composer require tombroucke/wefact-php-client

Quick Start

<?php

require 'vendor/autoload.php';

use Otomaties\Wefact\Client;
use Otomaties\Wefact\Request;

// Initialize the client
$client = new Client(
    apiKey: 'your-wefact-api-key',
    baseUri: 'https://api.mijnwefact.nl/v2' // Optional, defaults to WeFact API v2
);

// List all debtors
$request = new Request(
    controller: 'debtor',
    action: 'list'
);

$response = $client->send($request);
$data = json_decode($response->getBody(), true);

if ($data['status'] === 'success') {
    foreach ($data['debtors'] as $debtor) {
        echo "Customer: " . $debtor['CompanyName'] . "\n";
    }
}

Configuration

API Key

Get your API key from your WeFact administration:

1. Go to "Settings" → "API"
2. Generate or copy your API key
3. Add your server IP address to the whitelist

Usage Examples

Working with Debtors (Customers)

List All Debtors

$request = new Request(
    controller: 'debtor',
    action: 'list'
);

$response = $client->send($request);
$data = json_decode($response->getBody(), true);

Get Specific Debtor

$request = new Request(
    controller: 'debtor',
    action: 'show',
    parameters: ['DebtorCode' => 'DB10000']
);

$response = $client->send($request);
$data = json_decode($response->getBody(), true);

if ($data['status'] === 'success') {
    $debtor = $data['debtor'];
    echo "Company: " . $debtor['CompanyName'] . "\n";
    echo "Email: " . $debtor['EmailAddress'] . "\n";
    echo "Address: " . $debtor['Address'] . "\n";
}

Create New Debtor

$request = new Request(
    controller: 'debtor',
    action: 'add',
    parameters: [
        'CompanyName' => 'Example Company B.V.',
        'EmailAddress' => '[e-mail]',
        'Address' => 'Example Street 123',
        'ZipCode' => '1234 AB',
        'City' => 'Amsterdam',
        'Country' => 'NL'
    ]
);

$response = $client->send($request);

Working with Invoices

List Invoices

$request = new Request(
    controller: 'invoice',
    action: 'list'
);

$response = $client->send($request);

Create Invoice

$request = new Request(
    controller: 'invoice',
    action: 'add',
    parameters: [
        'DebtorCode' => 'DB10000',
        'InvoiceLines' => [
            [
                'Description' => 'Web development services',
                'PriceExcl' => 100.00,
                'Quantity' => 8,
                'TaxPercentage' => 21
            ]
        ]
    ]
);

$response = $client->send($request);

Filtering and Date Ranges

WeFact API supports filtering on modified dates to efficiently sync data:

$request = new Request(
    controller: 'debtor',
    action: 'list',
    parameters: [
        'modified' => [
            'from' => '2024-01-01 00:00:00',
            'to' => '2024-12-31 23:59:59'
        ]
    ]
);

Available Controllers

The WeFact API supports various controllers for different entities:

• debtor - Customer management
• invoice - Invoice operations
• creditinvoice - Credit notes
• recurring - Recurring invoices
• product - Product catalog
• group - Customer groups
• subscription - Subscription management

Response Handling

All API responses follow a consistent structure:

$response = $client->send($request);
$data = json_decode($response->getBody(), true);

// Check if request was successful
if ($data['status'] === 'success') {
    $debtor = $data['debtor'];
}

Error Handling

try {
    $response = $client->send($request);
    $data = json_decode($response->getBody(), true);

    if ($data['status'] !== 'success') {
        throw new \Exception('API Error: '.$data['errors'][0]);
    }

    // Process successful response

} catch (Exception $e) {
    echo "Request failed: " . $e->getMessage() . "\n";
}

Testing

The package includes comprehensive tests using Pest PHP:

# Run tests
./vendor/bin/pest

Test Configuration

Create a .env file in the project root for testing:

WEFACT_API_KEY=your-test-api-key

API Documentation

For complete API documentation, visit:

• WeFact API Documentation
• Customer/Debtor Endpoints
• API Rate Limits
• Error Handling

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.