# MyCentralino API

> Documentazione completa delle API REST del centralino VoIP in cloud MyCentralino.
> Base URL: https://api.mycentralino.com
> Docs: https://docs.mycentralino.com

## Autenticazione

Tutte le richieste (eccetto GET /v1/ping) richiedono l'header:
  X-API-KEY: sk_mycentralino_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Rate limiting per account (non per chiave):
- 20 richieste/minuto (default)
- 1000 richieste/giorno (default)

Headers di risposta inclusi: X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day.
Se superati: HTTP 429 con header Retry-After.

Formato risposte JSON: { "success": true, "data": {...} } oppure { "success": false, "error": "..." }
Codici HTTP: 200 (successo), 400 (richiesta non valida), 401 (API key mancante/non valida), 404 (non trovato), 429 (rate limit), 500 (errore interno), 503 (server non raggiungibile).

---

## Endpoint

### GET /v1/ping
Endpoint pubblico, non richiede autenticazione. Verifica che il servizio sia attivo.
Risposta: { "status": "ok", "timestamp": "2024-03-15 14:32:10" }

### GET /v1/account
Informazioni account, limiti configurati e utilizzo corrente.
Risposta: context (string), key_name (string), limits.requests_per_minute (int), limits.requests_per_day (int), usage.minute.used (int), usage.minute.limit (int), usage.day.used (int), usage.day.limit (int).

### GET /v1/extensions
Lista tutti gli interni del centralino.
Risposta array: id (int), extension (string, nome tecnico), internal_number (string, caller ID), description (string), outbound_provider (string: PRINCIPALE|DISABILITATE|SCELTA MANUALE).

### GET /v1/extensions/{number}
Dettaglio di un interno specifico con configurazione SIP. Il parametro {number} puo' essere l'extension o il numero interno.
Risposta: come /v1/extensions + sip_config: { server: "sip.mycentralino.com", stun_server: "stun.mycentralino.com", username (string), port: 5060 }.
Errore 404: "Interno non trovato".

### GET /v1/extensions/status
Stato di registrazione di tutti gli interni.
Risposta array: extension (string), internal_number (string), description (string), status (string), is_online (bool).
Include summary: { online (int), offline (int) }.
Valori status: ONLINE (is_online=true), OFFLINE (false), BUSY (true), RINGING (true), CALLING (true), UNKNOWN (false).

### GET /v1/extensions/status/{number}
Stato di un singolo interno. Stessi campi + timestamp.

### GET /v1/calls/in
Chiamate in entrata di oggi e ieri (default).
Query params: page (int, default 1), limit (int, default 200, max 500), search (string, filtra per numero), numbers[] (array, filtra per numeri VoIP).
Risposta array: id (int), linkedid (string), calldate (string), caller_number (string), caller_id (string), destination (string), status (string: answered|not_answered|abandoned), answered (bool), abandoned (bool), total_duration (int, secondi), duration_formatted (string HH:MM:SS), call_legs (int).
Include pagination: current_page, total_pages, total_calls, per_page, showing_from, showing_to.
Include filters: date_range (start, end, description), numbers, search.

### GET /v1/calls/in/{date}
Chiamate in entrata per data specifica. Formato: YYYY-MM-DD. Non accetta date future.
Stessi query params e risposta di GET /v1/calls/in.

### GET /v1/calls/out
Chiamate in uscita di oggi e ieri (default).
Query params: page (int, default 1), limit (int, default 200, max 500), search (string), extensions[] (array, filtra per interni).
Risposta array: calldate (string), caller_id (string), source (string), destination (string), billsec (int, secondi), duration (string HH:MM:SS), disposition (string: ANSWERED|NO ANSWER|BUSY|FAILED), uniqueid (string), provider (string).
Include pagination e filters.

### GET /v1/calls/out/{date}
Chiamate in uscita per data specifica. Formato: YYYY-MM-DD. Non accetta date future.
Stessi query params e risposta di GET /v1/calls/out.

### GET /v1/queue
Lista tutte le code configurate con i relativi membri.
Risposta array: queue_name (string), strategy (string), timeout (int), musiconhold (string), announce (string), maxlen (int), members (array: extension, callerid, description), total_members (int).
Valori strategy: ringall (squilla tutti), roundrobin (a rotazione), leastrecent (meno recente), fewestcalls (meno chiamate), random (casuale).

### GET /v1/queue/{name}
Dettaglio coda specifica con statistiche giornaliere.
Risposta: stessi campi di /v1/queue + statistics: { date (string), calls_entered (int), calls_answered (int), calls_abandoned (int), avg_wait_time (int, secondi), avg_wait_time_formatted (string mm:ss) }.
Errore 404: "Coda non trovata".

