1. Obiettivi del documento

Questo documento ha lo scopo di dettagliare il funzionamento tecnico e funzionale del nostro connettore. Definisce il perimetro di azione (cosa è coperto o meno) ed elenca i prerequisiti necessari per la sua implementazione.

Nota importante: I nostri team sono disponibili se hai bisogno di chiarimenti o ulteriori informazioni.

Come utilizzare questo documento? Si consiglia di consultare questo documento con tutte le persone competenti (CIO, CFO, Responsabile Amministrativo, IT Manager), con l'obiettivo di:

Verificare se i flussi proposti corrispondono alle esigenze della tua azienda.
Confermare che il tuo ambiente tecnico soddisfi i prerequisiti di installazione.

⚠️ Metodologia di deployment: Il nostro approccio è pragmatico. Se, dopo l'analisi, i prerequisiti risultano convalidati, privilegeremo l'installazione del connettore nativo. Tuttavia, se per motivi tecnici o per una configurazione specifica il connettore non potesse essere attivato, passeremo senza problemi a un metodo alternativo tramite SFTP per garantire la continuità del tuo progetto.

2. Prerequisiti e deployment

2.1 Obbligatori per qualsiasi connessione

Categoria	Requisito	Come verificare
Edizione NetSuite	Solo Oracle NetSuite OneWorld	Un'opzione Subsidiary Settings Manager è disponibile nella scheda Setup.
Funzionalità `Subsidiaries`	Deve essere abilitata	Necessaria per scaricare e installare l'Agicap SuiteApp dal marketplace NetSuite. Se è disattivata, la SuiteApp non può essere installata.
Ruolo utente	L'utente che esegue la configurazione deve avere il ruolo di Amministratore	Setup > Users/Roles > Manage Users
Funzionalità account	`REST WEB SERVICES`, `OAUTH 2.0`, `SuiteAnalytics Workbook`	Setup > Company > Enable Features (vedi A, step 2)
Agicap SuiteApp	Agicap for NetSuite installata	Crea il ruolo dedicato `AgicapIntegrationRole` e supporta l'autenticazione OAuth 2.0 M2M.

🔒 Si consiglia di utilizzare un utente di integrazione dedicato invece di un account personale. Questa è una raccomandazione, non un requisito: un account personale funziona se lo preferisci. Il motivo della raccomandazione è che l'autenticazione basata su certificato è legata a un solo utente NetSuite e a un solo ruolo, quindi la connessione smette di funzionare se quella persona lascia l'azienda o se i suoi permessi vengono rimossi.

2.2 Prerequisiti aggiuntivi per flusso

Flusso	SuiteApp aggiuntiva	Configurazione NetSuite aggiuntiva
Import file di pagamento	SFTP Connector (obbligatorio) Electronic Bank Payments (bundle ID 416781) se non generi già file di pagamento	Due cartelle File Cabinet, una chiave privata RSA 2048 in formato PEM e i tuoi conti bancari configurati per l'esecuzione dei pagamenti in Agicap.
Esportazione estratto conto bancario	Auto Bank Statement Import (ABSI)	`Client SuiteScript` e `Server SuiteScript` abilitati, una chiave privata RSA 2048 in formato PEM e un formato di estratto conto bancario supportato da un parser NetSuite.

2.3 Chi fa cosa

Fase	Responsabile
Installazione delle SuiteApp, abilitazione delle funzionalità account, assegnazione del ruolo	Il tuo amministratore NetSuite / power user
Compilazione del form di connessione in Agicap (account ID, certificato, ID certificato)	Tu, guidato da questo documento
Mappatura delle tue filiali NetSuite con le entità Agicap e convalida della connessione	Agicap — questo passaggio è a nostro carico ed è necessario prima dei flussi di dati
Attivazione di ogni flusso sulla tua connessione	Tu, dalla pagina Banche & integrazioni una volta creata la connessione. Ogni flusso ha il proprio toggle nei dettagli di sincronizzazione della connessione.
Configurazione dei flussi SFTP in NetSuite (ABSI, SFTP Connector, parser)	Il tuo amministratore NetSuite. Il lato Agicap di questi flussi viene configurato dal nostro team tecnico, quindi pianifica un incontro con loro prima di iniziare.

3. Informazioni generali

Il connettore Agicap NetSuite è un'integrazione bidirezionale sviluppata e mantenuta internamente da Agicap. Utilizza le REST API e gli endpoint SuiteQL di NetSuite, protetti da autenticazione a certificato OAuth 2.0 machine-to-machine, per importare i tuoi documenti aziendali e dati contabili in Agicap e per scrivere estratti conto bancari, registrazioni di pagamento e giornali contabili in NetSuite.

Un connettore, una SuiteApp. Ogni flusso è una funzionalità opzionale attivabile sulla tua connessione: puoi iniziare solo con la raccolta dei documenti aziendali e aggiungere altri flussi in seguito, sulla stessa connessione, senza rifare la configurazione.

