API di integrazione Ciamem

Identità della chiave

Verifica che la chiave funzioni: ritorna tenant, pacchetto, permessi e limiti.

curl "https://ciamem.com/api/v1/me" \
  -H "Authorization: Bearer ciamem_live_…"

Elenco del catalogo

Prodotti e servizi del tenant. Filtri: q (nome/categoria/sku), category. Il prezzo è null se non indicato.

Parametri: q · category · limit · offset

curl "https://ciamem.com/api/v1/catalog" \
  -H "Authorization: Bearer ciamem_live_…"

Crea un articolo di catalogo

Prodotto o servizio. Il prezzo è facoltativo. Tetto: 100 articoli.

{
  "name": "Vite inox M6",
  "category": "Ferramenta",
  "price": 0.12,
  "unit": "pz",
  "sku": "VX-M6",
  "notes": ""
}

curl -X POST "https://ciamem.com/api/v1/catalog" \
  -H "Authorization: Bearer ciamem_live_…" \
  -H "content-type: application/json" \
  -d '{"name":"Vite inox M6","category":"Ferramenta","price":0.12,"unit":"pz","sku":"VX-M6","notes":""}'

Aggiorna un articolo di catalogo

Aggiorna nome, categoria, prezzo (vuoto = nessun prezzo), unità, sku, note, attivo.

{
  "price": 0.15,
  "active": true
}

curl -X PUT "https://ciamem.com/api/v1/catalog/:id" \
  -H "Authorization: Bearer ciamem_live_…" \
  -H "content-type: application/json" \
  -d '{"price":0.15,"active":true}'

Elimina un articolo di catalogo

curl -X DELETE "https://ciamem.com/api/v1/catalog/:id" \
  -H "Authorization: Bearer ciamem_live_…"

Elenco degli ordini

Filtri: status (ricevuto|in-lavorazione|evaso|annullato|aperti), companyId, q, from, to (YYYY-MM-DD).

Parametri: status · companyId · q · from · to · limit · offset

curl "https://ciamem.com/api/v1/orders" \
  -H "Authorization: Bearer ciamem_live_…"

Dettaglio di un ordine

Accetta l'id o il codice (ORD-0001). Include righe, totale e timeline.

curl "https://ciamem.com/api/v1/orders/:id" \
  -H "Authorization: Bearer ciamem_live_…"

Aggiorna un ordine (stato, nota)

Cambia lo stato (ricevuto|in-lavorazione|evaso|annullato) o aggiunge una nota. Accetta anche PUT.

{
  "status": "evaso",
  "note": "Spedito con corriere"
}

curl -X PATCH "https://ciamem.com/api/v1/orders/:id" \
  -H "Authorization: Bearer ciamem_live_…" \
  -H "content-type: application/json" \
  -d '{"status":"evaso","note":"Spedito con corriere"}'

Elenco dei contatti

La rubrica del tenant. Filtri: q (numero, nome o azienda), companyId.

Parametri: q · companyId · limit · offset

curl "https://ciamem.com/api/v1/contacts" \
  -H "Authorization: Bearer ciamem_live_…"

Dettaglio di un contatto

