Vai al contenuto

Funzionalità

Questa pagina elenca le principali funzionalità dell'Amica Cloud API.

Accesso completo ai dati Amica 20

L'API espone gran parte delle funzionalità dell'applicazione web Amica 20, operando direttamente sui dati aziendali del cliente: anagrafiche (contatti, indirizzi, nazioni, valute, modalità di pagamento), magazzino (articoli, listini, giacenze, movimenti, distinte base), scadenze e documenti (fatture e fatturazione elettronica, note di credito, DDT, ordini, preventivi, proforma ed emissione). Ogni risorsa supporta il ciclo completo di lettura, creazione, aggiornamento ed eliminazione.

Supporto multi-azienda

Un'unica credenziale può operare su una o più aziende. La maggior parte degli endpoint è relativa a una specifica azienda e segue il pattern /api/v3/{companyId}/risorsa. L'elenco delle aziende disponibili per le credenziali in uso si ottiene da GET /api/v3/config/Azienda.

Per saperne di più consulta la guida Company ID e multi-azienda.

OAuth 2.0 con scope granulari

L'accesso all'API è protetto da OAuth 2.0, con due flussi disponibili: Authorization Code con PKCE (consigliato, per app che operano per conto di un utente) e Client Credentials (per integrazioni server-to-server, solo app private). Ogni token porta uno o più scope (comune, magazzino, contabilita, documenti, oltre a read/write) che limitano le aree accessibili secondo il principio del privilegio minimo.

Per saperne di più consulta la guida Autenticazione.

Filtri e ordinamento avanzati

Gli endpoint che restituiscono liste accettano un parametro Filter con una sintassi ricca — operatori come $eq, $ne, $gt, $ct (contiene), $sw (inizia con), connettori $and/$or e sotto-query — e un parametro Order per ordinare su più campi (con - per l'ordine discendente). Così la tua integrazione recupera esattamente i dati che le servono, senza filtrare lato client.

Per saperne di più consulta la guida Ordinamento e filtri.

Espansione degli oggetti correlati

Con il parametro Expand puoi richiedere che gli oggetti correlati vengano inclusi inline nella risposta anziché restituiti come semplici riferimenti, riducendo il numero di chiamate necessarie a ricostruire un'entità completa.

Per saperne di più consulta la guida Espansione oggetti correlati.

Paginazione

Le liste si paginano con i parametri Skip e Take. Ogni risposta riporta gli header X-Read-TotalCount (totale degli elementi che soddisfano il filtro) e X-Read-Count (elementi effettivamente restituiti), così puoi navigare grandi insiemi di dati in modo efficiente.

Per saperne di più consulta la guida Paginazione.

Controllo della concorrenza

Ogni entità espone un ConcurrencyToken. In aggiornamento (PUT) il token inviato viene confrontato con quello memorizzato: se non coincidono la richiesta riceve un 422 Unprocessable Entity, evitando di sovrascrivere modifiche fatte nel frattempo da altri. È il classico controllo di concorrenza ottimistico, senza lock.

Per saperne di più consulta la guida Controllo della concorrenza.

Gestione degli errori standard

L'API usa i codici di stato HTTP standard e restituisce gli errori nel formato RFC 7807 Problem Details, facilmente interpretabile da qualsiasi client. Alcune validazioni sono inoltre forzabili tramite il parametro validationOverride, quando il contesto lo consente.

Per saperne di più consulta la guida Gestione errori.

Rate limiting trasparente

Gli endpoint sono soggetti a rate limiting, comunicato su ogni risposta tramite gli header standard RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset e RateLimit-Policy. La tua integrazione può adattarsi dinamicamente senza basarsi su valori fissi.

Per saperne di più consulta la guida Rate limiting.

SDK ufficiali

Mettiamo a disposizione SDK open-source per C#, Python, TypeScript e PHP, generati automaticamente dalla specifica OpenAPI e aggiornati a ogni rilascio, così restano sempre allineati all'API. Gli SDK gestiscono serializzazione e chiamate HTTP: a tuo carico resta solo l'autenticazione. Con una manciata di righe sei operativo.

Per saperne di più consulta la sezione SDK e i Quickstart.

Specifica OpenAPI conforme

L'API è descritta da una specifica OpenAPI completamente conforme, da cui puoi generare client tipizzati nel linguaggio che preferisci e che alimenta numerosi strumenti dell'ecosistema.

API Reference interattiva

La API Reference interattiva è generata dalla specifica OpenAPI: documenta ogni endpoint e modello e consente di provare le chiamate direttamente dal browser, incollando un access token valido.