API · Piano Corporate

Collega i tuoi sistemi a Plensity

Crea clienti e offerte dal tuo CRM, segui lo stato di ogni offerta e scarica il PDF firmato e il suo certificato, senza passare dall’app.

Primi passi

1In Plensity, un amministratore va in Impostazioni → API e crea una chiave. Viene mostrata una sola volta: conservala in un luogo sicuro.
2Ogni chiamata porta la chiave nell’intestazione Authorization: Bearer pls_….
3Verifica che funzioni con GET /me: risponde con il nome della tua azienda e il permesso della chiave.

Indirizzo base

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

Chiavi e permessi

Sola lettura: consulta e scarica. Lettura e scrittura: inoltre crea e modifica.
Una chiave vede solo i dati della tua azienda e agisce per conto dell’amministratore che l’ha creata: le modifiche restano nel registro come «API: nome della chiave».
Smette di funzionare subito se viene revocata, se chi l’ha creata non è più amministratore o se l’azienda lascia il piano Corporate.
Plensity non conserva la chiave, solo un’impronta. Se la perdi, revocala e creane un’altra.

Formato

Richieste e risposte in JSON (Content-Type: application/json). I nomi dei campi sono in inglese.
Date in ISO 8601. Importi come numero, nella valuta di currency.
Gli elenchi si paginano con limit (fino a 200, predefinito 50) e offset, e rispondono {"data": [...], "total", "limit", "offset"}.
Fino a 120 chiamate al minuto per chiave. Oltre, 429 rate_limited: attendi un momento e riprova.

Riferimento

GET/me

Clienti

GET/clients

Elenca i clienti. Filtra con q (nome o settore).

GET/clients/{id}

Un cliente.

POST/clientsscrittura

Crea un cliente. name è obbligatorio; inoltre sector, contact_name, contact_role, contact_email e contact_phone. Se ne esiste già uno con quel nome (senza contare maiuscole e accenti), non viene duplicato: si restituisce quello esistente con 200 e already_existed: true.

PATCH/clients/{id}scrittura

Modifica i campi che invii.

Offerte

GET/proposals

Elenca le offerte. Filtra con status, client_id e updated_since (data ISO 8601).

GET/proposals/{id}

Un’offerta con i suoi servizi, se il cliente l’ha aperta (tracking), se è firmata e da chi (signature) e i link al PDF e al certificato. Ogni servizio indica come si paga in billing (fixed, per_day, monthly, per_unit), recurring_monthly è il canone mensile e amount il valore totale del contratto, IVA esclusa.

POST/proposalsscrittura

Crea la bozza di un’offerta, come «+ Nuova proposta». client_id è obbligatorio; inoltre title, description (ciò che chiede il cliente), deadline (AAAA-MM-GG), owner_email (chi la segue) e template_id.

PATCH/proposals/{id}scrittura

Cambia lo stato con status (e lost_reason se persa). Con le stesse regole di Plensity: una bozza non diventa vinta, né parte senza il margine approvato.

GET/proposals/{id}/pdf

Il PDF. Se già inviata, quello ricevuto dal cliente.

GET/proposals/{id}/signature-certificate

Il certificato di firma. 404 not_signed se non è firmata.

Stati dell’offerta

draftgeneratedsentclient_approvedwonlostcancelled

Esempio

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"}'

Errori

Sempre con la stessa forma. Con validation_failed, fields indica cosa non va in ogni campo.

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

400	invalid_json	Il corpo non è un oggetto JSON.
400	invalid_parameter	Un parametro dell’URL non è valido.
401	unauthorized	Manca la chiave.
401	invalid_key	La chiave non esiste o è stata revocata.
401	key_owner_inactive	Chi ha creato la chiave non è più un amministratore attivo.
403	plan_required	Il tuo piano non include l’API.
403	read_only_key	La chiave è di sola lettura.
404	not_found	Non esiste, o non è della tua azienda.
404	not_signed	L’offerta non è firmata.
405	method_not_allowed	Quel metodo non esiste su quel percorso.
409	invalid_transition	Quel cambio di stato non è consentito.
410	gone	Non esiste più. Le opportunità sono state rimosse: tutto viene dalle offerte (<code>/proposals</code>).
422	validation_failed	Alcuni campi non sono validi.
429	rate_limited	Troppe chiamate: attendi un momento.
500	server_error	Qualcosa è andato storto in Plensity: riprova tra poco.

Vuoi essere avvisato?

Per sapere subito quando un’offerta viene inviata, cambia stato o viene vinta, senza interrogare di continuo, configura un webhook in Impostazioni → Webhook: Plensity chiama il tuo sistema quando succede.

Scrivici del piano Corporate