Specifica OpenAPI
Le definizioni OpenAPI di Amica sono documenti conformi alla specifica OpenAPI che descrivono in modo completo l'API, con tutti i metodi e i modelli disponibili documentati nel dettaglio.
Una specifica OpenAPI è una fonte di documentazione sempre aggiornata ed è utilizzabile da numerosi strumenti disponibili online, ad esempio per l'auto-generazione dei client. La nostra API Reference interattiva è generata direttamente dalla specifica OpenAPI.
Ogni operazione ha un operationId leggibile, composto da risorsa e azione
(NazioneList, NazioneGet, NazionePost, DocumentoImportDdt, …): sono i nomi dei
metodi che trovi negli SDK e in qualunque client generato. I path
sono fissi sulla versione corrente (/api/v3/...), senza un parametro version da
valorizzare.
Provare l'API dalla API Reference
Dalla API Reference puoi autenticarti e chiamare gli endpoint direttamente dal
browser. Nel pannello di autenticazione scegli uno dei flussi OAuth 2.0 e inserisci
client_id e client_secret della tua app:
- Client Credentials: il token si ottiene subito, senza login.
- Authorization Code (con PKCE): accedi con un utente Amica e autorizzi l'app; il ritorno alla pagina della reference è già consentito, non serve registrarlo come redirect URI dell'app.
In alternativa puoi incollare un access token già ottenuto nello schema Bearer. Le chiamate operano sui dati reali dell'azienda: per le prove conviene un'app privata e un'azienda di test.
Dove trovarla
- API Reference interattiva (Scalar): https://customerws1.amica20.it/api/v3/docs
- Specifica in formato JSON: https://customerws1.amica20.it/api/v3/swagger.json
- Repository versionato: la specifica curata e taggata a ogni rilascio è pubblicata su github.com/amica-dev/openapi.
Sei libero di usarla come preferisci. Se realizzi qualcosa e vuoi condividerlo con altri sviluppatori (o promuoverlo presso gli utenti Amica), faccelo sapere.
Generare un client
A partire dalla specifica puoi generare un client nel linguaggio che preferisci con OpenAPI Generator:
openapi-generator-cli generate \
-i https://customerws1.amica20.it/api/v3/swagger.json \
-g <linguaggio> \
-o ./amica-client