### GET /v1/queue/live
Stato in tempo reale di TUTTE le code via connessione diretta al server telefonico (AMI).
Risposta array di code, ciascuna con:
- Parametri coda: queue_name, max, strategy, calls_waiting (int), holdtime (int), talktime (int), completed (int), abandoned (int), service_level (int), service_level_perf (float), weight (int).
- members (array): extension (string), name (string), status (string), status_code (int), paused (bool), in_call (bool), calls_taken (int), last_call (string|null), penalty (int), callerid (string), description (string).
- callers (array): position (int), channel (string), caller_number (string), caller_name (string), wait_seconds (int), wait_formatted (string mm:ss).
- summary: total_members (int), members_available (int), members_in_call (int), members_paused (int), members_unavailable (int), callers_waiting (int).
Valori status membri: AVAILABLE (1, disponibile), IN_CALL (2, in chiamata), BUSY (3, occupato), INVALID (4, non valido), UNAVAILABLE (5, offline), RINGING (6, squilla), RINGING_IN_USE (7, squilla in chiamata), ON_HOLD (8, in attesa), UNKNOWN (0).

### GET /v1/queue/{name}/live
Stato in tempo reale di una singola coda. Stessi campi di /v1/queue/live ma per una sola coda.
Il nome coda deve essere URL-encoded se contiene caratteri speciali (es: @ -> %40).
Errore 404: "Coda non trovata".

### POST /v1/call/originate
Origina una chiamata click-to-call: il centralino chiama prima l'interno, poi collega al numero di destinazione.
Request body JSON: extension (string, obbligatorio), number (string, obbligatorio), description (string, opzionale per caller ID).
Risposta successo: call_id (string), extension (string), number (string), channel (string), timestamp (string).
Errori: 400 parametri mancanti, 400 numero non valido (min 6 cifre), 404 interno non trovato, 503 connessione fallita.
Note: la chiamata e' asincrona, il numero viene pulito automaticamente, se description e' vuoto cerca nel CRM.

### GET /v1/blacklists
Elenco delle blacklist del centralino.
Risposta array: name (string), numbers_count (int), used_by_rules (array di string, numerazioni le cui regole usano la blacklist).

### POST /v1/blacklists
Crea una blacklist vuota.
Request body JSON: name (string, obbligatorio, max 50 caratteri, solo lettere/numeri/_/-).
Risposta 201: name, numbers (array vuoto), numbers_count, used_by_rules.
Errori: 400 nome non valido, 409 nome gia' esistente.

### GET /v1/blacklists/{name}
Dettaglio blacklist con tutti i numeri bloccati.
Risposta: name (string), numbers (array: id (int), number (string), description (string|null)), numbers_count (int), used_by_rules (array).
Il prefisso ^ in un numero indica blocco per prefisso (es. ^893 blocca tutti i numeri che iniziano con 893).
Errore 404: "Blacklist non trovata".
Variante GET /v1/blacklists/{name}/numbers: restituisce solo l'array dei numeri con count.

### DELETE /v1/blacklists/{name}
Elimina una blacklist con tutti i suoi numeri.
Query param: force (boolean, default false).
Se la blacklist e' usata da regole di instradamento risponde 409 con used_by_rules; con ?force=true elimina comunque.
Risposta: { name, deleted: true }.
Errore 404: "Blacklist non trovata".

