adt-workflow

adt-workflow

# Partner invio

## Attori coinvolti

- **Partner**: è l'utente che richiede il nostro servizio.
- **ttt-backend**: è il server di TicinoTopTen.
- **ses-transactional**: è il server il cui unico scopo è l'invio delle email.

## Registrazione

La registrazione è il primo passo per poter comunicare con il servizio.
Per effettuare la registrazione è necessario che abbiate a priori i parametri `slug` e  `apiKey` che rappresentano rispettivamente il nome univoco del vostro partner e la password a voi assegnata. Una volta che la registrazione è andata a buon fine, è possibile fare il polling al server per sapere se ci sono delle nuove campagne da inviare.

### Procedimento
Effettuare la chiamata `POST` al server *ttt-backend*

```ttt-backend.herokuapp.com/adt/partners/{slug}/register```

dove il parametro `{slug}` è il nome del partner a voi assegnato.
Come `body` ci aspettiamo l'oggetto

```javascript
{
	"slug":	"vostro-slug",
  "apiKey":	 "vostra-api-key"
}
```

In caso di successo la *risposta* sarà del tipo:

```
{
  "_id":	string,
  "slug":	string,
  "name":	string,
}
```

Il parametro che bisogna necessariamente salvare è `_id` che rappresenta univocamente il partner appena registrato. D'ora in poi questo parametro verrà indicato con il nome **partnerId**.

## Invio campagna

Una volta effettuata la registrazione è possibile richiedere a *ttt-backend* se ci sono delle nuove campagne da dover inviare via email. In caso di restituzione di una nuova campagna il prossimo passo è quello di iniziare la fase di invio delle email interrogando *ses-transactional*.

Ora viene riproposto sommariamente il flusso di lavoro completo dell'invio di una campagna.

1. Richiesta a *ttt-backend* se c'è una nuova campagna da inviare.
2. In caso affermativo si contatta *ses-transactional* utilizzando le informazioni ricevute al passo 1.


### Procedimento

#### 1. Richiesta campagna

Effettuare una chiamata `POST` a *ttt-backend*

```
ttt-backend.herokuapp.com/adt/partners/{partnerId}/tell
```

Dove `{partnerId}` è il `partnerId` che avete ottenuto durante la fase di registrazione.

- **header**: deve contenere le chiavi `Auth-PartnerId` e `Auth-ApiKey` necessarie per la corretta autenticazione. Il contenuto di queste chiavi sono rispettivamente il `partnerId` e `apiKey`.
- **body**: ci aspettiamo l'oggetto JSON

    ```
{
"clientsRegistred":	integer
}
  ```  
    Al suo interno si indica il numero di clienti a cui bisogna inviare le email.

La *risposta* è del tipo JSON

```
{
config:	
  {
    name:	string,
    credentials:	
     {
       partnerId:	string,
       apiKey:	string
     }
   },
sendEmail:	
{
   campaign:	{
    _id:	string,
    subject:	string,
    contentHtml:	string,
    contentText:	string
   },
   blacklist:	["id-blacklist1", "id-blacklist2", ...],
   fromEmail:	string,
   fromName:	string
}
``` 

Il parametro `config` è opzionale e viene inserito qualora *ttt-backend* modifichi le impostazioni di autenticazione.
Il parametro `sendEmail` è opzionale anch'esso e viene inserito solo se c'è una nuova campagna da inviare.
Bisogna tenere presente che gli utenti possono disiscriversi dalla newsletter e quindi non vogliono ricevere più alcuna campagna.  Per questo motivo è necessario filtrare gli utenti che sono presenti nel campo `blacklist` prima di inviare le email a *ses-transactional*.
Nel campo blacklist non abbiamo direttamente le email, ma il loro hash.

Ora abbiamo tutte le informazioni per passare alla fase successiva. L'effettivo invio della campagna tramite *ses-transactional*.

#### 2. Invio campagna

Per l'invio della campagna effettuare una chiamata `POST` a *ses-transactional*

```
ses-transactional.herokuapp.com/send
```

- **body**: tutti i campi del JSON sono obbligatori

```
{
  auth:	{
   partnerId:	string,
   apiKey:	string,
   campaignId:	string,
  }
  bulkMail:	{
    subject:	string,
    html:	string,
    text:	string,
    fromName:	string,
    fromEmail:	string,
    mails: [
     {
       email:	string,
       params:
       {
           "uuid": "hash-email",
           "placeholderDaSostituire": "nuovoValore"
       }
     }, ...
    ]
  }
}
```  

Per i campi `auth` abbiamo bisogno, oltre ai classici `partnerId` e `apiKey`, di `campaignId`. Questo parametro lo si può recuperare dalla prima chiamata a *ttt-backend*, precisamente nel campo di risposta `sendEmail.campaign._id`.
Nel campo `bulkMail` ci sono i vari campi che formeranno le email. Tutti questi dati provengono dalla chiamata precedente a *ttt-backend*. Più precisamente nel campo `sendEmail`.
- subject: Soggetto email
- html: il body della email in formato HTML.
- text: il body della email in formato testuale. 
- fromName: il nome del mittente.
- fromEmail: l'email del mittente.
- emails: contiene le effettive email d'invio. Il campo `params` è un oggetto JSON dove le chiavi sono i placeholder che sono presenti nell'HTML della campagna e che possono essere personalizzati in base alla singola email. Il valori  invece sono le stringhe che sostituiranno i placeholder ad esse collegate. Un placeholder che è presente in molti template è `uuid`: questo valore deve contenere l'hash della email dell'utente ed è necessario affinchè *ses-transactional* possa generare correttamente il link di disiscrizione dell'utente.