docs-dispatcher.io/sdk

PHP client to consume docs-dispatcher.io API services

v0.7.0 2025-12-30 20:24 UTC

Requires

• php: >=8.1
• guzzlehttp/guzzle: ^6.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.50
• phpunit/phpunit: ^10

MIT

• Olivier Roelants

README

DocsDispatcher PHP Client

Versions

SDK version	PHP version	Branch
v0.1.x	7.2+	php-7x
v0.2.x	8.1+	develop

Installation

$ composer require docs-dispatcher.io/sdk

Getting started

Concepts

This library relays on the following concepts in order to be able to use it with a minimal knowledge of the API itself.

Authentication

Two authentication methods are supported:

• Basic Auth (username/password)
• Bearer Token (JWT token) - recommended for API v3.6+

Service(s)

A service is an API endpoint having its own parameters. For a detailed list of them, please read the API documentation, also available as Swagger format.

ServiceMediator

A single class that will be in charge to temporary store your defined services and their corresponding configurations in order to build the request to be sent to the API.

Client

The class that actually triggers calls to API. It decorates a GuzzleHttp\Client instance.

Usage

A realistic usage can be found in the attached sample file exemple.php. For more details about configuring each services, please refer to the API documentation.

Authentication Examples

Using Bearer Token (JWT) - Recommended:

use DocsDispatcherIo\Sdk\Authentication\BearerTokenAuthentication;
use DocsDispatcherIo\Sdk\Client;

$authentication = new BearerTokenAuthentication('your-jwt-token-here');
$client = new Client($authentication);

Using Basic Auth:

use DocsDispatcherIo\Sdk\Authentication\BasicAuthAuthentication;
use DocsDispatcherIo\Sdk\Client;

$authentication = new BasicAuthAuthentication('username', 'password');
$client = new Client($authentication);

Available Services

The SDK supports the following services:

• EmailService: Send emails with attachments
• FileService: Generate documents from templates
• SmsService: Send SMS messages
• PostalService: Send postal mail
• ESignService: Handle electronic signatures
• UploadService: Upload files to external services
• InvoicingService: Create invoices, quotes, or credit notes (IpaidThat, Qonto, Stripe)

Invoicing Service Example

use DocsDispatcherIo\Sdk\Argument\Address;
use DocsDispatcherIo\Sdk\Argument\Enums\CustomerTypes;
use DocsDispatcherIo\Sdk\Argument\Enums\DiscountTypes;
use DocsDispatcherIo\Sdk\Argument\Enums\InvoiceDocumentTypes;
use DocsDispatcherIo\Sdk\Argument\InvoiceCustomer;
use DocsDispatcherIo\Sdk\Argument\InvoiceItem;
use DocsDispatcherIo\Sdk\Service\InvoicingService;
use DocsDispatcherIo\Sdk\ServiceMediator;

// Create customer billing address
$billingAddress = new Address(
    'Acme Corp',           // Name
    '123 Main Street',     // Address
    '75001',               // Postal code
    'Paris',               // City
    'FR'                   // Country code
);

// Create a company customer
$customer = new InvoiceCustomer(
    CustomerTypes::COMPANY,
    '[e-mail]',
    $billingAddress
);
$customer
    ->setName('Acme Corporation')
    ->setVatNumber('FR12345678901')
    ->setRegistrationNumber('123456789')
    ->setPhone('[phone]');

// Create invoice items
$item1 = new InvoiceItem('Consulting Services', 150.00);
$item1
    ->setQuantity(10.0)
    ->setTaxPercent(20.0)
    ->setAdditionalInfo('Monthly retainer');

$item2 = new InvoiceItem('Development Services', 200.00);
$item2
    ->setQuantity(5.0)
    ->setTaxPercent(20.0)
    ->setDiscount(DiscountTypes::PERCENTAGE, 10.0, 'Volume discount');

// Create the invoicing service
$invoicingService = new InvoicingService(
    $customer,
    [$item1, $item2],
    InvoiceDocumentTypes::INVOICE,
    '2025-11-20'  // Issue date
);

$invoicingService
    ->setProvider('ipaidthat')  // or 'qonto' or 'stripe'
    ->setTitle('Monthly Services Invoice')
    ->setExternalId('INV-2025-001')
    ->setCurrency('EUR')
    ->setLocale('fr_FR')
    ->setDueDate('2025-12-31')
    ->setShipping(25.50)
    ->setDiscount(DiscountTypes::PERCENTAGE, 5.0, 'Early payment discount')
    ->setSendByEmail(true)
    ->addRecipientEmail('[e-mail]')
    ->setSendCopy(true);

$serviceMediator = new ServiceMediator([$invoicingService]);
$response = $client->executeRequest($serviceMediator, 'application/json');

Customer Types:

• CustomerTypes::COMPANY - For businesses (requires name, registrationNumber, vatNumber)
• CustomerTypes::INDIVIDUAL - For consumers (requires firstname, lastname)
• CustomerTypes::FREELANCE - For freelancers (requires firstname, lastname, optional businessName, registrationNumber, vatNumber)

Document Types:

• InvoiceDocumentTypes::INVOICE - Standard invoice
• InvoiceDocumentTypes::E_INVOICE - Electronic invoice (e-facture)
• InvoiceDocumentTypes::QUOTE - Quotation/estimate
• InvoiceDocumentTypes::CREDIT - Credit note