Intégration API Pennylane dans CRM maison pour contrats, factures, etc

Contexte
Nous avons un CRM maison. Nous utilisons Pennylane pour la facturation. Nous voulons supprimer la double saisie et automatiser la création de contrats, la génération de factures (y compris facturation en plusieurs échéances) et l’envoi des données vers Pennylane via son API (et réception dans notre outil).

Objectif business
1 Créer un contrat en sélectionnant des produits issus du catalogue Pennylane
2 Générer une ou plusieurs factures pour un même contrat (facture unique, échelonnement, factures récurrentes)
3 Pousser automatiquement les informations vers Pennylane pour que les factures soient créées sans ressaisie
4 Mettre en place des abonnements automatiques pour nos clients, notamment des paiements en 2 ou 4 fois sans frais pour leur audit (selon ce que permet Pennylane)

Périmètre fonctionnel détaillé

A Synchronisation catalogue produits Pennylane vers CRM
• Recherche produits Pennylane depuis Appolo (typeahead, filtre, pagination)
• Récupération et stockage local des champs nécessaires (id produit Pennylane, libellé, prix, TVA, unité, compte si nécessaire)
• Gestion mises à jour (sync planifiée et ou à la demande)
• Gestion multi TVA : 0 8.5 20%

B Gestion clients et tiers
• Depuis Appolo, à la création d’un contrat, associer un client existant ou en créer un
• Si le client n’existe pas dans Pennylane, création automatique du client via API
• Mapping des champs client (raison sociale, email, adresse, SIREN/SIRET si B2B, TVA intracom, conditions de paiement)
• Déduplication simple (par exemple email et SIRET) avec règles explicites

C Contrats dans CRM
• Un contrat contient
• Client
• Produits et quantités
• Conditions de facturation (unique, multi factures, récurrent)
• Dates (signature, début, fin si abonnement)
• Échéancier si paiement en plusieurs fois
• Statuts (brouillon, validé, en cours, terminé, annulé)
• Un contrat peut générer plusieurs factures
• Facture d’acompte + solde
• 2 ou 4 échéances
• Facturation récurrente mensuelle ou autre périodicité

D Génération de factures depuis CRM ?
• Bouton ou action “Générer facture(s)” sur un contrat
• Prévisualisation avant envoi (montants, TVA, dates, échéances)
• Création dans Pennylane via API
• Création facture brouillon ou définitive selon règle définie
• Ajout des lignes produits avec références Pennylane
• Ajout des mentions nécessaires (référence contrat, période audit, etc.)
• Retour et stockage dans CRM
• id facture Pennylane
• numéro facture si disponible
• url ou lien Pennylane si disponible
• statut (brouillon, envoyée, payée, annulée) selon ce que l’API expose

E Abonnements et paiements en plusieurs fois
• Mise en place d’un mécanisme d’échéancier dans CRM
• 2 ou 4 échéances, dates, montants
• Génération automatique des factures à chaque échéance (job planifié)
• Paiement

Le freelance doit analyser le support réel de Pennylane concernant le paiement fractionné et proposer l’architecture
• Gestion des échecs
• relance, statut “échec”, notifications internes, reprise manuelle

F Synchronisation statuts et événements
• Récupération périodique des statuts factures et paiements depuis Pennylane
• Idéalement webhooks si disponibles, sinon polling planifié
• Mise à jour automatique dans CRM (payée, partiellement payée, en retard)

Exigences techniques

Architecture et intégration
• Le freelance doit s’adapter à notre stack (PHP 8)
• Intégration via un service d’intégration dédié (recommandé) plutôt que logique dispersée dans le front
• API Pennylane
• Authentification sécurisée (stockage secrets, rotation, env variables)
• Gestion pagination, rate limit, retries, idempotence

Qualité, robustesse, traçabilité
• Journalisation complète
• logs d’appels API, erreurs, payloads masqués (RGPD)
• corrélation contrat → factures → événements
• Gestion des erreurs et reprises
• file d’attente ou table de tâches “à rejouer”
• états explicites “envoi en cours”, “en échec”, “confirmé”
• Tests
• tests unitaires et tests d’intégration sur endpoints clés
• Documentation
• mapping des champs
• procédures d’exploitation
• guide de déploiement
• guide utilisateur côté CRM

Sécurité et conformité
• RGPD
• minimisation des données envoyées et stockées
• masquage des logs
• Gestion des droits
• qui peut créer un contrat, générer une facture, annuler
• Environnements
• dev, staging, production
• clés API séparées

Livrables attendus
• Spécification technique courte validée avant dev (mapping, flux, statuts)
• Code source propre, versionné (Git)
• Scripts de migration si besoin (tables factures, mapping ids)
• Documentation d’exploitation et d’usage
• Mise en production assistée
• Période de garantie correctifs (ex 15 jours)
• Option maintenance mensuelle (à chiffrer séparément)
- Usage de Jira obligatoire, s'intégrer dans notre environnement Jira et Git

Merci de me transmettre :
1 Références concrètes sur intégrations Pennylane ou outils compta proches (liens, descriptions, rôle exact)
2 Proposition d’architecture (service dédié, jobs planifiés, webhooks si possible)
3 Gestion du paiement fractionné 2x/4x sans frais
4 Estimation détaillée
• découpage par lots (MVP puis itérations)
• charge et délai par lot
5 Plan de tests et stratégie de reprise en cas d’échec API
6 Modalités de support après livraison

Critères de sélection
• Expérience démontrée d’intégrations API compta facturation et synchronisation bi directionnelle
• Capacité à gérer les cas réels (idempotence, retries, statuts, erreurs)
• Qualité de code, tests, documentation
• Approche produit et fiabilité opérationnelle, pas juste “ça marche sur mon poste”

• Stack CRM : PHP, MariaDB, aucune framework
• Mode d’auth Pennylane disponible (clé API, environnement sandbox)
• nombre de contrats par mois : 350
• nombre de factures par mois : 600
• nombre de produits au catalogue : 30