Laravel Autentique Laravel Package

Getting Started

Install the package and publish its config, then wire credentials via env — never hardcode the token:

composer require <vendor>/laravel-autentique   # per packagist name
php artisan vendor:publish --tag=autentique-config

AUTENTIQUE_TOKEN=your-api-token
AUTENTIQUE_SANDBOX=true   # keep true everywhere except production

Where to look first, in order:

1. config/autentique.php — endpoint/sandbox switch, rate-limit (60/min), max_wait, webhook secret. This is the file you'll actually touch.
2. The Autentique facade class — the full method surface (documents, signers, folders, me(), query()). Treat it as the API reference; there's no need to read the transport layer.
3. The registered webhook route + WebhookReceived event — confirm the URI and middleware so you know what the provider already did for you.

First use case — the happy path you'll build in every project: upload a PDF, attach a signer, hand back the signature link.

use Autentique; // facade alias from the package

$document = Autentique::createDocument(
    file: storage_path('app/contracts/termo.pdf'),
    name: 'Termo de Consentimento',
);

$signer = Autentique::addSigner($document['id'], [
    'name'  => $patient->name,
    'email' => $patient->email,
    'action' => 'SIGN',
]);

// Persist both IDs immediately — they're your only handle on the remote state.
$patient->update([
    'autentique_document_id' => $document['id'],
    'autentique_signer_id'   => $signer['id'],
]);

Then run it once against the sandbox before writing any tests around it. Sandbox behaviour (link formats, webhook timing) is what you'll be mocking anyway.

Implementation Patterns

Keep the facade at the edges. The facade is convenient but static — inject it behind a thin SignatureService of your own so tests and future API changes don't ripple through controllers. Resolve via the container and let Laravel swap in a fake.

Upload + sign is a two-phase workflow, not one call. Split it into a CreateSignatureRequest job (upload, persist document ID, add signers) and a separate delivery step (resend / fetch signature link). Documents outlive requests; treat the remote ID as the source of truth and store it in its own indexed column.

Webhooks: listen to the event, don't re-verify. The package already validates X-Autentique-Signature, so your listener should only act:

// app/Listeners/HandleAutentiqueWebhook.php
public function handle(WebhookReceived $event): void
{
    $payload = $event->payload;         // check actual property name in the event class
    $doc = Document::where('autentique_document_id', $payload['document_id'])->first();

    if (! $doc || $doc->isFinalized()) {
        return;                          // idempotency guard
    }

    match ($payload['event']) {
        'document.finished' => $doc->markSigned(),
        'signature.rejected' => $doc->markRejected(),
        default => null,
    };
}

Queue the listener (ShouldQueue) and return 200 fast — webhook providers retry aggressively on slow responses.

Use the sandbox for CI. Flip AUTENTIQUE_SANDBOX in .env.testing, and in unit tests swap the facade for a fake/mock so no HTTP leaves the box. The rate limiter alone will make a test suite flaky if you hit the real API.

Batch operations belong in jobs with generous timeouts. The client-side throttle waits rather than failing, so a loop over 200 documents can legitimately take minutes. Set $timeout above max_wait and split into chunks so one failure doesn't lose the batch.

Reach for query() sparingly. It's the escape hatch for fields the wrapper doesn't expose yet — wrap it in a repo method with a comment pointing at the GraphQL schema, so the next upgrade is a one-line fix.

Gotchas and Tips

The rate limiter is cache-backed — this bites in production. Throttle state is shared through Laravel's cache, so with multiple app servers you need a shared store (Redis/Memcached). The default file cache in a load-balanced setup gives each node its own 60/min window and the real limit gets blown. Set CACHE_STORE=redis and confirm.

max_wait trades latency for throughput. If the limit is hit and the wait exceeds max_wait, you get RateLimitException — which is not transient. Catch it distinctly and requeue with backoff rather than letting a job burn its retries. Also remember that waiting occupies a PHP worker: keep web requests to a handful of calls and push bulk work to the queue.

GraphQL returns HTTP 200 even on failure. You cannot rely on status codes; the package surfaces errors as AutentiqueException. Wrap mutating calls:

try {
    Autentique::updateDocument($id, [...]);
} catch (AutentiqueException $e) {
    report($e);
    $fields = method_exists($e, 'validation') ? $e->validation() : [];
    // validation() gives per-field errors — map them to form errors
}

validation() is a helper, not a guarantee. Some errors (auth, quota, malformed multipart) have no field mapping and will return empty — always have a generic fallback message.

Multipart uploads have two independent limits. PHP's upload_max_filesize/post_max_size and your HTTP client timeout both apply before the API ever responds. For large PDFs, cap file size in your form request and raise the job timeout — a silent 413 or curl timeout looks like a package bug but isn't.

Webhook endpoint config. Ensure the route is excluded from CSRF (it's POST), that it isn't behind auth middleware, and that no proxy/TrimStrings middleware rewrites the body before the HMAC check. If signature verification fails at the edge, point Autentique at your real hostname and test with a replayed payload.

Retry logic hides 5xx. The package retries 429/5xx honouring Retry-After, so intermittent failures vanish — which is good for reliability but means your logs are blind to upstream instability. Add a log line around the call if you need visibility.

Sandbox flag is the classic foot-gun. A missing AUTENTIQUE_SANDBOX=false in production silently sends real customers to sandbox documents that never legally exist. Assert on it in your deploy health check or config cache validation.

Pin the version. 1.0.0 is the first release with no deprecation history — lock it in composer.json (^1.0) and read the changelog before minor bumps, since the GraphQL surface is broad and query() consumers are exposed to upstream schema changes.