Meccanismo	Utilizzato per	Cosa installi in NetSuite
REST API + SuiteQL (OAuth 2.0 M2M)	Documenti aziendali, piano dei conti e terze parti, piano analitico, codici IVA, esportazione prima nota bancaria, esportazione giornale degli acquisti	Agicap for NetSuite SuiteApp — tutto qui. Crea il ruolo dedicato `AgicapIntegrationRole` e contiene tutto ciò che serve al connettore.
SFTP (server ospitato da Agicap)	Import file di pagamento, esportazione estratto conto bancario	SuiteApp SFTP Connector (uscita), SuiteApp Auto Bank Statement Import (ABSI) (entrata)

Frequenza di sincronizzazione

Il flusso dei documenti aziendali si sincronizza automaticamente due volte al giorno. Gli altri flussi API si sincronizzano una volta al giorno. Tutti possono essere avviati manualmente.
La maggior parte delle chiamate API filtra in base alla data di modifica del record, quindi viene trasferito solo ciò che è cambiato.
I flussi SFTP vengono eseguiti secondo la pianificazione configurata in NetSuite, abbinata a quella configurata lato Agicap.
Viene creata una connessione identificabile per ogni account NetSuite.

💡 Per impostazione predefinita, Agicap raccoglie i documenti aziendali la cui data di modifica in NetSuite è inferiore a un anno rispetto al momento della creazione della connessione. Un documento emesso prima può comunque apparire se è stato modificato di recente in NetSuite. Se hai bisogno di una cronologia più lunga, comunicacelo prima della prima sincronizzazione.

4. Flussi & casi d'uso

4.1 NetSuite → Agicap

Flusso	Stato	Trasporto	Alimenta
Import documenti aziendali	Attivo con limitazioni	REST API	Treasury, Accounts Receivable, purchase-to-pay
Import piano dei conti e terze parti	In beta	REST API	Abbinamento, prima nota bancaria
Import piano analitico	Attivo	REST API	Treasury e le registrazioni che Agicap scrive indietro
Import codici IVA	Attivo	REST API	Gestione IVA sui documenti esportati da Agicap e prerequisito per il giornale degli acquisti
Import ordini di acquisto con righe (P2P)	Attivo	REST API	Pagamenti, purchase-to-pay
Import file di pagamento	Attivo con limitazioni (via SFTP)	SFTP	Pagamenti
Import fornitori	In beta	REST API	Purchase-to-pay, base terze parti
Import beneficiari / IBAN	In beta	REST API	Pagamenti
Import PDF AR	Pianificato	REST API	Accounts Receivable
Import anagrafica clienti e contatti	Pianificato	REST API	Accounts Receivable

4.2 Agicap → NetSuite

Flusso	Stato	Trasporto	Scrive in NetSuite
Esportazione estratti conto bancari	Attivo con limitazioni (via SFTP)	SFTP + ABSI	Registrazioni di estratti conto bancari per abbinamento e reportistica finanziaria
Esportazione prima nota bancaria da Treasury, registrazioni contabili	In beta	REST API	Registrazioni contabili, per movimenti bancari senza documento aziendale e per contropartite manuali
Esportazione prima nota bancaria da Treasury, abbinamento fatture	In beta	REST API	Pagamenti clienti e fornitori abbinati alle tue fatture AR/AP aperte. NetSuite genera la registrazione contabile direttamente dal pagamento.
Esportazione fatture fornitori, giornale degli acquisti	Pianificato	REST API	Fatture fornitori, con PDF della fattura allegato. NetSuite genererà le registrazioni contabili a partire da esse. Non ancora attivabile.
Emissione e ricezione fatturazione elettronica (Francia)	Pianificato	—	—
Esportazione prima nota banca Spend, registrazioni transitorie, debito, finanziamenti infragruppo, solleciti AR, investimenti finanziari, previsioni	Non disponibile	—	Attualmente non coperto. Segnalaci se uno di questi aspetti ti interessa.

📘 Lettura degli stati.  Attivo significa distribuito e funzionante su diversi account clienti. Attivo con limitazioni significa disponibile, con una limitazione descritta al §5 e nella tabella Limitazioni. (via SFTP) significa che il flusso non è gestito dal connettore API: il file viene prodotto o consumato in NetSuite tramite SuiteApp dedicate e scambiato tramite un server SFTP ospitato da Agicap. In beta significa disponibile, in rollout graduale e ancora in miglioramento — l'attivazione viene concordata caso per caso con il tuo referente Agicap. Pianificato significa in roadmap e non ancora attivabile. Non disponibile significa che oggi non c'è alcun impegno.

5. Documentazione tecnica dettagliata per caso d'uso

5.1 Import documenti aziendali (NetSuite → Agicap)

Cosa fa. Alimenta Agicap Treasury con i movimenti di cassa attesi, Agicap Accounts Receivable con le fatture da incassare e sollecitare, e il flusso purchase-to-pay con i tuoi ordini e bolle di consegna.

Come. Agicap interroga le REST API e gli endpoint SuiteQL di NetSuite. Le chiamate filtrano in base alla data di modifica del record, quindi viene trasferito solo ciò che è cambiato e vengono recuperati solo i campi necessari ad Agicap.

Cosa viene raccolto — una sincronizzazione, tutti i tipi di documento insieme:

