Documentazione · tecnica
Per il partner Business Central
Questa pagina è pensata per chi gestisce il Business Central del cliente. i-Connect lavora con le API standard v2.0 (OAuth2 service-to-service): non servono personalizzazioni per partire. Le estensioni sotto sono opzionali e sbloccano la parità completa con gli import su misura e lo stock in tempo reale.
Cosa fa i-Connect con la sola API standard
- crea gli ordini di vendita (deep-insert testata+righe) su un cliente di appoggio o su un cliente reale creato/riusato con i dati fiscali;
- scrive indirizzi ship-to/sell-to, dimensioni globali 1/2, righe conto CoGe per trasporto e sconti,
pricesIncludeTax=false, riferimento e-commerce nel Nr. documento esterno; - azzera gli sconti riga automatici (i prezzi li governa il negozio);
- rilegge gli ordini per la verifica di evadibilità (diff righe);
- sincronizza gli articoli a delta su
lastModifiedDateTime.
Estensione consigliata (pagina API custom)
Le pagine API standard Microsoft non sono estensibili; una piccola app AL con una pagina API custom su Sales Header (Document Type = Order, chiave = SystemId) espone ciò che manca. Nomenclatura suggerita — i nomi campo sono configurabili per tenant nella dashboard, quindi il partner è libero:
publisher: iconnect · group: integration · version: v1.0
.../api/iconnect/integration/v1.0/companies({companyId})/salesOrderExtras({systemId})| Campo API | Campo BC | Accesso |
|---|---|---|
| id | SystemId (chiave) | lettura |
| number | No. | lettura |
| sellToCustomerName | “Vendere a - Nome” — il nominativo dell’acquirente (read-only nell’API standard) | scrittura |
| documentReference | “Riferimento documento” (campo del flusso di import esistente, se usato a valle) | scrittura |
| operationType | causale / tipo operazione della localizzazione IT (es. fattura vs corrispettivo) | scrittura |
| campi logistici | flag usati dai processi a valle (es. selezione per l’export magazzino) | scrittura |
| status | stato del documento | lettura |
Più una azione bound di rilascio(assente dall’API standard, dove gli ordini creati restano “Aperto”):
POST .../salesOrderExtras({systemId})/Microsoft.NAV.releaseSequenza usata da i-Connect (stesso token OAuth dell’app Entra già registrata):
1. POST /api/v2.0/companies({id})/salesOrders ← standard, già attivo
2. PATCH .../salesOrderExtras({systemId}) If-Match: *
{ "sellToCustomerName": "Mario Rossi",
"documentReference": "RHEKPTKTJ",
"operationType": "ECOMM_NOFA", ... }
3. POST .../salesOrderExtras({systemId})/Microsoft.NAV.releaseNessun permesso aggiuntivo
Webhook: stock in tempo reale
A ogni variazione di disponibilità (spedizione registrata, rettifica, carico) Business Central chiama l’endpoint del tenant — implementazione libera (Job Queue, subscriber sulle registrazioni, Power Automate). Batch ammessi, retry su HTTP ≠ 2xx:
POST https://i-connect.tech/api/webhooks/bc-stock?key=<chiave-tenant>
Content-Type: application/json
{
"items": [
{ "itemNo": "MF82", "availableQty": 152, "location": "053",
"timestamp": "2026-07-07T15:30:00Z" }
]
}La piattaforma applica subito la soglia di sicurezza e aggiorna il negozio; risponde { ok, updated, notOnShop[] }.
Webhook: ordine lavorato (flusso di ritorno)
Quando il magazzino ha lavorato/modificato un ordine, una chiamata fa scattare la verifica di evadibilità di quell’ordine (e l’eventuale gestione delle righe mancanti sul negozio):
POST https://i-connect.tech/api/webhooks/bc?key=<chiave-tenant>
Content-Type: application/json
{ "bcOrderNo": "OV26014470" }- in alternativa
{ "externalDocumentNumber": "<riferimento e-commerce>" }; - body vuoto = ricontrolla tutti gli ordini aperti;
- la chiave (unica per tenant, valida per entrambi gli endpoint) la genera il cliente dalla dashboard:
Impostazioni → Flussi → Verifica evadibilità → Webhook.
Fuori scope
- Prezzi e listini: governati dall’e-commerce; i-Connect non legge i listini BC.
- Fatturazione: resta nei processi Business Central del cliente.