Il contatto è identificato dal numero di telefono (o dall'id chat per i clienti Telegram).

curl "https://ciamem.com/api/v1/contacts/:number" \
  -H "Authorization: Bearer ciamem_live_…"

Crea o aggiorna un contatto

Se il contatto non esiste viene creato.

{
  "name": "Mario Rossi",
  "company": "Acme SRL",
  "companyId": "id azienda in anagrafica",
  "notes": "Cliente storico",
  "language": "it"
}

curl -X PUT "https://ciamem.com/api/v1/contacts/:number" \
  -H "Authorization: Bearer ciamem_live_…" \
  -H "content-type: application/json" \
  -d '{"name":"Mario Rossi","company":"Acme SRL","companyId":"id azienda in anagrafica","notes":"Cliente storico","language":"it"}'

Elimina un contatto

Il bot non lo riconoscerà più alla chiamata successiva.

curl -X DELETE "https://ciamem.com/api/v1/contacts/:number" \
  -H "Authorization: Bearer ciamem_live_…"

Elenco dei clienti (aziende)

Filtri: q (nome o P.IVA), status (regolare | bloccato).

Parametri: q · status · limit · offset

curl "https://ciamem.com/api/v1/companies" \
  -H "Authorization: Bearer ciamem_live_…"

Crea un cliente

Lo stato "bloccato" impedisce al bot di aprire ticket per i contatti di quest'azienda.

{
  "name": "Acme SRL",
  "vat": "01234567890",
  "status": "regolare",
  "phone": "",
  "email": "",
  "address": "",
  "notes": ""
}

curl -X POST "https://ciamem.com/api/v1/companies" \
  -H "Authorization: Bearer ciamem_live_…" \
  -H "content-type: application/json" \
  -d '{"name":"Acme SRL","vat":"01234567890","status":"regolare","phone":"","email":"","address":"","notes":""}'

Dettaglio di un cliente

curl "https://ciamem.com/api/v1/companies/:id" \
  -H "Authorization: Bearer ciamem_live_…"

Aggiorna un cliente

L'azienda predefinita "(anonimo)" non è modificabile.

{
  "name": "Acme SRL",
  "status": "bloccato"
}

curl -X PUT "https://ciamem.com/api/v1/companies/:id" \
  -H "Authorization: Bearer ciamem_live_…" \
  -H "content-type: application/json" \
  -d '{"name":"Acme SRL","status":"bloccato"}'

Elimina un cliente

I contatti associati tornano sull'azienda "(anonimo)". I ticket già aperti restano.

curl -X DELETE "https://ciamem.com/api/v1/companies/:id" \
  -H "Authorization: Bearer ciamem_live_…"

Ricerca ticket

Filtri: status (aperto | assegnato | chiuso | aperti = tutti i non chiusi), companyId, agent, from, to (YYYY-MM-DD), q. Per la sincronizzazione incrementale usa updatedSince (ISO): ricevi solo i ticket cambiati.

Parametri: status · companyId · agent · from · to · q · updatedSince · limit · offset

curl "https://ciamem.com/api/v1/tickets" \
  -H "Authorization: Bearer ciamem_live_…"

Apre un ticket

Il ticket viene annunciato agli agenti su Telegram col bottone di presa in carico, come quelli aperti dal bot. Intestazione Idempotency-Key: un retry dopo un timeout non crea un doppione.

{
  "text": "Stampante fiscale in blocco",
  "companyId": "id azienda (facoltativo)",
  "contactName": "Mario Rossi",
  "contactKey": "+393331234567",
  "priority": "normale | alta"
}

curl -X POST "https://ciamem.com/api/v1/tickets" \
  -H "Authorization: Bearer ciamem_live_…" \
  -H "content-type: application/json" \
  -d '{"text":"Stampante fiscale in blocco","companyId":"id azienda (facoltativo)","contactName":"Mario Rossi","contactKey":"+393331234567","priority":"normale | alta"}'

Dettaglio di un ticket

Accetta l'id interno o il codice (TK-0001). Include la timeline e i metadati delle foto allegate.

curl "https://ciamem.com/api/v1/tickets/:id" \
  -H "Authorization: Bearer ciamem_live_…"

Aggiunge una nota al ticket

La nota entra nella timeline ed è visibile agli agenti.

{
  "text": "Intervento pianificato per lunedì"
}

curl -X POST "https://ciamem.com/api/v1/tickets/:id/entries" \
  -H "Authorization: Bearer ciamem_live_…" \
  -H "content-type: application/json" \
  -d '{"text":"Intervento pianificato per lunedì"}'

Aggiorna un ticket (priorità, chiusura)

Chiudendo il ticket il cliente viene avvisato sul canale chat da cui l'ha aperto. Accetta anche PUT.

{
  "status": "chiuso",
  "note": "Sostituita la scheda",
  "priority": "alta"
}

curl -X PATCH "https://ciamem.com/api/v1/tickets/:id" \
  -H "Authorization: Bearer ciamem_live_…" \
  -H "content-type: application/json" \
  -d '{"status":"chiuso","note":"Sostituita la scheda","priority":"alta"}'

Elenco degli agenti

Gli agenti Telegram del tenant e il loro stato (in turno o in pausa).

curl "https://ciamem.com/api/v1/agents" \
  -H "Authorization: Bearer ciamem_live_…"

Mette un agente in pausa o lo rimette in turno

In pausa non riceve nuovi ticket né notifiche, ma continua a gestire i ticket già suoi. Aggiungere o rimuovere agenti resta un'operazione da console.

{
  "paused": true
}

curl -X PATCH "https://ciamem.com/api/v1/agents/:chatId" \
  -H "Authorization: Bearer ciamem_live_…" \
  -H "content-type: application/json" \
  -d '{"paused":true}'