Fatture clienti e note di credito
Fatture fornitori e note di credito
Ordini di vendita e ordini di acquisto con le relative righe
Bolle di consegna
Preventivi
Referenziali: valute, filiali, entità, clienti, fornitori, strumenti di pagamento

Entity qui si riferisce al record entity di NetSuite (clienti, fornitori e altre entità NetSuite). Non ha nulla a che vedere con un'entità Agicap, che viene mappata alle tue filiali NetSuite.

Non esiste un'opzione per tipo di documento: il flusso dei documenti aziendali li raccoglie tutti. Ciò che cambia è dove ogni tipo appare in Agicap, che dipende dai moduli Agicap attivi sul tuo account e dai filtri attivati per ciascun modulo.

Sempre attivo. L'import dei documenti aziendali è attivato di default su ogni connessione NetSuite e non può essere disattivato. Gli altri flussi sono opzionali e vengono attivati uno per uno.

⚠️ Limitazione nota — volumi elevati. Le connessioni con un volume molto elevato di documenti aziendali, o che funzionano su un'istanza NetSuite limitata, possono incorrere in errori di timeout durante la sincronizzazione. I documenti smettono quindi di aggiornarsi in Agicap fino al successivo ciclo riuscito. I nostri team stanno lavorando attivamente su questo problema. Se dovesse accadere, mantieni attiva la connessione API e contatta l'Assistenza Agicap fornendo il nome della connessione e il messaggio di errore visualizzato nei dettagli della sincronizzazione.

Opzionale — campi personalizzati. Puoi fare in modo che Agicap raccolga i campi personalizzati di NetSuite e li utilizzi per costruire il motivo dei tuoi documenti aziendali in Treasury e Accounts Receivable, oppure richiedere un filtro specifico. Facendo clic sull'etichetta di un campo in NetSuite viene mostrato il suo id interno, ad esempio custbody_phy_patient_name. Questo funziona per i campi a livello di intestazione di un documento di transazione; i campi a livello di riga non sono coperti. Dichiara i campi di cui hai bisogno quando crei la connessione (vedi B, passaggio 5) — aggiungerli successivamente richiede il rinnovo delle credenziali di connessione.

5.1.1 Importa ordini di acquisto con righe (NetSuite → Agicap)

Cosa fa. Porta i tuoi ordini di acquisto NetSuite, riga per riga, nel flusso purchase-to-pay di Agicap così che le fatture fornitore possano essere abbinate al loro ordine.

La raccolta stessa fa parte della sincronizzazione dei documenti aziendali (§5.1). Ciò che aggiunge questo flusso è l'esposizione di quegli ordini nel modulo Accounts Payable di Agicap, che richiede che il relativo modulo Agicap sia attivo sul tuo account — informa il tuo referente Agicap se ti aspetti di vedere gli ordini di acquisto lì e non compaiono.

5.2 Importa piano dei conti e terze parti (NetSuite → Agicap)

Cosa fa. Mantiene sincronizzati i tuoi conti contabili e le terze parti così da non dover mai gestire manualmente queste liste in Agicap.

Conti contabili. Agicap recupera l'elenco completo dei conti da NetSuite (ID interno, titolo, numero, tipo, assegnazione alla consociata) e collega ogni conto alle relative entità Agicap tramite la mappatura multi-entità configurata in fase di setup.

Esclusi dall'import: conti senza numero di conto e conti di tipo NonPosting.

Terze parti. Clienti e fornitori vengono importati nel modello terze parti di Agicap con ragione sociale, codice, conto contabile collegato e ID interno NetSuite.

💡 Se le liste di selezione dei conti in Agicap risultano troppo lunghe, disattivare i conti che non hanno mai avuto movimenti, per ciascuna consociata, è il modo più rapido per pulirle.

5.3 Importa piano analitico e codici IVA (NetSuite → Agicap)

Cosa fa. Importa le tue dimensioni analitiche NetSuite così che i flussi di cassa possano essere analizzati per asse in Agicap, e le stesse dimensioni possano essere riportate sulle registrazioni che Agicap scrive in NetSuite.

Cosa viene sincronizzato: class, department, location e i tuoi segmenti personalizzati.

I codici IVA vengono importati tramite lo stesso meccanismo e alimentano la gestione dell'IVA sui documenti esportati da Agicap.

👀 Segmenti personalizzati. Per importare segmenti personalizzati, il ruolo AgicapIntegrationRole (o il tuo ruolo personalizzato) deve avere il permesso di lettura su ciascun segmento personalizzato interessato. Verifica questo aspetto con il tuo amministratore NetSuite.

5.4 Importa file di pagamento (NetSuite → Agicap, via SFTP)

Cosa fa. I tuoi file di pagamento, generati in NetSuite, vengono esportati su un server SFTP ospitato da Agicap e alimentano il modulo Pagamenti di Agicap. Esegui poi i pagamenti tramite la connettività bancaria di Agicap, che ti offre un unico punto di esecuzione e controllo.

❗ Questo flusso non è gestito dal connettore API. Generi tu stesso il file di pagamento in NetSuite, in un formato supportato da NetSuite, e la SuiteApp SFTP Connector lo consegna. Configurazione in C.

