In breve: con l'architettura V17 di Mikro, la sua integrazione va ora costruita sulla Mikro Desktop API ufficiale, non sull'accesso SQL diretto. La frase che si sente dai system integrator sul mercato, «con la V17 l'accesso diretto al database è stato chiuso e il sistema è diventato completamente basato su API», è una sintesi efficace, ma non del tutto esatta. La documentazione ufficiale di Mikro afferma infatti con chiarezza che i campi delle tabelle non esposti nel JSON dell'API possono ancora essere richiamati direttamente con il loro nome nel database. La lettura corretta è quindi questa: con la V17 l'API ufficiale è diventata il canale di integrazione primario e supportato, mentre per i campi che l'API non espone resta un'eccezione documentata, l'«accesso tramite nome DB». Che cosa deve fare adesso? Tre passaggi: (1) censisca colonna per colonna tutti i punti di lettura e scrittura SQL attuali, (2) stabilisca per ogni campo se esiste un endpoint API o se serve il ripiego sul nome DB, (3) richieda un'API Key tramite il portale ufficiale per sviluppatori, testi il nuovo flusso in parallelo ed esegua poi il passaggio definitivo (cutover). In questa guida seguiamo la migrazione passo dopo passo, senza certezze inventate, sulla base della documentazione ufficiale di Mikro.

Come software house B2B e white-label con sede a Sakarya, gestiamo questa migrazione per integrazioni che dipendono da Mikro in ambito e-commerce, software su misura e contabilità. Di seguito condividiamo sia la logica della decisione sia il playbook concreto che applichiamo sul campo. Abbiamo mantenuto le affermazioni apparentemente «definitive» su date e porte solo dove potevamo basarle su una fonte ufficiale, e abbiamo segnalato con chiarezza i punti che sono interpretazioni dei system integrator.

Che cosa è cambiato esattamente?

Mikro ha pubblicato un portale ufficiale per sviluppatori dedicato ai suoi prodotti desktop: apidocs.mikro.com.tr. Lo slogan del portale è «Sviluppo, test, messa in produzione — Guida all'integrazione API di Mikro» e il pubblico di riferimento è definito in modo esplicito: clienti di Mikro Software, partner di Mikro Software e sviluppatori di soluzioni di terze parti. Questa API, quindi, non è riservata ai rivenditori: è il canale ufficiale anche per i team interni dei clienti e per le software house indipendenti.

Anche la natura tecnica dell'API è chiara: REST/JSON su HTTP. Il portale ufficiale offre guide intitolate «Fondamenti di JSON e API REST», «Protocollo HTTP e codici di stato» e «Uso degli endpoint», oltre a collection Postman ufficiali scaricabili sia per la V17 sia per la V16 («Postman Collection aggiornata (V17)» e «(V16)»). Queste collection sono il punto di partenza ufficiale della sua fase di test.

Una sfumatura fondamentale: dire che «la V17 ha eliminato ogni accesso diretto al database» è sbagliato. Secondo le FAQ ufficiali, «anche i campi delle tabelle non presenti nel JSON dell'API possono essere usati direttamente con il loro nome nel database». L'inquadramento corretto è questo: l'API ufficiale è ora il canale primario obbligatorio e supportato, mentre il nome DB è un'eccezione documentata per i campi che l'API non espone.

Perché l'accesso diretto al database è passato in secondo piano? (la logica della decisione)

