# 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 ` (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 - [x] Anbindungs-Spec recherchiert + dokumentiert (Auth, Create, Send, Webhook, Download, BYOK) - [x] 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](https://developers.pandadoc.com/reference/api-key-authentication-process) · [Create from Upload](https://developers.pandadoc.com/reference/create-document-from-upload) · [Field-Tags](https://developers.pandadoc.com/docs/field-tags) · [Send](https://developers.pandadoc.com/reference/send-document) · [Webhooks](https://developers.pandadoc.com/docs/webhook-events) · [Webhook-Verify](https://developers.pandadoc.com/docs/webhook-verification) · [Download-protected](https://developers.pandadoc.com/reference/download-protected-document) · [Limits](https://developers.pandadoc.com/reference/limits)