Document Signer Docusign Laravel Package

Product Decisions This Supports

• Build vs. buy for eSignature: This package is the "buy/integrate" answer to "should we build eSignature ourselves?" It wraps DocuSign behind the vendor-neutral SignatureProvider contract from la-souris/document-signer-sdk, so the roadmap decision becomes which provider (DocuSign now, others later) rather than whether to own signing infrastructure, certificate-of-completion handling, and audit retention.
• Provider portability as a roadmap hedge: Because DocuSign is one implementation of a shared contract, the product can commit to eSignature without locking the roadmap to DocuSign pricing, API changes, or regional availability. Swapping or adding a provider (e.g., ValidSign, given the explicit placement parity noted) is an implementation task, not a re-platforming project.
• Template-free document generation: Anchor-based placeholder replacement means product and legal can author documents in Word/PDF with text anchors, and the integration drops signature fields onto those anchors at send time. This supports dynamic, per-customer contracts (pricing tables, addenda, jurisdiction-specific clauses) without maintaining a parallel library of DocuSign templates — a meaningful reduction in ops and legal-review overhead.
• Placement quality as a product-quality lever: The per-tab anchorYOffset plus the document-wide anchorYOffsetPixels fine-tune let the team correct visual drift in signature placement without a code deploy. That's a config-level knob for a class of defects that otherwise generates support tickets and re-sends — worth calling out in launch readiness and QA plans.
• Reliable post-signature document retrieval: downloadSignedDocument() keyed on the caller's own Document::$id (mapped via a persisted envelope custom field, with a document-name fallback and Summary.pdf skipped) supports the downstream product surface — "download your signed contract" in the customer portal, archival to storage, and hand-off to billing. The retryable SignedDocumentUnavailableException explicitly models the real-world gap between "signing complete" and "document finalized," which shapes UX (show "preparing your document" states rather than hard failures).
• Compliance and audit as a first-class deliverable: downloadAudit() returning DocuSign's Certificate of Completion as PDF — with the raw audit_events JSON still reachable via DocuSignClient::downloadAuditEventsJson() — supports legal/audit requirements and any "prove who signed what, when" obligation. This is the artifact that often unblocks enterprise or regulated-customer deals.
• Webhook-driven state machines: The included EventType mapping for DocuSign Connect callbacks means product can design event-driven flows (sent → delivered → completed → declined → voided) without bespoke parsing per provider. This underpins notification, retry, and lifecycle features.
• Use cases this unblocks: self-serve contract signing in onboarding, sales quote/order-form acceptance, HR offer letters, vendor and partner agreements, terms acceptance with evidentiary audit trail, and multi-document packets with per-document retrieval.

When to Consider This Package

Adopt when:

• DocuSign is (or will be) the eSignature provider, and you want the integration to be a bounded, testable adapter rather than logic spread across controllers and jobs.
• You already use, or are willing to adopt, la-souris/document-signer-sdk ^1.0 — this package is explicitly a provider implementation for that contract, not a standalone signing library. Confirm the contract's abstractions fit your domain before committing.
• Your documents are generated dynamically from anchors rather than managed as DocuSign templates, or you want to migrate away from template sprawl.
• You need signed-document retrieval, Certificate of Completion, and webhook event handling as part of the product surface — not just "send for signature."
• Your runtime is PHP 8.3+ and a Laravel version compatible with the SDK. Verify this against your platform upgrade roadmap; if you're on 8.1/8.2, the PHP floor is a gating dependency, not a footnote.
• You want provider optionality later (the ValidSign placement-parity note signals multi-provider intent) and value the contract boundary.

Look elsewhere or defer when:

• You need a provider other than DocuSign today — check the SDK for existing implementations first; this release adds only DocuSign.
• You require embedded/in-person signing UX, identity verification, payment collection at signing, or notary workflows — none are described here; validate against DocuSign's own capabilities and whether this wrapper exposes them.
• You expect a full Laravel package surface (config publishing, migrations, facades, artisan tooling). This reads as a focused provider library: config objects and clients, not an opinionated application module. If you need batteries-included, budget integration work.
• You're mid-migration on PHP versions, or you cannot accept a v1.0.0 initial public release as a dependency. First public releases carry API-shape risk; the SignatureProvider contract softens this, but pin versions and expect minor churn.
• Your volume or compliance posture requires a vendor with a dedicated support SLA and a longer public track record than a brand-new release.
• You only need "email a PDF and collect a signature" — a lighter-weight service may be cheaper than DocuSign plus this integration.

How to Pitch It (Stakeholders)

To executives (business case): This package lets us ship DocuSign-powered contract signing inside our product without building signing infrastructure ourselves, and without hard-wiring the business to one vendor. It covers the full commercial loop that customers and auditors actually ask about: send for signature, place fields accurately on dynamically generated documents, retrieve the signed PDF, and produce DocuSign's Certificate of Completion as evidence. The strategic value is the contract boundary: DocuSign is the first provider behind a shared interface, so provider choice stays a commercial decision rather than a rewrite. Cost profile is DocuSign's per-envelope pricing plus integration effort — no new platform to operate. Risk to flag honestly: this is a v1.0.0 initial public release and requires PHP 8.3+, so we should pin the version, confirm our PHP upgrade timing, and treat early adoption as a tracked dependency with a fallback plan.

To engineering: This is a provider adapter, not a framework. It implements the la-souris/document-signer-sdk SignatureProvider contract: DocuSignProvider with DocuSignConfig, DocuSignClient, and JWT auth via DocuSignJwtAuth. Notable engineering-relevant specifics: anchor-based tab placement with per-tab anchorYOffset and a document-wide anchorYOffsetPixels fine-tune (config, not code, for drift correction); explicit sizing on every field type; document-id mapping persisted in an envelope-level sdkDocumentMap custom field with a normalized-name fallback and Summary.pdf excluded; retryable SignedDocumentUnavailableException for not-yet-finalized documents; downloadAudit() for the Certificate of Completion PDF with raw audit_events JSON available separately; and EventType mapping for Connect webhooks. Constraints: PHP 8.3+, SDK ^1.0. Expect to own config wiring, idempotent webhook handling, retry/backoff around the retryable exception, and observability. Given v1.0.0, pin the version and keep the boundary thin so an SDK bump is a contained change.

Ask: approve a scoped pilot (one document flow end-to-end: generate → anchor-place → send → webhook → retrieve signed PDF + certificate) to validate placement accuracy and the finalization-timing UX before committing to broader rollout.