Cosa serve

Sai già come generare file di pagamento in NetSuite, oppure installi la SuiteApp Electronic Bank Payments (bundle ID 416781).
La SuiteApp SFTP Connector.
Ogni conto bancario referenziato in questi file è configurato in Agicap per l'esecuzione dei pagamenti: host-to-host, EBICS TS, banca centralizzatrice o esportazione file globale.

Dove arriva il file in Agicap. Se il formato del file è accettato dalla banca per quel conto, può essere importato come Da pagare o Da preparare. Se il formato non è accettato dalla banca, viene importato come Da preparare così che Pagamenti Agicap possa convertirlo in un formato accettato dalla banca.

5.5 Esporta estratti conto bancari (Agicap → NetSuite, via SFTP)

Cosa fa. Agicap recupera i tuoi estratti conto bancari tramite la propria connettività bancaria (EBICS, H2H, SWIFT), poi li invia a un server SFTP. La SuiteApp ABSI li preleva e li importa in NetSuite, dove vengono analizzati e associati ai tuoi conti GL per la riconciliazione e la reportistica finanziaria.

Questo significa che non devi più mantenere una connessione bancaria separata lato NetSuite: una sola configurazione bancaria in Agicap serve entrambi gli strumenti.

⚠️ Il formato del file è il vincolo principale, controllalo subito. NetSuite supporta un elenco fisso di formati e versioni di estratto conto. Ad esempio CAMT.053.001.02 è supportato di default, mentre CAMT.053.001.08 no. Approccio consigliato: chiedi alla tua banca di fornire gli estratti conto in un formato e versione supportati da NetSuite. È la soluzione più semplice e robusta. Se non fosse possibile: Agicap può realizzare una trasformazione personalizzata del file, valutata caso per caso. Queste trasformazioni sono fornite come funzionalità beta su base best-effort e vengono concordate per iscritto prima dell'implementazione.

Configurazione in D.

5.6 Esporta prima nota bancaria e riconciliazione automatica (Agicap → NetSuite)

Cosa fa. Riconcili le movimentazioni bancarie con le fatture in Agicap. Agicap poi scrive il risultato in NetSuite, così la tua prima nota bancaria e le partite aperte AR/AP vengono aggiornate senza reinserimento manuale.

Come funziona. Due meccanismi, a seconda di cosa è stato riconciliato:

Caso	Cosa Agicap scrive in NetSuite
Una movimentazione bancaria riconciliata con un documento aziendale	Un oggetto pagamento — un pagamento cliente o un pagamento fornitore. NetSuite genera poi la registrazione contabile seguendo le tue regole contabili. È lo stesso meccanismo del flusso manuale "Effettua pagamento" in NetSuite.
Una movimentazione bancaria senza documento aziendale collegato, o contropartite manuali aggiunte a una movimentazione bancaria riconciliata.	La transazione bancaria viene scritta direttamente come registrazione contabile.

Stato: In beta.

Prerequisiti.

Il flusso del piano dei conti (§5.2) deve essere attivo, così i conti vengono risolti su entrambi i lati.
Le funzionalità di prima nota bancaria e riconciliazione devono essere attive sul tuo account Agicap, con l'opzione esportazione manuale disattivata. L'Assistenza Agicap attiva queste impostazioni per te: chiedi loro prima di attivare il flusso.

💡 Il campo Causale della prima nota bancaria Agicap non ha equivalente in NetSuite, quindi non viene mappato. Non è bloccante: l'esportazione funziona comunque.

Pagamenti che coprono più terze parti. NetSuite richiede che ogni pagamento cliente faccia riferimento a una sola terza parte. Quando un pagamento bancario salda fatture appartenenti a più anagrafiche terze parti NetSuite, Agicap lo suddivide automaticamente in un pagamento per ciascuna terza parte. Le righe senza terza parte identificabile vengono esportate direttamente come registrazione contabile separata.

⚠️ Due cose da preparare dalla tua parte. Deduplica i tuoi fornitori e clienti in NetSuite. Un pagamento deve fare riferimento in modo coerente alla fattura e alla terza parte. Due anagrafiche per la stessa azienda possono causare il rifiuto dell'esportazione. Le fatture fornitore create in Agicap, non in NetSuite, non possono ancora essere riconciliate automaticamente da questo flusso: il connettore cerca un riferimento lato NetSuite che su di esse non esiste. È previsto il supporto nativo. Se è il tuo caso, parla con il tuo referente Agicap per le opzioni temporanee.

5.7 Importa fornitori e beneficiari (NetSuite → Agicap)

Stato: In beta. Due flussi separati, stessa configurazione: nulla oltre A e B, più il relativo toggle.

Importa fornitori alimenta la base fornitori di Accounts Payable e il flusso purchase-to-pay con i dati dei fornitori da NetSuite.
Importa beneficiari / IBAN alimenta la lista beneficiari del modulo Pagamenti, così non devi gestirla manualmente in Agicap.

Se questo flusso fa parte del tuo progetto, parla con il tuo referente Agicap per ambito e tempistiche invece di pianificare da questa pagina.

5.8 Esporta fatture fornitore, giornale acquisti (Agicap → NetSuite)