### POST /v1/blacklists/{name}/numbers
Aggiunge un numero alla blacklist.
Request body JSON: number (string, obbligatorio, max 25 caratteri, cifre/+/*/# con eventuale prefisso ^), description (string, opzionale, max 100 caratteri).
Risposta 201: id (int), number, description.
Errori: 400 numero non valido, 404 blacklist non trovata, 409 numero gia' presente.

### GET /v1/blacklists/{name}/numbers/{id}
Dettaglio di un singolo numero della blacklist.
Risposta: id (int), number (string), description (string|null).
Errore 404: "Numero non trovato in questa blacklist".

### PUT /v1/blacklists/{name}/numbers/{id}
Modifica un numero esistente. I campi non forniti mantengono il valore attuale.
Request body JSON: number (string, opzionale), description (string, opzionale, stringa vuota per rimuoverla).
Risposta: id, number, description aggiornati.
Errori: 400 dati non validi, 404 numero non trovato, 409 numero gia' presente.

### DELETE /v1/blacklists/{name}/numbers/{id}
Rimuove un numero dalla blacklist. L'eliminazione dell'ultimo numero non elimina la blacklist.
Risposta: { id, deleted: true }.
Errore 404: "Numero non trovato in questa blacklist".

### GET /v1/voip/status
Stato di registrazione delle numerazioni VoIP.
Risposta array: number (string), registered (bool), provider (string), provider_label (string), username (string), sip_server (string), description (string), note (string).
Include summary: total (int), registered (int), unregistered (int).
Provider labels: Convergenze -> MyCentralino CVG, Messagenet -> MyCentralino MSG, SBC -> MyCentralino, VIRTUAL -> Virtuale.
Note: provider VIRTUAL e SBC risultano sempre registrati.

---

## Pagine documentazione

- [Benvenuto](https://docs.mycentralino.com): Panoramica del centralino VoIP in cloud
- [Introduzione API](https://docs.mycentralino.com/mycentralino-api/introduction): Autenticazione, rate limiting, formato risposte
- [Ping](https://docs.mycentralino.com/mycentralino-api/ping): Health check del servizio
- [Account](https://docs.mycentralino.com/mycentralino-api/account): Info account e utilizzo
- [Lista Interni](https://docs.mycentralino.com/mycentralino-api/extensions-list): Elenco interni
- [Dettaglio Interno](https://docs.mycentralino.com/mycentralino-api/extensions-detail): Dettaglio e configurazione SIP
- [Stato Interni](https://docs.mycentralino.com/mycentralino-api/extensions-status): Stato registrazione interni
- [Origina Chiamata](https://docs.mycentralino.com/mycentralino-api/call-originate): Click-to-call
- [Chiamate in Entrata](https://docs.mycentralino.com/mycentralino-api/calls-inbound): Storico chiamate in ingresso
- [Chiamate in Uscita](https://docs.mycentralino.com/mycentralino-api/calls-outbound): Storico chiamate in uscita
- [Code di Chiamata](https://docs.mycentralino.com/mycentralino-api/queue): Gestione e statistiche code
- [Stato Live Code](https://docs.mycentralino.com/mycentralino-api/queue-live): Stato real-time code via AMI
- [Stato Numerazioni VoIP](https://docs.mycentralino.com/mycentralino-api/voip-status): Stato registrazione numerazioni
- [Lista Blacklist](https://docs.mycentralino.com/mycentralino-api/blacklists-list): Elenco blacklist
- [Dettaglio Blacklist](https://docs.mycentralino.com/mycentralino-api/blacklists-detail): Dettaglio con numeri bloccati
- [Crea Blacklist](https://docs.mycentralino.com/mycentralino-api/blacklists-create): Creazione blacklist
- [Elimina Blacklist](https://docs.mycentralino.com/mycentralino-api/blacklists-delete): Eliminazione blacklist
- [Aggiungi Numero Blacklist](https://docs.mycentralino.com/mycentralino-api/blacklists-numbers-add): Aggiunta numero da bloccare
- [Dettaglio Numero Blacklist](https://docs.mycentralino.com/mycentralino-api/blacklists-numbers-detail): Dettaglio singolo numero
- [Modifica Numero Blacklist](https://docs.mycentralino.com/mycentralino-api/blacklists-numbers-update): Modifica numero bloccato
- [Elimina Numero Blacklist](https://docs.mycentralino.com/mycentralino-api/blacklists-numbers-delete): Rimozione numero dalla blacklist

## Link utili

- [Sito Web](https://mycentralino.com)
- [Supporto](https://www.mycentralino.com/contattaci/)
- [Dashboard](https://cloud.mycentralino.com/)

---

## Calendario (prese appuntamenti) — /v1/calendar
Date e ore in ora locale del centralino (campi separati date YYYY-MM-DD e time HH:MM, timezone dichiarato, starts_at_utc/ends_at_utc in più). Calendari e tipi si indicano con lo slug. Errori con code stabile: 409 slot_unavailable/outside_hours/notice_too_short/beyond_horizon/not_modifiable/already_cancelled/holiday_managed, 422 dati non validi, 403 calendar_not_enabled.

### GET /v1/calendar/calendars — i calendari (id, slug, name, location, address, timezone, is_active)
### GET /v1/calendar/events — i tipi di appuntamento (slug, duration_minutes, assignment_mode single|choice|round_robin|collective, requires_confirmation, calendars[], fields[])
### GET /v1/calendar/availability?event=&calendar=&from=&to= — slot liberi: slots[] {date, time, end_time, calendar, seats_left}. L'orario di una prenotazione deve essere uno di questi.
### GET /v1/calendar/bookings?view=upcoming|past|all&status=&calendar=&event=&from=&to=&q=&page=&limit= — prenotazioni + pagination
### POST /v1/calendar/bookings — body event, calendar (obbligatorio se choice), date, time, name, phone, email, notes, answers, status; header Idempotency-Key consigliato; 201 created:true, replay 200 created:false
### GET /v1/calendar/bookings/{id}
### PATCH /v1/calendar/bookings/{id} — date+time (sposta), status confirmed (conferma), name/phone/email/notes/staff_notes/answers (aggiorna)
### DELETE /v1/calendar/bookings/{id} — annulla, body {reason}; resta con status cancelled
### GET /v1/calendar/blocks?calendar=&from=&to= · POST /v1/calendar/blocks (calendar?, date, end_date?, all_day|time+end_time, title, note) · DELETE /v1/calendar/blocks/{id} (409 holiday_managed sulle festività)
### Webhook uscenti: POST JSON firmato (X-MyCentralino-Signature = sha256=HMAC-SHA256("{timestamp}.{body}", secret)), eventi booking.created/updated/cancelled/test, retry 1m/5m/30m/2h/6h.