I blog dei system integrator (ad esempio ozgurguler.net, mikrodestek.net) riassumono il cambiamento così: «a partire da Mikro V17 l'accesso diretto al database è stato chiuso e il sistema è passato a un modello interamente basato su API». Questa frase va riportata non come affermazione ufficiale di Mikro, ma come interpretazione dei system integrator: nelle fonti di Mikro non abbiamo trovato questa formulazione esatta e l'eccezione del nome DB descritta sopra attenua quell'affermazione assoluta. Resta comunque chiara la logica tecnica per cui un produttore di ERP impone un livello API controllato al posto dell'SQL diretto:

  • Stabilità e indipendenza dallo schema: l'SQL diretto si lega strettamente alla struttura di tabelle e colonne. Quando il produttore modifica lo schema in una release, le sue query si rompono senza alcun avviso. Un livello API interpone un contratto tra lo schema interno e il consumatore esterno: anche se la struttura interna cambia, il contratto dell'endpoint può restare invariato.
  • Sicurezza e superficie dei permessi: fornire alla sua applicazione le credenziali dirette del database (una connection string) significa aprire la superficie di permessi più ampia possibile. Con l'accesso tramite API, l'autenticazione viene delegata al meccanismo di sessione e autorizzazione di Mikro e l'accesso può essere limitato a livello di endpoint.
  • Supporto e prevedibilità: con l'SQL diretto il produttore non può sapere che cosa sta leggendo o scrivendo la sua applicazione. Poiché le regole di business possono essere aggirate, si crea un rischio per l'integrità dei dati. Le operazioni eseguite tramite API sono invece definite, versionate e supportabili. Mikro pubblica infatti un changelog dell'API V17 con date precise: la voce più vecchia che abbiamo potuto vedere è [17.03a] – 14.04.2025, la più recente [17.07b] – 05.08.2026. È la prova che l'API viene versionata ed evolve attivamente.

Chi è interessato?

Questa migrazione riguarda ogni integrazione che si collega direttamente al database di Mikro. Ecco i tre gruppi che incontriamo più spesso sul campo:

  • Integrazioni e-commerce: negozi che sincronizzano via SQL giacenze, prezzi, conti cliente e ordini tra un sito web o un marketplace e Mikro. Su questo fronte i rischi più critici sono le operazioni di scrittura, come lo scarico di magazzino, la creazione di fatture e documenti di trasporto e il trasferimento degli ordini.
  • Software su misura e progetti interni: sviluppi interni che usano Mikro come unica fonte di verità, ad esempio il monitoraggio della produzione, le app per le squadre sul campo e i portali rivenditori B2B. Per questo gruppo la licenza dell'API Key viene gestita manualmente (vedi sotto).
  • Integrazioni contabili e di reportistica: riconciliazione dei conti, ponti verso e-Fatura ed e-Arşiv (i sistemi turchi di fatturazione elettronica), dashboard di BI e reportistica, esportazioni ricorrenti. Anche se per lo più sono «in sola lettura», è il gruppo più radicato nelle query dirette alle tabelle.

Stabilire se i flussi e-commerce e di fatturazione elettronica lato Mikro vadano risolti con un modulo pronto o con un'integrazione API su misura è una decisione a sé. L'abbiamo trattata in un articolo separato: Integrazione e-commerce + ERP + e-Fatura: soluzione pronta o API su misura?

Il playbook di migrazione: dalle letture SQL agli endpoint API

I passaggi che seguono sono una raccomandazione redazionale costruita sui fatti documentati da Mikro: voci come l'esecuzione in parallelo e il rollback non sono una procedura imposta da Mikro, ma buone pratiche standard di integrazione.

1) Inventario dei campi: mappare ogni colonna SQL

Il primo passaggio, e il più trascurato: estragga ogni tabella e ogni colonna toccata dalla sua integrazione attuale. Poi scelga per ogni campo uno dei due percorsi:

  • Se il campo è esposto nel JSON dell'API → lo legga dalla risposta dell'endpoint REST corrispondente.
  • Se il campo non è nel JSON dell'API → come indicano le FAQ ufficiali, può essere richiamato direttamente con il suo nome DB. È un'importante via d'uscita, che allenta la pressione del «deve convertire tutto all'API in un colpo solo».
  • Se non esiste né come endpoint né come campo accessibile → apra una richiesta di nuova tabella o endpoint tramite il modulo di richiesta Program API (Mikro indica: «Per le richieste di nuove tabelle: modulo di richiesta API»).

Le migrazioni eseguite senza questo inventario saltano in produzione con errori di «campo mancante». La mappatura colonna per colonna è il passaggio più faticoso, ma anche il più decisivo della migrazione.

2) Autenticazione e richiesta di accesso

