Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/EXT-17.md
T

69 lines
5.8 KiB
Markdown

# 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
- [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)