SDK PHP de l’API Tiers de prestations
L’avance immédiate du crédit d’impôt pour les services à la personne
Le prestataire inscrit son client et transmet ses demandes de paiement ; l’Urssaf prélève au client la part non couverte par le crédit d’impôt et paie le prestataire. Le SDK couvre les quatre méthodes de l’API et tout le cycle de vie, de l’inscription au rapprochement des paiements.
thebeardedbear/urssaf-tiers-prestations
Parler de mon intégration UrssafÀ qui sert cette API
Prestataires de services à la personne et éditeurs de leurs logiciels de facturation qui proposent l’avance immédiate du crédit d’impôt.
- Authentification
- OAuth2 client credentials
- Accès à l’API
- Accès restreint : identifiants délivrés par l’Urssaf après validation de la demande.
Ce que couvre le SDK
010Inscrire un client020Suivre l’appariement (statut de transmission)050Transmettre des demandes de paiement070Rechercher des demandes de paiement
Fonctionnalités
- Authentification OAuth2 avec cache de jeton (PSR-6, PSR-16 ou mémoire), renouvelé avant expiration.
- Multi-tenant : identifiants résolus par client via un CredentialsProvider.
- Validation locale calquée sur les règles officielles (identité, adresse, IBAN, codes nature et activité, totaux, TVA, plafond d’acompte), avec des codes d’erreur stables traduits en français.
- Demandes de paiement envoyées par lots de 10, statuts suivis, envois restés sans réponse vérifiés auprès de l’Urssaf avant tout renvoi.
- Bundle Symfony : recette Flex, commandes console (urssaf:check…), Messenger, Scheduler, Lock contre les exécutions concurrentes.
- Bridge Doctrine : mapping XML, types DBAL, outils RGPD (anonymisation, suppression, colonnes chiffrables).
- Événements d’intégration via une outbox transactionnelle, livrés au moins une fois et dans l’ordre.
- Guide de migration depuis une intégration maison.
Installer le SDK
composer require thebeardedbear/urssaf-tiers-prestationsVersion v0.2.0, documentation Urssaf 1.30.19 implémentée. PHP 8.2+, bundle Symfony optionnel, client HTTP PSR-18 au choix.
Preuves de qualité publiques
Le même standard pour chaque SDK
Rapports publics accessibles depuis les liens ci-dessus.
Architecture hexagonale
Domaine, application, infrastructure et bridges séparés, règles de dépendance vérifiées par Deptrac. Le domaine reste du PHP pur.
Avec ou sans Symfony
Bundle Symfony (6.4 LTS ou 7.4) et builder autonome sans framework. À l’exécution, le SDK ne dépend que d’interfaces PSR (HTTP, cache, logs).
100 % de couverture et de mutants tués
PHPUnit à 100 % de couverture et Infection à 100 % de MSI, bloquants en CI, comme PHPStan au niveau max, Mago, PHP-CS-Fixer et Rector.
Testable sans réseau
Une passerelle Urssaf simulée pour tester votre application de bout en bout, et des tests de contrat contre le bac à sable Urssaf.
Secrets jamais persistés
Identifiants OAuth2 lus depuis l’environnement ou un fournisseur dédié, jamais sérialisés. Les logs ne contiennent ni jeton ni corps de requête.
PHP 8.2 à 8.4 testés
CI sur PHP 8.2, 8.3 et 8.4 avec les dépendances minimales et maximales. SemVer, changelog et politique de sécurité dans chaque dépôt.
De l’habilitation à la production
Habilitation et homologation
Demande d’accès à l’API, souscription, tests en bac à sable et passage en production : je prépare le dossier et les échanges avec l’Urssaf.
Intégration dans votre application
Branchement du SDK dans votre code : bundle Symfony, persistance Doctrine ou PHP sans framework, crons et workers, reprise d’une intégration maison.
Support avec délai de réponse garanti
Un interlocuteur qui connaît le SDK et l’API, avec un délai de réponse contractuel, et le suivi des évolutions des API Urssaf.
Développements sur mesure
Ce qui est propre à votre métier, construit au-dessus du SDK : écrans, rapprochements, exports, règles spécifiques.
Sur devis, après un appel de cadrage de 30 min.
Parler de mon intégration UrssafQuestions fréquentes
Oui. Les identifiants sont résolus par tenant, et les commandes, verrous et crons travaillent tenant par tenant : un éditeur peut servir plusieurs prestataires avec une seule installation.
L’envoi reste en attente de rapprochement. Une commande dédiée interroge l’Urssaf pour savoir s’il a été reçu avant de renvoyer quoi que ce soit : jamais de double demande de paiement à l’aveugle.
Les autres SDK Urssaf
- API Attestations Vérification Code SécuritéPublié sur PackagistVérifier une attestation Urssaf à partir de son code de sécuritéVoir le SDK
- API Tierce Déclaration CESUEn développementDéclarer les salaires Cesu pour le compte d’un particulier employeurVoir le SDK
- API Tierce Déclaration PAJEBientôt disponibleDéclarer les salaires Pajemploi pour le compte des parents employeursVoir le SDK
- API Tierce Déclaration auto-entrepreneurBientôt disponibleDéclarer le chiffre d’affaires et payer les cotisations d’un auto-entrepreneurVoir le SDK
- API portail Plateforme numériqueBientôt disponibleLe précompte des cotisations des auto-entrepreneurs par les plateformesVoir le SDK
- API DPAEBientôt disponibleDéposer les déclarations préalables à l’embauche en volumeVoir le SDK
- API Mobilité internationaleBientôt disponibleDéclarer les détachements de salariés dans l’Espace économique européenVoir le SDK
Intégrer l’API Tiers de prestations ?
Un appel de 30 min pour cadrer l’API, votre application et ce que vous souhaitez déléguer. Devis ensuite, sans engagement.
Parler de mon intégration Urssaf