thebeardedbear / urssaf-attestations-verification-code-securite
Client and domain model for the URSSAF "API Attestations Vérification Code Sécurité" (verification of URSSAF certificates by security code)
Package info
github.com/TheBeardedBearSAS/urssaf-attestations-verification-code-securite
Type:symfony-bundle
pkg:composer/thebeardedbear/urssaf-attestations-verification-code-securite
Requires
- php: >=8.2
- ext-json: *
- ext-mbstring: *
- psr/cache: ^2.0 || ^3.0
- psr/clock: ^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/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/property-access: ^6.4.3 || ^7.4
- symfony/property-info: ^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
- nyholm/psr7: PSR-17 factories used by the Symfony bridge default HTTP client
- symfony/config: Required by the Symfony bridge (bundle configuration)
- symfony/console: Required by the Symfony bridge (console commands)
- 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/translation: Translates the violation codes (English and French shipped)
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
Replaces
None
README
thebeardedbear/urssaf-attestations-verification-code-securite — client, domain model and Symfony integration for the
URSSAF API that checks the validity of a certificate (attestation de vigilance, CSG/CRDS, formation
professionnelle, micro-entrepreneur turnover, …) from the security code printed on it.
Namespace: TheBeardedBear\UrssafAttestationsVerificationCodeSecurite.
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 how your application uses the verification results.
Status: implementation complete for the specification v1.2.1; open points are tracked in docs/api-reference.md §5.
Scope
| Operation | Endpoint |
|---|---|
| Verify one certificate | GET /codes_securite/verifier?codeSecurite=… |
| Verify up to 100 certificates | POST /codes_securite/verifier |
OAuth2 client credentials, scope attn.codes_securite, base URL https://api.urssaf.fr/attn/verification/v1.
Quick start
Without a framework
use Symfony\Component\HttpClient\Psr18Client; use TheBeardedBear\UrssafAttestationsVerificationCodeSecurite\Application\Port\Credentials; use TheBeardedBear\UrssafAttestationsVerificationCodeSecurite\Application\Query\VerifyCertificate; use TheBeardedBear\UrssafAttestationsVerificationCodeSecurite\Domain\Certificate\RejectedCode; use TheBeardedBear\UrssafAttestationsVerificationCodeSecurite\Domain\Certificate\SecurityCode; use TheBeardedBear\UrssafAttestationsVerificationCodeSecurite\Domain\Certificate\VerifiedCertificate; use TheBeardedBear\UrssafAttestationsVerificationCodeSecurite\Domain\Shared\TenantId; use TheBeardedBear\UrssafAttestationsVerificationCodeSecurite\Infrastructure\Credentials\InMemoryCredentialsProvider; use TheBeardedBear\UrssafAttestationsVerificationCodeSecurite\Infrastructure\Urssaf\ApiConfiguration; use TheBeardedBear\UrssafAttestationsVerificationCodeSecurite\Infrastructure\Urssaf\Environment; use TheBeardedBear\UrssafAttestationsVerificationCodeSecurite\Infrastructure\Urssaf\HttpTransport; use TheBeardedBear\UrssafAttestationsVerificationCodeSecurite\Standalone\UrssafAttestationsVerificationBuilder; // Requires a PSR-17 implementation: composer require symfony/http-client nyholm/psr7 $client = new Psr18Client(); $urssaf = UrssafAttestationsVerificationBuilder::create( new HttpTransport($client, $client, $client), new InMemoryCredentialsProvider(['tenant-1' => Credentials::of($clientId, $clientSecret)]), ApiConfiguration::forEnvironment(Environment::Production), )->build(); $result = $urssaf->verifyCertificate()(new VerifyCertificate( TenantId::fromString('tenant-1'), SecurityCode::fromString($codeTypedByTheUser), )); if ($result instanceof VerifiedCertificate) { // valid certificate: nature, issuing body, issue date, details } elseif ($result instanceof RejectedCode) { // expired, unknown or incomplete code: an answer of URSSAF, not an exception }
See docs/standalone.md.
Symfony
With the Symfony Flex contrib recipe, composer require registers and configures the bundle (see installation with Symfony Flex); otherwise, register it by hand in config/bundles.php:
return [ // ... TheBeardedBear\UrssafAttestationsVerificationCodeSecurite\Bridge\Symfony\UrssafAttestationsVerificationCodeSecuriteBundle::class => ['all' => true], ];
Minimal configuration in config/packages/urssaf_attestations_verification_code_securite.yaml:
urssaf_attestations_verification_code_securite: environment: '%env(URSSAF_ENV)%' # sandbox | production credentials: tenant-1: client_id: '%env(URSSAF_CLIENT_ID)%' client_secret: '%env(URSSAF_CLIENT_SECRET)%'
Inject Application\Query\VerifyCertificateHandler in your services and call it with a VerifyCertificate query, or verify a
code from the shell:
bin/console urssaf:certificate:verify <code>
See docs/symfony.md.
Architecture
The package follows a hexagonal (ports and adapters) architecture: the application layer runs the use cases through ports, and the infrastructure implements those ports against the URSSAF API. Deptrac enforces the dependency rules between the layers, and the runtime depends on PSR interfaces only. The reference architecture is described in docs/adr/0000-reference-architecture.md.
Domain: security codes, certificates, the verification result, domain exceptions.Application: queries and their handlers, ports (gateway, credentials, token store).Infrastructure: URSSAF HTTP gateway, OAuth2, wire mappers, token stores, credentials providers.Standalone: framework-free builder and entry point.Testing: in-memory simulated gateway for the tests of host applications.Bridge\Symfony: Symfony bundle, configuration and console commands.
Documentation
- docs/api-reference.md — technical reference (single source of truth for the package).
- docs/roadmap.md — planned architecture and order of work.
- docs/adr/ — architecture decision records (0000: decisions inherited from the reference package).
- docs/standalone.md — usage without a framework.
- docs/testing.md — testing an application that uses the package.
- docs/symfony.md — Symfony bundle.
- 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/avcs
Requirements
PHP 8.2+. Development only needs Docker: every make target runs in a container.
Development
make install # build the image, install dependencies 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): security code validation, wire encoding and decoding make help # every target
make ci PHP_VERSION=8.4 runs the gate on another PHP version (PHPStan always runs on 8.2, see
ADR 0007).
Published proofs (public repository, main): the coverage report on Codecov, the full mutation report on the Stryker
Dashboard, the SonarQube Cloud quality gate and the OpenSSF Scorecard (.github/workflows/scorecard.yml), linked from
the badges at the top of this file. 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 %.
make test-contract runs the live sandbox tests: set URSSAF_SANDBOX_CLIENT_ID and URSSAF_SANDBOX_CLIENT_SECRET (required), optionally URSSAF_SANDBOX_BASE_URI, URSSAF_SANDBOX_VALID_SECURITY_CODE, URSSAF_SANDBOX_UNKNOWN_SECURITY_CODE (default xxx); without them every contract test is skipped. In CI the manual contract job reads the credentials and the valid code from repository secrets, the other two from repository variables.
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) |
| 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 |
Coming soon |
| Tierce Déclaration auto-entrepreneur | thebeardedbear/urssaf-tierce-declaration-auto-entrepreneur |
Coming soon |
| Tierce Déclaration CESU | thebeardedbear/urssaf-tierce-declaration-cesu |
Released (Packagist) |
| Tierce Déclaration PAJE | thebeardedbear/urssaf-tierce-declaration-paje |
Coming soon |
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-attestations-verification-code-securite.
Contributing and security
Contributions are welcome: see CONTRIBUTING.md. Report vulnerabilities privately as described in SECURITY.md, never in a public issue.
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.