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), Mappingpandadoc_document_id ↔ {tenant, projekt_id, angebot_id}. - Tenant-Zuordnung der Webhooks: pro-Tenant-URL (
…/webhooks/pandadoc/{tenantId}) +metadata.hivegrid_tenant_id/projekt_idam Dokument (kommt im Payload zurück, wennpayload:[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_keyin 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_idkommen 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. → Derpandadoc-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