Download the PHP package zelovance/php-sdk without Composer

Zelovance PHP SDK

SDK PHP autonome pour l’API publique Zelovance /api/v1.

Fonctionnalités de la version 0.2.0-beta.2

• authentification par clé API technique Bearer ;
• liste et consultation des contacts ;
• liste et consultation des factures ;
• création de factures brouillon ;
• création, lecture et modification partielle d’articles du catalogue ;
• lignes item, titres section et notes note ;
• pagination Laravel ;
• exceptions dédiées pour les réponses 401, 403, 404, 405, 409, 422 et 429 ;
• vérification des signatures HMAC des webhooks ;
• transport HTTP natif cURL, sans dépendance tierce.

Les contacts restent volontairement en lecture seule. L’émission, la modification et la suppression des factures ne sont pas exposées par le SDK, conformément au contrat public actuel.

Cette préversion est destinée au bêta-test avec https://dev.zelovance.com. Les endpoints Articles ne sont pas annoncés comme disponibles en production.

Prérequis

• PHP 8.2 ou supérieur ;
• extension curl ;
• extension json ;
• Composer 2.

Installation locale avec Composer

Décompressez l’archive dans votre application :

Déclarez ensuite le dépôt local et installez le package :

Depuis v0.2.0-beta.1, la mise à niveau vers v0.2.0-beta.2 est compatible : products()->create() conserve sa signature et les méthodes de lecture et de modification sont ajoutées.

Pour éviter un lien symbolique vers le dossier du package :

Configuration

Ne stockez pas la clé API dans le code source.

Dans Laravel, placez ces valeurs dans .env, puis exposez-les par un fichier de configuration. Dans un script PHP classique, chargez-les avec votre gestionnaire d’environnement habituel.

Initialisation

Lister les contacts

Parcourir automatiquement toutes les pages :

Consulter un contact :

Créer une facture avec titres de section

Créer, lire et modifier un article en bêta-test

Ces exemples utilisent l’environnement de développement. La clé API technique doit disposer de product:create, product:read ou product:update selon l’opération. L’article obtenu peut ensuite être référencé dans une ligne de facture avec son UUID.

Lister ou parcourir les articles visibles du catalogue :

Modifier un article par PATCH :

Les seuls champs acceptés à la création et en modification sont name, code, type, description, unit_price, unit et vat_rate. Une modification doit contenir au moins un de ces champs. Les statuts de catalogue et d’activation, la devise, le type de vente, les catégories et les champs internes restent gérés par l’API et sont refusés localement par le SDK.

Pour ne pas afficher d’unité sur une ligne, utilisez unit: '' ou unit: 'none'. Le builder normalise une chaîne vide vers la valeur API none.

Le SDK accepte aussi directement le tableau conforme au contrat API :

Lire les factures

Gestion des erreurs

Lors de la création d’une facture, une même idempotency_key ne doit être réutilisée qu’avec exactement le même contenu. Un rejeu identique renvoie la facture existante. Si le contenu est modifié, l’API répond avec HTTP 409 et le SDK lève IdempotencyConflictException ; utilisez alors une nouvelle clé d’idempotence.

Vérifier un webhook

La signature est vérifiée sur le corps JSON brut, avant son décodage.

Tests locaux du package

Après installation avec Composer :

Limites de cette première version

• aucune création ou modification de contact ;
• aucune modification, suppression ou émission de facture ;
• aucune suppression, archivage ou catégorisation d’article ;
• les résultats sont retournés sous forme de tableaux PHP afin de conserver le contrat JSON sans perte ;
• les paramètres de filtrage des listes sont transmis tels quels, mais seuls ceux réellement pris en charge par l’API Zelovance auront un effet.

Licence

Ce SDK est distribué sous licence MIT. Consultez LICENSE.