Documentazione · ordini

API custom del gestionale

Non tutte le aziende ricevono gli ordini web come ordine di vendita standard di Business Central. Alcune hanno un processo proprio — una tabella di importazione, una coda di lavorazione, un’anagrafica gestita internamente — che il partner BC espone con una API custom. i-Connect può scrivere lì invece che su salesOrders, senza sviluppi su misura: percorso, entità e mappatura dei campi si configurano dalla dashboard.

Cosa cambia rispetto all’ordine standard

Un’API custom è quasi sempre più povera dell’ordine di vendita: è un punto di ingresso, non un documento. Conviene sapere prima cosa si guadagna e cosa si perde.

Requisiti dell’API

Prima di configurare, verifica col partner che l’API soddisfi questi punti. Sono gli stessi requisiti per qualunque gestionale: i-Connect non presuppone nomi di campo, li scopre.

• è raggiungibile con le stesse credenziali OAuth2 service-to-service già usate per la connessione BC (nessuna autenticazione separata);
• espone il $metadata del proprio gruppo API: è da lì che i-Connect legge campi, tipi e lunghezze massime;
• accetta il POST di un record e supporta $filter sul campo che correla le righe;
• consigliato: PATCH sul singolo record, per poter correggere o azzerare una riga inviata per errore (molte tabelle di staging non espongono il DELETE).

Il modello: un record per riga

i-Connect scrive un record per ogni riga dell’ordine, ripetendo i dati di testata (cliente, indirizzi, riferimento) su ciascuno. Le righe di uno stesso ordine sono legate dal campo di correlazione, tipicamente il riferimento dell’ordine e-commerce.

POST .../api/<publisher>/<gruppo>/<versione>/companies({companyId})/<entità>

{ "documentReference": "RNNKVGABO", "itemNo": "PR2-5L", "quantity": "2", ... }
{ "documentReference": "RNNKVGABO", "itemNo": "HP12-1L", "quantity": "1", ... }

Configurare il collegamento

Tutto avviene in Impostazioni → Flussi → Ordini verso Business Central. Le modifiche vengono salvate da sole: non c’è un pulsante di conferma.

1. 1Alla voce Destinazione dell’ordine scegli “API custom — pubblicata da un’estensione del tuo partner BC”.
2. 2Inserisci il percorso API, cioè quello che segue /api/ nell’URL che ti ha dato il partner: publisher/gruppo/versione.
3. 3Premi Rileva campi: i-Connect legge il servizio e ti mostra le entità disponibili con il numero di campi. Se ce n’è una sola viene selezionata da sé.
4. 4Indica i campi di ritorno (vedi sotto) e il separatore decimale, poi associa ogni campo dell’API al dato dell’ordine corrispondente.

I campi di ritorno

Sono i campi che scrive il gestionale e che i-Connect si limita a leggere: sono il modo in cui l’ERP risponde. Indicarli è ciò che rende l’integrazione bidirezionale invece che un invio cieco.

Formato dei numeri

Molte tabelle di importazione dichiarano tutti i campi come testo, quantità e importi compresi. In quel caso è il gestionale a interpretarli, quindi il separatore decimale va concordato: un 38,10 letto all’inglese diventa trentottomilacento. Scegli il separatore che ti indica il partner; i-Connect non usa mai il separatore delle migliaia e scrive le quantità senza decimali forzati (3, non 3,00). Se invece i campi sono numerici veri, la scelta è ininfluente.

Totali di trasporto e sconto

Dato che la testata si ripete su ogni riga, chiedi al partner se i totali vanno ripetuti su tutte le righe o scritti solo sulla prima: dipende da come li rilegge il suo processo. Sbagliare significa spese di spedizione contate più volte. L’interruttore è in configurazione.

Come lavora l’invio

• Invio riga per riga, riprendibile: i-Connect registra ogni riga scritta man mano. Se l’invio si interrompe (timeout, riavvio), il tentativo successivo riparte dalla prima riga mancante invece di riscrivere l’ordine da capo. Queste API di solito non hanno protezione contro i duplicati, quindi la garanzia la mette i-Connect.
• Salvaguardia sui duplicati: se sull’API risultano già righe con quel riferimento ma i-Connect non ne ha traccia, l’invio si ferma e te lo segnala, invece di rischiare un ordine doppio.
• Lunghezze rispettate: i valori vengono adattati alle lunghezze massime dichiarate dal servizio, così un nome lungo non fa rifiutare l’intero ordine.
• Verifica dell’esito: come per l’ordine standard non avviene mai a intervalli di tempo, ma dal bottone sull’ordine o dal webhook di ritorno. Finché il gestionale non dichiara il record convertito, l’ordine resta “Inviato”: nessuno stato viene inventato.

Verificare che funzioni

1. 1Manda un ordine di prova dal negozio e controlla i log: deve comparire il numero di righe scritte e il riferimento usato.
2. 2Apri la tabella su Business Central e verifica che le righe ci siano, con importi e quantità nel formato atteso.
3. 3Quando il gestionale ha elaborato il record, premi Verifica su BC sull’ordine: lo stato deve passare a evadibile, parziale o non evadibile.