README

SDK for partner applications that receive dossiers from eService and instruct them.

Not the agent or citizen SDK.

Auth (APIM / Keycloak)

Avant chaque appel e-Service, le SDK peut obtenir un token OAuth2 client_credentials :

POST {ESERVICE_OAUTH_TOKEN_URL} (form-urlencoded)
Appel e-Service avec :
- Authorization: Bearer <access_token>
- X-Partner-Id / X-Partner-Secret

Toutes les valeurs viennent du .env partenaire.

ESERVICE_API_BASE=https://extapi.service-public.gov.gn/v2
ESERVICE_PARTNER_ID=prt_xxx
ESERVICE_PARTNER_SECRET=change-me
ESERVICE_OAUTH_TOKEN_URL=https://iamapim.service-public.gov.gn/realms/kong/protocol/openid-connect/token
ESERVICE_OAUTH_CLIENT_ID=your-client-id
ESERVICE_OAUTH_CLIENT_SECRET=your-client-secret
ESERVICE_OAUTH_GRANT_TYPE=client_credentials
ESERVICE_VERIFY_SSL=true
# CA auto-signé ServicePublic (chemin absolu dans le conteneur / hôte)
ESERVICE_CA_BUNDLE=/usr/local/share/ca-certificates/root-ca.crt

$client = new Client(Config::fromArray([
    'baseUrl' => getenv('ESERVICE_API_BASE'),
    'partnerId' => getenv('ESERVICE_PARTNER_ID'),
    'partnerSecret' => getenv('ESERVICE_PARTNER_SECRET'),
    'oauthTokenUrl' => getenv('ESERVICE_OAUTH_TOKEN_URL'),
    'oauthClientId' => getenv('ESERVICE_OAUTH_CLIENT_ID'),
    'oauthClientSecret' => getenv('ESERVICE_OAUTH_CLIENT_SECRET'),
    'oauthGrantType' => getenv('ESERVICE_OAUTH_GRANT_TYPE') ?: 'client_credentials',
    'verifySsl' => filter_var(getenv('ESERVICE_VERIFY_SSL') ?: 'true', FILTER_VALIDATE_BOOL),
    'caBundle' => getenv('ESERVICE_CA_BUNDLE') ?: null,
]));

$client->callback('DEM-2026-00042', CallbackRequest::completed(['numero' => 'REG-1']));

Sans variables OAuth, le SDK conserve le comportement historique (headers partenaire seuls — utile en local hors APIM).

Primary API (4 methods)

Toutes les méthodes prennent la référence de la demande (pas l’objet dossier).

Method	Action
`$client->sendMessage($reference, …)`	Message au citoyen
`$client->sendDocument($reference, …)`	Document / résultat (étape « Résultat système externe »)
`$client->requestDocuments($reference, …)`	Demande de pièces + remise à la 1re étape (citoyen peut modifier / resoumettre)
`$client->validAppointment($reference, …)`	Valider ou refuser un rendez-vous
`$client->completeDemand($reference, …)`	Marquer la demande comme terminée (`phase = done`)

$reference = 'DEM-2026-00042';

$client->sendMessage($reference, 'Votre dossier est en cours de traitement.');
// Recommandé : le fichier est téléversé et conservé avec la demande (15 Mo max).
$client->sendDocument(
    $reference,
    [
        'file' => __DIR__ . '/decision.pdf',
        'filename' => 'decision.pdf',
        'title' => 'Décision',
        'numero' => 'REG-2026-001',
    ],
    'Voici votre document.',
);
// Toujours compatible : document déjà hébergé par le partenaire.
$client->sendDocument(
    $reference,
    ResultData::make()->numero('REG-2026-001')->documentUrl('https://…/doc.pdf'),
);
$client->requestDocuments($reference, ['CNI', 'Justificatif de domicile'], 'Merci de compléter.');
$client->validAppointment($reference, 'rdv', 'approve');
$client->completeDemand($reference, 'Votre demande est terminée.');

// Callback webhook (demande entière — plus lié à une étape)
$client->callback($reference, CallbackRequest::completed(['numero' => 'REG-1']));

sendDocument accepte un chemin local, un SplFileInfo, ou un tableau contenant file/path et des métadonnées. Les formats acceptés sont PDF, JPEG, PNG et WebP (15 Mo maximum). Le serveur stocke le fichier et conserve sa clé dans la demande. Les URL et contenus base64 restent acceptés pour la rétrocompatibilité.

Les actions directes disponibles par référence évitent une requête de résolution préalable. Le callback utilise POST /partner/runs/by-reference/callback/.

Legacy helpers (review(), approval(), signature(), documentGeneration(), webhook callback) remain available.

Installation

Via Packagist :

composer require guinee/eservice:^2.1

Ou en développement local (path repository) :

{
  "repositories": [{ "type": "path", "url": "../eservice/sdks/php" }],
  "require": { "guinee/eservice": "2.1.*" }
}

PHP ≥ 8.1, ext-curl, ext-json.

Receive a dossier

use EService\Partner\Dossier\IncomingDossier;

$dossier = IncomingDossier::fromPayload(file_get_contents('php://input'));
$reference = $dossier->reference; // utiliser ensuite dans sendMessage / sendDocument / …

http_response_code(200);
header('Content-Type: application/json');
echo json_encode($dossier->ackResponse('JOB-' . uniqid(), 'accepted'));

Tests

composer test

guinee / eservice

Package info

Security

Statistics