Integrazioni

1. Caselle di posta (IMAP e SMTP)

Ogni coda dell'assistenza può avere la sua casella, configurata da un amministratore in Impostazioni › Code e posta.

• Lettura (IMAP): porta 993 con TLS (o 143 con STARTTLS), cartella a scelta (di solito INBOX). Il processo della posta legge le caselle ogni minuto (MAIL_POLL_SECONDS, da 10 secondi in su), importa i messaggi nuovi e li segna come letti: non sposta né cancella nulla. Alla prima lettura importa solo le 50 email non lette più recenti. Due code non possono leggere la stessa casella e cartella.
• Invio (SMTP): porta 465 con TLS o 587 con STARTTLS; se il fornitore del server blocca le porte di posta (DigitalOcean blocca 25, 465 e 587) si usa un servizio di invio sulla porta 2525 con STARTTLS (per esempio Mailgun EU, Mailjet, SMTP2GO EU) o sulle porte 2587/2465 (Amazon SES, Resend, Scaleway).
• Autenticazione: nome utente e password, conservata cifrata. Una password vale solo per il server, la porta e l'utente con cui è stata scritta: cambiandoli va riscritta.
• Prova la connessione: verifica lettura e invio e avvisa se il fornitore del server può bloccare le porte SMTP.
• Gmail e Google Workspace: con una password per le app. Microsoft 365: la lettura con la sola password non è accettata da Microsoft e l'accesso OAuth non è ancora disponibile (si inoltra la posta a un'altra casella); l'invio funziona se il tenant permette SMTP AUTH.
• Sicurezza: solo connessioni cifrate; nessuna connessione verso indirizzi di rete privati o interni; nuovi tentativi di invio dopo 1, 5, 15 e 60 minuti; intestazioni che evitano le risposte automatiche; nessun ciclo di risposte tra sistemi.
• Cosa viene importato: mittente, oggetto, testo (anche convertito dall'HTML) e identificativi del messaggio. Gli allegati non vengono importati: il ticket riporta i loro nomi. I messaggi molto grandi vengono importati solo nella parte iniziale del testo.

2. Gateway di inoltro delle email (API HTTP)

Un servizio di ricezione email (per esempio un servizio di "inbound parsing") può consegnare ogni email a Orafila con una richiesta HTTP, al posto della lettura IMAP.

Richiesta

POST https://psa.vostraazienda.it/api/inbound-email
Content-Type: application/json
x-nova-inbound-secret: <valore di INBOUND_EMAIL_SECRET del server>

{
  "to": "assistenza@cliente.it",
  "from": "mario.rossi@azienda-cliente.it",
  "subject": "Errore nella stampa delle fatture",
  "text": "Buongiorno, da stamattina...",
  "messageId": "<CAF1234@mail.azienda-cliente.it>",
  "receivedAt": "2026-10-27T09:15:00Z",
  "headers": { "In-Reply-To": "<...>", "References": "<...>", "Auto-Submitted": "no" }
}

Risposte

L'email viene salvata prima di essere smistata; i messaggi d'errore sono in italiano o in inglese secondo l'intestazione Accept-Language. Il gateway riguarda solo la ricezione: per le risposte serve comunque una casella SMTP sulla coda.

3. Fatture in Cloud (fattura elettronica e SDI)

• Collegamento: token manuale di un'applicazione creata nell'area sviluppatori di Fatture in Cloud, con permessi di lettura e scrittura sulle fatture e di lettura sulle impostazioni. Il token è conservato cifrato, non torna mai al browser né nel registro attività; le chiamate vanno solo all'API ufficiale (api-v2.fattureincloud.it).
• Creazione: ogni fattura emessa in Orafila diventa in Fatture in Cloud una fattura elettronica con lo stesso numero, gli stessi dati del cliente (codice destinatario e PEC compresi) e le stesse righe; a scelta automaticamente all'emissione. Prima Orafila verifica che Fatture in Cloud calcoli gli stessi totali; se non coincidono la fattura non viene creata. Una fattura viene "prenotata" prima della creazione, così due clic non creano due documenti.
• Invio allo SDI con la verifica del file XML; stato (consegnata, nel cassetto fiscale, scartata con il motivo) aggiornato a richiesta; nuovo invio di una fattura scartata con lo stesso numero dopo la correzione in Fatture in Cloud.
• Opzioni: azienda di Fatture in Cloud, sezionale, natura dell'esenzione per le righe con IVA 0% (obbligatoria se ci sono), codice di pagamento per la modalità "Altro".
• Limiti: le note di credito si emettono in Fatture in Cloud; Orafila non modifica né cancella i documenti già creati lì. Non va usata la stessa numerazione per fatture create a mano in Fatture in Cloud.
• Senza Fatture in Cloud la fattura elettronica si trasmette con il proprio intermediario o gestionale, partendo dai dati della fattura emessa in Orafila (oggi senza esportazione del file XML FatturaPA).

4. Fornitori di intelligenza artificiale

• Anthropic (Claude) tramite l'SDK ufficiale, OpenAI (GPT) tramite la Responses API, Google (Gemini) tramite l'API generateContent.
• Una chiave per fornitore nella configurazione del server; ogni azienda sceglie agente e budget dall'applicazione. Dettagli, costi e dati inviati in Intelligenza artificiale.

5. File CSV

6. Documenti PDF e stampa

• PDF di fatture, ricevute, ordini dei clienti (conferma d'ordine) e ordini ai fornitori, generati dall'applicazione senza servizi esterni, con l'intestazione dell'azienda e nella lingua dei documenti.
• Pagine di stampa per fatture e ricevute.
• Il PDF della fattura è la copia di cortesia e lo dice in fondo; con il bonifico riporta IBAN e causale.

7. Non ancora disponibili

• Accesso OAuth alle caselle Microsoft 365 e Google.
• Single sign-on (Microsoft 365 / Google) per gli utenti.
• API pubbliche e webhook per altri sistemi (oltre all'endpoint di ricezione delle email).
• Esportazione XML FatturaPA per intermediari diversi da Fatture in Cloud.
• Esportazione iCalendar del calendario per Outlook e Google Calendar.
• Connettori con gestionali ed ERP.