README

此库提供了一种简单的方法，用于在 PHP 编写的任何应用程序中使用 dpae.r3m.fr 的 DPAE API。

先决条件

PHP 7.1.0 及更高版本。

安装

推荐使用 Composer 进行安装。执行以下命令：

composer require r3mfr/api-dpae-php

请确保 Composer 的 autoload 文件已正确包含在您的应用程序中。

require_once('vendor/autoload.php');

文档

请参阅 DPAE API 文档，以了解 API 的完整功能和软件集成方式。

认证

所有请求都必须附带 JWT 令牌。

该令牌由 PHP 库自动为您创建，使用您的标识符。

要获取您的标识符，您必须在 API DPAE 上创建账户。

$username = 'foo';
$password = 'bar';
\R3m\Dpae\ApiClient::setCredentials($username, $password);

存储认证令牌

JWT 令牌有有限的有效期。默认情况下，它在内存中存储，因此每次请求都需要重新请求。这并不是最优的，并且可能会引发认证配额问题。

强烈建议通过定义 TokenStorage 在除内存之外的地方存储 JWT 令牌。示例：

$myTokenStorage = new class implements \R3m\Dpae\AuthTokenStorage\AuthTokenStorageInterface {
    public function get(): string
    {
        // Lire le token depuis la base de données ou depuis un fichier
    }

    public function set(string $token): void
    {
        // Stocker le token en base de données ou dans un fichier
    }
};
\R3m\Dpae\ApiClient::setAuthTokenStorage($myTokenStorage);

提交招聘信息

要执行 DPAE，您必须向 DPAE API 提交招聘信息。请参阅 文档 了解招聘信息的详细信息和属性格式。

$embauche = new \R3m\Dpae\Embauche();
$embauche
    ->setRaisonSociale('R3M EVENEMENT')
    ->setSiret('67846960300074')
    // ... définir les autres valeurs de l'embauche ...
    ->setIdExterne('123456');

try {
    $embauche->save();
} catch (\R3m\Dpae\Exception\BadRequestException $e) {
    foreach ($e->getViolations() as $violation) {
        echo("Erreur sur la propriété {$violation['propertyPath']}: {$violation['message']}");
    }
    exit(1);
} catch (\R3m\Dpae\Exception\ExceptionInterface $e) {
    echo("Erreur lors de la création de l'embauche : {$e->getCode()} {$e->getMessage()}");
    exit(1);
}

echo("Embauche {$embauche->id} créée. Statut de la DPAE: {$embauche->getDpae()->statutTraitementDescription}.");

检查招聘信息状态

尽管建议使用 Webhook 通知 DPAE 的返回，但您也可以手动查询 DPAE API。

$idExterne = '123456'; // ID de l'embauche dans l'application cliente

try {
    /** @var \R3m\Dpae\Embauche $embauche */
    $embauche = \R3m\Dpae\Embauche::one(['idExterne' => $idExterne]);
} catch (\R3m\Dpae\Exception\ExceptionInterface $e) {
    echo("Erreur {$e->getCode()} lors de la recherche de l'embauche : {$e->getMessage()}");
    exit(1);
}

if ($embauche) {
    if ($embauche->isDeclaree()) {
        echo("DPAE validée par l'URSSAF. Numéro de dossier : {$embauche->getDpae()->refDossier}");
    } else {
        if ($embauche->hasErreur()) {
            echo("Erreur avec la DPAE de l'embauche {$embauche->getId()} : {$embauche->getDpae()->codeRetourAr}-{$embauche->getDpae()->codeRetourArLibelle}");
        } else {
            echo("Statut de la DPAE pour l'embauche {$embauche->getId()} : {$embauche->getDpae()->statutTraitementDescription}");
        }
    }
} else {
    echo("Aucune embauche trouvée pour idExterne=$idExterne");
}

接收 Webhook 通知

您可以在收到接收证明后立即通过 API 被通知。只需将您的应用程序的 URL 声明为 webhook。这样，您就无需定期查询 API 以了解招聘信息的状态：API 会通知您的应用程序，并将所有必要的处理接收证明的信息传递给应用程序。

因此，您必须公开您的应用程序的 URL。在调用此 URL 时，执行以下代码：

// Il est conseillé de configurer une clé secrête pour valider la requête Webhook 
$secret = 'phrase_secrete';

try {
    $webhookEvent = \R3m\Dpae\WebhookEvent::receive($secret);
} catch (\R3m\Dpae\Exception\ExceptionInterface $e) {
    echo sprintf("Erreur lors de la réception du webhook : {$e->getMessage()}");

    // Retourner un code >= 400 informera l'API DPAE de l'erreur de traitement
    header($_SERVER['SERVER_PROTOCOL'] . ' 400 Bad Dequest', true, 400);
    exit(1);
}

$embauche = $webhookEvent->getEmbauche();

// Vous pouvez maintenant traitez le statut de la DPAE dans votre application :
// - mettre à jour le statut de la DPAE dans votre base de données
// - notifiez le déclarant si une erreur doit être corrigée
// - etc.

if ($embauche->isDeclaree()) {
    echo sprintf("DPAE validée par l'URSSAF. Numéro de dossier : {$embauche->getDpae()->refDossier}");
} else {
    // l'embauche n'est pas déclarée, la DPAE est en erreur
    echo sprintf("Erreur avec la DPAE de l'embauche {$embauche->getId()} : {$embauche->getDpae()->codeRetourAr}-{$embauche->getDpae()->codeRetourArLibelle}");
}

// Informer l'API DPAE du succès du traitement du webhook
header($_SERVER['SERVER_PROTOCOL'] . ' 200 OK', true, 200);

维护期间

在您的应用程序维护期间，您可以返回 503。这将允许 DPAE API 在稍后再次尝试通过 webhook 通知。

header($_SERVER['SERVER_PROTOCOL'] . ' 503 Service Unavailable', true, 503);
header('Retry-after: 3600');

使用其他 HTTP 客户端

默认情况下，使用 symfony/http-client 与 DPAE API 进行交互。如果您更喜欢，可以使用实现 \Psr\Http\Client\ClientInterface 的其他 HTTP 客户端。

$myhttpClient = new MyHttpClient(['option1' => true]);
Dpae\ApiClient::setHttpClient($myhttpClient);

贡献

欢迎拉取请求。

测试

使用 Codeception 进行测试。

$ composer run test