README

此包旨在与 Laravel 一起使用 PandaDoc API。它提供了一个数据库表，您可以在其中存储文档的响应，并使用 PandaDoc API 为您的应用程序创建电子签名工作流程。

安装

使用 composer 安装

composer require eorplatform/laravel-pandadoc

安装此包后，只需运行以下命令

php artisan laravel-pandadoc:install

使用上述代码，该命令将

• 发布配置文件
• 发布迁移
• 询问是否现在运行迁移

使用场景

假设您想集成应用程序的电子签名工作流程，并且您使用 PandaDoc 作为电子签名提供商。使用此包，您可以轻松地使用 PandaDoc 模板与 API 通信，并在网站上创建您希望的功能。

例如，您可以像这样开始合同的签署

$pandaApi = PandaDoc::addRecipient(
    'johndoe@example.com', // email
    'John', // First name
    'Doe', // Last name
    'CEO', // Role
    1, // his signing order)
    ->addRecipient(
    'peterfoe@example.com',
    'Peter',
    'Foe',
    'CTO',
    2)
    ->addToken('Client', 'AnnexNumber', 'A') // Your dynamic variable inside the PandaDoc templates
    ->addToken('Document', 'EffectiveDate', now()->format('F jS, Y'))
    ->createDocumentFromTemplate('My new MSA Annex', 'panda_doc_template_id'); // First param is name and the other is your PandaDoc template ID
    

// You can then store the response in your database related model
$pandaDocument = 
            MyModel::pandaDocDocument()->create([
                'name' => 'My new MSA Annex',
                'document_id' => $pandaApi['document_id'],
                'template_id' => $pandaApi['template_id'],
                'tokens' => $pandaApi['tokens'],
                'recipients' => $pandaApi['recipients'],
                'invite_expire_at' => now()->addDays(config('panda-doc.invitation_expire_after_days'))
            ]);

// We are also using the spatie/status package so you can set the status like that
$pandaDocument->setStatus($pandaApi['status']);

利用 PandaDoc 的 webhooks

在幕后，此包依赖并为您安装了 spatie/laravel-webhook-client。您需要做的就是运行

php artisan vendor:publish --provider="Spatie\WebhookClient\WebhookClientServiceProvider" --tag="webhook-client-config"

这基本上会发布 webhooks 包的配置文件。

配置 webhooks

这是将在 config/webhook-client.php 中发布的文件的 内容

<?php

return [
    'configs' => [
        [
            /*
             * This package supports multiple webhook receiving endpoints. If you only have
             * one endpoint receiving webhooks, you can use 'default'.
             */
            'name' => 'default',

            /*
             * We expect that every webhook call will be signed using a secret. This secret
             * is used to verify that the payload has not been tampered with.
             */
            'signing_secret' => env('WEBHOOK_CLIENT_SECRET'),

            /*
             * The name of the header containing the signature.
             */
            'signature_header_name' => 'Signature',

            /*
             *  This class will verify that the content of the signature header is valid.
             *
             * It should implement \Spatie\WebhookClient\SignatureValidator\SignatureValidator
             */
            'signature_validator' => \Spatie\WebhookClient\SignatureValidator\DefaultSignatureValidator::class,

            /*
             * This class determines if the webhook call should be stored and processed.
             */
            'webhook_profile' => \Spatie\WebhookClient\WebhookProfile\ProcessEverythingWebhookProfile::class,

            /*
             * This class determines the response on a valid webhook call.
             */
            'webhook_response' => \Spatie\WebhookClient\WebhookResponse\DefaultRespondsTo::class,

            /*
             * The classname of the model to be used to store webhook calls. The class should
             * be equal or extend Spatie\WebhookClient\Models\WebhookCall.
             */
            'webhook_model' => \Spatie\WebhookClient\Models\WebhookCall::class,

            /*
             * In this array, you can pass the headers that should be stored on
             * the webhook call model when a webhook comes in.
             *
             * To store all headers, set this value to `*`.
             */
            'store_headers' => [

            ],

            /*
             * The class name of the job that will process the webhook request.
             *
             * This should be set to a class that extends \Spatie\WebhookClient\Jobs\ProcessWebhookJob.
             */
            'process_webhook_job' => '',
        ],
    ],

    /*
     * The number of days after which models should be deleted.
     *
     * Set to null if no models should be deleted.
     */
    'delete_after_days' => 30,
];

在第一个（或只需在数组中添加另一个条目）中更改以下内容

/*
             * This package supports multiple webhook receiving endpoints. If you only have
             * one endpoint receiving webhooks, you can use 'default'.
             */
            'name' => 'pandadoc',
            
            /*
             * We expect that every webhook call will be signed using a secret. This secret
             * is used to verify that the payload has not been tampered with.
             */
            'signing_secret' => 'Your signing secret from PandaDoc',
            
             /*
             * The name of the header containing the signature.
             */
            'signature_header_name' => 'signature',
            
            /*
             *  This class will verify that the content of the signature header is valid.
             *
             * It should implement \Spatie\WebhookClient\SignatureValidator\SignatureValidator
             */
            'signature_validator' => \EorPlatform\LaravelPandaDoc\PandaDocWebhookSignatureValidator::class,
            
            /*
             * The class name of the job that will process the webhook request.
             *
             * This should be set to a class that extends \Spatie\WebhookClient\Jobs\ProcessWebhookJob.
             */
            'process_webhook_job' => \EorPlatform\LaravelPandaDoc\Jobs\PandaDocWebhookProcess::class,

其他内容应保持不变。

幕后 webhook 作业看起来像

class PandaDocWebhookProcess
{
    public function handle(): void
    {
        // $this->webhookCall // contains an instance of `WebhookCall`
        // get the body and parse
        $payload = $this->webhookCall->payload;

        if ( !empty( $payload[0] ) ) {

            $body = $payload[0];

            if ( isset( $body['event'] ) && $body['event'] === 'document_state_changed' ) {

                $model = app(PandaDocRegistrar::class)->getPandaDocModelClass();

                $doc = $model::findById($body['data']['id']);

                if ( !$doc ) {
                    return; // die silently because maybe is request from another environment
                }

                $doc->forceSetStatus($body['data']['status']);

                $newDoc = $model::find($doc->id);

                // Fire the event that the PandaDOcDocument status has been updated
                PandaDocDocumentStatusUpdated::dispatch($newDoc);
            }
        }
    }
}

然后它会检查 PandaDoc API 的状态，将当前状态设置在数据库中（如果您已存储它），然后分发事件

事件

您可以使用提供的 PandaDocumentStatusUpdated 事件利用您的监听器。例如

 PandaDocumentStatusUpdated::class => [
            DoWhatever::class,
            DoSomethingElse::class
        ],