Autentique V2 Laravel Package

Getting Started

• Install with composer require vinicinbgs/autentique-v2 and pin at least ^4.3.3 — this release is a patch on the 4.3.x line with no signature or config changes, so it is a drop-in upgrade from 4.3.2.
• Publish the package config (php artisan vendor:publish --tag=autentique-config or the tag listed in the README) and set AUTENTIQUE_TOKEN plus the sandbox/endpoint toggle in .env. Never commit a production token; generate a separate sandbox token from the Autentique dashboard.
• Look first at: config/autentique.php (token, endpoint/sandbox, timeouts), the facade/root class registered by the service provider, and the src/ endpoint classes — each Autentique API resource (documents, folders, signatures, webhooks) maps to one class, which is the fastest way to discover which methods actually exist in your pinned version.
• First use case: create a document, attach a PDF from storage/app/..., register one or more signers with name/email, and capture the returned document id plus each signer's signature link. That flow exercises auth, upload, and response parsing in one pass and is the shape 80% of real integrations use.
• Test against sandbox first. Autentique sandbox documents and tokens are isolated from production — a document created with a sandbox token simply does not exist under a production token, so don't debug "missing document" errors before checking which endpoint the config resolved to.
• Run the package's own test suite once locally (vendor/bin/phpunit or Pest, depending on the tag) to confirm your PHP/Laravel version combo is supported before writing integration code.

Implementation Patterns

• Wrap the client in your own service. Do not call the facade from controllers. A thin DocumentService/ContractService that takes the package client via constructor injection gives you one place to add logging, retries, and tenant-specific tokens, and makes tests trivial.
• Model the relationship locally, don't re-query Autentique for everything. Persist document_id, folder_id, signer emails, status, and the signature links in your own tables (a polymorphic signable relation on Invoice, Contract, Employee, etc. works well). Treat Autentique as the source of truth for status but your DB as the source of truth for "which of my records does this document belong to".
• Queue the write calls. Creating a document, moving it to a folder, and adding signers are three network round-trips; run them in a job so a slow API or a 429 does not block a web request. Use $tries, backoff(), and only retry on 5xx/timeouts — retrying a 422 just burns quota.
• Webhooks are the status pipeline, not polling. Register the webhook endpoint once, then process events in a queued listener/job with idempotency keyed on the event/document id. Polling listDocuments on a schedule is fine as a reconciliation safety net, but should not be the primary path.
• Multi-tenant / multi-account setups. Rather than relying solely on the singleton config, instantiate the client (or config()->set() before resolving) per tenant. If the package binds a singleton, use app()->forgetInstance(...) or a factory wrapper so token switching actually takes effect.
• Feature-gated reads. Biometry data only appears on signatures where the biometric capture actually happened and completed — so iterate signatures and null-check the biometry block rather than assuming its presence. Store it as structured JSON alongside the signature record, and surface it in your audit view rather than parsing it at display time.
• Testing. Fake the HTTP layer (Http::fake() if the package uses Laravel's client) or bind a mock of your own service wrapper; assert on the payload you send (file, signer list, folder) more than on the package's parsing, so package upgrades don't churn your tests.

Gotchas and Tips

• The v4.3.3 fix is a read-path fix. Missing biometry information was being dropped from responses; upgrading gets you the field on new fetches only. Already-persisted rows in your database stay empty — write a one-off backfill command that re-fetches completed documents and re-saves the signature/biometry payload if you rely on it for audit or compliance evidence.
• Verify webhooks against the raw body. Signature/HMAC checks must use $request->getContent(), not the decoded array — re-encoding JSON changes key order and whitespace and will fail valid payloads. Also exclude the webhook route from CSRF and from any global body-parsing middleware that rewrites the request.
• Config caching bites silently. php artisan config:cache after changing the token or sandbox flag, otherwise you'll debug 401s that are really stale config. This is the most common "the package is broken" report.
• The API is strict about file input. Pass real paths/exists-checked UploadedFile instances, respect the size limit, and prefer storing an immutable copy of the signed PDF yourself — Autentique URLs are not permanent, and you want the evidence locally.
• Error handling is message-based, not exception-class-based. Autentique returns validation-style messages (missing signer email, already-signed document, invalid file). Catch the package exception, log the response body plus any request id, and map known messages to user-facing errors; don't let a raw API string reach the UI in Portuguese when your app is in another language.
• Status values are strings from the API. Normalise them into your own enum early (pending, signed, rejected, expired) — comparing raw API strings across the codebase is where silent bugs appear when Autentique adds a state.
• Timezones and dates. Response timestamps are API-formatted; cast them in your DTO rather than storing strings, or ordering/filtering by "signed date" will break in reports.
• Extension points to prefer. Published config for tuning (timeouts, endpoint override, HTTP client options), your own wrapper for behaviour (retries, tenant tokens, DTO mapping). Avoid editing vendor/; if you need a missing endpoint, extend the package class or open an upstream PR — the project is active and small fixes like this one land quickly.
• Watch the 4.x line for minor releases. Patches have been safe so far; when moving to a new minor, skim the changelog for renamed methods or changed response shapes and run your fakes against recorded real responses once before deploying.