Files
HiveGrid-Wireframes/hivegrid-cloud/.planning/ticket-docs/EXT-17.md
T

5.8 KiB

EXT-17 · PandaDoc-BYOK-Adapter (optionale Signatur-Anbindung)

Typ Feature / Integration (Apps-Engine-Adapter)
Owner Raffael
Cycle/Fenster optional zu P16 — Adapter neben dem SES-Default (AD-25)
Status In Progress (BYOK-Beispiel wird mit Kunden-Account durchgespielt)

Was zu tun ist

Optionaler pandadoc-byok-Adapter (Apps-Engine, defineAdapter) neben dem SES-Eigenbau-Default (EXT-09, AD-25). Tenants mit eigenem PandaDoc-Account tragen ihren eigenen API-Key ein; HiveGrid erstellt/sendet Angebots-Dokumente über deren Account und holt den Signatur-Status zurück. CLOUD-Act-/DSGVO-Verantwortung liegt durch das Opt-in beim Tenant.

Anbindungs-Spec (recherchiert 2026-06-21)

Base-URL: https://api.pandadoc.com/public/v1 · Auth-Header: Authorization: API-Key <key> (NICHT Bearer).

Schritt Endpoint Notiz
Dokument aus PDF POST /documents?upload (multipart: file + data) PDF max 50 MB; Feld-Positionen via Field-Tags im PDF ([signature:kunde], [textfield:kunde:angebotsnr___]) oder parse_form_fields:true
(alt.) aus Template POST /documents (JSON: name,template_uuid,recipients,tokens,fields)
Verarbeitung abwarten Status uploaded → draft (~3-5 s) per Webhook document_state_changed statt pollen
Senden POST /documents/{id}/send nur aus draft; Status → sent→viewed→completed
Status (Pull) GET /documents/{id} bis 600 req/min
Webhook (Push) POST /webhook-subscriptions (url,triggers,payload:[metadata],shared_key) Events: document_state_changed, document_completed_pdf_ready, recipient_completed
Signiertes PDF GET /documents/{id}/download-protected rechtsverbindlich versiegelt; nur Production-Key (Sandbox→401)

Webhook-Verifizierung: HMAC-SHA256 über den rohen Body mit dem Subscription-Shared-Key; Signatur kommt als Query-Param ?signature=… → timing-safe vergleichen.

BYOK / Multi-Tenant

  • Tenant richtet ein: Dev Center → API-Key generieren (stabiler User!); Production-API braucht Enterprise-Plan + Sales-Approval, Sandbox geht ab Business/Dev-Center.
  • Adapter speichert pro Tenant: API-Key (Sandbox+Prod, DEK-verschlüsselt im Credential-Store/core.prisma), Webhook-Subscription-ID + Shared-Key, Env-Flag (Sandbox/Prod), Mapping pandadoc_document_id ↔ {tenant, projekt_id, angebot_id}.
  • Tenant-Zuordnung der Webhooks: pro-Tenant-URL (…/webhooks/pandadoc/{tenantId}) + metadata.hivegrid_tenant_id/projekt_id am Dokument (kommt im Payload zurück, wenn payload:[metadata] abonniert).
  • Rate-Limits: Prod 60 req/min (endpoint-spezifisch höher), Sandbox nur 10 req/min → Backoff bei 429.

Offene Punkte (beim Bau verifizieren)

  • Kommt der shared_key in der Create-Subscription-Response zurück (→ vollautomatisches Provisioning) oder nur aus dem Dashboard? (entscheidet, ob der Tenant manuell kopieren muss)
  • Exaktes data-Schema beim Multipart-Upload gegen offizielles SDK/Postman gegenchecken.
  • Production-Approval-Vorlauf im Adapter-UI als Voraussetzung kommunizieren.

Warum / was es blockt

  • Blocks: P16 (AK-P16d) — optionaler Adapter; Default bleibt SES.

Abhängigkeiten

  • blocked-by: Tenant mit eigenem PandaDoc-Account + API-Key (für BYOK-Durchlauf: Kunden-Sandbox-Key)
  • blocks: P16 (AK-P16d, optionaler Pfad)

POC-Ergebnis (2026-06-21, Geerkens-Sandbox-Key)

End-to-end gegen die echte PandaDoc-Sandbox durchgespielt + validiert:

  • ✅ Auth (Authorization: API-Key), Create-from-PDF, Draft-Übergang, Tags.
  • ✅ Metadata-Mandanten-Trennung: hivegrid_tenant_id/projekt_id kommen am Dokument zurück → BYOK-Tenant-Zuordnung funktioniert.
  • ✅ Send: an org-interne Adresse (entwicklung@geerkens.de) → document.sent, Mail kam beim Empfänger an.

Account-bedingte Befunde (kein Code-Problem, aber wichtig für den Adapter):

  • Send nur org-intern in der Sandbox → 403 „send outside organization" (Account-Policy; in Prod erlaubt der Tenant externen Versand ohnehin, sonst könnte er keine Kunden anschreiben).
  • PDF-Field-Tags werden nicht geparst (Empfänger fällt auf CC, fields: 0) — Geerkens' Account ist Template-basiert. → Der pandadoc-byok-Adapter sollte für PandaDoc den Template-Weg nutzen (template_uuid + fields/tokens), nicht PDF-Field-Tags.
  • Test-Dokumente nach dem Durchlauf wieder gelöscht (Account sauber).

Definition of Done

  • Anbindungs-Spec recherchiert + dokumentiert (Auth, Create, Send, Webhook, Download, BYOK)
  • BYOK-Beispiel mit echtem Kunden-Account (Geerkens-Sandbox) durchgespielt — Auth → Create → Draft → Metadata → Send → Mail ✅
  • [→] pandadoc-byok-Adapter bauen → P16 / AK-P16d (Dev-Arbeit, Template-Weg; Credential-Store, Webhook-Verify HMAC-SHA256)
  • [→] Tenant-Settings-UI „PandaDoc verbinden" → P16 / AK-P16d

Status: Externals-/Vorarbeits-Scope erfüllt — abschlussreif (Done). Spec dokumentiert + BYOK real validiert (POC oben). Der eigentliche Adapter-Bau + UI sind P16-Dev-Arbeit (AK-P16d, Spec dort verlinkt). Selbst als Externals offen: 0.

Quellen

developers.pandadoc.com: Auth · Create from Upload · Field-Tags · Send · Webhooks · Webhook-Verify · Download-protected · Limits