Firm API (cabinets d'expertise comptable)¶

Les cabinets d'expertise comptable disposent d'une API dédiée pour travailler sur l'ensemble de leur portefeuille de dossiers clients : lister les sociétés qu'ils gèrent, lire et poster des écritures comptables, téléverser des documents, lancer des exports, le tout pour chaque dossier client.

Dossiers clients et jeton¶

<?php

use Pennylane\Sdk\PennylaneFirm;

$firm = new PennylaneFirm(); // lit PENNYLANE_FIRM_API_TOKEN

Le jeton est généré depuis votre compte cabinet (aucun bac à sable nécessaire). La Firm API est soumise à une limite de débit de 5 requêtes par seconde ; le SDK applique une régulation de débit en conséquence.

Un jeton cabinet atteint de vrais dossiers clients

Il n'existe pas de bac à sable pour la Firm API : chaque appel authentifié avec un jeton cabinet agit sur les données réelles d'un dossier client. Testez avec prudence, en particulier avant de poster des écritures comptables ou de lancer des exports, car une erreur affecte la comptabilité réelle d'un client, pas un compte de test jetable.

Parcourir votre portefeuille¶

foreach ($firm->companies->list() as $company) {
    echo $company->id . ' ' . $company->name . ' ' . $company->siren . PHP_EOL;
}

Toute autre ressource prend l'identifiant du dossier client comme premier argument :

$companyId = 4217;

// Exercices fiscaux
foreach ($firm->fiscalYears->list($companyId) as $fy) {
    echo $fy->start->format('Y-m-d') . ' ' . $fy->finish->format('Y-m-d') . PHP_EOL;
}

// Balance générale sur une période
foreach ($firm->trialBalance->list(
    $companyId,
    periodStart: '2026-01-01',
    periodEnd: '2026-06-30',
) as $row) {
    echo $row->number . ' ' . $row->debits . ' ' . $row->credits . PHP_EOL;
}

Trois endpoints paginent par numéro de page

La plupart des endpoints de liste paginent par curseur, mais trois endpoints de la Firm API paginent au contraire avec page et perPage : companies, fiscalYears et trialBalance. Ils renvoient un NumberedPage avec des propriétés totalPages et currentPage au lieu du CursorPage habituel. Itérer avec foreach parcourt de toute façon toutes les pages de façon transparente.

Poster des écritures comptables¶

$firm->ledgerEntries->create(
    $companyId,
    date: '2026-07-08',
    label: 'OD de régularisation',
    journalId: 12,
    ledgerEntryLines: [
        ['ledger_account_id' => 411, 'debit' => '120.00', 'credit' => '0.00'],
        ['ledger_account_id' => 706, 'debit' => '0.00', 'credit' => '120.00'],
    ],
);

Comme sur la Company API, chaque ligne d'écriture doit porter à la fois une clé debit et une clé credit ("0.00" sur le côté non utilisé), et les lignes doivent être équilibrées.

Documents (DMS)¶

La ressource DMS, réservée aux cabinets, gère la bibliothèque documentaire de chaque dossier client :

use Pennylane\Sdk\FileUpload;

$firm->dms->folders->list($companyId);
$firm->dms->files->upload($companyId, FileUpload::fromPath('path/to/piece.pdf'));

Exports¶

$export = $firm->exports->fecs->create($companyId, periodStart: '2026-01-01', periodEnd: '2026-12-31');
$export = $firm->exports->fecs->get($companyId, $export->id); // interroger jusqu'à ce que status soit "done"

Endpoints de facturation en bêta, lecture seule¶

La Firm API peut lire les factures clients et fournisseurs d'un dossier client, mais cette surface est en bêta et en lecture seule : uniquement list() et get(), sans création ni changement d'état.

foreach ($firm->customerInvoices->list($companyId) as $invoice) {
    // ...
}
$firm->supplierInvoices->get($companyId, $supplierInvoiceId);

La création de factures et les actions de cycle de vie (finaliser, envoyer, marquer comme payée, etc.) se font via l'API Company propre à chaque dossier client, avec son propre PENNYLANE_API_TOKEN.

Synchronisation de masse¶

Les changelogs permettent de synchroniser de nombreux dossiers clients de façon incrémentale, sans tout relire :

foreach ($firm->companies->list() as $company) {
    foreach ($firm->changelogs->ledgerEntryLines($company->id) as $event) {
        // ...
    }
}

Scopes Company vs Firm

La Firm API est en lecture-écriture sur la comptabilité (écritures, comptes, journaux, banque) mais en lecture seule sur la facturation (factures clients et fournisseurs, en bêta). La création de factures se fait via l'API Company propre à chaque dossier client.