L'API REST che Dolibarr dovrebbe avere di serie
32 domini del core con i permessi nativi di Dolibarr, idempotenza reale e operazioni massive. Con server MCP per collegare agenti IA.
|
32
domini del core
|
697
operazioni
|
3.849
test
|
V15–V23
PHP da 7.0 a 8.3
|
Il problema che risolve
L'API nativa di Dolibarr non è soltanto limitata: ogni sua stranezza ti costa ore. Queste sono quelle che ricorrono in ogni integrazione.
| Quello che ti trovi davanti |
Quello che ti costa |
| Un POST restituisce un intero, un altro l'oggetto |
Un parser diverso per ogni endpoint, e nessuno riutilizzabile |
| Il join dei commerciali usa t.rowid = sc.fk_soc |
Si infilano record di terzi che quell'utente non dovrebbe vedere |
| Arriva un 401 dove serviva un 403 |
La tua logica di retry insiste su qualcosa che non funzionerà mai |
| accountancy espone solo exportData |
La contabilità resta fuori dalla tua integrazione |
| Non c'è idempotenza su nessuna scrittura |
Un timeout più un retry e hai fatturato due volte |
EasyAPI non è uno strato sopra l'API nativa: è una reimplementazione completa con un contratto dichiarativo uniforme.
NOVITÀ 2.1
Server MCP nativo per agenti IA
Collega Claude, Cursor o qualsiasi agente IA al tuo Dolibarr in un minuto: l'URL del modulo e la tua DOLAPIKEY come token Bearer.
Invece di riversare centinaia di strumenti sull'agente, espone tre meta-tool —search, describe e invoke— sulle 697 operazioni, con schemi ed esempi pronti da invocare. L'agente concatena operazioni in più passi, scrive con idempotenza e riceve errori auto-correttivi: un 422 gli indica il campo esatto da sistemare.
Eredita i tuoi permessi e ACL nativi di Dolibarr, quindi non può vedere né toccare nulla che l'utente non potrebbe. Include la scheda di amministrazione «MCP / IA» e una guida al collegamento dentro il modulo stesso.
Documentazione integrata
La specifica OpenAPI si genera da sola dalle risorse e viene servita dentro il modulo, filtrata in base ai permessi dell'utente che la consulta. Scegli il visualizzatore: Scalar, Swagger UI o Redoc, tutti e tre inclusi.
I 32 domini navigabili, con selettore del server e autenticazione con DOLAPIKEY. Ogni operazione porta con sé schema ed esempio pronto da invocare.
Confronto con l'API nativa
| Dimensione |
API nativa di Dolibarr |
EasyAPI |
| Copertura |
~25 classi con copertura disomogenea; metodi commentati o inesistenti |
32 domini del core completi + sotto-risorse |
| Risposte |
Eterogenee: un POST restituisce un int, un altro l'oggetto |
Envelope uniforme {success, data}, con meta.pagination negli elenchi · POST → 201 + oggetto · DELETE → 204 |
| Errori |
Codici e messaggi disomogenei, senza tassonomia né request_id |
Catalogo completo (422, 409, 410, 412, 413, 415, 428, 429, 503…) con request_id e doc_url |
| Sicurezza |
Diritti nativi, ma con veri bug di ACL e codici sbagliati |
Stessi diritti nativi, ACL per record corretta e uniforme, senza fughe tra entità |
| Idempotenza |
Non esiste |
Idempotency-Key con prenotazione atomica e replay su ogni scrittura |
| Validazione |
400 con «campo mancante» |
422 dichiarativa con error.fields per regola |
| Query |
sqlfilters + limit/page |
Filtri JSON:API, ordinamento, ricerca, sparse fields, include, paginazione offset e cursore |
| Bulk |
Non esistono |
207 Multi-Status in creazione, aggiornamento ed eliminazione (100 per lotto) |
| Resilienza |
Non esiste |
Rate-limit, retry dei deadlock, ETag / If-Match, modalità manutenzione, /health |
| Documentazione |
Explorer Swagger di base |
OpenAPI completo con Scalar, Swagger UI e Redoc integrati |
| Estensibilità |
Bisogna toccare o forkare il core |
Auto-discovery delle risorse dal tuo stesso modulo |
| Agenti IA |
Non previsto |
Server MCP nativo incluso |
Come si usa
Autenticazione con la tua DOLAPIKEY di Dolibarr. Ogni risposta arriva con lo stesso envelope: il tuo client lo scrivi una volta e vale per tutti i 32 domini.
CREARE UNA FATTURA, SENZA DUPLICATI ANCHE SE RIPROVI
curl -X POST https://tuo-dolibarr.com/custom/easyapi/api/invoices \
-H "DOLAPIKEY: tua_chiave" \
-H "Idempotency-Key: ordine-4417" \
-H "Content-Type: application/json" \
-d '{"socid": 128, "lines": [{"fk_product": 55, "qty": 2}]}'
Il percorso base è custom/easyapi/api in un'installazione standard. Se hai il modulo in un'altra cartella di moduli registrata nel tuo conf.php, sostituisci custom con la tua: EasyAPI non ha percorsi fissi, si adatta a dove lo installi.
201 CREATED
{
"success": true,
"data": {
"id": 902,
"ref": "FA2607-0043"
}
}
422 — TI DICE COSA SISTEMARE
{
"success": false,
"error": {
"type": "validation_error",
"code": 422,
"message": "Validation failed",
"fields": {
"socid": "does not exist"
},
"request_id": "req_a1b2",
"doc_url": "…#validation_error"
}
}
Gli elenchi aggiungono un blocco meta.pagination con la modalità (offset o cursore), il totale e la pagina. E ogni risposta, riuscita o in errore, porta l'header X-Request-Id: se qualcosa va storto, quell'identificatore ci permette di tracciare la tua richiesta precisa.
Cosa include
Estendi l'API senza toccare il core
Risorse auto-scoperte con filtri JSON:API, ordinamento, ricerca, sparse fields, include e paginazione per offset o cursore. Estendi l'API dal tuo stesso modulo senza toccare il core.
Scritture sicure ed errori che si spiegano da soli
Idempotenza tramite Idempotency-Key, validazione 422 dichiarativa, errori strutturati con request_id, operazioni massive 207 e ACL per record.
Regge picchi, interruzioni e retry
Rate-limit configurabile, retry automatico dei deadlock, ETag e If-Match per la concorrenza ottimistica, modalità manutenzione ed endpoint /status e /health.
Documentazione che non si disallinea
OpenAPI completo con Scalar, Swagger UI e Redoc integrati, raggruppato per dominio e con esempi automatici. Interfaccia del modulo in 8 lingue.
A cosa serve
- Integrare Dolibarr con e-commerce, app mobili o ERP esterni tramite REST moderna.
- Sincronizzazione massiva di prodotti, terzi e ordini in lotti da 100.
- Automazioni headless con garanzia di esecuzione esattamente una volta.
- Alimentare BI e cruscotti con filtri e paginazione veri.
- Dare a un agente IA un accesso sicuro e tracciato al tuo ERP.
- Costruire la tua API di dominio estendendo le risorse, senza forkare Dolibarr.
Messa in funzione
1
Installa e attiva EasyAPI, poi esegui composer install nella cartella del modulo.
2
Configura resilienza e CORS nella scheda «API»: rate-limit, retry, ETag e modalità manutenzione.
3
Autenticati con la tua DOLAPIKEY e usa i 32 domini con Idempotency-Key e If-Match.
4
Apri /docs per esplorare l'API, e la scheda «MCP / IA» per collegare il tuo agente.
Requisiti
| Dolibarr |
Da V15 a V23 |
| PHP |
Da 7.0 a 8.3 |
| Database |
MySQL 5.7+ · MariaDB 10.2+ · PostgreSQL 10+ |
| Server web |
Apache con mod_rewrite o Nginx |
| Dipendenze |
Composer per installare le librerie del modulo |
Prima di acquistare
Posso adattarlo al mio caso?
Sì. EasyAPI è distribuito con licenza GNU GPL v3: ricevi tutto il codice sorgente e puoi leggerlo, modificarlo e adattarlo alla tua installazione senza chiedere permesso. Inoltre il framework scopre le risorse da solo, quindi la cosa normale è aggiungere i tuoi endpoint dal tuo modulo invece di toccare il nostro.
Come lo provo senza rischiare i miei dati?
Installalo su una copia del tuo Dolibarr e chiama GET /status: risponde senza toccare un solo record. Da lì in poi tutte le letture (i 32 domini con filtri e paginazione) sono innocue. Le scritture invece creano dati reali, quindi provale su quella copia; ciò che Idempotency-Key garantisce è che un retry dopo una caduta di rete non ti duplichi il record, non che l'operazione sia reversibile.
E se qualcosa non va con la mia installazione?
Scrivici a
info@easysoft.es prima di acquistare e lo guardiamo insieme: versione di Dolibarr, PHP, hosting e cosa devi integrare. Preferiamo dirti che non va bene piuttosto che venderti qualcosa che non ti serve.
E se aggiorno? Mi si rompe l'integrazione?
No. EasyAPI è API v1 stabile e ogni risposta lo dichiara nell'header X-EasyAPI-Version. Dentro la v1 entrano solo modifiche retrocompatibili: nuovi campi opzionali, nuovi endpoint, nuovi header. Una modifica che rompe il contratto —rinominare un campo, cambiare un tipo— non finisce nella v1: uscirebbe come v2, e la tua integrazione continuerebbe a puntare alla v1 mentre migri quando ti fa comodo.
Cosa include l'acquisto?
Il modulo completo con il suo codice sorgente e 365 giorni di accesso agli aggiornamenti e ai download da Dolistore, più assistenza via e-mail per installazione, integrazione e collegamento di agenti IA.
Manutenzione attiva
EasyAPI non è un modulo pubblicato e poi dimenticato. La versione attuale è la 2.13 e ogni rilascio passa dalla suite di 4.110 test più QA dal vivo. L'ultimo giro ha trasformato la specifica in un contratto vero e ha eliminato l'N+1 dagli elenchi, senza rompere la compatibilità:
- Contratto OpenAPI pronto per la generazione di codice: elenchi tipizzati con la loro paginazione reale e required, nullable ed enum onesti. Il tuo client genera i suoi tipi invece di scriverli a mano.
- Basta N+1: il terzo del documento arriva nella stessa chiamata su 13 risorse, così come le sue righe e i suoi pagamenti, e ora si può ordinare e filtrare per campi del terzo.
- Nuovi endpoint di dominio: KPI di fatturazione, giacenze valorizzate per magazzino, definizioni di extrafield per moduli dinamici, movimenti di tutti i conti bancari e dizionari dei ticket.
- Server MCP conforme alla specifica 2025-11-25, con trasporto STDIO e ricerca multilingua per agenti IA.
Il dettaglio versione per versione è nel ChangeLog, accessibile dalla scheda di amministrazione del modulo stesso.
|
24
moduli pubblicati su Dolistore
|
GPLv3
codice sorgente completo
|
8
lingue nell'interfaccia
|
365
giorni di aggiornamenti
|
Fa al caso tuo per quello che devi integrare?
Raccontaci il tuo caso e ti diciamo se EasyAPI ti serve — e se non ti serve, te lo diciamo lo stesso. Rispondiamo su installazione, integrazione e collegamento di agenti IA.
info@easysoft.es www.easysoft.es