thebeardedbear / urssaf-tierce-declaration-cesu
Client and domain model for the URSSAF "API Tierce Déclaration CESU" (third-party declaration for private employers, Cesu+ and immediate tax credit advance)
Package info
github.com/TheBeardedBearSAS/urssaf-tierce-declaration-cesu
Type:symfony-bundle
pkg:composer/thebeardedbear/urssaf-tierce-declaration-cesu
Requires
- php: >=8.2
- ext-json: *
- ext-mbstring: *
- psr/cache: ^2.0 || ^3.0
- psr/clock: ^1.0
- psr/event-dispatcher: ^1.0
- psr/http-client: ^1.0
- psr/http-factory: ^1.1
- psr/http-message: ^1.1 || ^2.0
- psr/log: ^2.0 || ^3.0
- psr/simple-cache: ^2.0 || ^3.0
Requires (Dev)
- carthage-software/mago: ^1.59
- deptrac/deptrac: ^4.7
- doctrine/dbal: ^4.5
- doctrine/doctrine-bundle: ^2.19
- doctrine/orm: ^3.5.3
- doctrine/persistence: ^3.4.1 || ^4.0
- ergebnis/composer-normalize: ^2.56
- ergebnis/phpstan-rules: ^2.17
- friendsofphp/php-cs-fixer: ^3.95
- icanhazstring/composer-unused: ^0.9
- infection/infection: ^0.32
- maglnet/composer-require-checker: ^4.17
- nyholm/psr7: ^1.8.2
- php-http/client-common: ^2.7.2
- php-http/discovery: ^1.19.3
- php-http/httplug: ^2.4.1
- php-http/message: ^1.16.1
- php-http/mock-client: ^1.6.1
- php-http/promise: ^1.2.2
- phpstan/extension-installer: ^1.4
- phpstan/phpdoc-parser: ^2.0
- phpstan/phpstan: ^2.0
- phpstan/phpstan-deprecation-rules: ^2.0
- phpstan/phpstan-doctrine: ^2.1
- phpstan/phpstan-phpunit: ^2.1
- phpstan/phpstan-strict-rules: ^2.1
- phpstan/phpstan-symfony: ^2.1
- phpunit/phpunit: ^11.0
- rector/rector: ^2.8
- roave/security-advisories: dev-latest
- shipmonk/phpstan-rules: ^4.4
- symfony/cache: ^6.4 || ^7.4
- symfony/cache-contracts: ^2.5.3 || ^3.4.2
- symfony/clock: ^6.4.3 || ^7.4
- symfony/console: ^6.4 || ^7.4
- symfony/dependency-injection: ^6.4.26 || ^7.4
- symfony/doctrine-bridge: ^6.4.11 || ^7.4
- symfony/error-handler: ^6.4.3 || ^7.4
- symfony/event-dispatcher-contracts: ^2.5.3 || ^3.4.2
- symfony/framework-bundle: ^6.4.3 || ^7.4
- symfony/http-client: ^6.4 || ^7.4
- symfony/lock: ^6.4.3 || ^7.4
- symfony/messenger: ^6.4.3 || ^7.4
- symfony/polyfill-php83: ^1.31
- symfony/process: ^6.4.3 || ^7.4
- symfony/property-access: ^6.4.3 || ^7.4
- symfony/property-info: ^6.4.3 || ^7.4
- symfony/scheduler: ^6.4.3 || ^7.4
- symfony/serializer: ^6.4.3 || ^7.4
- symfony/string: ^6.4.3 || ^7.4
- symfony/translation: ^6.4.3 || ^7.4
- symfony/translation-contracts: ^2.5.3 || ^3.4.2
- symfony/uid: ^6.4.3 || ^7.4
- symfony/validator: ^6.4.3 || ^7.4
- symfony/var-dumper: ^6.4.3 || ^7.4
- symfony/var-exporter: ^6.4.3 || ^7.4
- symfony/yaml: ^6.4 || ^7.4
- tomasvotruba/type-coverage: ^2.5
Suggests
- doctrine/dbal: Required by the Doctrine bridge (custom types)
- doctrine/doctrine-bundle: Required for the Doctrine bridge
- doctrine/orm: Required for the Doctrine bridge
- nyholm/psr7: PSR-17 factories for the HTTP gateway (any PSR-17 implementation works)
- symfony/cache: PSR-6 / PSR-16 pool for the OAuth2 token cache (Psr6TokenStore, Psr16TokenStore)
- symfony/config: Required by the Symfony bridge (bundle configuration)
- symfony/console: Provides the console commands of the bundle
- symfony/dependency-injection: Required by the Symfony bridge
- symfony/framework-bundle: Required to use the Symfony bundle
- symfony/http-client: PSR-18 compatible HTTP client for the API
- symfony/http-kernel: Required by the Symfony bridge (bundle)
- symfony/lock: Prevents overlapping runs of the same command / handler (see the "lock" bundle option)
- symfony/messenger: Asynchronous employer status refresh and integration event delivery
- symfony/scheduler: Runs the safety crons of the package as a Symfony Scheduler schedule (see the "scheduler" bundle option)
- symfony/translation: Translates the violation codes (English and French shipped)
- symfony/validator: Converts the violations of the package into a ConstraintViolationList (ViolationListConverter)
Provides
None
Conflicts
- doctrine/dbal: <4.0
- doctrine/doctrine-bundle: <2.19
- doctrine/orm: <3.5.3
- nyholm/psr7: <1.8.2
- symfony/clock: <6.4.3
- symfony/console: <6.4
- symfony/dependency-injection: <6.4.26
- symfony/framework-bundle: <6.4.3
- symfony/http-client: <6.4
- symfony/http-kernel: <6.4
- symfony/lock: <6.4.3
- symfony/messenger: <6.4.3
- symfony/scheduler: <6.4.3
Replaces
None
This package is auto-updated.
Last update: 2026-11-18 22:29:15 UTC
README
thebeardedbear/urssaf-tierce-declaration-cesu — client, domain model and Symfony integration for the URSSAF API that
lets a platform act as third-party declarant for a private employer: Cesu enrolment, Cesu+ and immediate tax credit
advance (AICI) activation, contribution estimates, salary declaration with withholding at source, and mandate management.
Namespace: TheBeardedBear\UrssafTierceDeclarationCesu.
Developed and maintained by The Bearded Bear.
Important
Unofficial package. This project is an independent open-source implementation of a public API. It is not developed, endorsed, certified or supported by URSSAF, and it is not affiliated with URSSAF in any way. "URSSAF" is used only to name the API this package talks to. Using this package does not replace the URSSAF habilitation process; the URSSAF documentation remains the authority on the API, and you remain responsible for the data your application sends to URSSAF.
Status: 0.1.0 released; sandbox contract run still to do (see docs/roadmap.md). The nine operations, the workflow, the standalone builder, the Symfony bundle and the Doctrine bridge are in place; the sandbox contract run that settles the open points of the API reference is still to do. See the architecture decision records in docs/adr/.
Scope
| Method | Operation | Endpoint |
|---|---|---|
| CESU010 | Register an employer | POST /employeurs |
| CESU020 | Verify an employer account | GET /employeurs/{numeroCesu} |
| CESU021 | Verify an employee account | GET /salaries |
| CESU030 | Register a third-party declaration mandate | POST /mandats |
| CESU031 | Cancel a mandate | DELETE /mandats |
| CESU040 | Estimate contributions | POST /estimer |
| CESU050 | Declare a salary (Cesu or Cesu+ with AICI) | POST /employeurs/{numeroCesu}/declarer |
| CESU060 | Activate Cesu+ | POST /employeurs/{numeroCesu}/cesuplus |
| CESU070 | Activate AICI | POST /employeurs/{numeroCesu}/aici |
OAuth2 client credentials, scope tiersdecl.cesu, base URL https://api.urssaf.fr/tiersdecl/v1/cesu (sandbox:
https://api-edi.urssaf.fr/tiersdecl/v1/cesu). Restricted access: subscription through DataPass.
Documentation
- docs/api-reference.md — technical reference (single source of truth for the package).
- docs/roadmap.md — implementation status and what remains.
- docs/workflow.md — employer, mandate and declaration lifecycles, idempotency, retries, monitoring, GDPR erasure.
- docs/integration-events.md — public integration events (
urssaf.cesu.*) and the outbox. - docs/doctrine.md — Doctrine persistence: tables, dedicated entity manager, concurrency, personal data and encryption, migrations.
- docs/standalone.md — wiring without the Symfony bundle: builder options, scheduling, manual wiring.
- docs/symfony.md — Symfony bundle: configuration reference, console commands, Messenger, Scheduler, locks, validation, translations.
- docs/testing.md — testing a host application with the in-memory simulated gateway.
- docs/adr/ — architecture decision records.
- docs/openapi/ — official OpenAPI contract(s) from the URSSAF API portal.
docs/reference/— official URSSAF documentation: not versioned (URSSAF documents), download it from the links in docs/api-reference.md into this local, git-ignored folder.- Catalogue page: https://portailapi.urssaf.fr/fr/catalogue-api/prd/td-cesu
Installation
composer require thebeardedbear/urssaf-tierce-declaration-cesu
With Symfony Flex, the recipe of the package registers the bundle, copies a commented
config/packages/urssaf_tierce_declaration_cesu.yaml (the simulated URSSAF platform in the test environment) and adds
URSSAF_CESU_ENV, URSSAF_CESU_CLIENT_ID and URSSAF_CESU_CLIENT_SECRET to .env. The recipe is prepared for
symfony/recipes-contrib but not published there yet: it will be submitted
there. Until then, do these steps by hand (Quick start B below), or serve the recipe from your own Flex endpoint built by
bin/build-flex-endpoint (see docs/symfony.md).
Then generate the tables of the package (it ships no migration, see docs/doctrine.md) and check the installation:
php bin/console doctrine:migrations:diff --em=urssaf_cesu && php bin/console doctrine:migrations:migrate
php bin/console urssaf:cesu:check
Architecture
Hexagonal / DDD, the same as thebeardedbear/urssaf-tiers-prestations (ADR 0000).
Layers are enforced by Deptrac (deptrac.yaml):
+-----------------------------------------------+
| Bridge (Symfony, Doctrine) - framework glue |
+----------------------+------------------------+
|
+----------------------v------------------------+
| Infrastructure - HTTP gateway, OAuth2, wire |
| encoding, token stores, clock, ids, in-memory |
+----------------------+------------------------+
| implements ports
+----------------------v------------------------+
| Application - commands, queries, handlers, |
| ports (CesuGateway, repositories...), DTOs |
+----------------------+------------------------+
|
+----------------------v------------------------+
| Domain - aggregates, value objects, rules |
| (pure PHP, no PSR, no framework) |
+-----------------------------------------------+
- Domain: employers, mandates, declarations (sum type
StandardDeclaration|CesuPlusDeclaration), value objects (CalendarDate,Moneyin cents,Address...), validation, domain events. - Contract: public, versioned integration events relayed through the outbox.
- Application: one
final readonlyhandler per use case, ports implemented by the outer layers. - Infrastructure:
UrssafHttpGateway(implementsCesuGateway), OAuth2 token provider, JSON client, adapters. - Standalone / Testing: framework-free builder and an in-memory simulated gateway for host test suites.
- Bridge:
Bridge\Symfony(bundle, commands, Messenger, Lock, Scheduler) andBridge\Doctrine(XML mapping, DBAL types, repositories with atomic claims, optimistic locking, outbox, statistics, transaction manager; no IBAN, BIC nor NIR column).
Decisions: docs/adr/.
Quick start A: Standalone (framework-agnostic)
use Nyholm\Psr7\Factory\Psr17Factory; use TheBeardedBear\UrssafTierceDeclarationCesu\Application\Command\DeclareSalary; use TheBeardedBear\UrssafTierceDeclarationCesu\Application\Command\RegisterEmployer; use TheBeardedBear\UrssafTierceDeclarationCesu\Application\Command\RegisterMandate; use TheBeardedBear\UrssafTierceDeclarationCesu\Application\Dto\EmployerSelector; use TheBeardedBear\UrssafTierceDeclarationCesu\Application\Port\Credentials; use TheBeardedBear\UrssafTierceDeclarationCesu\Domain\Shared\ExternalReference; use TheBeardedBear\UrssafTierceDeclarationCesu\Domain\Shared\TenantId; use TheBeardedBear\UrssafTierceDeclarationCesu\Infrastructure\Credentials\InMemoryCredentialsProvider; use TheBeardedBear\UrssafTierceDeclarationCesu\Infrastructure\Urssaf\ApiConfiguration; use TheBeardedBear\UrssafTierceDeclarationCesu\Infrastructure\Urssaf\Environment; use TheBeardedBear\UrssafTierceDeclarationCesu\Infrastructure\Urssaf\HttpTransport; use TheBeardedBear\UrssafTierceDeclarationCesu\Standalone\UrssafTierceDeclarationCesuBuilder; $factory = new Psr17Factory(); $urssaf = UrssafTierceDeclarationCesuBuilder::create( new HttpTransport($psr18Client, $factory, $factory), // any PSR-18 client and PSR-17 factories new InMemoryCredentialsProvider(['tenant-1' => Credentials::of((string) getenv('URSSAF_CLIENT_ID'), (string) getenv('URSSAF_CLIENT_SECRET'))]), ApiConfiguration::forEnvironment(Environment::Sandbox), ) ->withDoctrine($urssafEntityManager) // a dedicated entity manager (docs/doctrine.md); default: in-memory (tests, prototypes) ->withTokenStore($sharedTokenStore) // default: in-memory (a token per process) ->build(); $tenant = TenantId::fromString('tenant-1'); $employer = EmployerSelector::byExternalReference(ExternalReference::fromString('employer-42')); // 1. Enrol the employer (method 010, synchronous; bank details are never stored). $draft is a Domain\Employer\Input\NewEmployerDraft. $urssaf->registerEmployer()(new RegisterEmployer($tenant, ExternalReference::fromString('employer-42'), $draft)); // 2. Notify the third-party declaration mandate (method 030), required before any declaration (ADR 0009). $urssaf->registerMandate()(new RegisterMandate($tenant, $employer)); // 3. Declare a salary (method 050, idempotent per external reference). $declaration is a Domain\Declaration\Input\DeclarationDraft. $submission = $urssaf->declareSalary()(new DeclareSalary($tenant, ExternalReference::fromString('payslip-2026-10'), $declaration)); // $submission->outcome: declared, rejected, already_declared, outcome_unknown (never resent: resolveDeclarationOutcome())...
The other use cases are one accessor away: verifyEmployer(), verifyEmployee(), syncEmployerStatus(),
estimateContributions(), activateCesuPlus(), activateAici(), getEmployerAccount(), findDeclarations(), forgetEmployer() (GDPR erasure)... Every
option of the builder and the manual wiring are described in docs/standalone.md; test your
integration with the simulator (docs/testing.md).
Quick start B: Symfony
Once the recipe is published in symfony/recipes-contrib, Symfony Flex will register the bundle, copy the configuration
and add the variables to .env:
composer require thebeardedbear/urssaf-tierce-declaration-cesu
Without the recipe (not published yet), do it by hand. Register the bundle in config/bundles.php:
return [ // ... TheBeardedBear\UrssafTierceDeclarationCesu\Bridge\Symfony\UrssafTierceDeclarationCesuBundle::class => ['all' => true], ];
Configure it in config/packages/urssaf_tierce_declaration_cesu.yaml (every option is described in
docs/symfony.md):
framework: cache: pools: urssaf_cesu.token_cache: # the access tokens, shared by every process (web, workers, cron) adapter: cache.adapter.redis provider: '%env(REDIS_DSN)%' urssaf_tierce_declaration_cesu: environment: '%env(URSSAF_CESU_ENV)%' # sandbox | production credentials: default: # one entry per platform account (tenant) client_id: '%env(URSSAF_CESU_CLIENT_ID)%' client_secret: '%env(URSSAF_CESU_CLIENT_SECRET)%' token_store: { cache_pool: urssaf_cesu.token_cache } persistence: { driver: doctrine, entity_manager: urssaf_cesu } # a dedicated entity manager; default driver when doctrine/orm is installed # persistence: { driver: custom, employer_account_repository: ..., mandate_repository: ..., declaration_record_repository: ... } when@test: urssaf_tierce_declaration_cesu: gateway: { simulated: true } # the in-memory URSSAF platform: nothing is sent to URSSAF
and set the variables in .env.local (never commit the secret):
URSSAF_CESU_ENV=sandbox URSSAF_CESU_CLIENT_ID= URSSAF_CESU_CLIENT_SECRET=
The use case handlers are public services, ready to be injected:
#[Route('/declarations/{reference}', methods: ['PUT'])] public function declare(string $reference, #[MapRequestPayload] DeclarationDraft $draft, DeclareSalaryHandler $declareSalary): Response { $submission = $declareSalary(new DeclareSalary(TenantId::fromString('default'), ExternalReference::fromString($reference), $draft)); return $this->json(['state' => $submission->outcome->value]); }
Check the installation, then run the safety commands from cron or the Symfony Scheduler:
php bin/console urssaf:cesu:check php bin/console urssaf:cesu:employers:sync-status
Create the tables with your migrations (the package ships none): php bin/console doctrine:migrations:diff then
doctrine:migrations:migrate (docs/doctrine.md). Without Doctrine, the in_memory persistence loses
every record when the process ends: give your own repositories (custom driver), see
docs/symfony.md.
Requirements
PHP 8.2+. Symfony 6.4 / 7.x for the bundle (optional). Doctrine persistence (optional): doctrine/orm 3.5.3+, doctrine/dbal 4.0+ and, with Symfony, doctrine/doctrine-bundle 2.19+. Development only needs Docker: every make target runs in a container.
Development
make install # build the image, install dependencies make coverage-branches # branch coverage (Xdebug, slow), at least 96 % enforced make ci # full quality gate: cs, rector, phpstan, mago, deptrac, composer checks, hadolint, guard, coverage, infection make test # unit + functional tests make bench # benchmarks (PHPBench, tests/Benchmark), added with the implementation make help # every target
make ci PHP_VERSION=8.4 runs the gate on another PHP version.
Once the repository is public, main publishes its quality proofs, linked from the badges at the top of this file: the
coverage report on Codecov, the full mutation report on the Stryker Dashboard, the SonarQube Cloud quality gate and the
OpenSSF Scorecard. The benchmarks (tests/Benchmark, PHPBench in tools/phpbench, out of the package dependencies)
run on every pull request against the base commit, and the job fails on a regression of more than 20 %.
Sandbox contract tests
make test-contract runs the contract suite against the URSSAF sandbox. It is opt-in: without credentials every test is
skipped and the command exits 0. The suite is never part of the default run, of the coverage or of the mutation testing.
Variables (environment of the shell running make, or secrets / variables of the urssaf-sandbox environment for the
manual contract CI job):
| Variable | Required | Meaning |
|---|---|---|
URSSAF_SANDBOX_CLIENT_ID |
yes | OAuth2 client id of your sandbox subscription (secret) |
URSSAF_SANDBOX_CLIENT_SECRET |
yes | OAuth2 client secret (secret) |
URSSAF_SANDBOX_BASE_URI |
no | sandbox host override (default https://api-edi.urssaf.fr); an https URI is required and the production host is refused |
URSSAF_SANDBOX_TOKEN_URI |
no | full token URL used instead of <base>/api/oauth/v1/token (open point 5.14 of the API reference); an https URI is required and the production host is refused, as for the base URI, since the client credentials are posted to it |
URSSAF_SANDBOX_EMPLOYER_CESU_NUMBER |
no | a sandbox employer Cesu number (enables the employer tests) |
URSSAF_SANDBOX_EMPLOYER_BIRTH_DATE |
with the above | its birth date, YYYY-MM-DD |
URSSAF_SANDBOX_EMPLOYEE_CESU_NUMBER |
no | a sandbox employee Cesu number (enables the pair and employee tests) |
URSSAF_SANDBOX_ALLOW_WRITES |
no | exactly 1 to also run the tests that write sandbox state |
Read-only by default: token, 020, 021 and 040 (official example, nothing is stored). URSSAF_SANDBOX_ALLOW_WRITES=1
also runs 010 (a fictitious employer), 030/031 (the mandate of your test employer, restored afterwards), 050 (one
declaration of the previous month plus its duplicate), 060 (activates Cesu+ for your test pair) and 070 (on the
fictitious employer). These create sandbox state that cannot be undone.
Report: var/contract/sandbox-report.json (git-ignored) lists what the sandbox answered for each open point of
docs/api-reference.md section 5: enum values, key names, JSON types and HTTP statuses only,
no personal data, no token. The CI job uploads it as the contract-report artifact.
CI: Actions > CI > Run workflow, tick contract (and contract_writes); environment urssaf-sandbox.
Never commit these values. Do not set failOnSkipped / failOnIncomplete in phpunit.xml.dist: the suite must pass
when skipped. The 050 test targets the previous calendar month: the idDeclaration type is observable once per
employer / employee pair and month, later runs see the duplicate refusal.
Versioning
Semantic Versioning. SpecVersion::CURRENT holds the version of the official URSSAF documentation implemented.
Other URSSAF packages
The same architecture, quality gate and conventions, one package per URSSAF API (overview: the-bearded-bear.com/open-source/urssaf):
| API | Package | Status |
|---|---|---|
| Tiers de prestations (immediate tax-credit advance) | thebeardedbear/urssaf-tiers-prestations |
Released (Packagist) |
| Attestations Vérification Code Sécurité (certificate verification) | thebeardedbear/urssaf-attestations-verification-code-securite |
Released (Packagist) |
| DPAE (pre-employment declaration) | thebeardedbear/urssaf-dpae |
Coming soon |
| Mobilité internationale (posting of workers abroad) | thebeardedbear/urssaf-mobilite-internationale |
Coming soon |
| Plateforme numérique (withholding of contributions by digital platforms) | thebeardedbear/urssaf-plateforme-numerique |
Released (Packagist) |
| Tierce Déclaration auto-entrepreneur | thebeardedbear/urssaf-tierce-declaration-auto-entrepreneur |
Released (Packagist) |
| Tierce Déclaration PAJE | thebeardedbear/urssaf-tierce-declaration-paje |
Released (Packagist) |
Professional support
This package is developed and maintained by The Bearded Bear. If you need help with an URSSAF integration, The Bearded Bear can help with:
- the URSSAF habilitation and homologation process (subscription, sandbox tests, move to production);
- integrating the package into your application (Symfony, Doctrine or framework-free);
- support with a guaranteed response time, including the follow-up of URSSAF API changes;
- custom developments on top of the package.
Project page and integration offer: the-bearded-bear.com/open-source/urssaf-tierce-declaration-cesu.
Contributing and security
Contributions are welcome: see CONTRIBUTING.md and the Code of Conduct. The project's governance is described in GOVERNANCE.md and its direction in ROADMAP.md. Report vulnerabilities privately as described in SECURITY.md, never in a public issue. Security design and review: assurance case (threat model, trust boundaries, design principles, countered weaknesses) and security review.
License
MIT. See LICENSE. The software is provided "as is", without warranty of any kind.
The API specification summarised in docs/api-reference.md belongs to URSSAF; see the sources listed there.