Stato: In programma. Lo sviluppo è in corso e il flusso non può ancora essere attivato.

Cosa farà. Le fatture fornitore digitalizzate da Agicap (OCR) vengono create in NetSuite come vendor bills, con il PDF della fattura allegato alla registrazione. NetSuite genera poi le registrazioni contabili da queste fatture, così il tuo giornale acquisti viene alimentato senza reinserimento manuale.

Se questo flusso fa parte del tuo progetto, parla con il tuo referente Agicap per ambito e tempistiche invece di pianificare da questa pagina.

Procedura di configurazione

🧭 Ordine delle operazioni. A e B sono obbligatori per ogni flusso API e devono essere completati prima di attivare qualsiasi flusso. C e D sono i flussi SFTP: sono indipendenti e possono essere preparati in parallelo. Prevedi circa 30 minuti con il tuo amministratore NetSuite per A e B.

A - Configurazione NetSuite

Passaggio 1 — Installa la SuiteApp Agicap

Inizia da qui: un'installazione riuscita è di per sé la prova che la tua edizione NetSuite è compatibile.

Fai clic sui tre puntini in alto a destra, poi su SuiteApps.
Cerca Agicap for NetSuite (casella di ricerca in alto a sinistra) e fai clic su Installa.
Verifica l'installazione: Personalizzazione → SuiteCloud Development → Elenco SuiteApp installate. Dovresti vedere la registrazione AgicapSuiteApp.

⚠️ Se la SuiteApp non può essere installata, verifica che la funzionalità Subsidiaries sia abilitata. Su un account non-OneWorld non è disponibile e il connettore API non può essere utilizzato — in tal caso si passa all'alternativa SFTP.

Passaggio 2 — Abilita le funzionalità richieste dell'account

Vai su Setup → Company → Enable Features. La maggior parte di queste è solitamente già attiva, ma controlla attentamente queste tre:

Funzionalità	Sottoscheda → sezione	Perché è necessaria
`REST WEB SERVICES`	SuiteCloud → SuiteTalk (Web Services)	Tutte le chiamate di lettura e scrittura dei record
`OAUTH 2.0`	SuiteCloud → Gestione autenticazione	Autenticazione machine-to-machine
`SuiteAnalytics Workbook`	Analytics → SuiteAnalytics Workbook	Query SuiteQL utilizzate per i documenti aziendali e il piano dei conti

Salva. L'attivazione di una funzionalità può richiedere qualche istante.

Passaggio 3 — Assegna l'AgicapIntegrationRole

La SuiteApp di Agicap crea un ruolo dedicato che include esattamente le autorizzazioni necessarie al connettore, e nulla di più.

Setup → Utenti/Ruoli → Gestisci utenti.
Seleziona l'utente che gestirà l'integrazione — consigliamo di creare un utente dedicato all'integrazione — e clicca su Modifica.
Nella scheda Accesso in fondo alla pagina, aggiungi AgicapIntegrationRole.
Clicca su Aggiungi, poi su Salva.

🔒 Il ruolo è gestito da Agicap e viene fornito con la SuiteApp. Quando un nuovo flusso o una correzione richiede un'autorizzazione aggiuntiva, aggiorniamo il ruolo e la modifica si propaga con la versione della SuiteApp: nessuna riconnessione e nessun nuovo certificato da parte tua. Se la tua policy di sicurezza lo richiede, puoi sostituire il ruolo standard con un ruolo personalizzato dedicato al tuo account, limitato ai tuoi team. Segnala questa esigenza al tuo referente Agicap prima della chiamata di configurazione. Una conseguenza da conoscere prima di sceglierlo: un ruolo personalizzato non riceve gli aggiornamenti automatici delle autorizzazioni sopra descritti. Quando un nuovo flusso o una correzione richiede un'autorizzazione, la tua connessione può andare in errore finché il tuo team non la aggiunge manualmente.

B - Modulo di connessione Agicap

In Agicap, apri Banche & integrazioni e cerca NetSuite. Si apre il modulo di connessione. Tieni aperta una scheda NetSuite accanto: dovrai passare avanti e indietro due volte.

Passaggio 1 — Account ID

Il tuo Account ID NetSuite è visibile direttamente nell'URL della sessione NetSuite, oppure in Setup → Azienda → Informazioni azienda.

Passaggio 2 — Scarica la chiave pubblica Agicap

Agicap si autentica tramite un flusso OAuth 2.0 client credentials supportato da un certificato. Agicap genera il certificato; tu lo carichi in NetSuite.

Nel modulo di connessione, clicca su Scarica la chiave pubblica e tieni il file a portata di mano.

Passaggio 3 — Crea l'integrazione M2M in NetSuite

In NetSuite, vai su Setup → Integrazione → OAuth 2.0 Client Credentials (M2M) Setup.
Crea una nuova mappatura client credentials tra:
1. l'entità, cioè l'utente NetSuite dal punto A, passaggio 3,
2. il ruolo AgicapIntegrationRole,
3. l'applicazione Agicap SuiteApp,

e carica il certificato che hai scaricato al passaggio 2.

Salva.

