Aller au contenu

Bien démarrer

De zéro à vos premiers appels à l'API Pennylane en quelques minutes.

1. Installer le paquet

composer require goatandcow7/pennylane-sdk

PHP 8.2 ou supérieur est requis. Le SDK dialogue en HTTP via PSR-18 ; si aucun client PSR-18 ni fabriques PSR-17 ne sont déjà présents dans votre projet, ajoutez Guzzle :

composer require guzzlehttp/guzzle

et autorisez le plugin de découverte une fois dans composer.json :

"config": {
    "allow-plugins": {
        "php-http/discovery": true
    }
}

2. Obtenir un jeton d'API

Le SDK dialogue avec deux API Pennylane distinctes, chacune avec son propre jeton :

Company API (vous gérez la comptabilité et la facturation d'une seule société) :

  1. Connectez-vous à Pennylane avec un compte administrateur.
  2. Allez dans Paramètres > Connectivité > Développeurs.
  3. Créez un jeton : donnez-lui un nom, choisissez les permissions (lecture seule, ou lecture et écriture) et une date d'expiration.
  4. Copiez-le immédiatement : Pennylane ne l'affiche qu'une seule fois.

Firm API (vous êtes un cabinet d'expertise comptable travaillant sur plusieurs dossiers clients) : générez un jeton Firm depuis les paramètres de votre compte cabinet.

3. Configurer le jeton

La méthode recommandée est une variable d'environnement, pour que le jeton ne se retrouve jamais dans votre code :

export PENNYLANE_API_TOKEN="your-token"        # Company API
export PENNYLANE_FIRM_API_TOKEN="your-token"   # Firm API

<?php

use Pennylane\Sdk\Pennylane;

$client = new Pennylane(); // récupère PENNYLANE_API_TOKEN

Vous pouvez aussi le passer explicitement, par exemple lorsqu'un même processus gère plusieurs sociétés :

$client = new Pennylane(apiToken: 'your-token');

4. Premiers appels

Récupérez l'identité liée au jeton courant :

$me = $client->me->retrieve();
print_r($me);

Si le jeton est valide, vous récupérez le profil de votre société. Sinon, le SDK lève une Pennylane\Sdk\Exception\AuthenticationException.

Lister des factures :

foreach ($client->customerInvoices->list(limit: 20) as $invoice) {
    echo $invoice->invoiceNumber . ' ' . $invoice->currencyAmount . PHP_EOL;
}

Créer un produit :

use Pennylane\Sdk\Exception\ValidationException;

try {
    $product = $client->products->create(
        label: 'Journée de conseil',
        priceBeforeTax: '450.00',
        vatRate: 'FR_200',
    );
    echo $product->id . PHP_EOL;
} catch (ValidationException $e) {
    echo $e->getMessage() . PHP_EOL;
}

Les montants sont toujours passés sous forme de chaînes numériques ('450.00'), jamais de flottants PHP : les flottants perdraient de la précision décimale sur des données comptables, et le SDK les rejette.

5. Gestion des erreurs, les bases

Toute exception levée par le SDK dérive de Pennylane\Sdk\Exception\PennylaneException, il suffit donc de l'intercepter pour gérer n'importe quel échec du SDK en un seul endroit :

use Pennylane\Sdk\Exception\PennylaneException;

try {
    $client->customerInvoices->finalize($invoiceId);
} catch (PennylaneException $e) {
    echo $e->getMessage() . PHP_EOL;
}

Pour une gestion plus fine, interceptez plutôt la sous-classe spécifique (AuthenticationException, PermissionDeniedException, ValidationException, RateLimitException...). Voir le guide des erreurs et nouvelles tentatives pour la hiérarchie complète et la politique de nouvelles tentatives.

6. Explorer les ressources

Le client expose une propriété par ressource de l'API, en camelCase. Quelques exemples :

Propriété Ce qu'elle gère
$client->customerInvoices Factures de vente et avoirs : création, finalisation, envoi, import de PDF et de factures électroniques
$client->quotes Devis, et leur transformation en factures
$client->customers Clients, avec ->companies (B2B) et ->individuals (B2C)
$client->products Catalogue produits
$client->supplierInvoices Factures d'achat, imports, statut de paiement
$client->transactions Transactions bancaires, rapprochement avec les factures
$client->ledgerEntries Écritures comptables
$client->ledgerEntryLines Lignes d'écriture, lettrage
$client->trialBalance Balance générale
$client->exports Exports FEC, grand livre et analytiques
$client->changelogs Flux de modifications pour synchroniser les données de façon incrémentale

La liste complète se trouve dans le contrat de conception.

7. Options du client

$client = new Pennylane(
    apiToken: null,        // par défaut : variable d'environnement PENNYLANE_API_TOKEN
    baseUrl: null,         // à surcharger pour les proxys
    httpClient: null,      // utilisez votre propre client PSR-18
    requestFactory: null,  // utilisez votre propre fabrique de requêtes PSR-17
    streamFactory: null,   // utilisez votre propre fabrique de flux PSR-17
    autoThrottle: true,    // cadence les requêtes sous la limite de débit de l'API
    maxRetries: 3,         // nouvelles tentatives automatiques (429, erreurs réseau transitoires)
    timeout: 60.0,         // secondes, nécessite Guzzle ou un client injecté
);

Pour aller plus loin