Prima di tutto l'accesso: i system integrator compilano il modulo di richiesta Program API. Secondo la guida ufficiale, le API Key vengono assegnate automaticamente a chi usa una soluzione verticale, mentre per il software interno viene rilasciata una licenza manuale. (I passaggi descritti su alcuni blog di system integrator, come la «valutazione dettagliata con domande e risposte via email e il trasferimento al reparto Password», non sono documentati in questo modo nel materiale ufficiale: la fonte ufficiale contiene solo il modulo, la distinzione tra le licenze e gli indirizzi di contatto.)

Il modello di autenticazione non è OAuth: meglio chiarirlo subito. Si basa su API Key + sessione/login. Secondo la guida ufficiale, in ogni richiesta si usano le seguenti informazioni:

Campo A che cosa serve
ApiKey La chiave ottenuta con la richiesta di accesso; viene inviata nel corpo JSON. Se è errata, viene restituito l'errore «Api key non valida».
FirmaKodu Codice azienda.
CalismaYili Anno di esercizio.
KullaniciKodu Codice utente.
Sifre Password; secondo la guida ufficiale si calcola come Data + Password → hash MD5.

Nella gestione della sessione c'è una differenza di versione. I metodi V1 aprono prima una sessione con APILogin (indirizzo riportato nella pagina ufficiale di installazione: POST http://localhost:8094/Api/APIMethods/APILogin, con FirmaKodu, CalismaYili, ApiKey, KullaniciKodu, Sifre nel corpo). I metodi V2/V3, invece, inviano i dati dell'utente direttamente nel JSON di ogni endpoint ed eseguono il logout automatico al termine dell'operazione. Tenga conto di questa distinzione fin dall'inizio, quando definisce l'architettura (sessione persistente o su richiesta).

3) Installazione e impostazioni delle porte

L'API si installa tramite l'opzione «Server» nella pagina degli aggiornamenti di versione e registra un servizio Windows denominato Mikro Desktop API. Il servizio viene eseguito con l'account NT SERVICE\MikroDesktopAPIContainer; i parametri della porta si trovano in HKLM\SYSTEM\CurrentControlSet\Services\MikroDesktopAPIContainer\Parameters. Per cambiare la porta occorre arrestare il servizio, modificarla con regedit (base decimale) e poi aprirla in Windows Firewall.

Le porte di servizio predefinite variano in base alla versione: 8094 per la V17, 8084 per la V16. Sono valori predefiniti, modificabili dal registro di sistema. Per questo, invece di dire «Mikro ha cambiato la porta da 8084 a 8094», è più corretto dire «il valore predefinito della V16 è 8084 e quello della V17 è 8094». Se ha personalizzato questa porta nel suo ambiente, imposti di conseguenza gli indirizzi delle chiamate.

4) Test: la collection Postman ufficiale

Prima di scrivere codice, verifichi le chiamate a mano. Scarichi il pacchetto ufficiale Postman Collection (V17) di Mikro ed esegua con le sue credenziali gli endpoint individuati nell'inventario. Confronti le risposte attese con l'output SQL attuale e non vada in produzione finché non ottiene una corrispondenza campo per campo. In questa fase il canale ufficiale di assistenza tecnica è [email protected], mentre per le domande su API Key e partner l'indirizzo è [email protected].

5) Esecuzione in parallelo e rollback

Il passaggio che riduce al minimo il rischio: esegua il nuovo flusso basato su API accanto al vecchio flusso SQL. Per un periodo definito, entrambi i percorsi devono produrre gli stessi dati (letture e scritture) e i risultati vanno confrontati automaticamente (riconciliazione). Se non ci sono divergenze, la fiducia cresce. In questa fase tenga pronto il piano di rollback: con un feature flag deve poter tornare al vecchio flusso con un clic. Questo approccio con esecuzione in parallelo e rollback non è un'istruzione di Mikro, ma la rete di sicurezza standard per le integrazioni che raccomandiamo.

6) Cutover e scelta della versione

Quando il confronto è pulito, esegua il cutover: sposti il traffico di scrittura sull'API, porti il percorso SQL in modalità di osservazione in sola lettura, poi lo disattivi del tutto. Blocchi l'API su una versione nota e riesegua il suo set di regressione Postman a ogni aggiornamento della Mikro Desktop API: il fatto che il changelog sia attivo dimostra che sono possibili modifiche silenziose.