Passaggio 4 — Copia l'ID del certificato in Agicap

Copia l'ID del certificato appena creato e incollalo nel campo Certificate ID del modulo Agicap.

👀 L'elenco dei certificati NetSuite non è ordinato per data di creazione. Se hai creato più di un certificato, assicurati di prendere quello creato più di recente. Controlla l'utente e il ruolo collegati al certificato per confermare.

Passaggio 5 — Facoltativo: dichiara i campi personalizzati che vuoi raccogliere

Se vuoi che Agicap costruisca le etichette dei documenti aziendali dai campi personalizzati di NetSuite, dichiara qui i loro ID interni, in fase di connessione. Cliccando sull'etichetta di un campo in NetSuite viene mostrato il suo ID interno, ad esempio custbody_phy_patient_name. Solo campi a livello di intestazione nei documenti di transazione.

Per aggiungere campi personalizzati dopo che la connessione è attiva:

Apri la connessione in Banche & integrazioni → Gestisci connessione → Rinnova autorizzazione e completa il flusso.
La connessione torna in stato In configurazione: il Supporto Agicap deve convalidarla nuovamente prima che le sincronizzazioni riprendano.
Una volta che la sincronizzazione è ripresa, contatta il Supporto Agicap indicando il tipo di documento aziendale e il modulo in cui deve essere costruita l'etichetta.

⚠️ Quando clicchi su Rinnova autorizzazione o Modifica credenziali, viene generata una nuova chiave pubblica e i dati di autenticazione precedenti vengono eliminati. Devi completare il flusso, altrimenti tutte le sincronizzazioni successive falliranno. Se succede, ripeti semplicemente il flusso fino alla fine.

Passaggio 6 — Agicap convalida la connessione

Dopo aver inviato il modulo, la connessione appare in Banche & integrazioni con stato In configurazione. Agicap completa quindi la mappatura multi-entità tra le tue filiali NetSuite e le entità Agicap, e convalida la connessione.

⚠️ Questa mappatura non può essere modificata una volta convalidata. Rivedi l'elenco delle filiali con il tuo referente Agicap prima che venga salvato. Correggere un errore significa eliminare la connessione e ricrearla da zero.

Le filiali inattive non devono essere selezionate: il connettore le ignora.

Finché la connessione è in stato In configurazione, nessun dato viene trasferito. È normale.

Passaggio 7 — Verifica la prima sincronizzazione

La connessione ha lasciato lo stato In configurazione

La timeline di sincronizzazione mostra un'esecuzione completata

I tuoi documenti compaiono in Treasury e Accounts Receivable, per almeno un'entità

Importi e valute corrispondono a quanto visualizzato in NetSuite

La sincronizzazione automatica viene poi eseguita due volte al giorno per i documenti aziendali e una volta al giorno per gli altri flussi, e può essere avviata manualmente in qualsiasi momento.

💡 Su un account di grandi dimensioni, la prima sincronizzazione può richiedere molto più tempo rispetto a quelle giornaliere, perché raccoglie l'arretrato storico in finestre temporali successive. Se sembra bloccata, contatta il tuo referente Agicap invece di ricreare la connessione.

C - File di pagamento tramite SFTP (NetSuite → Agicap)

📌 Inizia chiedendo al tuo referente Agicap di predisporre il trasferimento file. L'URL del server, la porta, il nome utente e la chiave host ti verranno forniti da lui, e la configurazione NetSuite qui sotto non può essere completata senza queste informazioni.

Passaggio 1 — Prepara la chiave SSH

⚠️ Vincoli sul formato della chiave. Il connettore SFTP di NetSuite accetta chiavi RSA, ECDSA e DSA, e la chiave privata deve essere in formato PEM. I server Agicap accettano RSA ed EdDSA. La scelta sicura è una chiave RSA 2048 la cui chiave privata sia in formato PEM. L'esportazione OpenSSH di WinSCP qui sotto serve a produrre quel file, non è un formato diverso.

Genera una coppia di chiavi RSA 2048 bit, ad esempio con il generatore di chiavi di WinSCP.
Assicurati che il file della chiave privata inizi con -----BEGIN RSA PRIVATE KEY-----. In caso contrario, convertilo: WinSCP → Strumenti → Converti file chiave → carica la chiave privata → Esporta chiave OpenSSH. Non selezionare "forza nuovo formato".
Invia la chiave pubblica al tuo referente Agicap, che predisporrà il trasferimento file e ti restituirà l'URL del server, la porta, il nome utente e la chiave host.

Passaggio 2 — Prepara i file di pagamento in NetSuite

Se già generi file di pagamento in NetSuite, non devi fare nulla qui.

Se non lo fai, installa la SuiteApp Electronic Bank Payments: Personalizzazione → SuiteBundler → Cerca & installa bundle → Elenco, bundle ID 416781, poi configura i tuoi modelli di file di pagamento per ogni banca.

💡 La generazione dei file di pagamento è un tema di configurazione NetSuite, non Agicap. Il tuo integratore NetSuite è solitamente la via più rapida se lo stai configurando per la prima volta.

Passaggio 3 — Crea le cartelle File Cabinet

