EasyAPI - API REST professionale per Dolibarr (32 domini del core) + MCP

La API REST che Dolibarr dovrebbe avere di serie

EasyAPI reimplementa i 32 domini del core di Dolibarr (vendite, acquisti, magazzino, contabilità, progetti, risorse umane, associazioni…) su un contratto unico: lo stesso envelope di risposta, la stessa tassonomia di errori, idempotenza su ogni scrittura e un server MCP per agenti IA. I tuoi permessi e la tua ACL di Dolibarr continuano a comandare.

Lo stesso envelope, gli stessi codici e gli stessi filtri nei 32 domini. Si impara una volta e vale per tutti: non c'è un modo diverso di paginare, filtrare o leggere l'errore a seconda della risorsa che tocchi.

Quello che chiede l’agente di IA aspetta la tua conferma

Con la conferma umana attiva, una scrittura chiesta da un agente tramite MCP non viene eseguita. Resta in Strumenti › Azioni in sospeso (IA) con i suoi dati e un’anteprima, e avviene solo quando la persona che ha collegato l’agente preme Conferma.

• Decidi tu cosa aspetta. Tutte le scritture, oppure solo l’invio di e-mail e le eliminazioni. L’opzione è spenta, quindi l’aggiornamento non cambia nulla.
• L’agente non può confermarsi da solo. La conferma non esiste per il MCP: si fa in Dolibarr o tramite l’API REST (POST /mcp/pending/{token}/confirm), e solo chi ha chiesto l’azione può darla.
• Una volta sola e con scadenza. Ogni azione si conferma una volta e scade dopo 10 minuti; il termine arriva fino a 24 ore.
• E-mail marcate. Un’e-mail inviata dopo la conferma porta X-AI-Generated e X-AI-Reviewed.

Chi ti deve quanto e da quando, e il prezzo che l'ERP applicherebbe a ogni cliente

La versione 2.25 ha portato indicatori di business che prima si ricostruivano sommando le fatture a mano. E l'MCP dice all'agente cosa fa ogni operazione prima che la chiami.

• Anzianità del credito. GET /invoices/kpis/aging e GET /supplier-invoices/kpis/aging dividono il residuo in non scaduto, 1-30, 31-60, 61-90 e oltre 90 giorni. Le fasce si cambiano con ?buckets=0,15,45 e ?group=thirdparty dà il dettaglio per soggetto terzo. Seguono la stessa ACL degli elenchi: il commerciale che vede solo i suoi clienti vede solo il debito di quei clienti.
• Tempi medi e residuo reale. /invoices/kpis aggiunge dso e /supplier-invoices/kpis aggiunge dpo, i giorni medi di incasso e di pagamento degli ultimi 90 giorni. I KPI outstanding e overdue sommano quello che resta davvero da pagare: sottraggono pagamenti parziali, note di credito e acconti con lo stesso calcolo di getRemainToPay() del core.
• Prezzo effettivo per cliente. GET /products/{id}/price?socid=&qty= restituisce il prezzo che l'ERP metterebbe nella riga per quel cliente e quella quantità, con IVA, sovrattassa e ritenuta d'acconto, i totali e da dove arriva il prezzo: base, price_level, customer_price o quantity.
• Errori senza SQL. Il messaggio del motore di database resta nel syslog con il request_id, e la risposta porta un codice su cui si può agire: un duplicato è un 409 con reason: duplicate_record, e un blocco un 503 con Retry-After: 2 per riprovare.
• Ogni operazione dichiara il suo effetto. x-effect dice se legge (read), scrive nell'ERP (internal), esce verso l'esterno (external) o non si può annullare (irreversible), e l'MCP lo traduce in readOnlyHint e destructiveHint. Le cancellazioni via MCP si possono vietare nel setup (EASYAPI_MCP_ALLOW_DELETE) o utente per utente, e vale l'impostazione più restrittiva.
• IBAN mascherato. Via MCP, l'IBAN, il numero di conto e il riferimento del mandato dei conti bancari dei terzi mostrano solo gli ultimi 4 caratteri. Via REST non cambia nulla.

curl -X POST "https://tu-dolibarr.com/custom/easyapi/api/invoices" \
  -H "DOLAPIKEY: tu_clave" \
  -H "Idempotency-Key: pedido-4417" \
  -H "Content-Type: application/json" \
  -d '{"socid": 128, "lines": [{"fk_product": 55, "qty": 2, "subprice": 49.90}]}'

{
  "success": true,
  "data": {
    "id": 902,
    "ref": "(PROV902)",
    "socid": 128,
    "statut": 0,
    "total_ttc": 119.76,
    "lines": [ { "id": 3311, "qty": 2, "subprice": 49.90 } ]
  }
}

{
  "success": false,
  "error": {
    "type": "validation_error",
    "code": 422,
    "message": "Validation failed",
    "fields": { "socid": "does not exist" },
    "request_id": "req_7f3a91c2",
    "doc_url": "https://easysoft.es/docs/api#validation_error"
  }
}

EasyAPI non è un modulo pubblicato e dimenticato: la versione attuale è la 2.28.0 e ogni rilascio aggiunge test che tengono fermo quello che corregge. La 2.28 porta un test per ogni regola della conferma umana, verificato rompendo apposta la regola, un test nel browser della pagina delle azioni in sospeso e una verifica HTTP su Dolibarr 15, 18 e 24. Oltre ai test, ogni release passa il QA contro istanze reali di Dolibarr prima di essere pubblicata.

Fa al caso tuo per quello che devi integrare?

Raccontaci il tuo caso e ti diciamo se EasyAPI fa al caso tuo — e se non lo fa, te lo diciamo lo stesso.