API: communication-signing-and-realtime

Ort: work7_laendletech/docs/api/api-communication-signing-and-realtime.md

Überblick

• Base-URL / Prefix: /api/whatsapp, /api/ai, /api/speech, /api/notifications, /api/realtime, /api/docusign, /api/signing, /api/pdf, /api/contact
• Auth: Gemischt; interne Session-Endpunkte, Provider-Webhooks und oeffentliche Callback-/Kontakt-Endpunkte
• Format: JSON

Endpoint(s)

GET|POST /api/whatsapp/webhook

Zweck:

Webhook-Verifikation und eingehende WhatsApp-Nachrichten; POST antwortet sofort mit 200 und proxyt asynchron an den Agent-Service.

Request

Feld	Typ	Pflicht	Beschreibung
hub.mode	query string	bei GET ja	Webhook-Handshake
hub.verify_token	query string	bei GET ja	Verify-Token
hub.challenge	query string	bei GET ja	Challenge-Antwort
entry	JSON	bei POST ja	Provider-Payload

Response 200

{
  "ok": true
}

Fehler

HTTP	Bedeutung	Body-Hinweis
403	Webhook-Verifikation fehlgeschlagen	Plain text / forbidden

GET /api/whatsapp/health

Zweck:

Health-Check fuer WhatsApp-Integration.

POST /api/whatsapp/test-send

Zweck:

Testnachricht senden.

POST /api/ai/chat

Zweck:

Webbasierter Chat-Endpunkt fuer AI-/Agent-Funktionen.

POST /api/speech/transcribe

Zweck:

Transkribiert Audio.

GET /api/notifications

Zweck:

Benachrichtigungen laden.

POST /api/notifications/mark-read

Zweck:

Benachrichtigungen als gelesen markieren.

POST /api/notifications/clear

Zweck:

Benachrichtigungen leeren.

GET /api/notifications/stream

Zweck:

Streaming-Endpunkt fuer Live-Benachrichtigungen.

GET /api/realtime/socket

Zweck:

Initialisiert oder exponiert Socket.IO / Realtime-Konnektivitaet.

GET /api/swagger

Zweck:

Liefert OpenAPI-/Swagger-Dokumentation.

GET /api/pdf/offers/[id]

Zweck:

Erzeugt oder liefert Angebots-PDF.

GET /api/pdf/invoices/[id]

Zweck:

Erzeugt oder liefert Rechnungs-PDF.

GET /api/pdf/rapport/[id]

Zweck:

Erzeugt oder liefert Rapport-PDF.

GET /api/docusign/start

Zweck:

Initialisiert Signaturflow.

GET /api/docusign/callback

Zweck:

Verarbeitet Callback des Signaturproviders.

POST /api/signing/callback

Zweck:

Verarbeitet Signatur-Callback.

POST /api/signing/offer/[id]

Zweck:

Startet oder verarbeitet Signierung eines Angebots.

POST /api/signing/rapport/[id]

Zweck:

Startet oder verarbeitet Signierung eines Rapports.

POST /api/contact

Zweck:

Kontaktformular oder Kontaktanfrage verarbeiten.

POST /api/contact/access-request

Zweck:

Zugriffsanfrage oder Demo-/Kontaktwunsch verarbeiten.

Rate Limiting / Limits

• Max Requests: Webhooks und Kontaktformulare sollten als sensible Endpunkte betrachtet werden
• Timeout: Webhooks antworten schnell; Provider- und Streaming-Endpunkte haben eigene Laufzeitprofile
• Max Payload: JSON, bei Audio- und Messaging-Endpunkten variabel

Breaking Changes / Versionierung

• Webhook-Contracts mit Providern sind besonders empfindlich gegen Payload-Aenderungen.
• Realtime- und Streaming-Endpunkte sollten nur kompatibel erweitert werden.

Beispiel (curl)

curl -sS -X POST http://localhost:3000/api/whatsapp/webhook \
  -H "Content-Type: application/json" \
  -d '{"entry":[{"changes":[{"value":{"messages":[]}}]}]}'

Verwandte Notes

• Feature-Spec: work7
• OpenAPI/Schema: /api/swagger

Follow-ups

• [ ] Postman Collection prüfen: passt es in bestehende Collection? Sonst neu anlegen → work7_laendletech/src/postman/ 📅 2026-04-16
• [ ] In Feature-Spec verlinken falls zugehörig 📅 2026-04-16