API · Corporate-Plan

Verbinde deine Systeme mit Plensity

Lege Kunden und Angebote aus deinem CRM an, verfolge den Stand jedes Angebots und lade das unterschriebene PDF samt Zertifikat herunter, ohne die App zu öffnen.

Erste Schritte

1In Plensity öffnet ein Admin Einstellungen → API und erstellt einen Schlüssel. Er wird nur einmal angezeigt: bewahre ihn sicher auf.
2Jeder Aufruf trägt den Schlüssel im Header Authorization: Bearer pls_….
3Prüfe mit GET /me, ob er funktioniert: Die Antwort nennt deinen Firmennamen und die Berechtigung des Schlüssels.

Basis-URL

https://app.plensity.io/api/v1

Schlüssel und Berechtigungen

Nur lesen: abfragen und herunterladen. Lesen und schreiben: zusätzlich anlegen und ändern.
Ein Schlüssel sieht nur die Daten deiner Firma und handelt im Namen des Admins, der ihn erstellt hat: Änderungen stehen im Audit-Log als „API: Name des Schlüssels“.
Er funktioniert sofort nicht mehr, wenn er widerrufen wird, wenn sein Ersteller kein Admin mehr ist oder wenn die Firma den Corporate-Plan verlässt.
Plensity speichert den Schlüssel nicht, nur einen Fingerabdruck. Geht er verloren, widerrufe ihn und erstelle einen neuen.

Format

Anfragen und Antworten in JSON (Content-Type: application/json). Feldnamen sind englisch.
Datumsangaben in ISO 8601. Beträge als Zahl, in der Währung aus currency.
Listen werden mit limit (bis 200, Standard 50) und offset geblättert und liefern {"data": [...], "total", "limit", "offset"}.
Bis zu 120 Aufrufe pro Minute und Schlüssel. Darüber 429 rate_limited: kurz warten und erneut versuchen.

Referenz

GET/me

Kunden

GET/clients

Listet die Kunden. Filter mit q (Name oder Branche).

GET/clients/{id}

Ein Kunde.

POST/clientsschreiben

Legt einen Kunden an. name ist Pflicht; dazu sector, contact_name, contact_role, contact_email und contact_phone. Gibt es bereits einen mit diesem Namen (ohne Groß-/Kleinschreibung und Akzente), wird er nicht doppelt angelegt: Der vorhandene wird mit 200 und already_existed: true zurückgegeben.

PATCH/clients/{id}schreiben

Ändert die gesendeten Felder.

Angebote

GET/proposals

Listet die Angebote. Filter mit status, client_id und updated_since (ISO-8601-Datum).

GET/proposals/{id}

Ein Angebot mit seinen Leistungen, ob der Kunde es geöffnet hat (tracking), ob und von wem es unterschrieben wurde (signature) und Links zu PDF und Zertifikat. Jede Leistung nennt in billing ihre Abrechnungsart (fixed, per_day, monthly, per_unit), recurring_monthly ist die Monatsgebühr und amount der gesamte Vertragswert ohne Steuer.

POST/proposalsschreiben

Legt den Entwurf eines Angebots an, wie «+ Neues Angebot». client_id ist Pflicht; dazu title, description (was der Kunde möchte), deadline (JJJJ-MM-TT), owner_email (wer es betreut) und template_id.

PATCH/proposals/{id}schreiben

Ändert den Status mit status (und lost_reason bei Verlust). Mit denselben Regeln wie in Plensity: Ein Entwurf wird nicht gewonnen, und nichts geht ohne freigegebene Marge raus.

GET/proposals/{id}/pdf

Das PDF. Nach dem Versand das, was der Kunde erhalten hat.

GET/proposals/{id}/signature-certificate

Das Signaturzertifikat. 404 not_signed, wenn nicht unterschrieben.

Angebotsstatus

draftgeneratedsentclient_approvedwonlostcancelled

Beispiel

curl "https://app.plensity.io/api/v1/proposals/42" \
  -H "Authorization: Bearer pls_…"

{
  "id": 42,
  "reference": "REF-2026-042",
  "title": "Servicio gestionado 2027",
  "client_id": 7,
  "client_name": "Transportes Aldama",
  "status": "sent",
  "amount": 24900.0,
  "currency": "EUR",
  "sent_at": "2026-09-21T10:14:03",
  "tracking": {
    "opened": true,
    "views": 3,
    "first_opened_at": "2026-09-21T11:02:40",
    "last_opened_at": "2026-09-24T08:31:12"
  },
  "signature": { "signed": false, "signed_at": null, "signer_name": null, "signer_email": null, "signer_company": null },
  "recurring_monthly": 2075.0,
  "services": [{
    "name": "Servicio gestionado", "type": "managed", "price": 24900.0,
    "billing": { "type": "monthly", "unit_price": 2075.0, "quantity": 12, "unit": null }
  }],
  "links": {
    "pdf": "https://app.plensity.io/api/v1/proposals/42/pdf",
    "signature_certificate": null
  }
}

curl -X POST "https://app.plensity.io/api/v1/proposals" \
  -H "Authorization: Bearer pls_…" \
  -H "Content-Type: application/json" \
  -d '{"title": "Renovación 2027", "client_id": 7,
       "deadline": "2027-01-31",
       "owner_email": "laura@tuempresa.com"}'

Fehler

Immer in derselben Form. Bei validation_failed nennt fields das Problem je Feld.

{
  "error": {
    "code": "validation_failed",
    "message": "…",
    "fields": { "client_id": "…" }
  }
}

400	invalid_json	Der Body ist kein JSON-Objekt.
400	invalid_parameter	Ein URL-Parameter ist ungültig.
401	unauthorized	Der Schlüssel fehlt.
401	invalid_key	Der Schlüssel existiert nicht oder wurde widerrufen.
401	key_owner_inactive	Der Ersteller des Schlüssels ist kein aktiver Admin mehr.
403	plan_required	Dein Plan enthält die API nicht.
403	read_only_key	Der Schlüssel ist nur zum Lesen.
404	not_found	Existiert nicht oder gehört nicht zu deiner Firma.
404	not_signed	Das Angebot ist nicht unterschrieben.
405	method_not_allowed	Diese Methode gibt es auf dieser Route nicht.
409	invalid_transition	Dieser Statuswechsel ist nicht erlaubt.
410	gone	Gibt es nicht mehr. Verkaufschancen wurden entfernt: alles kommt aus den Angeboten (<code>/proposals</code>).
422	validation_failed	Einige Felder sind ungültig.
429	rate_limited	Zu viele Aufrufe: kurz warten.
500	server_error	In Plensity ist etwas schiefgelaufen: gleich erneut versuchen.

Benachrichtigt werden?

Um sofort zu erfahren, dass ein Angebot versendet, im Status geändert oder gewonnen wurde, ohne ständig abzufragen, richte unter Einstellungen → Webhooks einen Webhook ein: Plensity ruft dein System auf, wenn es passiert.

Zum Corporate-Plan schreiben