# Registrare un esercente

> Richiesta di registrazione di un esercente via API o modulo web, campi richiesti e attivazione dopo l'approvazione.

Pagina HTML: https://app.billyssw.it/documentazione/esercente  
Indice della documentazione: https://app.billyssw.it/documentazione/index.md  
Tutta la documentazione in un file: https://app.billyssw.it/documentazione/full.md

## Registrare un esercente

### Richiesta di registrazione

L'esercente chiede di aderire dal modulo web `https://pem-staging.billyssw.it/auth/register` oppure il tuo software invia la richiesta per lui con `POST /api/auth/register`. Affinché il cliente ti venga assegnato correttamente, aggiungi il tuo codice affiliato: al modulo con `?aff=AFF-XXXXXXXX`, all'API nel campo `affiliate_code`.

| Campo | Contenuto |
| --- | --- |
| nome, cognome, email, telefono | Il titolare. email è l'indirizzo dell'account Billy ed è anche il nome utente per l'accesso: deve essere unica. telefono di 9 o 10 cifre. |
| denominazione, partita\_iva, codice\_fiscale | Dati fiscali dell'attività. La partita IVA è verificata ed è unica. |
| indirizzo, civico, cap, comune, provincia, nazione | Sede legale. provincia e nazione di 2 caratteri. |
| regime\_fiscale | Obbligatorio: ordinario, semplificato o forfettario\_minimo. |
| pec, sdi | Facoltativi. sdi di 7 caratteri. |
| sede\_operativa | Facoltativa: indirizzo e referente del punto vendita. Se manca vale la sede legale. È la sede del primo PEM. |
| affiliate\_code | Facoltativo: il codice del partner che ha portato l'esercente. |
| privacy | Obbligatorio: accettazione dell'informativa (true). |

POST /api/auth/register

```bash
curl -X POST https://pem-staging.billyssw.it/api/auth/register \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Mario",
    "cognome": "Rossi",
    "email": "mario.rossi@example.it",
    "telefono": "3331234567",
    "denominazione": "Bar Centrale di Mario Rossi",
    "partita_iva": "01234567897",
    "codice_fiscale": "RSSMRA80A01F205X",
    "indirizzo": "Via Roma",
    "civico": "1",
    "cap": "20121",
    "comune": "Milano",
    "provincia": "MI",
    "nazione": "IT",
    "regime_fiscale": "ordinario",
    "affiliate_code": "AFF-7K2M9QXA",
    "privacy": true
  }'
```

La risposta conferma la presa in carico: non crea ancora l'account. L'esercente riceve un'email di conferma della richiesta. Lo stato della richiesta non si legge via API: l'esito arriva all'esercente per email.

### Approvazione e attivazione

Sender verifica i dati e approva la richiesta. Da lì il sistema procede da solo:

-   crea l'account dell'esercente e gli invia l'email _Completa la configurazione del tuo account Billy_, per scegliere la password e confermare l'indirizzo;
-   crea il primo **PEM** sulla sede operativa e avvia il **censimento** presso l'Agenzia delle Entrate;
-   al termine del censimento porta il PEM nello stato `In servizio` e lo comunica via email al referente della sede.

### Collegare il gestionale

Con l'account attivo, l'esercente autorizza il tuo software dalla schermata di consenso del flusso OAuth: non ci sono chiavi API da generare o copiare. Il seriale dei suoi PEM lo ottieni con `GET /api/pem`.

PEM aggiuntivi

Altri punti di emissione (una seconda cassa, un altro punto vendita) si chiedono a Sender: vedi **Registrare un PEM**.