Crea due cartelle nel tuo File Cabinet, una per i file in attesa di trasferimento e una per i file già trasferiti. Nomi suggeriti:

agicap payment - processing
agicap payment - processed

Annota l'ID interno di ciascuna cartella, ti serviranno al passaggio 5.

Passaggio 4 — Installa la SuiteApp SFTP Connector

Personalizzazione → SuiteApps → cerca SFTP Connector → Installa.

Passaggio 5 — Crea e mappa la configurazione di invio

SFTP → SFTP Records → Outbound Configurations → Nuovo.
Compila nome, URL server, porta, chiave host e metodo di autenticazione, utilizzando le credenziali fornite da Agicap.
Nella sottoscheda Outbound Mapping, inserisci gli ID interni delle due cartelle File Cabinet dal passaggio 3, e il nome della cartella sul server SFTP Agicap nel campo Bank folder.
Salva, poi riapri la configurazione in modalità Modifica e clicca su Test Connection. Nota: Test Connection non funziona in modalità Visualizza.
Clicca su Outbound-Manual per eseguire un'esportazione manuale e confermare che il file arrivi.

Passaggio 6 — Pianifica l'esportazione

SFTP → SFTP Records → Outbound Configurations → Visualizza sul tuo record.
Clicca su Outbound-Schedule. Si apre una pagina di distribuzione script.
Imposta la frequenza desiderata e Salva.

💡 Se gestisci più entità, concorda la struttura delle cartelle e la denominazione dei file con il tuo referente Agicap prima di pianificare, così i file di pagamento potranno essere separati per entità all'arrivo.

D - Estratti conto bancari tramite SFTP e ABSI (Agicap → NetSuite)

📌 Stesso punto di partenza della sezione C: chiedi prima al tuo referente Agicap di predisporre il trasferimento file. Le credenziali e la chiave host ti verranno fornite da lui.

Passaggio 1 — Controlla prima i formati degli estratti conto

Prima di qualsiasi configurazione, elenca le banche e i formati di estratto conto coinvolti e conferma che ciascuno sia supportato da un parser NetSuite. È qui che i progetti solitamente si bloccano. Vedi il riquadro nel §5.5.

Passaggio 2 — Permessi e SuiteApp

Assicurati di avere i diritti da amministratore, o le autorizzazioni ABSI specifiche.
Installa Auto Bank Statement Import: Personalizzazione → SuiteApps (o SuiteCloud Development → SuiteApp Marketplace) → cerca → Installa.

Passaggio 3 — Abilita SuiteScript

Setup → Azienda → Abilita funzionalità → sottoscheda SuiteCloud.
Sotto SuiteScript, seleziona Client SuiteScript e Server SuiteScript.
Salva. Questo rende accessibile la pagina delle Chiavi Private.

Passaggio 4 — Carica la chiave privata

Setup → Azienda → Preferenze → Chiavi → Crea nuovo.
Scheda Dettagli: un Nome descrittivo, uno script ID senza spazi o caratteri speciali (NetSuite lo prefigge con custkey), e una Descrizione che indichi a cosa serve la chiave e chi la gestisce.
Scheda File: scegli il file della chiave privata. Deve essere in formato PEM — vedi sezione C, passaggio 1 per come produrlo.
Password: la passphrase usata durante la generazione della chiave, se presente.
Scheda Audience, opzionale: seleziona Restrict to Employees per limitare quali dipendenti possono utilizzare la chiave in SuiteScript e utilizza Restrict to Scripts per limitarla a specifici script.
Salva. NetSuite convalida e memorizza la chiave.

Passaggio 5 — Crea il record dell'Istituto Finanziario e il Profilo di Formato

❗ Crea un record di Istituto Finanziario per ogni banca, poi un Profilo di Formato per ogni formato e versione di file al suo interno. Mescolare formati in un unico profilo è la causa più comune di importazioni fallite.

Setup → Accounting → Financial Institutions → List → Nuovo.
Nel record, aggiungi un Profilo di Formato e scegli Connettività SFTP come metodo.
Inserisci l'URL del server, il nome utente, la password e la host key forniti da Agicap. Per un server Agicap l'URL è files.agicap.com; la porta, il nome utente e la host key vengono forniti insieme alle credenziali che il tuo referente ti invia.
Definisci il pattern del nome file di download. Concorda il nome file e la directory esatti con il tuo referente Agicap.

Passaggio 6 — Collegamento dei conti

Mappa i dati che NetSuite analizzerà sui tuoi conti GL. Elenca ogni conto interessato dagli estratti conto che importi e, per ogni valore che il parser estrarrà, inserisci quel valore nella prima colonna e collegalo al corrispondente conto GL di NetSuite nella terza colonna.

Il formato della prima colonna deve corrispondere esattamente a ciò che produce il parser scelto.

Passaggio 7 — Configura il parser

Formato	Cosa controllare
CAMT.053	Aggiungi tutti i codici transazione che possono comparire negli estratti conto che ricevi. Un codice mancante fa fallire l'intera importazione. Poi controlla la mappatura dei tag per ogni campo NetSuite.
MT940	Parser standard NetSuite, segui la documentazione NetSuite.
BAI2	Parser standard NetSuite, segui la documentazione NetSuite.
CSV	Soluzione di fallback quando è stata necessaria una trasformazione. Colonne e formati devono corrispondere esattamente alla definizione di importazione CSV di NetSuite.