Un'avvertenza. La frase secondo cui Mikro ERP richiederebbe la «V17 o superiore» per usare l'API non compare testualmente nella home page o nelle guide ufficiali di apidocs, ma nella pagina di un system integrator terzo (Ovo Yazılım). Non presentiamo questo prerequisito di versione come fonte ufficiale e le consigliamo di verificarlo nella sua installazione tramite il browser.

Tempistiche: quali date circolano per la V16?

Per i team che vogliono legare la migrazione a un calendario, circolano spesso due date. Non siamo riusciti a confermarle da una fonte primaria di Mikro: le pagine degli annunci ufficiali erano chiuse all'accesso automatizzato. Le date che seguono si basano su un blog di system integrator che cita l'annuncio di Mikro (ozgurguler.net) e su segnalazioni di reclami dei consumatori. Pertanto vanno verificate nel browser sulla pagina ufficiale degli annunci di Mikro prima della pubblicazione:

  • 15 ottobre 2025 — data limite per i rinnovi (operazioni di rinnovo): secondo quanto riportato, dopo questa data tutti i rinnovi verranno effettuati solo sulla V17. Non è la fine completa del supporto, ma solo il termine per i rinnovi.
  • 15 ottobre 2026 — fine definitiva del supporto: secondo l'annuncio che risulterebbe datato 29 settembre 2025, in questa data per la V16 terminano del tutto gli aggiornamenti di versione e normativi, i nuovi sviluppi, l'assistenza clienti e le licenze aggiuntive per utenti, moduli e soluzioni verticali. È una scadenza distinta, che arriva un anno dopo il termine per i rinnovi: non confonda le due date.

In pratica, qualunque data venga confermata, la strada più sicura è trasformare il passaggio della sua integrazione all'API in un progetto e completarlo con largo anticipo sulla scadenza. Le migrazioni lasciate all'ultimo giorno eliminano sia la finestra di test sia il lusso del rollback.

