Documentazione dell’integrazione

Quando un cliente di Closer Suite preme «Connetti», Flow crea il suo spazio di lavoro sotto l’agenzia Marketing Semplice, con il marchio dell’agenzia, e il cliente ci entra con un clic, senza registrarsi e senza password. Lato Closer Suite servono tre cose: una chiave, una chiamata dal server, un reindirizzamento.

Creare la chiave dall’agenzia

La chiave si crea una volta sola, dall’account agenzia, e vale per tutti i clienti. Collegamento diretto: *https://agenzia-matt.theclientarea.com/integrations/platform-key* In alternativa, dal gestionale dell’agenzia: *Integrazioni* nel menu a sinistra e, sulla scheda *Chiave per il tuo gestionale*, il pulsante *Collega*.

Dare un nome e premere «Crea la chiave»

Il nome serve solo a riconoscerla nell’elenco, per esempio «Closer Suite». In cima alla stessa schermata c’è l’indirizzo completo a cui Closer Suite manda la chiamata del passaggio 2.

Copiarla subito: compare una volta sola

Va salvata sul server di Closer Suite. Non deve mai finire nel browser, in un’email o in una chat. Se viene persa o esposta, dalla stessa schermata si preme *Revoca* e se ne crea un’altra: gli spazi già creati restano attivi.

La chiamata, quando il cliente preme «Connetti»

Il server di Closer Suite manda una richiesta POST a: *https://agenzia-matt.theclientarea.com/api/v1/partners/provision* con due intestazioni: *x-partner-key* con la chiave del passaggio 1, e *Content-Type: application/json*. Nel corpo vanno l’azienda del cliente, il titolare e, se servono, le altre persone. L’identificativo (external_id) è quello che Closer Suite usa già nel proprio database: serve a riconoscere la stessa azienda e la stessa persona nelle chiamate successive. Ruoli ammessi: setter, closer, member. Le password non vanno mandate: se il campo c’è, la richiesta viene rifiutata.

{ "organization": { "name": "Studio Rossi", "external_id": "cs_org_123" }, "owner": { "email": "anna@studiorossi.it", "name": "Anna Rossi", "external_id": "cs_user_1" }, "users": [ { "email": "luca@studiorossi.it", "name": "Luca", "role": "setter", "external_id": "cs_user_2" }, { "email": "sara@studiorossi.it", "name": "Sara", "role": "closer", "external_id": "cs_user_3" } ] }

La risposta, e dove mandare il cliente

Se tutto va a buon fine la risposta è 200 e contiene *login_url*. Closer Suite reindirizza il browser del cliente a quell’indirizzo, e il cliente è dentro. Il login_url vale una sola volta e scade dopo un’ora: va usato subito, non salvato. Per farlo entrare di nuovo in un secondo momento basta ripetere la stessa chiamata, che restituisce un login_url nuovo.

{ "account_id": "fbb2e498-…", "slug": "studio-rossi", "login_url": "https://studio-rossi.theclientarea.com/auth/confirm?token_hash=…", "users": [ { "external_id": "cs_user_1", "user_id": "…" } ], "skipped_existing_users": [], "request_id": "req_…" }

Aggiungere persone, o ripetere dopo un errore

Con lo stesso *organization.external_id* non nasce un secondo spazio: vengono aggiunte solo le persone nuove. È così che si aggiunge un setter settimane dopo, ed è sicuro ripetere la chiamata dopo un errore di rete. Una persona che il cliente ha tolto dal proprio spazio non viene rimessa dentro da una chiamata successiva.

Cosa significano

• 401 unauthorized_partner: la chiave manca, è sbagliata o è stata revocata.
• 400 invalid_request: un campo non è valido; il campo details dice quale.
• 409 owner_already_exists: l’email del titolare appartiene già a un utente Flow non creato da Closer Suite. Quel cliente si collega dall’interno di Flow.
• 500 internal_error: errore da parte nostra. Ripetere la chiamata; se continua, scriverci indicando il request_id.

Cosa vede il cliente, e come rientra

Il cliente atterra sul proprio indirizzo, per esempio *studio-rossi.theclientarea.com*, con il logo di Marketing Semplice, direttamente sulla schermata per collegare il numero WhatsApp. Se in seguito vuole il proprio logo, lo cambia dalle impostazioni del marchio. Per rientrare nei giorni successivi va sullo stesso indirizzo e accede con la propria email: riceve un codice, oppure usa Google. Non c’è una password da gestire, né da parte di Closer Suite né da parte del cliente. Un dominio proprio del cliente (per esempio app.studiorossi.it) si attiva su richiesta.

Dove si ritrovano i clienti

Ogni spazio creato compare nell’account agenzia, nella sezione Sotto-account, già configurato come l’agenzia. Da lì l’agenzia entra nello spazio del cliente per verifiche e assistenza.

Cosa serve da Closer Suite

Quanto descritto sopra è già operativo. Per le due funzioni concordate servono gli endpoint di Closer Suite e la struttura dei dati:

• Link dei calendari: letti da Closer Suite e proposti dentro la conversazione, già scelti in base al canale (WhatsApp o Instagram). Il setter non copia nessun link.
• Elenco di setter e closer: letto da Closer Suite, il cliente spunta chi abilitare invece di inserirli a mano.