Passaggio 8 — Test e attivazione

Chiedi ad Agicap di posizionare prima un file corrispondente sul server SFTP, così il test sarà significativo.
Clicca su Invia, non su Salva direttamente.
Se il risultato è verde, clicca su Salva.
Clicca su Traccia stato per confermare che il file sia stato recuperato e analizzato.

💡 Frequenza. Il flusso di importazione viene eseguito circa una volta al giorno. Puoi avviarlo manualmente reinviando il Profilo di Formato, con un minimo di 60 minuti tra due esecuzioni. Conservazione. NetSuite non sposta né elimina i file una volta processati. La strategia di archiviazione sul server SFTP viene concordata con il tuo referente Agicap durante la configurazione, così lo stesso estratto conto non viene importato due volte.

Evitare importazioni duplicate. NetSuite dovrebbe saltare un file già importato, ma consigliamo una di queste strategie, da concordare con il tuo referente Agicap:

Data nel nome file — ogni nome file include la sua data (ad esempio bank_statement_2024-06-15.csv) e il tuo pattern di nome file NetSuite accetta quella data.
Flusso a due cartelle — i file vengono consegnati in una cartella da processare e spostati in una cartella processati una volta che la finestra di elaborazione di NetSuite è passata.
SuiteScript personalizzato dal tuo lato che rinomina o sposta i file dopo l'importazione.

Diverse banche o formati. Ogni parser NetSuite deve prelevare solo i file della propria banca. Usa una cartella per banca (ad esempio /Bank_A/, /Bank_B/), oppure una singola cartella con una convenzione di denominazione (un prefisso o suffisso della banca in ogni nome file, ad esempio BANKA_20240615.csv) e configura ogni Profilo di Formato per selezionare solo il proprio pattern. È possibile anche una combinazione di entrambe le soluzioni.

Come attivare ciascun caso d'uso

Una volta completata la configurazione e dopo aver eseguito una prima raccolta di documenti aziendali, puoi attivare gli altri flussi direttamente dalla pagina Banche & integrazioni > Dettagli sincronizzazione. Ogni flusso ha il proprio interruttore on/off. L'importazione dei documenti aziendali è attivata di default e non può essere disattivata.

6. Errori frequenti

Errore	Cosa vedi	Causa	Cosa fare
Timeout alla prima sincronizzazione	Nessuna transazione in attesa appare in Treasury dopo la prima sincronizzazione	Troppa cronologia recuperata in una volta sola (per impostazione predefinita, gli ultimi 365 giorni di documenti modificati)	Contatta l'Assistenza Agicap: possono ridurre la finestra di raccolta iniziale, ad esempio a 90 giorni.
Timeout su una connessione attiva Messaggio nei dettagli di sincronizzazione: `The request was canceled due to the configured HttpClient.Timeout of 300 seconds elapsing. > The operation was canceled.`	I documenti non vengono più aggiornati in Agicap	NetSuite ha impiegato più di 5 minuti per rispondere a una chiamata API. Agicap interrompe le chiamate dopo 5 minuti per evitare che le sincronizzazioni restino bloccate indefinitamente.	Esegui nuovamente la sincronizzazione dopo un po'. Se l'errore persiste, contatta l'Assistenza Agicap indicando il nome della connessione e il messaggio di errore. Non eliminare né sostituire la connessione.
`Aggregator error : Invalid URL: The hostname could not be parsed.`	Tutte le sincronizzazioni falliscono dopo la modifica delle credenziali	Modifica credenziali o Rinnova autorizzazione è stato avviato ma non completato. Viene generata una nuova chiave pubblica non appena si clicca e i precedenti dati di autenticazione vengono eliminati.	Ripeti la procedura delle credenziali e completala fino alla fine (B, passaggi da 2 a 4).
La connessione rimane su Impostazione in corso	La connessione è stata creata ma nulla si sincronizza	La mappatura tra le tue filiali NetSuite e le tue entità Agicap non è stata ancora completata e convalidata, oppure una rinnovata autorizzazione non è stata riconvalidata	Contatta l'Assistenza Agicap: la mappatura e la convalida vengono effettuate dal lato Agicap (B, passaggio 6).
Esportazione della prima nota rifiutata su uno specifico cliente/fornitore	Un'esportazione fallisce, le altre vanno a buon fine	Cliente/fornitore duplicato in NetSuite, quindi il riferimento della fattura e quello del cliente/fornitore non puntano allo stesso record	Elimina i duplicati di fornitori e clienti in NetSuite.
Ordini di acquisto raccolti ma non visibili in Accounts Payable	Nulla appare in Accounts Payable dopo una sincronizzazione riuscita	La funzione corrispondente di Agicap non è attivata sul tuo account	Contatta l'Assistenza Agicap per attivarla.

Hai bisogno di aiuto o di maggiori informazioni?

Contatta il supporto Agicap.

Oracle NetSuite (esterno)