Errori comuni

  • Saltare l'inventario: è il presupposto che «tanto l'API darà tutto». Alcuni campi arrivano solo con il nome DB; per altri occorre aprire una richiesta di nuova tabella. Inventario incompleto = sorprese in produzione.
  • Scambiare l'autenticazione per OAuth: il modello è API Key + login/sessione e la password è Data + Password → hash MD5. I client costruiti con la logica dei Bearer token incontrano errori «Api key non valida» e di sessione.
  • Dare per scontata la porta: chi arriva dalla V16 si aspetta la 8084, ma il valore predefinito della V17 è 8094 e potrebbe essere stato modificato dal registro di sistema. Invece di scrivere una porta fissa nel codice, la renda configurabile.
  • Non bloccare la versione: l'API è in continua evoluzione. Senza il blocco della versione, ogni aggiornamento comporta il rischio di una regressione silenziosa.
  • Scambiare strumenti di terze parti per ufficiali: alcuni strumenti di test e installazione che circolano nella community (ad esempio quello che un blogger chiama «l'app di test gratuita che ho sviluppato») non sono prodotti ufficiali di Mikro. L'artefatto di test ufficiale è la collection Postman pubblicata da Mikro.
  • Cutover senza periodo in parallelo: un passaggio diretto, senza riconciliazione e rollback, fa emergere le incoerenze dei dati solo attraverso i reclami dei clienti.

Come La aiuta Partnerfy

Come software house con sede a Sakarya, gestiamo queste migrazioni ERP non come una «promessa», ma come un processo ripetibile: prima un inventario a livello di campo delle sue dipendenze SQL esistenti, poi la costruzione del livello di integrazione API (richiesta di accesso, autenticazione, mappatura degli endpoint), quindi i test con la collection Postman ufficiale, l'esecuzione in parallelo con riconciliazione e un cutover controllato. Se i suoi flussi CRM/ERP collegati a Mikro riguardano l'e-commerce o il software web su misura, progettiamo e manteniamo questo livello con un unico punto di responsabilità.

Una nota onesta: nessun system integrator può garantire che un sistema basato sull'API del produttore resti immune da ogni futuro cambio di versione. Per questo realizziamo un'architettura resiliente ai cambiamenti, osservabile e con versione bloccata. Può anche valutare con un criterio a parte se un investimento in un ERP/CRM specifico per la sua azienda sia adatto alle sue esigenze: Un software ERP/CRM su misura per l'azienda fa per Lei?

Conclusione

Con la V17, la Mikro Desktop API ufficiale è diventata il canale primario e supportato per le integrazioni; le architetture radicate nell'SQL diretto sono ormai fragili e non supportate. Dire però che «tutto l'accesso al database è stato chiuso» sarebbe sbagliato: per i campi che l'API non espone rimane un'eccezione documentata basata sul nome DB. La mossa giusta è creare un inventario a livello di campo, richiedere l'accesso all'API ufficiale e testare con Postman, quindi eseguire in parallelo prima di un cutover controllato, con la rete di sicurezza del rollback. Verifichi sull'annuncio ufficiale di Mikro le date del 15 ottobre 2025 e 2026 che circolano e non aspetti la scadenza per migrare. Se desidera pianificare o affidarci questa migrazione, ci contatti: individueremo le sue dipendenze SQL e le proporremo un piano per trasferirle su un'API su misura.

Fonti

Domande frequenti

Con Mikro V17 è stato davvero chiuso ogni accesso diretto al database?

No, dire che «è stato chiuso tutto» non è esatto. L'API ufficiale è ora il canale primario e supportato, ma le FAQ di Mikro indicano che i campi delle tabelle non esposti nel JSON dell'API possono ancora essere usati direttamente con il loro nome DB. La frase «l'accesso al database è stato chiuso del tutto» non è un'affermazione ufficiale di Mikro, ma un'interpretazione dei system integrator.

Come si richiede l'accesso all'API di Mikro e come si ottiene un'API Key?

La domanda si presenta con il modulo di richiesta Program API su mikro.com.tr. Secondo la guida ufficiale, le API Key vengono assegnate automaticamente a chi usa una soluzione verticale, mentre per il software interno viene rilasciata una licenza manuale. Anche le richieste di nuove tabelle o endpoint passano dallo stesso modulo. Per le domande tecniche l'indirizzo ufficiale è [email protected], per le API Key è [email protected].

La Mikro Desktop API usa OAuth? Come funziona l'autenticazione?

No, non è OAuth. Il modello si basa su API Key + sessione/login: ogni richiesta invia ApiKey (nel corpo JSON), FirmaKodu, CalismaYili, KullaniciKodu e Sifre, e la password si calcola come «Data + Password → hash MD5». I metodi V1 usano una sessione APILogin; i metodi V2/V3 inviano i dati direttamente in ogni endpoint ed eseguono il logout automatico al termine dell'operazione.

Quale porta usa l'API di Mikro?

La porta predefinita del servizio varia in base alla versione: 8094 per la V17, 8084 per la V16. Sono valori predefiniti e si possono modificare con regedit (arrestando il servizio e usando la base decimale); quando si cambia la porta, occorre aprirla in Windows Firewall. Per questo, nel suo client, renda configurabile la porta invece di scriverla fissa nel codice.

Quando finisce il supporto alla V16? Entro quando devo migrare?

Nelle fonti dei system integrator circolano due date: il 15 ottobre 2025 (operazioni di rinnovo solo sulla V17) e il 15 ottobre 2026 (fine definitiva di aggiornamenti di versione e normativi, supporto e licenze per la V16). Non siamo riusciti a confermare queste date da una fonte primaria di Mikro; le verifichi su mikro.com.tr/duyurular prima della pubblicazione. In ogni caso, la scelta più sicura è completare la migrazione con largo anticipo sulla scadenza.

Perché scegliere la migliore software house di Sakarya per l'integrazione API di Mikro V17?

Partnerfy è una software house B2B e white-label con sede centrale ad Adapazarı, Sakarya, e uffici in Turchia, Germania, Russia e Irlanda. Gestisce la migrazione a Mikro V17 con un processo ripetibile: inventario SQL a livello di campo, richiesta di accesso all'API ufficiale e configurazione dell'autenticazione, test con Postman, esecuzione in parallelo con riconciliazione e cutover controllato. Senza vendere statistiche inventate o garanzie e realizzando un'integrazione osservabile e con versione bloccata, è annoverata tra le aziende preferite per le integrazioni e-commerce, software su misura e contabili.