Introduzione
Benvenuto nella documentazione di Adamo API! Puoi usare le API di Adamo per accedere ai diversi endpoints, dove potrai creare, modificare e ottenere informazioni sui diversi oggetti memorizzati dentro Adamo.
Le risorse in questa guida ti permetteranno di sviluppare velocemente la tua applicazione.
Le API di Adamo sono organizzate intorno a REST. Le API sono disegnate per essere intuitive, con URL orientati alle risorse e con i codici HTTP utilizzati per indicare eventuali errori.
Tutte le richieste devono essere passate per HTTPS.
Le richieste e le risposte utilizzano JSON per formattare le risorse, inclusi gli errori.
Per qualsiasi dubbio puoi scrivere a [email protected].
Registra la tua app
Registrati su Adamo come un normale utente. Nelle impostazioni vai su Organizzazione e scegli la scheda Sviluppatori.
Qui potrai registrare diverse applicazioni, ognuna con un proprio name, description e redirect_uri. Una volta registrata, ti verranno fornite le credenziali client_id, client_secret della tua app.
Qualora tu voglia creare un'app che interagisce unicamente con i tuoi dati su Adamo, o tu voglia velocemente ottenere delle credenziali di test, puoi richiedere, sempre nell'area Sviluppatori un access token personale, senza dover creare una nuova app.
Autenticazione
Adamo permette l'autenticazione delle API in due diversi modi:
- Protocollo OAuth 2.0 per connettersi agli accounti di altri utenti, compiendo delle richieste per conto di questi utenti;
- Utilizzo diretto di un access token personale per utilizzare Adamo con il proprio account, compiendo dunque richieste per conto proprio.
Si consiglia di utilizzare il secondo metodo nel caso si voglia creare una web app o un plugin personale, che quindi interagisca unicamente con i propri dati e informazioni memorizzati sulla piattaforma.
Il primo metodo, più complesso, è invece opportuno quando si vuole pubblicare un plugin o un'applicazione pubblica, dove gli utenti potranno connettersi con il proprio account di Adamo, e il plugin o l'applicazione interagirà con i dati di questi ultimi.
Access Token Personale
Richiedi un Access Token
All'interno delle tue impostazioni di Adamo, potrai richiedere un access token personale che potrai utilizzare per tutte le chiamate API che vorrai fare.
Piuttosto semplice.
OAuth 2.0
Le API di Adamo supportano il protocollo OAuth 2.0 per autorizzare applicazioni di terze parte a connettersi all'account di un utente senza utilizzare username e password.
Come sviluppatore devi registrare la tua applicazione su Adamo prima di usare il flusso OAuth 2.0.
Seguendo i passi qui sotto puoi ottenere un access_token per la tua web app usando OAuth 2.0. Un access token permette alla tua app di compiere delle richieste per l'utente.
Si consiglia di visionare il protocollo OAuth 2.0 per altre informazioni.
Ottieni un Authorization Code
Dalla tua web app, reindirizza l'utente di cui vorresti l'accesso al link:
GET https://app.adamogestionale.it/oauth/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}
| Parameter | Description |
|---|---|
| client_id | il client ID ricevuto quando hai registrato la tua app su Adamo. |
| response_type | Il tipo di risposta. Per un flusso web, utilizzare code. |
| redirect_uri | La URL url-encoded a cui sarà reindirizzato l'utente dopo aver accettato di fornire alla tua app l'autorizzazione a procedere. |
Response
L'utente vedrà una schermata di autorizzazione in cui gli si chiederà conferma di voler accettare che la tua applicazione acceda ai suoi dati.
Accettando, darà alla tua app l'autorizzazione a accedere agli endpoint per conto suo.
Adamo reindrizza l'utente al tuo sito
Se l'utente accetta la richiesta, viene reindirizzato al tuo sito con un codice code nella querystring.
https://{redirect_uri}/?code={auth_code}
Questo codice ha una validità di 30 secondi, dopodiché non potrà più essere utilizzato.
Se l'utente rifiuta di concedere l'autorizzazione, l'utente verrà reindirizzato al tuo sito con un codice d'errore.
https://{redirect_uri}/?error=access_denied&error_description=The+user+denied+access+to+your+application
Scambia l'Auth code con un Access Token
Dopo aver ricevuto il code dovrai scambiarlo con il server per ottenere un access_token.
Fai una richiesta all'indirizzo:
GET https://app.adamogestionale.it/oauth/token?grant_type=authorization_code&code={auth_code}&client_id={client_id}&client_secret={client_secret}
| Parameter | Description |
|---|---|
| client_id | il client ID ricevuto quando hai registrato la tua app su Adamo. |
| auth_code | L'auth code ricevuto. |
| client_secret | il client_secret ricevuto quando hai registrato la tua app su Adamo. |
Restituisce
Risposta:
{
"access_token": "{access_token}",
"expires_in": 31104000,
"token_type": "bearer",
"refresh_token": "{refresh_token}"
}
La risposta include una stringa JSON che contiene l'access_token
{"access_token": "{access_token}"}
Devi salvare l'access_token fornito per qualsiasi compiere qualsiasi richiesta per l'utente.
Il parametro expire_in, restituito con la richiesta indica per quanto tempo (in secondi) sarà valido quel token. Il token ha una durata di un anno.
Utilizza l'Access Token
Il Token deve essere incluso in ogni richiesta API. Questo può essere fatto in query string:
curl https://app.adamogestionale.it/api/invoices?access_token={access_token}
Oppure come HTTP Header:
curl -H "Authorization: Bearer {access_token}"
Api
Endpoint
Quando si ha un access_token si può interagire con le API di Adamo per conto dell'utente che ha concesso l'autorizzazione e a cui è associato quel access_token.
Gli endpoint, cioè gli indirizzi, a cui puoi collegarti sono elencati in questo documento. Tutte le richieste devono venire fatte via JSON attraverso HTTPS.
Schema
Richiesta di Esempio:
POST /api/invoices/?expand=Income,IncomeDue&access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/invoices/?expand=Income,IncomeDue
-X POST
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Risposta di esempio:
{
"id": {
"type": "integer",
"null": false,
"default": null,
"length": 10,
"key": "primary"
},
"name": {
"type": "string",
"null": true,
"default": null,
"length": 100,
"collate": "latin1_swedish_ci",
"charset": "latin1"
},
{...}
}
Con il termine Oggetti intendiamo un gruppo di informazioni. Ad esempio una fattura o un contatto sono considerati oggetti.
Tutti gli oggetto su Adamo hanno una propria struttura, chiamata schema.
Per conoscere lo schema di un determinato oggetto è possibile fare una richiesta
GET https://app.adamogestionale.it/api/{object}/schema
In questo modo verrà restituito un oggetto che elenca tutti gli attributi e il loro tipo.
ID Autogenerati
Ogni oggetto su Adamo possiede un id, cioè un identificativo univoco appartente all'oggetto, e viene autogenerato dal sistema in fase di creazione dell'oggetto.
Qualora, in fase di creazione o modifica di un oggetto, si tenti di passare un proprio id, cioè sovrascrivere quello esistente, questo verrà ignorato.
L'unico modo per recuperare l'id di un oggetto dopo la sua creazione, è analizzare la risposta che viene fornita dal sistema.
Rate Limit
Errore di esempio:
{
"name": "rate limit exceeded",
"url": "\/api\/invoices?access_token={token}"
}
Esiste un limite di utilizzo delle API di Adamo. Questo limite è applicato a tutte le chiamate fatte in una finestra di 15 minuti, indipendentemente dall'endpoint richiesto.
Il limite è sugli Access Token. Questo significa che non puoi fare più di un certo numero di chiamate per ogni access token (quindi per ogni utente) di cui sei dotato.
| Type | Rate Limit |
|---|---|
| Access Token | 1.000 Richieste / 15 Minuti |
Ad ogni chiamata vengono calcolate le richieste fatte con lo stesso access_token negli ultimi 15 minuti. Se il limite è stato superato ti verrà restituito un Errore, con status code pari a 403.
Contatti
I contatti sono gli elementi di una rubrica e comprendono persone e aziende di cui si vuole tenere traccia.
I contatti sono chiamati Contact e sono identificati da un unico id.
Ogni oggetto Contact è associato a diversi oggetti. Ogni contatto può avere da zero a molti di questi oggetti.
| Oggetto | Ritorna | Description |
|---|---|---|
| Address | Array di Address | Gli indirizzi del Contatto. |
| Array di Mail | Gli indirizzi email associati a questo contatto. | |
| Phone | Array di Phone | I numeri di telefono. |
| Field | Array di Field | Campi personalizzati. |
Oggetto Contatto
{
"id": "714",
"name": "Mario",
"last_name": "Rossi",
"prefix": "Signor",
"suffix": "Jr.",
"middle": null,
"nickname": "marietto",
"job": "Dirigente",
"company": "Adamo Lab",
"is_natural_person": true,
"fiscal_code": "RSSMR45X19S",
"vat_number": null,
"avatar_id": null,
"notes": "",
"birthday": null,
"modified": "2015-06-01 14:54:55",
"created": "2015-05-16 08:45:12",
"facebook": null,
"twitter": null,
"google": "",
"linkedin": null,
"is_customer": false,
"is_supplier": false
}
L'oggetto Contatto possiede diverse attributi al suo interno.
Tutti gli attributi sono opzionali.
Attributi
| Attributo | Tipo | Descrizione |
|---|---|---|
| id | Integer (read-only) | L'identificativo del contatto |
| created | Datetime (read-only) | Quando l'oggetto è stato creato |
| updated | Datetime (read-only) | Quando l'oggetto è stato modificato |
| name | String | Nome |
| last_name | String | Cognome |
| prefix | String | Prefisso del nome |
| middle | String | Secondo nome |
| suffix | String | Suffisso del nome |
| nickname | String | soprannome |
| job | String | Ruolo lavorativo |
| company | String | Nome dell'azienda per cui lavora |
| is_natural_person | Boolean. Default: false | True se questo contatto è una persona, False se è un'azienda |
| fiscal_code | String | Codice Fiscale |
| vat_number | String | Partita IVA |
| avatar_id | Integer | id del Upload avatar |
| birthday | Date | Data di nascita |
| is_customer | Boolean. Default: false | E' un cliente? |
| is_supplier | Boolean. Default: false | E' un fornitore? |
Associazioni
Address
{
"id": "193",
"contact_id": "714",
"street": "Via di Prova",
"city": "Roma",
"province": "RO",
"zip": "10100",
"country": "Italy",
"title": "Residenza"
}
Rappresenta gli indirizzi del contatto.
| Attributo | Tipo | Descrizione |
|---|---|---|
| id | Integer (read-only) | L'identificativo |
| street | String | Via |
| city | String | Città |
| province | String | Provincia |
| zip | String | Codice Avviamento Postale |
| country | String | Stato |
| title | String | Definizione dell'indirizzo |
Phone
{
"id": "187",
"contact_id": "714",
"label": "Telefono di Casa",
"value": "011 101010"
}
Rappresenta i numeri di telefono del contatto.
| Attributo | Tipo | Descrizione |
|---|---|---|
| id | Integer (read-only) | L'identificativo |
| label | String | Descrizione |
| value | String | Numero di telefono |
{
"id": "180",
"contact_id": "715",
"label": "Ufficio",
"value": "[email protected]"
}
Rappresenta gli indirizzi email del contatto
| Attributo | Tipo | Descrizione |
|---|---|---|
| id | Integer (read-only) | L'identificativo |
| label | String | Descrizione |
| value | String | Indirizzo email |
Field
{
"id": "1",
"contact_id": "714",
"label": "Nome del Fratello",
"value": "Luigi"
}
Rappresenta i campi personalizzati del contatto
| Attributo | Tipo | Descrizione |
|---|---|---|
| id | Integer (read-only) | L'identificativo |
| label | String | Descrizione |
| value | String | Valore del campo |
Crea un nuovo Contatto
Richiesta di esempio:
POST /api/contacts?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/contacts
-X POST
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
-d "{request_body}"
Body della richiesta nel POST:
{
"Contact": {
"name" : "Luigi",
"last_name" : "Bianchi"
},
"Mail" : [{
"label" : "casa",
"value" : "[email protected]"
}]
}
Body della risposta di esempio:
{
"Contact": {
"id": "717",
"name": "Luigi",
"last_name": "Bianchi",
"prefix": null,
"suffix": null,
"middle": null,
"nickname": null,
"job": null,
"company": null,
"is_natural_person": true,
"fiscal_code": null,
"vat_number": null,
"avatar_id": null,
"removed": false,
"notes": "",
"birthday": null,
"modified": "2015-06-03 10:52:52",
"created": "2015-06-03 10:52:52",
"facebook": null,
"twitter": null,
"google": "",
"linkedin": null,
"is_customer": false,
"is_supplier": false
},
"Address": [
],
"Mail": [
{
"id": "188",
"contact_id": "717",
"label": "casa",
"value": "[email protected]"
}
],
"Field": [
],
"Phone": [
]
}
Crea un nuovo oggetto contatto.
HTTP Request
POST /api/contacts/
Corpo della richiesta
E' necessario inviare un oggetto comprendente un oggetto Contact. E' possibile inviare insieme all'oggetto Contact anche array di oggetti associati perchè vengano salvati insieme.
Non è necessario inviare tutti i campi di Contact, ma solamente quelli di interesse. Tutti gli altri prenderanno il valore di default.
Restituisce
In caso di successo viene restituito un oggetto che contiene l'oggetto Contact appena salvato e tutti i suoi oggetti associati.
In caso di errore viene invece restituito un Errore.
Ottieni un solo Contatto
Richiesta di esempio:
GET /api/contacts/{id}?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/contacts/{id}
-X GET
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Body della Risposta di esempio:
{
"Contact": {
"id": "717",
"domain_id": "254",
"name": "Luigi",
"last_name": "Bianchi",
"prefix": null,
"suffix": null,
"middle": null,
"nickname": null,
"job": null,
"company": null,
"is_natural_person": true,
"fiscal_code": null,
"vat_number": null,
"avatar_id": null,
"removed": false,
"notes": "",
"birthday": null,
"modified": "2015-06-03 10:52:52",
"created": "2015-06-03 10:52:52",
"facebook": null,
"twitter": null,
"google": "",
"linkedin": null,
"portal_username": null,
"portal_password": null,
"portal_active": null,
"is_customer": false,
"is_supplier": false,
"stripe_id": null
},
"Address": [
],
"Mail": [
{
"id": "188",
"contact_id": "717",
"label": "casa",
"value": "[email protected]",
"pref": false,
"order_preference": null,
"removed": null
}
],
"Field": [
],
"Phone": [
]
}
Ottieni i dettagli di un singolo contatto. E' necessario solo fornire l'id del Contatto fornito dopo che è stato creato.
HTTP Request
GET /api/contacts/{id}
Argomenti
| Argomento | Tipo | Descrizione | |
|---|---|---|---|
| id | Integer | Obbligatorio | ID del contatto da passare come parametro. |
Restituisce
In caso di successo viene restituito un oggetto che contiene l'oggetto Contact corrispondente all'id fornito e tutti i suoi oggetti associati.
In caso di errore viene invece restituito un Errore.
Modifica Contatto
Richiesta di Esempio:
PUT /api/contacts/{id}?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/contacts/{id}
-X PUT
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Body della Richiesta:
{
"Contact": {
"fiscal_code" : "BNCLGG123X10A"
},
"Mail" : [{
"label" : "ufficio",
"value" : "[email protected]"
}]
}
Body della Risposta:
{
"Contact": {
"id": "717",
"domain_id": "254",
"name": "Luigi",
"last_name": "Bianchi",
"prefix": null,
"suffix": null,
"middle": null,
"nickname": null,
"job": null,
"company": null,
"is_natural_person": true,
"fiscal_code": "BNCLGG123X10A",
"vat_number": null,
"avatar_id": null,
"notes": "",
"birthday": null,
"modified": "2015-06-03 13:55:25",
"created": "2015-06-03 10:52:52",
"facebook": null,
"twitter": null,
"google": "",
"linkedin": null,
"is_customer": false,
"is_supplier": false
},
"Address": [
],
"Mail": [
{
"id": "189",
"contact_id": "717",
"label": "ufficio",
"value": "[email protected]"
}
],
"Field": [
],
"Phone": [
]
}
Dopo che un contatto è stato creato, è possibile modificarlo indicando il suo id.
HTTP Request
PUT /api/contacts/{id}
Tutti i dati passati nel corpo della richiesta verranno elaborati per modificare l'oggetto Contact e le sue associazioni.
Cosa inviare
Tutti i campi dell'oggetto Contact che vengono inviati nel corpo della richiesta sovrascriveranno quelli già memorizzati per il contatto. Per i campi non inviati verranno invece conservati i valori già memorizzati. Non è quindi necessario inviare tutti i campi dell'Contact ma solamente quelli che si intende memorizzare.
Per modificare una degli oggetti associati Address, Mail, Phone o Field è necessario inviare un array di questi oggetti. Si noti che inviando un array di nuovi oggetti, tutti gli oggetti associati precedentemente memorizzati verranno eliminati.
Ad esempio, se un Contatto possiede due numeri di telefono, inviando un nuovo array di Phone questi due vecchi verranno eliminati e verranno memorizzati quelli nuovi appena inviati.
Se si vuole mantenere i vecchi oggetti associati è necessario inviare nell'array gli id dei vecchi oggetti che si vuole conservare. Per aggiungere un numero di telefono ad un contatto, ad esempio, si può inviare al server gli id dei due numeri preesitenti più quello nuovo.
Esempio. Richiesta di aggiunta di un nuovo numero di telefono a un Contatto con già due numeri di telefono:
PUT /api/contacts/{id}?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/contacts/{id}
-X PUT
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
{
"Contact": {...},
"Phone": [
{
"id": 188
},
{
"id": 189
},
{
"contact_id": "717",
"label": "ufficio",
"value": "[email protected]"
}
]
}
Elimina Contatto
Richiesta di esempio:
DELETE /api/contacts/{id}?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/contacts/{id}
-X DELETE
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Risposta:
{
"code": "200",
"message": "Contatto Eliminato Correttamente"
}
Elimina definitivamente un singolo Contatto. Non si può annullare questa azione.
Eliminando il contatto verranno anche eliminati gli oggetti associati Address, Mail, Phone, Field.
HTTP Request
DELETE /api/contacts/{id}
Restituisce
Restituisce un oggetto indicante un code 200 in caso di successo.
In caso di errore, come ad esempio per un id inesistente, viene restituito un Errore.
Ottieni tutti i Contatti
Richiesta di esempio:
GET /api/contacts?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/contacts
-X GET
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Risposta di esempio:
[
{
"Contact": {
"id": "714",
"name": "Mario",
"last_name": "Rossi",
"prefix": null,
"suffix": null,
"middle": null,
"nickname": null,
"job": null,
"company": null,
"is_natural_person": true,
"fiscal_code": "RSSMR...",
"vat_number": null,
"avatar_id": null,
"notes": "",
"birthday": null,
"modified": "2015-06-01 14:54:55",
"created": "2015-05-16 08:45:12",
"facebook": null,
"twitter": null,
"google": "",
"linkedin": null,
"is_customer": false,
"is_supplier": false
},
"Address": [
{
"id": "193",
"contact_id": "714",
"street": "Via di Prova",
"city": "Roma",
"province": null,
"zip": null,
"country": null,
"title": "Residenza"
}
],
"Mail": [
{
"id": "187",
"contact_id": "714",
"label": "casa",
"value": "0111"
}
],
"Field": [
],
"Phone": [
]
},
{...}
]
E' possibile ottenere tutti i contatti memorizzati.
I contatti sono elecanti per data di creazione, con il più recente per primo.
È possibile, in maniera opzionale, chiedere una paginazione dei risultati, utile quando sono memorizzati molti contatti.
Esempio di richiesta con paginazione:
GET /api/contacts?access_token={access_token}&with_pagination=1&page=2 HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/contacts?with_pagination=1&page=2
-X GET
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Risposta di esempio con paginazione:
{
"contacts": [
{
"Contact": {
"id": "714",
"name": "Mario",
"last_name": "Rossi",
"prefix": null,
"suffix": null,
"middle": null,
"nickname": null,
"job": null,
"company": null,
"is_natural_person": true,
"fiscal_code": "RSSMR...",
"vat_number": null,
"avatar_id": null,
"notes": "",
"birthday": null,
"modified": "2015-06-01 14:54:55",
"created": "2015-05-16 08:45:12",
"facebook": null,
"twitter": null,
"google": "",
"linkedin": null,
"is_customer": false,
"is_supplier": false
},
"Address": [
{
"id": "193",
"contact_id": "714",
"street": "Via di Prova",
"city": "Roma",
"province": null,
"zip": null,
"country": null,
"title": "Residenza"
}
],
"Mail": [
{
"id": "187",
"contact_id": "714",
"label": "casa",
"value": "0111"
}
],
"Field": [
],
"Phone": [
]
},
{...}
],
"meta": {
"current_page": 1,
"from": 1,
"last_page": 14,
"per_page": 20,
"to": 20,
"total": 270
}
}
HTTP Request
GET /api/contacts
Argomenti
| Argomento | Tipo | Descrizione | |
|---|---|---|---|
| with_pagination | boolean | Opzionale | Se si vuole la paginazione degli elementi, è possibile passare questo parametro. Esempio: ?with_pagination=1. |
| page | Integer | Opzionale | Se la paginazione è abilitata, si può passare la pagina che si vuole visualizzare. Default: 1. Esempio: ?page=3. |
Restituisce
In caso di successo viene restituito un array di oggetti.
Ogni oggetto contiene al suo interno un Contact e le sue associazioni.
In caso non ci sia nessun Contatto memorizzato da mostrare viene restituito un array vuoto.
Prodotti e servizi
I prodotto o servizi sono gli elementi del catalogo. Il catalogo comprende dunque quelli che sono i prodotti e i servizi di cui si vuole tenere traccia.
Tenere traccia dei propri prodotti è utile per gestire un magazzino e per poter elaborare dei report sul venduto e sull'acquistato.
I prodotti sono chiamati Product e sono identificati da un unico id.
Ogni oggetto Product è associato a diversi oggetti.
| Oggetto | Ritorna | Description |
|---|---|---|
| Prezzo di Vendita | Oggetto ProductPrice | Il prezzo di vendita. |
| Prezzo di acquisto | Oggetto ProductSupplier | Dettagli di acquisto: prezzo e fornitore. |
| Available | Oggetto Available | Situazione del magazzino |
| Upload | Array di Upload | File allegati per questo prodotto |
Oggetto Prodotto
{
"id": 1168,
"name": "Bottiglie",
"description": null,
"internal_code": null,
"measure_unit": "pz",
"length": "20 cm",
"height": "30 cm",
"depth": "20 cm",
"barcode": null,
"created": "2015-05-21 16:30:14",
"updated": "2015-05-29 08:16:16",
"weight": "3 kg"
}
L'oggetto Prodotto possiede diverse attributi al suo interno.
Tutti gli attributi sono opzionali.
Attributi
| Attributo | Tipo | Descrizione |
|---|---|---|
| id | Integer (read-only) | L'identificativo del prodotto |
| created | Datetime (read-only) | Quando l'oggetto è stato creato |
| updated | Datetime (read-only) | Quando l'oggetto è stato modificato |
| name | String | Nome del prodotto |
| description | String | Descrizione estesa del prodotto |
| internal_code | String | Codice assegnato a questo prodotto |
| measure_unit | String | Unità di misura |
| length | String | Lunghezza |
| height | String | Altezza |
| depth | String | Profondità |
| weight | String | Peso |
| barcode | String | Codice a barre assegnato |
Associazioni
Prezzo di vendita
{
"id": 1,
"product_id": 2,
"price": 200,
"vat": 0.22,
"tax_id": 15,
"discount": "0.10"
}
Rappresenta i dettagli di vendita del prodotto.
| Attributo | Tipo | Descrizione |
|---|---|---|
| id | Integer (read-only) | L'identificativo |
| price | Float | Prezzo IVA Esclusa |
| vat | Float | Aliquota IVA in percentuale (es: 0.22) |
| tax_id | Integer | id dell'oggetto Tax |
| discount | String | Sconti |
Dettagli di Acquisto
{
"id": 1,
"supplier_id": 16,
"product_id": 2,
"cost": 100,
"discount": "0.1",
"vat": 0.22,
"tax_id": 15,
"code": "Cod_Pr_For",
"created": null,
"updated": null,
}
Rappresenta i dettagli di acquisto per questo prodotto.
| Attributo | Tipo | Descrizione |
|---|---|---|
| id | Integer (read-only) | L'identificativo |
| supplier_id | Integer (read-only) | Id del Fornitore tra i Contatti |
| cost | Float | Costo IVA Esclusa |
| discount | String | Sconti applicati dal fornitore |
| vat | Float | percentuale IVA |
| tax_id | Integer | id dell'oggetto Tax |
| code | String | Codice interno |
Disponibilità
{
"available_quantity": 5,
"updated": "2015-05-29 08:16:16"
}
Rappresenta la quantità disponibile a magazzino per questo prodotto.
| Attributo | Tipo | Descrizione |
|---|---|---|
| available_quantity | Float | Quantità disponibile in magazzino |
Crea un nuovo Prodotto
Richiesta di esempio:
POST /api/products?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/products
-X POST
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
-d "{request_body}"
Body della richiesta nel POST:
{
"Product" : {
"name" : "Creazione sito web"
},
"ProductPrice":
{
"price" : 500,
"vat" : 0.22
}
}
Body della risposta di esempio:
{
"Product": {
"id": 1171,
"name": "Creazione sito web",
"description": null,
"internal_code": null,
"measure_unit": null,
"length": null,
"height": null,
"depth": null,
"barcode": null,
"domain_id": 254,
"created": "2015-06-06 14:08:45",
"updated": "2015-06-06 14:09:19",
"weight": null
},
"ProductPrice": {
"id": 164,
"product_id": 1171,
"price": 500,
"vat": 0.22,
"tax_id": null,
"discount": "0",
"currency": "EUR"
},
"ProductSupplier": {
"id": null,
"supplier_id": null,
"product_id": null,
"cost": 0,
"discount": null,
"vat": 0,
"tax_id": null,
"main": null,
"code": null,
"created": null,
"updated": null,
"currency": null
},
"Available": {
"available_quantity": 0,
"updated": null
}
}
Crea un nuovo oggetto Prodotto.
HTTP Request
POST /api/products/
Corpo della richiesta
E' necessario inviare un oggetto comprendente un oggetto Product. E' possibile inviare insieme all'oggetto Product anche gli oggetti associati che si vuole vengano salvati.
Non è necessario inviare tutti i campi di Product, ma solamente quelli di interesse. Tutti gli altri prenderanno il valore di default.
Restituisce
In caso di successo viene restituito un oggetto che contiene l'oggetto Product appena salvato e tutti i suoi oggetti associati.
In caso di errore viene invece restituito un Errore.
Ottieni un solo Prodotto
Richiesta di esempio:
GET /api/products/{id}?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/products/{id}
-X GET
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Body della Risposta di esempio:
{
"Product": {
"id": 1171,
"name": "Creazione sito web",
"description": null,
"internal_code": null,
"removed": false,
"measure_unit": null,
"length": null,
"height": null,
"depth": null,
"barcode": null,
"created": "2015-06-06 14:08:45",
"updated": "2015-06-06 14:09:19",
"weight": 0
},
"ProductSupplier": {
"id": null,
"supplier_id": null,
"product_id": null,
"cost": 0,
"discount": null,
"vat": 0,
"tax_id": null,
"code": null,
"created": null,
"updated": null,
"currency": null
},
"ProductPrice": {
"id": 164,
"price_list_id": 1,
"product_id": 1171,
"price": 500,
"vat": 0.22,
"tax_id": null,
"discount": "0",
"currency": "EUR"
},
"Available": {
"available_quantity": 0,
"updated": null
}
}
Ottieni i dettagli di un singolo prodotto. E' necessario solo fornire l'id del Prodotto fornito dopo che è stato creato.
HTTP Request
GET /api/products/{id}
Argomenti
| Argomento | Tipo | Descrizione | |
|---|---|---|---|
| id | Integer | Obbligatorio | ID del prodotto da passare come parametro. |
Restituisce
In caso di successo viene restituito un oggetto che contiene l'oggetto Product corrispondente all'id fornito e tutti i suoi oggetti associati.
In caso di errore viene invece restituito un Errore.
Modifica Prodotto
Richiesta di Esempio:
PUT /api/products/{id}?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/products/{id}
-X PUT
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Body della Richiesta:
{
"ProductPrice":
{
"price" : 450,
"vat" : 0.22
},
"ProductSupplier":
{
"cost" : 200,
"vat" : 0.22
}
}
Body della Risposta:
{
"Product": {
"id": 1171,
"name": "Creazione sito web",
"description": null,
"internal_code": null,
"measure_unit": null,
"length": null,
"height": null,
"depth": null,
"barcode": null,
"created": "2015-06-06 14:08:45",
"updated": "2015-06-06 14:21:58",
"weight": 0
},
"ProductSupplier": {
"id": 149,
"supplier_id": null,
"product_id": 1171,
"cost": 200,
"discount": null,
"vat": 0.22,
"tax_id": null,
"code": null,
"created": "2015-06-06 14:21:58",
"updated": "2015-06-06 14:21:58",
"currency": "EUR",
"Supplier": [
]
},
"ProductPrice": {
"id": 164,
"product_id": 1171,
"price": 450,
"vat": 0.22,
"tax_id": null,
"discount": "0",
"currency": "EUR"
},
"Available": {
"available_quantity": 0,
"updated": null
},
"Upload": [
],
"Category": [
]
}
Dopo che un prodotto è stato creato, è possibile modificarlo indicando il suo id.
HTTP Request
PUT /api/products/{id}
Tutti i dati passati nel corpo della richiesta verranno elaborati per modificare l'oggetto Product e le sue associazioni.
Cosa inviare
Tutti i campi dell'oggetto Product che vengono inviati nel corpo della richiesta sovrascriveranno quelli già memorizzati per il prodotto. Per i campi non inviati verranno invece conservati i valori già memorizzati. Non è quindi necessario inviare tutti i campi del Product ma solamente quelli che si intende memorizzare.
Elimina Prodotto
Richiesta di esempio:
DELETE /api/products/{id}?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/products/{id}
-X DELETE
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Risposta:
{
"code": "200",
"message": "Articolo Eliminato Correttamente"
}
Elimina definitivamente un singolo Prodotto. Non si può annullare questa azione.
Eliminando il prodotto verranno anche eliminati gli oggetti associati ProductPrice, ProductSupplier e Available.
HTTP Request
DELETE /api/products/{id}
Restituisce
Restituisce un oggetto indicante un code 200 in caso di successo.
In caso di errore, come ad esempio per un id inesistente, viene restituito un Errore.
Ottieni tutti i Prodotti
Richiesta di esempio:
GET /api/products?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/products
-X GET
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Risposta di esempio:
[
{
"Product": {
"id": 1168,
"name": "Bottiglie",
"description": null,
"internal_code": null,
"measure_unit": "pz",
"length": null,
"height": null,
"depth": null,
"barcode": null,
"created": "2015-05-21 16:30:14",
"updated": "2015-05-29 08:16:16",
"weight": 0
},
"ProductSupplier": {
"id": null,
"supplier_id": null,
"product_id": null,
"cost": 0,
"discount": null,
"vat": 0,
"tax_id": null,
"code": null,
"created": null,
"updated": null,
"currency": null
},
"ProductPrice": {
"id": null,
"product_id": null,
"price": 0,
"vat": 0,
"tax_id": null,
"discount": null,
"currency": null
},
"Available": {
"available_quantity": 5,
"updated": "2015-05-29 08:16:16"
}
},
{...}
]
E' possibile ottenere tutti i prodotti memorizzati.
I prodotti sono elecanti per data di creazione, con il più recente per primo.
HTTP Request
GET /api/products
Restituisce
In caso di successo viene restituito un array di oggetti.
Ogni oggetto contiene al suo interno un Product e le sue associazioni.
In caso non ci sia nessun Prodotto memorizzato da mostrare viene restituito un array vuoto.
Magazzino
Per ogni prodotto puoi gestire le quantità a magazzino, il loro valore, e i diversi movimenti di merce (cioè le entrate e uscite di magazzino).
Se i tuoi prodotti non hanno un magazzino o intendi tracciare solo dei servizi, puoi ignorare questa parte della guida.
Per vedere la quantità a magazzino di un determinato prodotto, puoi analizzare l'oggetto Available che ottieni quando richiedi un prodotto. Al suo interno è contenuta la quantità attualmente disponibile.
Valore di magazzino
Richiesta di esempio:
GET /api/products/stock_value/{id}?method=fifo&access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/products/stock_value/{id}?method=fifo
-X GET
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Risposta di esempio:
{
"code": 200,
"method": "fifo",
"value": 500
}
E' possibile calcolare qual è il valore a magazzino di un determinato prodotto.
GET /api/products/stock_value/{id}
E' possibile indicare in querystring il parametro method per indicare con quale metodo si vuole calcolare il valore. Utilizzano uno dei due valori. Se assente, verrà utilizzato il valore fifo.
| Valore | Descrizione |
|---|---|
| fifo | First In First Out. Default. |
| lifo | Last In First Out |
In questo modo, in caso di successo, viene restituito un oggetto con code pari a 200, e value pari al valore del prodotto a magazzino.
Elenca i Movimenti
Esempio di elencazione di un movimento. Richiesta:
GET /api/products/stock_movements/{id}?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/products/stock_movements/{id}
-X GET
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Esempio di elencazione di un movimento. Risposta:
[
{
"type": "departure",
"id": 27,
"product_id": 1168,
"delivery_product_id": null,
"invoice_product_id": 11670,
"quantity": 10,
"updated": "2015-06-08 16:05:52",
"causal": null,
"date": "2015-06-08",
"value": "200",
"InvoiceProduct": {
"id": 11670
...,
"Invoice": {...}
}
},
{...}
]
Si possono elencare i diversi movimenti di magazzino, quindi tutti i carichi e scarichi di merce, accedendo all'endpoint:
GET /api/products/stock_movements/{id}
In caso di successo verrà restituito un array di oggetti. Ognuno di questi rappresenta un movimento, con il valore type pari a departure se si tratta di un'uscita di merce o pari a arrival se si tratta di un ingresso.
Qualora il movimento dipenda da una fattura emessa, un documento di trasporto (per le uscite di merce) o una spesa (per un ingresso), al suo interno possono essere presenti rispettivamente gli oggetti InvoiceProduct, DeliveryProduct e ArrivalProduct. Questi oggetti, se presenti, al loro interno contengono rispettivamente un oggetto Invoice, Delivery o Arrival a cui appartengono.
Se non esistono movimenti verrà restituito un array vuoto.
Crea un nuovo movimento
Esempio di creazione di un movimento. Richiesta:
POST /api/products/stock_movements/{id}?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/products/stock_movements/{id}
-X POST
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
{
"Departed" : [{
"quantity" : 10
}]
}
Esempio di creazione di un movimento. Risposta:
{
"Departed": {
"id": "30",
"product_id": "1173",
"delivery_product_id": null,
"invoice_product_id": null,
"quantity": "10",
"updated": "2015-06-09 10:05:07",
"causal": null,
"date": "2015-06-09",
"value": null,
"domain_id": "254"
},
"Product": {...}
}
Normalmente i movimenti di magazzino sono automatici e scattano quando si emette una fattura, un documento di trasporto o quando si registra una spesa.
Tuttavia può essere utile talvolta registrare un movimento indipendente, senza che dunque dipenda da qualche documento di vendita.
L'oggetto Departed indica un'uscita di merce. L'oggetto Arrived indica invece un'ingresso di merce.
POST /api/products/stock_movements/{id}
Elimina un movimento
Esempio di eliminazione di un movimento. Richiesta:
DELETE /api/products/stock_movements/{id}?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/products/stock_movements/{id}
-X DELETE
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
{
"Departed" : {
"id" : 124
}
}
Esempio di eliminazione di un movimento. Risposta:
{
"code": 200,
"message" : "Movimento Eliminato Correttamente"
}
Per eliminare un movimento di magazzino è necessario mandare una richiesta all'indirizzo:
DELETE /api/products/stock_movements/{id}
Fornendo l'id del prodotto a cui è associato il movimento.
Nel corpo della richiesta è necessario passare un oggetto Departed o Arrived, cioè un movimento d'uscita o d'ingresso, con all'interno l'id del movimento che si vuole eliminare.
Ad esempio per eliminare l'oggetto Departed con l'id 124, devi mandare nel body della richiesta:
{ "Departed" : { "id" : 124 } }
In caso di successo verrà restituito un oggetto con code 200.
Fatture
Ogni Fattura, chiamata Invoice, è identificata da un un'unico ID.
E' possibile tramite le API elencare, visualizzare, eliminare e modificare una fattura. E' possibile anche visualizzarla in pdf e inviarla via email.
Associazioni
Ogni Fattura è associata a diversi oggetti.
E' possibile vedere gli oggetti associati a ciascuna Fattura utilizzando il parametro expand in querystring e indicando i nomi degli oggetti da mostrare separati da una virgola.
Es: ?expand=Income,Customer
| Oggetto | Ritorna | Description |
|---|---|---|
| InvoiceProduct | Array di InvoiceProduct | Righe della fattura |
| Income | Array di Income | Tranches di Pagamento. I pagamenti ricevuti per questa fattura. |
| IncomeDue | Array di IncomeDue | Scadenze di Pagamento. Una o più date con relativi importi da pagare. |
| Customer | Oggetto Contact | Il cliente di questa fattura selezionato tra i diversi contatti. |
| ShippingDetail | Oggetto ShippingDetail | Dettagli di Spedizione se è una Fattura d'accompagnamento |
Oggetto Fattura
Risposta di Esempio:
{
"Invoice": {
"id": 1758,
"created": "2015-05-16 09:52:30",
"updated": "2015-06-01 09:44:34",
"number": "2",
"date": "2015-05-15",
"customer_id": 714,
"customer_name": "Mario Rossi",
"customer_address": "Via Roma, Torino",
"customer_address_shipment": "",
"customer_fiscal": "RSSMR",
"customer_vat_number": "",
"payment_method": "",
"payment_dues": "pers",
"payment_notes": "",
"notes": "",
"currency": "EUR",
"view_preferences": null,
"view_preference_id": 62,
"seen": null,
"updated_by": 153,
"net_amount": 200,
"vat_amount": 44,
"total_amount": 244,
"total_paid": 488,
"contribution_amount": 0,
"withholding_amount": 0,
"withholding_rate": 0,
"withholding_on": 0,
"contribution_text": "",
"contribution_rate": 0,
"contribution_withholding": false
}
}
L'oggetto fattura possiede diverse attributi al suo interno.
Alcuni di questi sono passati dall'utente quando crea o modifica una fattura, altri invece vengono calcolati automaticamente appena la fattura viene salvata e sono quindi di sola lettura.
Attributi
| Attributo | Tipo | Descrizione |
|---|---|---|
| id | Integer (read-only) | L'identificativo della fattura |
| created | Datetime (read-only) | Quando l'oggetto è stato creato |
| updated | Datetime (read-only) | Quando l'oggetto è stato modificato |
| number | String | Identificativo (progressivo) della fattura |
| date | Date | Data della fattura |
| customer_id | Integer | Identificativo del cliente (tra i Contatti) |
| customer_name | String | Nome del cliente |
| customer_address | String (read-only) | Indirizzo del cliente formattato in base ai dati di dettaglio sotto |
| customer_street | String | Via del cliente (Via Rossi 15) |
| customer_city | String | Città del cliente (Torino) |
| customer_province | String | Provicia del cliente (TO) |
| customer_zip | String | CAP del cliente (10129) |
| customer_country | String | Stato del cliente (IT) |
| customer_address_shipment | String | Indirizzo di spedizione del cliente |
| customer_fiscal | String | Codice Fiscale del cliente |
| customer_vat_number | String | Partita IVA del cliente |
| customer_fe_code | String | Codice Destinatario del cliente (per invio della fatturazione elettronica) |
| customer_pec | String | Indirizzo pec del cliente |
| payment_method | String | Metodo di pagamento |
| payment_dues | String | Scadenze di pagamento |
| payment_notes | String | Note di Pagamento |
| notes | String | Note della fattura |
| currency | String | Valuta. Solo EUR supportata |
| finalized | Datetime | Indica quando questa fattura è passata da Proforma a fattura definitiva. Quando viene creata non come proforma, questo campo è uguale a created |
| seen | Datetime (read-only) | Quando il cliente ha visualizzato la fattura |
| net_amount | Float (read-only) | Imponibile |
| vat_amount | Float (read-only) | Importo IVA |
| total_amount | Float (read-only) | Importo Totale in fattura |
| total_paid | Float (read-only) | Importo pagato. |
I payment_method possono essere memorizzati come stringa se volti solo alla generaione del PDF. Se invece si intende inviare fatture elettroniche, è opportuno utilizzare uno dei payment_method predisposti da Adamo, inviando una voce "Chiave" tra queste:
| Chiave | Valore |
|---|---|
| cash | Contanti. |
| check | Assegno. |
| circular_check | Assegno Circolare. |
| creditcard | Carta di credito. |
| bancomat | Bancomat. |
| bank | Bonifico. |
| riba | Riba. |
| loan | Finanziamento. |
| paypal | Paypal. |
| rid | RID. |
| form | Bollettino. |
| bank_domiciliation | Domiciliazione bancaria. |
| post_domiciliation | Domiciliazione postale. |
| post_form | Bollettino Postale. |
| sepa_direct_debit | SEPA Direct Debit. |
| withholding_gathered | Trattenuta Somme già ricevut. |
Esistono inoltre alcuni attributi riguardanti dati contabili, da considerare solamente quando si hanno esigenze contabili particolari (es: ritenute d'acconto, cassa previdenziale, ecc...).
| Attributo | Tipo | Descrizione |
|---|---|---|
| withholding_amount | Float (read-only) | Importo Ritenuta d'acconto. |
| contribution_amount | Float (read-only) | Importo dell'eventuale contributo previdenziale o maggiorazione. |
| contribution_rate | Float | Rata dell'eventuale contributo previdenziale (es: 30% di imponibile) |
| contribution_text | String | Descrizione del contributo previdenziale (es: "Cassa Ingegneri"). |
| contribution_withholding | Boolean | Contributi previdenziali si calcolano anche sulla ritenuta d'acconto? |
| withholding_rate | Float | Rata della ritenuta d'acconto |
| withholding_on | Boolean | Percentuale dell'imponibile su cui si applica la ritenuta d'acconto. |
Esistono alcuni campi che riguardano la fatturazione elettronica.
| Attributo | Tipo | Descrizione |
|---|---|---|
| acube_uuid | String (read-only) | Identificativo della fattura per l'invio al SDI. |
| sdi_sent | Datetime (read-only) | Quando è stata inviata elettronicamente la fattura elettronica |
| e_notification | Enum | Può avere i valori RC, MC, NS o null. Guarda le informazioni riguardanti la Fatturazione Elettronica per i dettagli. |
| e_notification_received | Datetime | Quando è stata ricevuta la notifica dal SDI. |
| e_notification_payload | Json | Json contentente le informazioni aggiuntive sulla notifica ricevuta dal SDI. |
Righe della Fattura
Risposta di Esempio:
{
"InvoiceProduct": {
"id": 11653,
"invoice_id": 1771,
"product_id": 1168,
"name": "Riga di prova",
"internal_code": null,
"note": null,
"qty": 1,
"measure_unit": "pz",
"catalog": 0,
"cost_ev": 0,
"cost_iv": 0,
"price_ev": 200,
"net_price": 200,
"vat": 0.22,
"price_iv": 244,
"supplier_id": null,
"supplier_code": null,
"supplier_discount": "",
"supplier_vat": 0,
"markup": 0,
"margin": 0,
"tax_id": null,
"withholding": 0,
"non_taxable": false,
"discount": "",
"order_preference": 0,
"descriptive": null,
"use_stock": false
}
}
Ogni fattura porta con sé diverse righe, chiamate InvoiceProduct.
Queste sono il corpo del documento, e grazie a loro viene calcolato il totale in fattura.
L'oggetto InvoiceProduct viene sempre restituito quando viene richiesta una Fattura, anche se non viene fatta richiesta diretta tramite expand.
Attributi
| Attributo | Tipo | Descrizione |
|---|---|---|
| id | Integer | The ID della riga della fattura |
| invoice_id | Integer | Id della fattura |
| product_id | Integer | Id del Prodotto associato a questa riga |
| name | String | Nome della riga |
| internal_code | String | Codice della riga |
| note | String | Note e altre descrizioni |
| qty | Float | Quantità |
| measure_unit | String | Unità di misura |
| price_ev | Float | Prezzo di vendita IVA esclusa |
| net_price | Float (read-only) | Prezzo di vendita IVA esclusa al netto di sconti |
| vat | Float | Percentuale di IVA |
| price_iv | Float | Prezzo di vendita IVA compresa |
| supplier_id | Integer | id del Fornitore (Contatto) |
| tax_id | Integer | id della Aliquota IVA |
| withholding | Float | Si applica la ritenuta d'acconto a questo prodotto? |
| non_taxable | Boolean. Default false | Il prodotto è non imponibile? |
| discount | String | Sconto applicato al cliente |
| order_preference | Integer | Ordine delle righe in fattura (ascendente). |
| descriptive | Boolean | E' una riga solo descrittiva? |
| use_stock | Boolean | Bisogna aggiornare il magazzino? |
Tra gli attributi da considerare come avanzati, cioè di cui solo in rare occasioni si ha bisogno, ma che può essere talvolta importante tracciare, vediamo:
| Attributo | Tipo | Descrizione |
|---|---|---|
| markup | Float | Markup |
| margin | Float | Margine di vendita |
| catalog | Float | Prezzo di acquisto senza sconti |
| cost_ev | Float | Prezzo di acquisto Iva esclusa |
| cost_iv | Float | Prezzo di acquisto Iva compresa |
| supplier_code | String | codice assegnato dal fornitore |
| supplier_discount | String | Sconto applicato dal fornitore |
| supplier_vat | Float | IVA d'acquisto |
Nota che l'attributo discount è pari a String. Questo perché è possibile indicare diversi sconti cumulativi. Ad esempio per indicare un sconto del 50%+10%, si può utilizzare per il campo discount "0.5 0.1", separando i diversi sconti con un spazio.
Come vengono calcolati i totali
Quando una fattura viene salvata, in fase di creazione o modifica, i totali al suo interno vengono calcolati in base agli oggetti InvoiceProduct associati e agli attributi della fattura.
Per ogni InvoiceProduct viene prima calcolato il net_price come price_ev * (1- discount). Se non viene fornito un price_ev, quest'ultimo viene calcolato automaticamente come price_iv/(1+vat).
Ottenuto il net_price, questo viene moltiplicato per la quantità per ottenere l'imponibile (net_amount in Invoice). Se il prodotto possiede l'attributo non_taxable pari a true questo non contribuirà all'incremento dell'imponibile.
E' possibile, se richiesto, calcolare anche Contributi Previdenziali e Ritenute d'acconto per ogni fattura.
L'importo totale (total_amount) corrisponderà alla somma dell'imponibile e del totale IVA (vat_amount). Qualora esistano ritenute d'acconto o contributi previdenziali, il totale terrà conto anche di questi.
Ritenuta d'acconto
Se vogliamo calcolare la ritenuta d'acconto, ad esempio 10% del 50% dell'imponibile, è necessario indicare per l'Invoice i campi withholding_rate a 0.1, withholding_on a 0.5, e per ogni InvoiceProduct assegnare withholding pari a true per tutte le righe che contribuiscono alla ritenuta.
Contributi previdenziali
Per inserire dei contributi previdenziali o altre maggiorazioni in fattura, possiamo inserire in Invoice i campi contribution_rate (ad esempio 0.3, se vogliamo inserire un contributo del 30%), contribution_text (ad esempio: "Cassa Previdenziale"), e contribution_withholding pari a true se la ritenuta d'acconto deve venire calcolata sull'imponibile maggiorato del contributo, false altrimenti.
Crea una fattura
Richiesta di Esempio:
POST /api/invoices/?expand=Income,IncomeDue&access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/invoices/?expand=Income,IncomeDue
-X POST
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Corpo della richiesta:
{
"Invoice" : {
"customer_id" : 714
},
"InvoiceProduct":
[
{
"name" : "Servizio numero 1",
"qty" : 1,
"price_ev" : 200,
"vat" : 0.22
},
{
"name" : "Servizio numero 2",
"qty" : 2,
"price_iv" : 244,
"vat" : 0.22
}
]
}
Risposta di esempio:
{
"Invoice": {
"id": 1787,
"customer_id": 714,
"created": "2015-06-02 14:58:03",
"updated": "2015-06-02 14:58:03",
"number": "21",
"date": "2015-06-02",
"customer_name": "Mario Rossi",
"customer_address": "Via di Prova\r\n Roma \r\n ",
"customer_address_shipment": "",
"customer_fiscal": null,
"customer_vat_number": null,
"payment_method": null,
"payment_dues": null,
"payment_notes": null,
"notes": null,
"currency": "EUR",
"advance_id": null,
"view_preferences": null,
"view_preference_id": 62,
"seen": null,
"updated_by": 153,
"net_amount": 600,
"vat_amount": 132,
"total_amount": 732,
"total_paid": 0,
"contribution_amount": 0,
"withholding_amount": 0,
"withholding_rate": 0,
"withholding_on": 0,
"contribution_text": null,
"contribution_rate": 0,
"contribution_withholding": null
},
"InvoiceProduct": [
{
"id": 11661,
"invoice_id": 1787,
"product_id": null,
"name": "Servizio numero 1",
"note": null,
"qty": 1,
"measure_unit": null,
"cost_ev": 0,
"cost_iv": 0,
"price_ev": 200,
"net_price": 200,
"price_iv": 244,
"internal_code": null,
"removed": false,
"supplier_id": null,
"supplier_code": null,
"catalog": 0,
"supplier_discount": "",
"supplier_vat": 0,
"markup": 0,
"margin": 0,
"vat": 0.22,
"tax_id": null,
"withholding": 0,
"non_taxable": false,
"discount": "",
"order_preference": 0,
"descriptive": null,
"use_stock": null
},
{
"id": 11662,
"invoice_id": 1787,
"product_id": null,
"name": "Servizio numero 2",
"note": null,
"qty": 2,
"measure_unit": null,
"cost_ev": 0,
"cost_iv": 0,
"price_ev": 200,
"net_price": 200,
"price_iv": 244,
"internal_code": null,
"removed": false,
"supplier_id": null,
"supplier_code": null,
"catalog": 0,
"supplier_discount": "",
"supplier_vat": 0,
"markup": 0,
"margin": 0,
"vat": 0.22,
"tax_id": null,
"withholding": 0,
"non_taxable": false,
"discount": "",
"order_preference": 0,
"descriptive": null,
"use_stock": null
}
],
"Income": [
],
"IncomeDue": [
]
}
E' possibile creare facilmente una fattura con pochissimi dati.
HTTP Request
POST /api/invoices/
Corpo della richiesta
E' necessario inviare un oggetto Invoice e, facoltativamente, i suoi oggetti associati. Tutti i campi sono opzionali. E' bene notare tra gli attributi dell'oggetto Invoice
| Argomento | Descrizione |
|---|---|
| customer_id | Id del cliente tra i Contatti. Se non esiste un contatto con questo id l'attributo verrà settato a null. Se esiste, verranno prelevati i dati del Contatto per gli attributi descrittivi customer_name, customer_fiscal, customer_vat_number, customer_address, qualora non siano già presenti nella richiesta. |
| number | Se non presente nella richiesta verrà automaticamente utilizzato il progressivo successivo all'ultima Fattura. Cioè il numero dell'ultima Fattura (in ordine di date) + 1. |
| date | Se non indicata viene automaticamente inserita la data odierna del momento della chiamata. |
| is_proforma | Boolean. Indica se questa fattura è una fattura proforma. Di default è false, ovvero crea una fattura non proforma. In caso di valorizzazione a true, la fattura creata sarà un proforma. |
Insieme all'oggetto Invoice può venire inviato nella richiesta un array di oggetti InvoiceProduct. Anche in questo caso tutti gli attributi sono opzionali, ma è bene notare che:
| Argomento | Descrizione |
|---|---|
| qty | Se assente, viene settata a 0. Questa riga dunque non contribuirà al totale in fattura. |
| price_ev | Se assente, viene automaticamente calcolato come price_iv/(1+vat). |
| price_iv | Se assente, viene calcolato come price_ev * (1+vat). |
Insieme all'oggetto Invoice può venire inviato nella richiesta un array di oggetti Income e IncomeDue, e un oggetto ShippingDetail.
Restituisce
In caso di sucesso viene restituito un oggetto comprendente al suo interno l'oggetto Invoice appena salvato, gli associati in forma di array InvoiceProduct, Income, IncomeDue e un oggetto ShippingDetail.
In caso di errore viene restituito un Errore.
Ottieni una fattura
Richiesta di Esempio:
GET /api/invoices/{id}?expand=Income,IncomeDue&access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/invoices/{id}?expand=Income,IncomeDue
-X GET
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Risposta di esempio:
{
"Invoice":
{
"id": 1758,
"created": "2015-05-16 09:52:30",
"updated": "2015-06-01 09:44:34",
"number": "2",
"date": "2015-05-15",
"customer_id": 714,
"customer_name": "Mario Rossi",
"customer_address": "Via Roma, Torino",
"customer_address_shipment": "",
"customer_fiscal": "RSSMR",
"customer_vat_number": "",
"payment_method": "",
"payment_dues": "pers",
"payment_notes": "",
"notes": "",
"currency": "EUR",
"view_preferences": null,
"view_preference_id": 62,
"seen": null,
"updated_by": 153,
"net_amount": 200,
"vat_amount": 44,
"total_amount": 244,
"total_paid": 488,
"contribution_amount": 0,
"withholding_amount": 0,
"withholding_rate": 0,
"withholding_on": 0,
"contribution_text": "",
"contribution_rate": 0,
"contribution_withholding": false
},
"InvoiceProduct": [
{
"id": 11653,
"invoice_id": 1771,
"product_id": 1168,
"name": "",
"note": null,
"qty": 1,
"measure_unit": null,
"cost_ev": 0,
"cost_iv": 0,
"price_ev": 200,
"net_price": 200,
"price_iv": 244,
"internal_code": null,
"removed": false,
"supplier_id": null,
"supplier_code": null,
"catalog": 0,
"supplier_discount": "",
"supplier_vat": 0,
"markup": 0,
"margin": 0,
"vat": 0.22,
"tax_id": null,
"withholding": 0,
"non_taxable": false,
"discount": "",
"order_preference": 0,
"arrangement_product_id": null,
"descriptive": null,
"use_stock": true
},
{...}
],
"Income": [{...}],
"IncomeDue": [{...}]
}
Recupera una determinata fattura data il suo ID.
HTTP Request
GET /api/invoices/{id}
Argomenti
| Argomento | Tipo | Descrizione |
|---|---|---|
| id | Integer | Obbligatorio. Identificativo della fattura |
Parametri Query
| Argomento | Tipo | Default | Descrizione |
|---|---|---|---|
| expand | String | InvoiceProduct | Lista di oggetti associati alla fattura da mostrare. Nomi separati da una virgola. |
Restituisce
In caso di successo, viene restituito un array contente un oggetto Invoice, i diversi InvoiceProduct associati e tutti gli oggetti associati specificati nel parametro expand della richiesta.
In caso di errore o se l'id fornito non è valido viene invece restituito un Errore.
Ogni Invoice ha al suo interno diversi totali (net_amount, total_amount, total_paid, ...).
Il total_amount rappresenta il totale della fattura, il net_amount l'imponibile, il vat_amount la parte di IVA.
A questi si aggiungono gli eventuali contributon_amount, indicante eventuali contributi previdenziali e withholding_amount che indica la ritenuta d'acconto.
Tutti questi campi vengono calcolati al momento del salvataggio della Fattura (sia quando la si crea che quando la si aggiorna) in base agli InvoiceProduct associati.
Il campo total_paid indica quanto è stato pagato per quella fattura. E' un campo read-only e viene calcolato ogni volta che una Fattura viene salvata (sia quando la si crea che quando la si aggiorna) in base agli oggetti Income associati.
Modifica una fattura
Richiesta di Esempio:
PUT /api/invoices/{id}?expand=Income,IncomeDue&access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/invoices/{id}?expand=Income,IncomeDue
-X PUT
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Corpo della richiesta:
{
"Invoice" : {
"date" : "2015-04-01",
"customer_fiscal": "RXMR912AS912D"
},
"InvoiceProduct":[
{
"name" : "Servizio numero 1",
"qty" : 1,
"price_ev" : 200,
"vat" : 0.22
},
{
"name" : "Prodotto numero 1",
"qty" : 10,
"price_iv" : 1000,
"vat" : 0.22,
"discount" : "0.1"
}
],
"IncomeDue": [
{
"due_date": "2015-05-01",
"amount": 300,
"description": "Scadenza acconto"
}
]
}
Risposta di esempio:
{
"Invoice": {
"id": 1787,
"customer_id": 714,
"created": "2015-06-02 14:58:03",
"updated": "2015-06-02 15:56:42",
"number": "21",
"date": "2015-04-01",
"customer_name": "Mario Rossi",
"customer_address": "Via di Prova\r\n Roma \r\n ",
"customer_address_shipment": "",
"customer_fiscal": "RXMR912AS912D",
"customer_vat_number": null,
"payment_method": null,
"payment_dues": null,
"payment_notes": null,
"notes": null,
"currency": "EUR",
"seen": null,
"updated_by": 153,
"view_token": null,
"use_price": null,
"finalized": "2015-06-02 14:58:03",
"net_amount": 7577.0492,
"total_amount": 9244,
"vat_amount": 1666.951,
"contribution_amount": 0,
"withholding_amount": 0,
"withholding_rate": 0,
"withholding_on": 0,
"contribution_text": null,
"contribution_rate": 0,
"contribution_withholding": null,
"total_paid": 0
},
"InvoiceProduct": [
{
"id": 11663,
"invoice_id": 1787,
"product_id": null,
"name": "Servizio numero 1",
"note": null,
"qty": 1,
"measure_unit": null,
"cost_ev": 0,
"cost_iv": 0,
"price_ev": 200,
"net_price": 200,
"price_iv": 244,
"internal_code": null,
"supplier_id": null,
"supplier_code": null,
"catalog": 0,
"supplier_discount": "",
"supplier_vat": 0,
"markup": 0,
"margin": 0,
"vat": 0.22,
"tax_id": null,
"withholding": 0,
"non_taxable": false,
"discount": "",
"order_preference": 0,
"descriptive": null,
"use_stock": null
},
{
"id": 11664,
"invoice_id": 1787,
"product_id": null,
"name": "Prodotto numero 1",
"note": null,
"qty": 10,
"measure_unit": null,
"cost_ev": 0,
"cost_iv": 0,
"price_ev": 819.672131148,
"net_price": 737.704918033,
"price_iv": 1000,
"internal_code": null,
"supplier_id": null,
"supplier_code": null,
"catalog": 0,
"supplier_discount": "",
"supplier_vat": 0,
"markup": 0,
"margin": 0,
"vat": 0.22,
"tax_id": null,
"withholding": 0,
"non_taxable": false,
"discount": "0.1",
"order_preference": 0,
"descriptive": null,
"use_stock": null
}
],
"Income": [
],
"IncomeDue": [
{
"id": 40,
"due_date": "2015-05-01",
"amount": 300,
"description": "Scadenza acconto",
"invoice_id": 1787,
"domain_id": 254,
"created": "2015-06-02 15:56:42",
"updated": "2015-06-02 15:56:42"
}
]
}
Quando una fattura viene creata, è possibile modificarla in un secondo momento fornendo l'id di quella fattura.
HTTP Request
PUT /api/invoices/{id}
Tutti i dati passati nel corpo della richiesta verranno elaborati per modificare l'oggetto Invoice e le sue associazioni.
Cosa inviare
Tutti i campi dell'oggetto Invoice che vengono inviati nel corpo della richiesta sovrascriveranno quelli già memorizzati per la fattura. Per i campi non inviati verranno invece conservati i valori già memorizzati. Non è quindi necessario inviare tutti i campi dell'Invoice ma solamente quelli che si intende cambiare.
Per modificare una degli oggetti associati InvoiceProduct, Income o IncomeDue è necessario inviare un array di questi oggetti.
Si noti che inviando un array di nuovi oggetti InvoiceProduct o IncomeDue, tutti gli oggetti di questo tipo già precedentemente memorizzati verranno eliminati.
Ad esempio, se una fattura possiede due righe, inviando un nuovo array di InvoiceProduct queste due righe verranno eliminate e verranno memorizzate quelle nuove appena inviate, e quindi calcolati i nuovi totali.
Se si vuole mantenere i vecchi oggetti associati è necessario inviare nell'array gli id dei vecchi oggetti che si vuole conservare. Per aggiungere un prodotto ad una fattura esistente, ad esempio, si può inviare al server gli id delle due righe preesitenti più la nuova riga.
Esempio di aggiunta di una nuova riga. Richiesta:
{
"InvoiceProduct": [
{
"id": 11663
},
{
"id": 11664
},
{
"name": "Nuova Riga",
"qty": 1,
"price_ev": 100
}
]
}
Restituisce
In caso di successo viene restituito un oggetto contenente un oggetto Invoice e gli oggetti associati.
In caso di errore viene restituito un Errore.
Esempio. Pagamento di una fattura
Se una fattura viene pagata o si riceve una nuova tranche di pagamento, è possibile segnalare il pagamento in due modi:
- Creare un nuovo oggetto Income indicando come invoice_id l'id della fattura di riferimento.
- Inviare una richiesta a
PUT /api/invoices/{id}, fornendo un array di oggetti Income da creare.
In entrambi i casi il campo total_paid della fattura verrà aggiornato di conseguenza. Verranno cioè presi in considerazione i diversi Income associati alla fattura (quello appena creato e eventuali già esistenti) sommando gli importi.
Visualizza PDF di una fattura
Richiesta di esempio:
GET /api/invoices/{id}.pdf?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/invoices/{id}.pdf
-X GET
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
E' possibile visualizzare la versione PDF di una fattura.
Fornire l'ID della che è stato consegnato da una richiesta precedente, inserendo l'estensione .pdf alla richiesta.
HTTP Request
GET /api/invoices/{id}.pdf
Argomenti
| Argomento | Descrizione | |
|---|---|---|
| id | Obbligatorio | Identificativo della fattura. |
Restituisce
Viene restituito un file pdf in caso di successo, altrimenti un errore.
Visualizza XML di una fattura
Richiesta di esempio:
GET /api/invoices/{id}.xml?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/invoices/{id}.xml
-X GET
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
E' possibile visualizzare la versione XML di una fattura nel formato che verrà utilizzato per l'invio allo SDI della fattura elettronica
Fornire l'ID della che è stato consegnato da una richiesta precedente, inserendo l'estensione .xml alla richiesta.
HTTP Request
GET /api/invoices/{id}.xml
Argomenti
| Argomento | Descrizione | |
|---|---|---|
| id | Obbligatorio | Identificativo della fattura. |
Restituisce
Viene restituito un file xml in caso di successo, altrimenti un errore.
Controlla XML pre-invio
Richiesta di esempio:
POST /api/invoices/send_sdi/{id}?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/invoices/send_sdi/{id}
-X POST
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
-d '{request_body}'
Risposta:
{
"success": false,
"message": [
"Element 'CAP': [facet 'pattern'] The value '10129x' is not accepted by the pattern '[0-9][0-9][0-9][0-9][0-9]'.",
"Element 'CAP': '10129x' is not a valid value of the atomic type '{http://ivaservizi.agenziaentrate.gov.it/docs/xsd/fatture/v1.2}CAPType'."
]
}
Prima di inviare una fattura elettronica, è possibile controllarne la validità. Adamo controllerà il tracciato XML prodotto con il file XSD predisposto dall'agenzia delle entrate per verificare che i campi siano presenti e adeguatamente formattati.
Restituisce
La risposta contiene il campo success a true se la fattura è corretta. In caso di false, il tracciato XML non è corretto, e nel campo messages verranno elencate le risposte di validazione fornite dal XSD.
Invia al SDI
Richiesta di esempio:
POST /api/invoices/send_sdi/{id}?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/invoices/send_sdi/{id}
-X POST
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
-d '{request_body}'
Risposta:
{
"success": true,
"uuid": "xxxxx-xxx-11eb-be0a-xxxx"
}
È possibile inviare una fattura elettronica al Sistema di Interscambio. Adamo convertirà la fattura in XML e la invierà allo SDI.
Restituisce
La risposta contiene il campo success a true se la fattura è stata correttamente inviata. In caso di false, si è verificato un errore che impedisce l'invio, il più comune dei quali è l'esaurimento del credito di fatture elettroniche inviabili tramite Adamo.
Inoltre la risposta contiene un campo uuid, che identifica univocamente l'invio e che viene memorizzato da Adamo negli attributi della fattura.
Come funziona
Quando il SDI riceve la fattura elettronica, farà una serie di controlli sul contenuto della fattura appena inviata, terminati i quali inoltrerà la fattura al destinatario (identificato dal codice destinatario o pec, rispettivamente i campi customer_fe_code e customer_pec dell'Invoice).
Il SDI notificherà Adamo dopo un lasso di tempo variabile (da qualche minuto a qualche ora, in casi più rari giorni) sull'esito dell'invio della fattura.
L'esito verrà memorizzato nel campo e_notification dell'Invoice.
Potrà assumere uno dei seguenti valori:
- RC: Ricevuta Consegna. Fattura valida e consegnata.
- MC: Mancata Consegna. Fattura valida ma non consegnata (il destinatario potrebbe avere la casella PEC piena o cambiato codice destinatario). In questo caso non è necessario ripetere l'invio perché la fattura è stata registrata dal SDI.
- NS: Notifica di Scarto. Fattura non valida e non consegnata. Il SDI ha bocciato la fattura perché ritenuta non valida. Nel campo
e_notification_payloadsono contenute le ragioni dello scarto.
In caso di NS è possibile ritentare nuovamente l'invio.
Invia via Email
Richiesta di esempio:
POST /api/invoices/email/{id}?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/invoices/email/{id}
-X POST
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
-d '{request_body}'
Corpo della richiesta:
{
"to" : "[email protected]",
"subject" : "Documento in allegato",
"message" : "Testo in HTML",
"attachment" : true
}
Risposta:
{
"Email": {
"id": "63",
"created": "2015-06-01 12:06:57",
"sender": "[email protected]",
"receiver": [
"[email protected]"
],
"subject": "Documento in allegato",
"body": "Testo in HTML",
"sent": null,
"seen": null
}
}
Chiamando uno specifico endpoint, puoi inviare via email una fattura.
HTTP Request
POST /api/invoices/email/{id}
Argomenti
| Argomento | Tipo | Descrizione | |
|---|---|---|---|
| id | Integer | Obbligatorio | ID della fattura da passare come parametro. |
| to | String or Array | Obbligatorio | A chi inviare l'email. |
| subject | String | Opzionale | Oggetto dell'email. |
| message | String | Opzionale | Corpo dell'email in HTML |
| attachment | Boolean | Opzionale. Default: true | Inviare il documento in pdf allegato oppure sotto forma di link |
La fattura sarà inviata in allegato come pdf se l'attributo attachment è pari a true nella richiesta. In caso di attributo attachment pari a false, nel corpo dell'email verrà inserito un link su cui il destinatario può cliccare per visualizzare il pdf della fattura.
Puoi scegliere se spedire la tua email a un solo indirizzo o a più di uno, fornendo per il campo to una stringa oppure un array di stringhe. Quando uno dei tuoi destinatari visualizzerà l'email, automaticamente questa sarà marcata come letta, con l'attributo seen a indicare quando è stata letta.
Restituisce
In caso di success viene restituito un oggetto Email, altrimenti un Errore
Elimina una Fattura
Richiesta di esempio:
DELETE /api/invoices/{id}?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/invoices/{id}
-X DELETE
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Risposta:
{
"code": "200",
"message": "Documento Eliminato Correttamente"
}
E' possibile eliminare una fattura indicando il suo id.
Eliminando una fattura verranno eliminati allo stesso tempo tutti gli oggetti InvoiceProduct, IncomeDue e ShippingDetail associati.
HTTP Request
DELETE /api/invoices/{access_token}
Restituisce
Restituisce un oggetto indicante code 200 in caso di successo, un Errore altrimenti.
Ottieni tutte le fatture
Richiesta di Esempio:
GET /api/invoices/?expand=Income,IncomeDue&access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/invoices/?expand=Income,IncomeDue
-X GET
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Risposta di Esempio:
[
{
"Invoice":
{
"id": 1758,
"created": "2015-05-16 09:52:30",
"updated": "2015-06-01 09:44:34",
"number": "2",
"date": "2015-05-15",
"customer_id": 714,
"customer_name": "Mario Rossi",
"customer_address": "Via Roma, Torino",
"customer_address_shipment": "",
"customer_fiscal": "RSSMR",
"customer_vat_number": "",
"payment_method": "",
"payment_dues": "pers",
"payment_notes": "",
"notes": "",
"currency": "EUR",
"view_preferences": null,
"view_preference_id": 62,
"seen": null,
"updated_by": 153,
"net_amount": 200,
"vat_amount": 44,
"total_amount": 244,
"total_paid": 488,
"contribution_amount": 0,
"withholding_amount": 0,
"withholding_rate": 0,
"withholding_on": 0,
"contribution_text": "",
"contribution_rate": 0,
"contribution_withholding": false
},
"InvoiceProduct": [
{
"id": 11653,
"invoice_id": 1771,
"product_id": 1168,
"name": "",
"note": null,
"qty": 1,
"measure_unit": null,
"cost_ev": 0,
"cost_iv": 0,
"price_ev": 200,
"net_price": 200,
"price_iv": 244,
"internal_code": null,
"removed": false,
"supplier_id": null,
"supplier_code": null,
"catalog": 0,
"supplier_discount": "",
"supplier_vat": 0,
"markup": 0,
"margin": 0,
"vat": 0.22,
"tax_id": null,
"withholding": 0,
"non_taxable": false,
"discount": "",
"order_preference": 0,
"arrangement_product_id": null,
"descriptive": null,
"use_stock": true
},
{...}
],
"Income": [{...}],
"IncomeDue": [{...}]
},
{
"Invoice": {...},
"InvoiceProduct": [{...}],
"Income": [{...}],
"IncomeDue": [{...}]
}
]
Questo endpoint elenca tutte le fatture precedentemente create.
HTTP Request
GET /api/invoices/
Parametri Query
E' possibile filtrare e ordinare la richiesta indicato alcuni parametri in querystring
| Argomento | Tipo | Default | Descrizione |
|---|---|---|---|
| from | Date | 30 giorni fa | Fatture con data posteriore a una certa data |
| to | Date | oggi | Fatture con data anteriore a una certa data |
| customer_id | Integer | null | Se presente, filtra le fatture di uno specifico Customer |
| order | String asc or desc | desc | Dalla più recente alla più vecchia (desc) o viceversa |
| expand | String | InvoiceProduct | Lista di oggetti associati alla fattura da mostrare. Nomi separati da una virgola. |
Restituisce
In caso di successo viene restituito un array di oggetti.
Ogni oggetto contiene al suo interno un Invoice e le sue associazioni.
In caso non ci sia nessuna Fattura da mostrare viene restituito un array vuoto.
Scadenze di Pagamento
{
"IncomeDue":
{
"id": 36,
"due_date": "2015-04-01",
"amount": 244,
"description": null,
"invoice_id": 1758,
"created": "2015-05-18 13:54:31",
"updated": "2015-05-18 13:55:55"
}
}
Le scadenze di pagamento di una fattura sono descritte dall'oggetto IncomeDue.
Attributi
| Attributo | Tipo | Descrizione |
|---|---|---|
| id | Integer (read-only) | ID della scadenza di pagamento. |
| due_date | Date | Data della scadenza di pagamento. |
| amount | Float | Importo di questa scadenza. |
| invoice_id | Integer (read-only) | ID della fattura a cui appartiene. |
Dettagli di Spedizione
{
"ShippingDetail":
{
"id": 123,
"created": "2015-05-18 13:54:31",
"updated": "2015-05-18 13:55:55",
"causal": "Consegna beni di vendita",
"transport_charge": "Vettore",
"updated": "2015-06-18 13:55:55",
"appearance": "Pacco",
"weight": "12kg",
"n_packages": "4",
"port": "Franco",
"notes": "Cautela",
"invoice_id": 1758
}
}
Se si vuole creare una fattura accompagnatoria, cioè che prevede la consegna di merce, si può associare alla fattura un oggetto ShippingDetail.
Se la fattura possiede un oggetto ShippingDetail viene considerata accompagnatoria.
Attributi
| Attributo | Tipo | Descrizione |
|---|---|---|
| id | Integer (read-only) | ID della scadenza di pagamento. |
| invoice_id | Integer (read-only) | ID della fattura a cui appartiene. |
Tutti gli altri attributi sono descrittivi e sono opzionali.
Spese
Ogni Spesa viene chiamata Arrival, è identificate da un un'unico id.
E' possibile tramite le API elencare, visualizzare, eliminare e modificare tutte le spese.
Associazioni
Ogni Spesa è associata a diversi oggetti.
E' possibile vedere gli oggetti associati a ciascuna Spesa utilizzando il parametro expand in querystring e indicando i nomi degli oggetti da mostrare separati da una virgola.
Es: ?expand=Income,Customer
| Oggetto | Ritorna | Description |
|---|---|---|
| ArrivalProduct | Array di ArrivalProduct | Voci della spesa |
| Outflow | Array di Outflow | Tranches di Pagamento. I pagamenti effettuati per questa spesa. |
| OutflowDue | Array di OutflowDue | Scadenze di Pagamento. Una o più date con relativi importi da pagare. |
| Supplier | Oggetto Contact | Il fornitore di questa spesa selezionato tra i diversi contatti. |
| Category | Array di Category | Le diverse categorie a cui appartiene questa spesa |
| Upload | Array di Upload | Uno o più file allegati a questa spesa |
Oggetto Spesa
Risposta di Esempio:
{
"Arrival": {
"id": 48,
"number": "4",
"supplier_id": null,
"customer_id": null,
"supplier_name": null,
"created": "2015-05-16 14:45:52",
"updated": "2015-05-30 14:32:09",
"date": "2015-05-30",
"payment_method": "",
"payment_dues": "",
"reference": null,
"notes": "",
"currency": "EUR",
"causal": null,
"total_amount": 341.6,
"total_paid": 0,
"vat_amount": 61.6,
"net_amount": 280,
"contribution_amount": 0,
"withholding_amount": 0,
"withholding_rate": 0,
"withholding_on": 0,
"contribution_rate": 0,
"contribution_text": null,
"contribution_withholding": null
}
}
L'oggetto Spesa possiede diverse attributi al suo interno.
Alcuni di questi sono passati dall'utente quando crea o modifica una spesa, altri invece vengono calcolati automaticamente appena la spesa viene salvata e sono quindi di sola lettura.
Attributi
| Attributo | Tipo | Descrizione |
|---|---|---|
| id | Integer (read-only) | L'identificativo della spesa |
| created | Datetime (read-only) | Quando l'oggetto è stato creato |
| updated | Datetime (read-only) | Quando l'oggetto è stato modificato |
| number | String | Identificativo della spesa |
| date | Date | Data della spesa |
| supplier_id | Integer | Identificativo del fornitore (tra i Contatti) |
| supplier_name | String | Nome del fornitore |
| payment_method | String | Metodo di pagamento |
| payment_dues | String | Scadenze di pagamento |
| reference | String | Il motivo dell'acquisto |
| notes | String | Note della spesa |
| currency | String | Valuta. Solo EUR supportata |
| net_amount | Float (read-only) | Imponibile |
| vat_amount | Float (read-only) | Importo IVA |
| total_amount | Float (read-only) | Importo Totale |
| total_paid | Float (read-only) | Importo pagato. |
Esistono anche altri attributi specifici per esigenze contabili, da considerare in casi particolari.
| Attributo | Tipo | Descrizione |
|---|---|---|
| withholding_amount | Float (read-only) | Importo Ritenuta d'acconto. |
| contribution_amount | Float (read-only) | Importo contributo previdenziale o maggiorazione. |
| contribution_rate | Float | Rata del contributo previdenziale (es: 30% di imponibile) |
| contribution_text | String | Descrizione del contributo previdenziale. |
| contribution_withholding | Boolean. Default false | Contributi previdenziali si calcolano anche sulla ritenuta d'acconto?. |
| withholding_rate | Float | Rata della ritenuta d'acconto |
| withholding_on | Float | Percentuale dell'imponibile su cui si applica la ritenuta d'acconto. |
| causal | String | Causale di carico magazzino |
Voci della Spesa
Risposta di Esempio:
{
"ArrivalProduct": {
"id": 96,
"arrival_id": 48,
"product_id": null,
"internal_code": null,
"supplier_code": null,
"name": "Servizio Marketing",
"qty": 1,
"catalog": 0,
"supplier_discount": null,
"cost_ev": 280,
"vat": 0.22,
"cost_iv": 341.6,
"tax_id": null,
"order_preference": null,
"use_stock": null,
"measure_unit": null,
"withholding": null,
"non_taxable": false
}
}
Ogni spesa porta con sé diverse voci, chiamate ArrivalProduct.
Queste sono il corpo del documento, e grazie a loro viene calcolato il totale della spesa.
L'oggetto ArrivalProduct viene sempre restituito quando viene richiesta una Spesa, anche se non viene fatta richiesta diretta tramite expand.
Attributi
| Attributo | Tipo | Descrizione |
|---|---|---|
| id | Integer | ID della voce della spesa |
| arrival_id | Integer | Id della Spesa |
| product_id | Integer | Id del Prodotto associato a questa riga |
| internal_code | String | Codice della voce |
| supplier_code | String | Codice della voce assegnato dal fornitore |
| name | String | Nome della voce |
| qty | Float | Quantità |
| measure_unit | String | Unità di misura |
| supplier_discount | String | Sconto applicato dal fornitore |
| catalog | Float | Prezzo di acquisto senza sconti |
| cost_ev | Float | Prezzo di acquisto IVA esclusa |
| vat | Float | Percentuale di IVA |
| cost_iv | Float | Prezzo di acquisto Iva compresa |
| supplier_vat | Float | IVA d'acquisto |
| tax_id | Integer | id della Tassa |
| withholding | Float | Si applica la ritenuta d'acconto a questo prodotto? |
| non_taxable | Boolean | Il prodotto è non imponibile? |
| discount | String | Sconto applicato al cliente |
| order_preference | Integer | Ordine delle righe in spesa (ascendente). |
| descriptive | Boolean. Default false | E' una riga solo descrittiva? |
| use_stock | Boolean. Default false | Bisogna aggiornare il magazzino? |
Come vengono calcolati i totali
Quando una spesa viene salvata, in fase di creazione o modifica, i totali al suo interno vengono calcolati in base agli oggetti ArrivalProduct associati e agli attributi della spesa.
Per ogni ArrivalProduct viene prima calcolato il cost_ev come catalog * (1- discount). O, se fornito direttamente il cost_ev viene utilizzato quest'ultimo. Se non viene fornito un catalog né un cost_ev, quest'ultimo viene calcolato automaticamente come cost_iv/(1+vat).
Ottenuto il cost_ev, questo viene moltiplicato per la quantità per ottenere l'imponibile (net_amount in Arrival). Se il prodotto possiede l'attributo non_taxable pari a true questo non contribuirà all'incremento dell'imponibile.
E' possibile, se richiesto, calcolare anche Contributi Previdenziali e Ritenute d'acconto per ogni spesa.
L'importo totale (total_amount) corrisponderà alla somma dell'imponibile e del totale IVA (vat_amount). Qualora esistano ritenute d'acconto o contributi previdenziali, il totale terrà conto anche di questi.
Ritenuta d'acconto
Se vogliamo calcolare la ritenuta d'acconto, ad esempio 10% del 50% dell'imponibile, è necessario indicare per l'Arrival i campi withholding_rate a 0.1, withholding_on a 0.5, e per ogni ArrivalProduct assegnare withholding pari a true per tutte le righe che contribuiscono alla ritenuta.
Contributi previdenziali
Per inserire dei contributi previdenziali o altre maggiorazioni in spesa, possiamo inserire in Arrival i campi contribution_rate (ad esempio 0.3, se vogliamo inserire un contributo del 30%), contribution_text (ad esempio: "Cassa Previdenziale"), e contribution_withholding pari a true se la ritenuta d'acconto deve venire calcolata sull'imponibile maggiorato del contributo, false altrimenti.
Crea una spesa
Richiesta di Esempio:
POST /api/arrivals/?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/arrivals/
-X POST
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Corpo della richiesta:
{
"Arrival" : {
"supplier_id" : 714
},
"ArrivalProduct":
[
{
"name" : "Servizio acquistato 1",
"qty" : 1,
"cost_ev" : 200,
"vat" : 0.22
},
{
"name" : "Servizio acquistato 2",
"qty" : 2,
"cost_iv" : 244,
"vat" : 0.22
}
]
}
Risposta di esempio:
{
"Arrival": {
"id": 579,
"number": "5",
"supplier_id": 714,
"customer_id": null,
"supplier_name": null,
"created": "2015-06-05 13:26:46",
"updated": "2015-06-05 13:26:46",
"date": "2015-06-05",
"payment_method": "",
"payment_dues": "",
"notes": "",
"currency": "EUR",
"reference": null,
"causal": null,
"vat_amount": 132,
"net_amount": 600,
"total_amount": 732,
"total_paid": 0,
"contribution_amount": 0,
"withholding_amount": 0,
"withholding_rate": 0,
"withholding_on": 0,
"contribution_rate": 0,
"contribution_text": null,
"contribution_withholding": null
},
"OutflowDue": [
],
"ArrivalProduct": [
{
"id": 627,
"arrival_id": 579,
"order_product_id": null,
"arrangement_product_id": null,
"product_id": null,
"catalog": 200,
"supplier_discount": null,
"cost_ev": 200,
"vat": 0.22,
"tax_id": null,
"internal_code": null,
"supplier_code": null,
"qty": 1,
"name": "Servizio acquistato 1",
"order_preference": null,
"use_stock": null,
"measure_unit": null,
"withholding": null,
"non_taxable": false,
"cost_iv": 244
},
{
"id": 628,
"arrival_id": 579,
"order_product_id": null,
"arrangement_product_id": null,
"product_id": null,
"catalog": 200,
"supplier_discount": null,
"cost_ev": 200,
"vat": 0.22,
"tax_id": null,
"internal_code": null,
"supplier_code": null,
"qty": 2,
"name": "Servizio acquistato 2",
"order_preference": null,
"use_stock": null,
"measure_unit": null,
"withholding": null,
"non_taxable": false,
"cost_iv": 244
}
],
"Outflow": [
]
}
E' possibile creare facilmente una spesa con pochissimi dati.
HTTP Request
POST /api/arrivals/
Corpo della richiesta
E' necessario inviare un oggetto Arrival e, facoltativamente, i suoi oggetti associati. Tutti i campi sono opzionali. E' bene notare tra gli attributi dell'oggetto Arrival
| Argomento | Descrizione |
|---|---|
| supplier_id | Id del fornitore tra i Contatti. Se non esiste un contatto con questo id l'attributo verrà settato a null. Se esiste, verranno prelevati i dati del Contatto per gli attributi descrittivi supplier_name. |
| number | Se non presente nella richiesta verrà settato a null. |
| date | Se non indicata viene automatiacmente inserita la data odierna del momento della chiamata. |
Insieme all'oggetto Arrival può venire inviato nella richiesta un array di oggetti ArrivalProduct. Anche in questo caso tutti gli attributi sono opzionali, ma è bene notare che:
| Argomento | Descrizione |
|---|---|
| qty | Se assente, viene settata a 0. Questa riga dunque non contribuirà al totale in spesa. |
| catalog | Se assente, viene automaticamente calcolato come cost_ev/(1+discount). |
| cost_iv | Se assente, viene calcolato come cost_ev * (1+vat). |
Insieme all'oggetto Arrival può venire inviato nella richiesta un array di oggetti Outflow, OutflowDue, Category, Upload.
Restituisce
In caso di sucesso viene restituito un oggetto comprendente al suo interno l'oggetto Arrival appena salvato, gli associati in forma di array ArrivalProduct, Outflow, OutflowDue.
In caso di errore viene restituito un Errore.
Ottieni una Spesa
Richiesta di Esempio:
GET /api/arrivals/{id}?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/arrivals/{id}
-X GET
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Risposta di esempio:
{
"Arrival": {
"id": 579,
"number": "5",
"supplier_id": 714,
"supplier_name": null,
"created": "2015-06-05 13:26:46",
"updated": "2015-06-05 13:26:46",
"date": "2015-06-05",
"payment_method": "",
"payment_dues": "",
"notes": "",
"currency": "EUR",
"reference": null,
"causal": null,
"vat_amount": 132,
"net_amount": 600,
"total_amount": 732,
"total_paid": 0,
"contribution_amount": 0,
"withholding_amount": 0,
"withholding_rate": 0,
"withholding_on": 0,
"contribution_rate": 0,
"contribution_text": null,
"contribution_withholding": null
},
"OutflowDue": [
],
"ArrivalProduct": [
{
"id": 627,
"arrival_id": 579,
"order_product_id": null,
"arrangement_product_id": null,
"product_id": null,
"catalog": 200,
"supplier_discount": null,
"cost_ev": 200,
"vat": 0.22,
"tax_id": null,
"internal_code": null,
"supplier_code": null,
"qty": 1,
"name": "Servizio acquistato 1",
"order_preference": null,
"use_stock": null,
"measure_unit": null,
"withholding": null,
"non_taxable": false,
"cost_iv": 244
},
{
"id": 628,
"arrival_id": 579,
"order_product_id": null,
"arrangement_product_id": null,
"product_id": null,
"catalog": 200,
"supplier_discount": null,
"cost_ev": 200,
"vat": 0.22,
"tax_id": null,
"internal_code": null,
"supplier_code": null,
"qty": 2,
"name": "Servizio acquistato 2",
"order_preference": null,
"use_stock": null,
"measure_unit": null,
"withholding": null,
"non_taxable": false,
"cost_iv": 244
}
],
"Outflow": [
],
"Upload": [
]
}
Recupera una determinata spesa dato il suo ID.
HTTP Request
GET /api/invoices/{id}
Argomenti
| Argomento | Tipo | Default | Descrizione |
|---|---|---|---|
| id | Integer | Obbligatorio | Identificativo della spesa |
Restituisce
In caso di successo, viene restituito un array contente un oggetto Arrival, i diversi ArrivalProduct associati e tutti gli oggetti associati.
In caso di errore o se l'id fornito non è valido viene invece restituito un Errore.
Ogni Arrival ha al suo interno diversi totali (net_amount, total_amount, total_paid, ...).
Il total_amount rappresenta il totale della spesa, il net_amount l'imponibile, il vat_amount la parte di IVA. A questi si aggiungono contributon_amount, indicante eventuali contributi previdenziali e withholding_amount che indica la ritenuta d'acconto. Tutti questi campi vengono calcolati al momento del salvataggio della Spesa (sia quando la si crea che quando la si aggiorna) in base agli ArrivalProduct associati.
Il campo total_paid indica quanto è stato pagato per quella spesa. E' un campo read-only e viene calcolato ogni volta che una Spesa viene salvata (sia quando la si crea che quando la si aggiorna) in base agli oggetti Outflow associati
Modifica una Spesa
Richiesta di Esempio:
PUT /api/arrivals/{id}?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/invoices/{id}
-X PUT
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Corpo della richiesta:
{
"Arrival" : {
"date" : "2015-04-01"
},
"ArrivalProduct":[
{
"name" : "Servizio numero 1",
"qty" : 1,
"cost_ev" : 200,
"vat" : 0.22
},
{
"name" : "Prodotto numero 1",
"qty" : 10,
"cost_iv" : 1000,
"vat" : 0.22,
"supplier_discount" : "0.1"
}
],
"OutflowDue": [
{
"due_date": "2015-05-01",
"amount": 300,
"description": "Scadenza"
}
]
}
Risposta di esempio:
{
"Arrival": {
"id": 579,
"number": "5",
"supplier_id": 714,
"customer_id": null,
"supplier_name": null,
"created": "2015-06-05 13:26:46",
"updated": "2015-06-05 13:53:00",
"date": "2015-04-01",
"payment_method": "",
"payment_dues": "",
"notes": "",
"currency": "EUR",
"reference": null,
"causal": null,
"total_amount": 10244,
"total_paid": 0,
"vat_amount": 1847.279,
"net_amount": 8396.721,
"contribution_amount": 0,
"withholding_amount": 0,
"withholding_rate": 0,
"withholding_on": 0,
"contribution_rate": 0,
"contribution_text": null,
"contribution_withholding": null
},
"OutflowDue": [
{
"id": 12,
"due_date": "2015-05-01",
"amount": 300,
"description": "Scadenza",
"arrival_id": 579,
"created": "2015-06-05 13:53:00",
"updated": "2015-06-05 13:53:00",
}
],
"ArrivalProduct": [
{
"id": 631,
"arrival_id": 579,
"order_product_id": null,
"arrangement_product_id": null,
"product_id": null,
"catalog": 200,
"supplier_discount": null,
"cost_ev": 200,
"vat": 0.22,
"tax_id": null,
"internal_code": null,
"supplier_code": null,
"qty": 1,
"name": "Servizio numero 1",
"order_preference": null,
"use_stock": null,
"measure_unit": null,
"withholding": null,
"non_taxable": false,
"cost_iv": 244
},
{
"id": 632,
"arrival_id": 579,
"order_product_id": null,
"arrangement_product_id": null,
"product_id": null,
"catalog": 910.747,
"supplier_discount": "0.1",
"cost_ev": 819.672,
"vat": 0.22,
"tax_id": null,
"internal_code": null,
"supplier_code": null,
"qty": 10,
"name": "Prodotto numero 1",
"order_preference": null,
"use_stock": null,
"measure_unit": null,
"withholding": null,
"non_taxable": false,
"cost_iv": 1000
}
],
"Outflow": [
],
"Upload": [
]
}
Quando una spesa viene creata, è possibile modificarla in un secondo momento fornendo l'id di quella spesa.
HTTP Request
PUT /api/arrivals/{id}
Tutti i dati passati nel corpo della richiesta verranno elaborati per modificare l'oggetto Arrival e le sue associazioni.
Cosa inviare
Tutti i campi dell'oggetto Arrival che vengono inviati nel corpo della richiesta sovrascriveranno quelli già memorizzati per la spesa. Per i campi non inviati verranno invece conservati i valori già memorizzati. Non è quindi necessario inviare tutti i campi dell'Arrival ma solamente quelli che si intende memorizzare.
Per modificare una degli oggetti associati ArrivalProduct, Outflow, OutflowDue, Category o Upload è necessario inviare un array di questi oggetti.
Si noti che inviando un array di ArrivalProduct o di OutflowDue, tutti gli oggetti associati precedentemente memorizzati verranno eliminati.
Ad esempio, se una spesa possiede due voci, inviando un nuovo array di ArrivalProduct queste due voci verranno eliminate e verranno memorizzate quelle nuove appena inviate, e quindi calcolati i nuovi totali.
Se si vuole mantenere i vecchi oggetti associati è necessario inviare nell'array gli id dei vecchi oggetti che si vuole conservare. Per aggiungere un prodotto ad una spesa esistente, ad esempio, si può inviare al server gli id delle due voci preesitenti più la nuova riga.
Richiesta di aggiunta di una nuova voce
{
"ArrivalProduct": [
{
"id": 11663
},
{
"id": 11664
},
{
"name": "Nuova Voce",
"qty": 1,
"cost_ev": 100
}
]
}
Restituisce
In caso di successo viene restituito un oggetto contenente un oggetto Arrival e gli oggetti associati.
In caso di errore viene restituito un Errore.
Esempio. Pagamento di una fattura
Se una spesa viene pagata, è possibile segnalare il pagamento in due modi:
- Creare un nuovo oggetto Outflow indicando come arrival_id l'id della spesa di riferimento.
- Inviare una richiesta a
PUT /api/arrivals/{id}, fornendo un array di oggetti Outflow da creare.
In entrambi i casi il campo total_paid della spesa verrà aggiornato di conseguenza. Verranno cioè presi in considerazione i diversi Outflow associati alla spesa (quello appena creato e eventuali già esistenti) sommando gli importi.
Elimina una Spesa
Richiesta di esempio:
DELETE /api/arrivals/{id}?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/arrivals/{id}
-X DELETE
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Risposta:
{
"code": "200",
"message": "Documento Eliminato Correttamente"
}
E' possibile eliminare una spesa indicando il suo id.
Eliminando una spesa verranno eliminati allo stesso tempo tutti gli oggetti ArrivalProduct e OutflowDue associati.
Sopravviveranno invece gli oggetti Outflow, Upload e Category dovranno essere eliminati con altre richieste.
HTTP Request
DELETE /api/arrivals/{access_token}
Restituisce
Restituisce un oggetto indicante code 200 in caso di successo, un Errore altrimenti.
Ottieni tutte le Spese
Richiesta di Esempio:
GET /api/arrivals/?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/arrivals/
-X GET
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Risposta di Esempio:
[
{
"Arrival": {
"id": 579,
"number": "5",
"supplier_id": 714,
"customer_id": null,
"supplier_name": null,
"created": "2015-06-05 13:26:46",
"updated": "2015-06-05 13:53:00",
"date": "2015-04-01",
"payment_method": "",
"payment_dues": "",
"notes": "",
"currency": "EUR",
"reference": null,
"causal": null,
"total_amount": 10244,
"total_paid": 0,
"vat_amount": 1847.279,
"net_amount": 8396.721,
"contribution_amount": 0,
"withholding_amount": 0,
"withholding_rate": 0,
"withholding_on": 0,
"contribution_rate": 0,
"contribution_text": null,
"contribution_withholding": null
},
"OutflowDue": [
{
"id": 12,
"due_date": "2015-05-01",
"amount": 300,
"description": "Scadenza",
"arrival_id": 579,
"created": "2015-06-05 13:53:00",
"updated": "2015-06-05 13:53:00"
}
],
"ArrivalProduct": [
{
"id": 631,
"arrival_id": 579,
"order_product_id": null,
"arrangement_product_id": null,
"product_id": null,
"catalog": 200,
"supplier_discount": null,
"cost_ev": 200,
"vat": 0.22,
"tax_id": null,
"internal_code": null,
"supplier_code": null,
"qty": 1,
"name": "Servizio numero 1",
"order_preference": null,
"use_stock": null,
"measure_unit": null,
"withholding": null,
"non_taxable": false,
"cost_iv": 244
},
{
"id": 632,
"arrival_id": 579,
"order_product_id": null,
"arrangement_product_id": null,
"product_id": null,
"catalog": 910.747,
"supplier_discount": "0.1",
"cost_ev": 819.672,
"vat": 0.22,
"tax_id": null,
"internal_code": null,
"supplier_code": null,
"qty": 10,
"name": "Prodotto numero 1",
"order_preference": null,
"use_stock": null,
"measure_unit": null,
"withholding": null,
"non_taxable": false,
"cost_iv": 1000
}
],
"Outflow": [
],
"Upload": [
{
"id": 178,
"real_name": "254\/948df65482fcfc4a48d7c0521.jpg",
"name": "10171627_10152908373599664_2161444716751927217_n.j",
"size": 81491,
"created": "2015-05-30 14:13:22",
"modified": "2015-05-30 14:32:09",
"mime": "image\/jpeg",
"docket_id": null,
"revision_of": null,
"updated_by": 153,
"public": false
}
]
},
{
"Arrival": {...},
"ArrivalProduct": [{...}],
"Outflow": [{...}],
"OutflowDue": [{...}],
"Category": [{...}],
"Upload":[{...}]
}
]
Questo endpoint elenca tutte le spese precedentemente create.
HTTP Request
GET /api/arrivals/
Parametri Query
E' possibile filtrare e ordinare la richiesta indicato alcuni parametri in querystring
| Argomento | Tipo | Default | Descrizione |
|---|---|---|---|
| from | Date | 30 giorni fa | Spese con data posteriore a una certa data |
| to | Date | oggi | Spese con data anteriore a una certa data |
| order | String asc or desc | desc | Dalla più recente alla più vecchia (desc) o viceversa |
Restituisce
In caso di successo viene restituito un array di oggetti.
Ogni oggetto contiene al suo interno un Arrival e le sue associazioni.
In caso non ci sia nessuna Spesa da mostrare viene restituito un array vuoto.
Scadenze di Pagamento
{
"OutflowDue":
{
"id": 36,
"due_date": "2015-04-01",
"amount": 244,
"description": null,
"invoice_id": 1758,
"created": "2015-05-18 13:54:31",
"updated": "2015-05-18 13:55:55"
}
}
Le scadenze di pagamento di una fattura sono descritte dall'oggetto OutflowDue.
Sono l'opposto dell'oggetto IncomeDue.
Attributi
| Attributo | Tipo | Descrizione |
|---|---|---|
| id | Integer (read-only) | ID della scadenza di pagamento. |
| due_date | Date | Data della scadenza di pagamento. |
| amount | Float | Importo di questa scadenza. |
| arrival_id | Integer (read-only) | ID della spesa a cui appartiene. |
Categoria
{
"Category" :
{
"id": 40,
"arrival_id": 48,
"category": "Spese per il personale"
}
}
Ogni Arrival può avere diverse categorie, chiamate Category.
Attributi
| Attributo | Tipo | Descrizione |
|---|---|---|
| id | Integer (read-only) | ID della categoria. |
| arrival_id | Integer | Id della spesa. |
| category | String | Testo della categoria. |
Altri Documenti
Esistono diversi altri tipi di documenti, strutturalmente molto simili alle fatture Invoice ma con ruoli diversi.
In questa sezione descriviamo velocemente quali sono gli oggetti che rappresentano questi documenti, qual è il loro ruolo e come manipolare i dati.
Essendo per larga parte simili a quanto già visto per l'oggetto Invoice, se ne da qui una descrizione sommaria. Si consiglia pertanto di rifarsi alla documentazione di Invoice per tutti i dettagli.
Preventivi
{
"Quote": {
"id": 94,
"customer_id": null,
"created": "2015-05-15 09:38:24",
"updated": "2015-05-15 09:38:24",
"removed": false,
"accepted": null,
"accepted_date": null,
"number": 2,
"date": "2015-05-15",
"customer_name": "",
"customer_address": "",
"customer_address_shipment": "",
"payment_method": null,
"payment_dues": null,
"payment_notes": null,
"customer_fiscal": "BLTZ",
"notes": "",
"currency": "EUR",
"updated_by": 153,
"seen": null,
"net_amount": 5000,
"total_amount": 6000,
"contribution_amount": 0,
"withholding_amount": 0,
"withholding_rate": 0,
"withholding_on": 0,
"contribution_text": null,
"contribution_rate": 0,
"contribution_withholding": null
},
"QuoteProduct": [
{
"id": 793,
"quote_id": 94,
"product_id": null,
"name": "TEST",
"description": "",
"note": null,
"qty": 2,
"measure_unit": null,
"cost_ev": 0,
"cost_iv": 0,
"price_ev": 2500,
"net_price": 0,
"price_iv": 0,
"internal_code": null,
"supplier_id": null,
"supplier_code": null,
"catalog": 0,
"supplier_discount": "",
"supplier_vat": 0,
"markup": 0,
"margin": 0,
"vat": 0.2,
"tax_id": null,
"discount": "",
"order_preference": 0,
"withholding": 0,
"non_taxable": false
},
{...}
]
}
I Preventivi sono chiamati Quote.
Un preventivo è documento che viene emesso prima di una vendita e serve per informare il cliente su quelli che saranno i prezzi di vendita.
Ogni oggetto Quote ha delle associazioni
| Oggetto | Ritorna | Description |
|---|---|---|
| QuoteProduct | Array di QuoteProduct | Righe del preventivo |
| Customer | Oggetto Contact | Il cliente di questo preventivo selezionato tra i diversi contatti. |
Ogni preventivo porta con sé diverse righe, chiamate QuoteProduct.
Queste sono il corpo del documento, e grazie a loro viene calcolato il totale.
Gli attributi di Quote sono identici a quelli di Invoice, così come quelli di QuoteProduct sono identici a quelli di InvoiceProduct.
L'oggetto Quote ha inoltre i campi
| Oggetto | Ritorna | Description |
|---|---|---|
| accepted | Boolean. Default false | Il preventivo è stato accettato dal cliente? |
| accepted_date | DateTime | Quando è stato accettato |
Crea un nuovo preventivo
E' possibile creare un nuovo preventivo con una richiesta ad uno specifico endpoint:
POST /api/quotes/
Inviando nel corpo della richiesta un oggetto Quote con gli attributi che si vuole salvare.
Ottieni un preventivo
Chiamando l'endpoint:
GET /api/quotes/{id}
Verrà restituito un oggetto contentente un oggetto Quote e un array di QuoteProduct, qualora l'id fornito sia valido.
Modifica un preventivo
Chiamando l'endpoint:
PUT /api/quotes/{id}
Indicando nel corpo del documento l'oggetto Quote (e, se si vuole, i diversi QuoteProduct).
In caso di successo viene restituito un oggetto contenente l'oggetto Quote e tutti i suoi associati.
Elimina un preventivo
E' possibile chiamare l'endpoint:
DELETE /api/quotes/{id}
Per eliminare in modo permanente un preventivo.
In caso di successo viene restituto un oggetto con attributo code 200.
Ottieni tutti i preventivi
Chiamando l'endpoint:
GET /api/quotes
In caso di successo viene restituito un array di oggetti.
Ogni oggetto contiene al suo interno un Quote e le sue associazioni.
In caso non ci sia nessun preventivo da mostrare viene restituito un array vuoto.
Invia via email un preventivo
Chiamando uno specifico endpoint, puoi inviare via email il tuo preventivo.
POST /api/quotes/email/{id}
Dovranno essere indicati nel corpo della richiesta gli attributi to, subject, message e attachment.
In caso di success viene restituito un oggetto Email, altrimenti un Errore.
Visualizza un preventivo pdf
E' possibile visualizzare la versione PDF di un preventivo fornendo l'ID della che è stato consegnato da una richiesta precedente, inserendo l'estensione .pdf alla richiesta.
GET /api/quotes/{id}.pdf
Viene restituito un file pdf in caso di successo, altrimenti un errore.
Contratti
{
"Arrangement": {
"id": 102,
"commission_id": 87,
"customer_id": null,
"created": "2015-06-06 21:51:55",
"updated": "2015-06-06 21:51:55",
"number": 2,
"date": "2015-06-06",
"payment_method": "",
"payment_dues": "",
"payment_notes": "",
"customer_name": "",
"customer_address": "",
"customer_address_shipment": "",
"customer_fiscal": null,
"notes": "",
"currency": "EUR",
"quote_id": null,
"updated_by": 153,
"view_preferences": null,
"view_preference_id": 62,
"view_token": null,
"seen": null,
"net_amount": 200,
"total_amount": 200,
"contribution_amount": 0,
"withholding_amount": 0,
"withholding_rate": 0,
"withholding_on": 0,
"contribution_text": null,
"contribution_rate": 0,
"contribution_withholding": null
},
"ArrangementProduct": [
{
"id": 691,
"arrangement_id": 102,
"product_id": null,
"name": "TEST",
"description": "",
"note": null,
"qty": 1,
"cost_ev": 0,
"cost_iv": 0,
"price_ev": 200,
"net_price": 200,
"price_iv": 200,
"internal_code": null,
"removed": false,
"supplier_id": null,
"supplier_code": null,
"catalog": 0,
"supplier_discount": "",
"supplier_vat": 0,
"markup": 0,
"margin": 0,
"vat": 0,
"tax_id": null,
"discount": "",
"order_preference": 0,
"descriptive": null,
"withholding": 0,
"non_taxable": false,
"measure_unit": null
}
]
}
I Contratti sono chiamati Arrangement.
Un contratto normalmente segue il preventivo e precede la fattura. Se il preventivo viene accettato, si può creare un contratto.
Ogni oggetto Arrangement ha delle associazioni
| Oggetto | Ritorna | Description |
|---|---|---|
| ArrangementProduct | Array di ArrangementProduct | Righe del contratto |
| Customer | Oggetto Contact | Il cliente di questo contratto selezionato tra i diversi contatti. |
Ogni contratto porta con sé diverse righe, chiamate ArrangementProduct.
Queste sono il corpo del documento, e grazie a loro viene calcolato il totale.
Gli attributi di Arrangement sono identici a quelli di Invoice, così come quelli di ArrangementProduct sono identici a quelli di InvoiceProduct.
L'oggetto Arrangement ha inoltre i campi
| Oggetto | Ritorna | Description |
|---|---|---|
| quote_id | Integer. opzionale | L'id del preventivo dal quale è nato questo contratto. |
Crea un nuovo Contratto
E' possibile creare un nuovo contratto con una richiesta ad uno specifico endpoint:
POST /api/arrangements/
Inviando nel corpo della richiesta un oggetto Arrangement con gli attributi che si vuole salvare.
Ottieni un Contratto
Chiamando l'endpoint:
GET /api/arrangements/{id}
Verrà restituito un oggetto contentente un oggetto Arrangement e un array di ArrangementProduct, qualora l'id fornito sia valido.
Modifica un Contratto
Chiamando l'endpoint:
PUT /api/arrangements/{id}
Indicando nel corpo del documento l'oggetto Arrangement (e, se si vuole, i diversi ArrangementProduct).
In caso di successo viene restituito un oggetto contenente l'oggetto Arrangement e tutti i suoi associati.
Elimina un Contratto
E' possibile chiamare l'endpoint:
DELETE /api/arrangements/{id}
Per eliminare in modo permanente un contratto.
In caso di successo viene restituto un oggetto con attributo code 200.
Ottieni tutti i Contratti
Chiamando l'endpoint:
GET /api/arrangements
In caso di successo viene restituito un array di oggetti.
Ogni oggetto contiene al suo interno un Arrangement e le sue associazioni.
In caso non ci sia nessun contratto da mostrare viene restituito un array vuoto.
Invia via email un contratto
Chiamando uno specifico endpoint, puoi inviare via email il tuo contratto.
POST /api/arrangements/email/{id}
Dovranno essere indicati nel corpo della richiesta gli attributi to, subject, message e attachment.
In caso di success viene restituito un oggetto Email, altrimenti un Errore.
Visualizza un Contratto pdf
E' possibile visualizzare la versione PDF di un contratto fornendo l'ID della che è stato consegnato da una richiesta precedente, inserendo l'estensione .pdf alla richiesta.
GET /api/arrangements/{id}.pdf
Viene restituito un file pdf in caso di successo, altrimenti un errore.
Documento di consegna
{
"Delivery": {
"id": 93,
"customer_id": null,
"created": "2015-06-07 16:41:30",
"updated": "2015-06-07 16:41:30",
"number": 3,
"date": "2015-06-07",
"customer_name": null,
"customer_address": null,
"customer_address_shipment": null,
"customer_fiscal": null,
"causal": null,
"transport_charge": null,
"delivery_date": null,
"appearance": null,
"weight": null,
"port": null,
"n_packages": null,
"notes": null,
"currency": "EUR",
"net_amount": 200,
"total_amount": 200,
"contribution_amount": 0,
"withholding_amount": 0,
"withholding_rate": 0,
"withholding_on": 0,
"contribution_text": null,
"contribution_rate": 0,
"contribution_withholding": null
},
"DeliveryProduct": [
{
"id": 704,
"delivery_id": 93,
"product_id": null,
"name": "TEST",
"description": "",
"note": null,
"qty": 1,
"price_ev": 200,
"net_price": 200,
"price_iv": 200,
"internal_code": null,
"removed": false,
"vat": 0,
"tax_id": null,
"withholding": 0,
"non_taxable": false,
"discount": "",
"order_preference": 0,
"descriptive": null,
"use_stock": null,
"measure_unit": null
}
]
}
I Documenti di Trasporto sono chiamati Delivery.
Un Documento di Trasporto è un documento che viene redatto quando c'è una consegna di merce.
Ogni oggetto Delivery ha delle associazioni
| Oggetto | Ritorna | Description |
|---|---|---|
| DeliveryProduct | Array di DeliveryProduct | Righe del Documento |
| Customer | Oggetto Contact | Il cliente di questo documento selezionato tra i diversi contatti. |
Ogni DDT porta con sé diverse righe, chiamate DeliveryProduct.
Queste sono il corpo del documento, e grazie a loro viene calcolato il totale.
Gli attributi di Delivery sono identici a quelli di Invoice, così come quelli di DeliveryProduct sono identici a quelli di InvoiceProduct.
L'oggetto Delivery ha inoltre i campi opzionali:
| Oggetto | Ritorna | Description |
|---|---|---|
| causal | String | Causale di scarico merce |
| transport_charge | String | Consegna a mezzo (es: mittente, destinatario,...) |
| delivery_date | DateTime | Data di consegna |
| appearance | String | Aspetto esteriore dei beni (es: pacco) |
| weight | String | Peso |
| port | String | Porto (es: franco,...) |
| n_packages | String | Numero di colli |
Crea un nuovo DDT
E' possibile creare un nuovo DDT con una richiesta ad uno specifico endpoint:
POST /api/deliveries/
Inviando nel corpo della richiesta un oggetto Delivery con gli attributi che si vuole salvare.
Ottieni un DDT
Chiamando l'endpoint:
GET /api/deliveries/{id}
Verrà restituito un oggetto contentente un oggetto Delivery e un array di DeliveryProduct, qualora l'id fornito sia valido.
Modifica un DDT
Chiamando l'endpoint:
PUT /api/deliveries/{id}
Indicando nel corpo del documento l'oggetto Delivery (e, se si vuole, i diversi DeliveryProduct).
In caso di successo viene restituito un oggetto contenente l'oggetto Delivery e tutti i suoi associati.
Elimina un DDT
E' possibile chiamare l'endpoint:
DELETE /api/deliveries/{id}
Per eliminare in modo permanente un DDT.
In caso di successo viene restituto un oggetto con attributo code 200.
Ottieni tutti i DDT
Chiamando l'endpoint:
GET /api/deliveries
In caso di successo viene restituito un array di oggetti.
Ogni oggetto contiene al suo interno un Delivery e le sue associazioni.
In caso non ci sia nessun DDT da mostrare viene restituito un array vuoto.
Invia via email un DDT
Chiamando uno specifico endpoint, puoi inviare via email il tuo DDT.
POST /api/deliveries/email/{id}
Dovranno essere indicati nel corpo della richiesta gli attributi to, subject, message e attachment.
In caso di success viene restituito un oggetto Email, altrimenti un Errore.
Visualizza un DDT in pdf
E' possibile visualizzare la versione PDF di un DDT fornendo l'ID della che è stato consegnato da una richiesta precedente, inserendo l'estensione .pdf alla richiesta.
GET /api/deliveries/{id}.pdf
Viene restituito un file pdf in caso di successo, altrimenti un errore.
Note di Credito
{
"CreditNote": {
"id": 16,
"customer_id": null,
"created": "2015-06-07 16:58:07",
"updated": "2015-06-07 16:58:07",
"number": 2,
"date": "2015-06-07",
"customer_name": "",
"customer_address": "",
"customer_address_shipment": "",
"customer_fiscal": null,
"details": null,
"notes": "",
"currency": "EUR",
"contribution_amount": 0,
"withholding_amount": 0,
"withholding_rate": 0,
"withholding_on": 0,
"contribution_text": null,
"contribution_rate": 0,
"contribution_withholding": null,
"intestation_id": null,
"total_amount": 200,
"total_paid": 0,
"net_amount": 200,
"invoice_id": null
},
"Invoice": {
"id": null,
"number": null,
"date": null
},
"CreditNoteProduct": [
{
"id": 40,
"credit_note_id": 16,
"product_id": null,
"name": "TEST",
"note": null,
"qty": 1,
"measure_unit": null,
"cost_ev": 0,
"cost_iv": 0,
"price_ev": 200,
"net_price": 200,
"price_iv": 200,
"diluted_price_ev": 0,
"diluted_price_iv": 0,
"internal_code": null,
"removed": false,
"supplier_id": null,
"supplier_code": null,
"catalog": 0,
"supplier_discount": "",
"supplier_vat": 0,
"markup": 0,
"margin": 0,
"vat": 0,
"tax_id": null,
"withholding": 0,
"non_taxable": false,
"discount": "",
"order_preference": 0,
"arrangement_product_id": null,
"descriptive": null,
"use_stock": null
}
]
}
Le Note di Credito sono chiamate CreditNote.
Una Nota di Credito è un documento che attesta un credito del cliente nei confronti dell'azienda. Può essere immaginato come l'opposto della fattura.
Ogni oggetto CreditNote ha delle associazioni
| Oggetto | Ritorna | Description |
|---|---|---|
| CreditNoteProduct | Array di CreditNoteProduct | Righe del Documento |
| Invoice | Oggetto Invoice | La fattura che ha originato questa nota di credito. |
| Outflow | Array di Outflow | Tutti i pagamenti (in uscita) per saldare questa nota. |
Ogni NdC porta con sé diverse righe, chiamate CreditNoteProduct.
Queste sono il corpo del documento, e grazie a loro viene calcolato il totale.
Gli attributi di CreditNote sono identici a quelli di Invoice, così come quelli di CreditNoteProduct sono identici a quelli di InvoiceProduct.
L'oggetto CreditNote ha inoltre i campi opzionali:
| Oggetto | Ritorna | Description |
|---|---|---|
| invoice_id | Integer | Indica l'id della fattura che ha originato questa nota. |
Crea una nuova Nota di Credito
E' possibile creare una nuova nota di credito con una richiesta ad uno specifico endpoint:
POST /api/credit_notes/
Inviando nel corpo della richiesta un oggetto CreditNote con gli attributi che si vuole salvare.
Ottieni una Nota di Credito
Chiamando l'endpoint:
GET /api/credit_notes/{id}
Verrà restituito un oggetto contentente un oggetto CreditNote e un array di CreditNoteProduct, qualora l'id fornito sia valido.
Modifica una Nota di Credito
Chiamando l'endpoint:
PUT /api/credit_notes/{id}
Indicando nel corpo del documento l'oggetto CreditNote (e, se si vuole, i diversi CreditNoteProduct).
In caso di successo viene restituito un oggetto contenente l'oggetto CreditNote e tutti i suoi associati.
Elimina una Note di Credito
E' possibile chiamare l'endpoint:
DELETE /api/credit_notes/{id}
Per eliminare in modo permanente una Note di Credito.
In caso di successo viene restituto un oggetto con attributo code 200.
Ottieni tutte le Note di Credito
Chiamando l'endpoint:
GET /api/credit_notes
In caso di successo viene restituito un array di oggetti.
Ogni oggetto contiene al suo interno un CreditNote e le sue associazioni.
In caso non ci sia nessuna Nota di Credito da mostrare viene restituito un array vuoto.
Invia via email una Nota di Credito
Chiamando uno specifico endpoint, puoi inviare via email la tua nota di credito.
POST /api/credit_notes/email/{id}
Dovranno essere indicati nel corpo della richiesta gli attributi to, subject, message e attachment.
In caso di successo viene restituito un oggetto Email, altrimenti un Errore.
Visualizza una Nota di Credito in pdf
E' possibile visualizzare la versione PDF di una Nota di Credito fornendo l'ID della che è stato consegnato da una richiesta precedente, inserendo l'estensione .pdf alla richiesta.
GET /api/credit_notes/{id}.pdf
Viene restituito un file pdf in caso di successo, altrimenti un errore.
Ricevute
{
"Receipt": {
"id": 94,
"customer_id": null,
"created": "2015-05-15 09:38:24",
"updated": "2015-05-15 09:38:24",
"removed": false,
"accepted": null,
"accepted_date": null,
"number": 2,
"date": "2015-05-15",
"customer_name": "",
"customer_address": "",
"customer_address_shipment": "",
"payment_method": null,
"payment_dues": null,
"payment_notes": null,
"customer_fiscal": "BLTZ",
"notes": "",
"currency": "EUR",
"updated_by": 153,
"seen": null,
"net_amount": 5000,
"total_amount": 6000,
"contribution_amount": 0,
"withholding_amount": 0,
"withholding_rate": 0,
"withholding_on": 0,
"contribution_text": null,
"contribution_rate": 0,
"contribution_withholding": null
},
"ReceiptProduct": [
{
"id": 793,
"quote_id": 94,
"product_id": null,
"name": "TEST",
"description": "",
"note": null,
"qty": 2,
"measure_unit": null,
"cost_ev": 0,
"cost_iv": 0,
"price_ev": 2500,
"net_price": 0,
"price_iv": 0,
"internal_code": null,
"supplier_id": null,
"supplier_code": null,
"catalog": 0,
"supplier_discount": "",
"supplier_vat": 0,
"markup": 0,
"margin": 0,
"vat": 0.2,
"tax_id": null,
"discount": "",
"order_preference": 0,
"withholding": 0,
"non_taxable": false
},
{...}
]
}
Le Ricevute sono chiamati Receipt.
In alternativa a una fattura, può essere emessa una Ricevuta.
Ogni oggetto Receipt ha delle associazioni
| Oggetto | Ritorna | Description |
|---|---|---|
| ReceiptProduct | Array di ReceiptProduct | Righe della ricevuta |
| Customer | Oggetto Contact. Opzionale | Il cliente di questa ricevuta selezionato tra i diversi contatti. |
Ogni ricevuta porta con sé diverse righe, chiamate ReceiptProduct.
Queste sono il corpo del documento, e grazie a loro viene calcolato il totale.
Gli attributi di Receipt sono identici a quelli di Invoice, così come quelli di ReceiptProduct sono identici a quelli di InvoiceProduct.
L'oggetto Receipt ha inoltre i campi
| Oggetto | Ritorna | Description |
|---|---|---|
| type | String, receipt o till. Default: receipt | Indica se è una ricevuta fiscale (receipt) o uno scontrino (till). |
Crea una nuova Ricevuta
E' possibile creare una nuova ricevuta con una richiesta ad uno specifico endpoint:
POST /api/receipts/
Inviando nel corpo della richiesta un oggetto Receipt con gli attributi che si vuole salvare.
Quando crei una ricevuta verrà automaticamente creato anche un pagamento (oggetto Income), per un importo pari all'importo della ricevuta, e con gli attributi date e mean (quest'ultimo preso dall'attributo payment_method della ricevuta) indicati nella ricevuta.
Ottieni una Ricevuta
Chiamando l'endpoint:
GET /api/receipts/{id}
Verrà restituito un oggetto contentente un oggetto Receipt e un array di ReceiptProduct, qualora l'id fornito sia valido.
Modifica una Ricevuta
Chiamando l'endpoint:
PUT /api/receipts/{id}
Indicando nel corpo del documento l'oggetto Receipt (e, se si vuole, i diversi ReceiptProduct).
In caso di successo viene restituito un oggetto contenente l'oggetto Receipt e tutti i suoi associati.
Elimina una Ricevuta
E' possibile chiamare l'endpoint:
DELETE /api/receipts/{id}
Per eliminare in modo permanente una ricevuta.
In caso di successo viene restituto un oggetto con attributo code 200.
Ottieni tutte le Ricevute
Chiamando l'endpoint:
GET /api/receipts
In caso di successo viene restituito un array di oggetti.
Ogni oggetto contiene al suo interno un Receipt e le sue associazioni.
In caso non ci sia nessuna ricevuta da mostrare viene restituito un array vuoto.
Invia via email una ricevuta
Chiamando uno specifico endpoint, puoi inviare via email la tua ricevuta.
POST /api/receipts/email/{id}
Dovranno essere indicati nel corpo della richiesta gli attributi to, subject, message e attachment.
In caso di success viene restituito un oggetto Email, altrimenti un Errore.
Visualizza una ricevuta pdf
E' possibile visualizzare la versione PDF di una ricevuta, fornendo l'ID della che è stato consegnato da una richiesta precedente, inserendo l'estensione .pdf alla richiesta.
GET /api/receipts/{id}.pdf
Viene restituito un file pdf in caso di successo, altrimenti un errore.
Ordini di Acquisto
{
"Order": {
"id": 171,
"supplier_id": 7632,
"created": "2017-08-21 12:32:50",
"updated": "2017-08-21 12:32:50",
"removed": false,
"sent": null,
"confirmed": false,
"confirmed_date": null,
"domain_id": 28,
"number": 13,
"date": "2017-08-21",
"payment_method": "",
"payment_dues": "",
"supplier_name": "My Test Web",
"supplier_address": "",
"address_shipment": "Ap #739-6704 Aliquam Ave\nGaya\nMalaysia",
"supplier_fiscal": "Codice Fiscale",
"notes": "NOTESSSS",
"currency": "EUR",
"arrival_date": null,
"reference": "",
"view_preferences": null,
"updated_by": 102,
"view_preference_id": 74,
"supplier_real_name": "My Test Web"
},
"OrderProduct": [
{
"id": 349,
"order_id": 171,
"arrangement_product_id": null,
"product_id": null,
"catalog": 140,
"supplier_discount": "0",
"cost_ev": 140,
"vat": 0,
"tax_id": null,
"internal_code": "",
"supplier_code": "",
"qty": 5,
"name": "bl0",
"order_preference": 1,
"measure_unit": "",
"cost_iv": 140
}
]
}
Gli ordini di acquisto vengono chiamati Order.
Gli ordini di acquisto vengono generati per informare i fornitori dei prodotti e servizi di cui si ha bisogno. Di norma, precedono la creazione di un Acquisto. Per questo motivo, sono molto simili all'oggetto oggetto Spesa
Ogni oggetto Order ha delle associazioni
| Oggetto | Ritorna | Description |
|---|---|---|
| OrderProduct | Array di OrderProduct | Righe dell'ordine |
| Supplier | Oggetto Contact | Il fornitore di quest'Ordine selezionato tra i diversi contatti. |
Ogni ordine porta con sé diverse righe, chiamate OrderProduct.
Queste sono il corpo del documento, e grazie a loro viene calcolato il totale.
Gli attributi di Order sono identici a quelli di Arrival, così come quelli di OrderProduct sono identici a quelli di ArrivalProduct.
L'oggetto Order ha inoltre i campi:
| Oggetto | Ritorna | Description |
|---|---|---|
| sent | Datetime. Default: null | Indica se e quanto l'ordine è stato spedito al fornitore |
Crea un nuovo Ordine
E' possibile creare un nuovo ordine con una richiesta ad uno specifico endpoint:
POST /api/orders/
Inviando nel corpo della richiesta un oggetto Order con gli attributi che si vuole salvare.
Ottieni un Ordine
Chiamando l'endpoint:
GET /api/orders/{id}
Verrà restituito un oggetto contentente un oggetto Order e un array di OrderProduct, qualora l'id fornito sia valido.
Modifica un Ordine
Chiamando l'endpoint:
PUT /api/orders/{id}
Indicando nel corpo del documento l'oggetto Order (e, se si vuole, i diversi OrderProduct).
In caso di successo viene restituito un oggetto contenente l'oggetto Order e tutti i suoi associati.
Elimina un Ordine
E' possibile chiamare l'endpoint:
DELETE /api/orders/{id}
Per eliminare in modo permanente un ordine.
In caso di successo viene restituto un oggetto con attributo code 200.
Ottieni tutti gli Ordini
Chiamando l'endpoint:
GET /api/orders
In caso di successo viene restituito un array di oggetti.
Ogni oggetto contiene al suo interno un Order e le sue associazioni.
In caso non ci sia nessun ordine da mostrare viene restituito un array vuoto.
Invia via email un ordine
Chiamando uno specifico endpoint, puoi inviare via email il tuo ordine.
POST /api/orders/email/{id}
Dovranno essere indicati nel corpo della richiesta gli attributi to, subject, message e attachment.
In caso di success viene restituito un oggetto Email, altrimenti un Errore.
Visualizza un Ordine in pdf
E' possibile visualizzare la versione PDF di un ordine, fornendo l'ID della che è stato consegnato da una richiesta precedente, inserendo l'estensione .pdf alla richiesta.
GET /api/orders/{id}.pdf
Viene restituito un file pdf in caso di successo, altrimenti un errore.
Pagamenti
Ogni flusso di pagamento, in entrata e uscita, viene memorizzato su Adamo. Tramite le API è possibile visualizzare, modificare, eliminare questi flussi.
Pagamenti in ingresso
{
"Income": {
"id": 1248,
"date": "2015-05-29",
"amount": 0,
"mean": null,
"invoice_id": null,
"receipt_id": null,
"causal": null,
"created": "2015-05-29 09:23:35",
"updated": "2015-05-29 09:23:35",
"note": "",
"resource": null,
"resource_id": null
}
}
I pagamenti in ingresso sono chiamati Income. Ogni Income simboleggia un flusso di pagamento che hai ricevuto da qualcuno.
Gli attributi sono i seguenti:
| Attributo | Tipo | Descrizione |
|---|---|---|
| date | Date. Default: data di oggi | Quando è stato effettuato il pagamento. |
| amount | Float | L'importo del pagamento |
| mean | String | Come è stato effettuato il pagamento. Es: Bonifico, Carta di credito. |
| invoice_id | Integer | L'id della fattura emessa associata a questo pagamento |
| receipt_id | Integer | L'id della ricevuta emessa associata a questo pagamento |
| causal | String | Il motivo di questo pagamento. |
| note | String | Altre note |
| resource | String | Il nome del conto su cui è finito questo pagamento. |
| resource_id | Integer | L'id del conto su cui è finito questo pagamento. |
Il conto, chiamato resource, può essere un valore testuale oppure un oggetto Resource, e simboleggia il conto dal quale entrano e escono i flussi di cassa, es: Banca XX, Cassa, PostePay di Mario, ecc...
Indicando un resource_id valido, il saldo della Resource associata verrà incrementato di conseguenza.
Crea un nuovo pagamento
Richiesta di Esempio:
POST /api/incomes/?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/incomes/ -X POST
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Corpo della richiesta:
{
"Income": {
"amount" : 200,
"mean" : "Bonifico",
"causal" : "Rimborso"
}
}
Risposta di esempio:
{
"Income": {
"id": 1261,
"date": "2015-06-08",
"amount": 200,
"mean": "Bonifico",
"invoice_id": null,
"receipt_id": null,
"causal": "Rimborso",
"created": "2015-06-08 08:23:10",
"updated": "2015-06-08 08:23:10",
"note": "",
"resource": null,
"resource_id": null
},
"Invoice": {...}
}
Accedendo all'endpoint:
POST /api/incomes/
Si può facilmente creare un nuovo pagamento.
Se l'attributo date non viene inviato con la richiesta, allora verrà inserita la data di oggi.
Viene restituito un oggetto comprendente un oggetto Income in caso di successo.
Inviando con la richiesta un valore invoice_id valido, si può facilmente creare una nuova tranche di pagamento per una fattura. In questo modo, per questa richiesta, verrà restituito anche l'oggetto Invoice associato all'id fornito.
Ottieni un pagamento
Indicando l'id del pagamento in ingresso creato si può ottenere l'oggetto Income.
GET /api/incomes/{id}
Viene restituito un oggetto contenente un oggetto Income in caso di successo, un Errore altrimenti.
E' possibile utilizzare in querystring l'attributo expand pari a invoice per ottenere, oltre all'oggetto Income anche l'eventuale Invoice associato.
Elimina un pagamento
Indicando l'id del pagamento in ingresso creato si può eliminare l'oggetto Income in modo irreversibile.
DELETE /api/incomes/{id}
Viene restituito un oggetto contenente un attributo code pari a 200 in caso di successo, un Errore altrimenti.
Si noti che eliminando un pagamento verrà aggiornato (decrementato) il saldo dell'oggetto Resource associato.
Elenca i pagamenti
E' possibile elencare tutti i pagamenti in entrata tramite l'endpoint:
GET /api/incomes/
Verrà restituito un array comprendente oggetti che contengono gli oggetti Income.
Se nessun Income è presente verrà restituito un array vuoto.
Pagamenti in uscita
{
"Outflow": {
"id": 153,
"date": "2015-01-02",
"amount": 244.00,
"arrival_id": null,
"tribute_id": null,
"credit_note_id": null,
"mean": "cash",
"causal": null,
"created": "2015-01-18",
"updated": "2015-01-18 21:43:01",
"note": "",
"resource": "Cassa",
"resource_id": null
}
}
I pagamenti in uscita sono chiamati Outflow. Ogni Outflow simboleggia un flusso di pagamento che hai dato a qualcuno.
Gli attributi sono i seguenti:
| Attributo | Tipo | Descrizione |
|---|---|---|
| date | Date. Default: data di oggi | Quando è stato effettuato il pagamento. |
| amount | Float | L'importo del pagamento |
| mean | String | Come è stato effettuato il pagamento. Es: Bonifico, Carta di credito. |
| arrival_id | Integer | L'id della spesa fatta associata a questo pagamento |
| credit_note_id | Integer | L'id della nota di credito emessa associata a questo pagamento |
| causal | String | Il motivo di questo pagamento. |
| note | String | Altre note |
| resource | String | Il nome del conto da cui è uscito questo pagamento. |
| resource_id | Integer | L'id del conto da cui è uscito questo pagamento. |
Il conto, chiamato resource, può essere un valore testuale oppure un oggetto Resource, e simboleggia il conto dal quale entrano e escono i flussi di cassa, es: Banca XX, Cassa, PostePay di Mario, ecc...
Indicando un resource_id valido, il saldo della Resource associata verrà decrementato di conseguenza.
Crea un nuovo pagamento
Richiesta di Esempio:
POST /api/outflows/?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/outflows/ -X POST
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Corpo della richiesta:
{
"Outflow": {
"amount" : 200,
"mean" : "Bonifico",
"causal" : "Rimborso"
}
}
Risposta di esempio:
{
"Outflow": {
"id": 613,
"date": "2015-06-08",
"amount": 200,
"arrival_id": null,
"tribute_id": null,
"credit_note_id": null,
"mean": "Bonifico",
"causal": "Rimborso",
"updated": "2015-06-08 08:49:16",
"updated": "2015-06-08 08:49:16",
"note": "",
"resource": null,
"resource_id": null
},
"Arrival": {...},
"CreditNote": {...}
}
Accedendo all'endpoint:
POST /api/outflows/
Si può facilmente creare un nuovo pagamento.
Se l'attributo date non viene inviato con la richiesta, allora verrà inserita la data di oggi.
Viene restituito un oggetto comprendente un oggetto Outflow in caso di successo.
Inviando con la richiesta un valore arrival_id valido, si può facilmente creare una nuova tranche di pagamento per una spesa effettuata. In questo modo, per questa richiesta, verrà restituito anche l'oggetto Arrival associato all'id fornito.
Stessa cosa per credit_note_id e l'oggetto CreditNote.
Ottieni un pagamento
Indicando l'id del pagamento in uscita creato si può ottenere l'oggetto Outflow.
GET /api/outflows/{id}
Viene restituito un oggetto contenente un oggetto Outflow in caso di successo, un Errore altrimenti.
E' possibile utilizzare in querystring l'attributo expand pari a arrival o credit_note per ottenere, oltre all'oggetto Outflow anche l'eventuale Arrival o CreditNote associato.
Elimina un pagamento
Indicando l'id del pagamento in uscita creato si può eliminare l'oggetto Outflow in modo irreversibile.
DELETE /api/outflows/{id}
Viene restituito un oggetto contenente un attributo code pari a 200 in caso di successo, un Errore altrimenti.
Si noti che eliminando un pagamento verrà aggiornato (aumentato) il saldo dell'oggetto Resource associato.
Elenca i pagamenti
E' possibile elencare tutti i pagamenti in uscita tramite l'endpoint:
GET /api/outflows/
Verrà restituito un array comprendente oggetti che contengono gli oggetti Outflow.
Se nessun Outflow è presente verrà restituito un array vuoto.
Conti
{
"Resource": {
"id": 221,
"name": "Cassa",
"situation": 1500,
"created": "2015-01-18 21:27:00",
"updated": "2015-05-29 09:31:23"
}
}
I conti, chiamati Resource, sono i diversi conti su cui possiedi dei soldi. Ad esempio potresti voler tenere traccia del tuo saldo in Banca, in Cassa, sulla tua Carta di Credito, sulla tua Carta Prepagata, ecc...
Utilizzando i conti puoi fare in modo che i diversi pagamenti in entrata e uscita aggiornino automaticamente il saldo del rispettivo conto. Quando creerai un nuovo Income o Outflow, indicando un resource_id valido, il sistema automaticamente si preoccuperà di incrementare o di scalare l'importo dal rispettivo conto.
| Attributo | Tipo | Descrizione |
|---|---|---|
| name | String Obbligatorio | Nome del conto |
| situation | Float | Importo attualmente sul conto |
Elenca tutti i conti
Consula la situazione dei tuoi conti accedendo all'endpoint:
GET /api/resources/
Ti verrà restituito un array contente degli oggetti che contengono l'oggetto Resource.
Se non hai nessun conto ti verrà restituito un array vuoto.
Crea un nuovo conto
POST /api/resources/?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/outflows/ -X POST
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Corpo della richiesta:
{
"Resource" : {
"name" : "Carta Prepagata di Mario",
"situation" : 1400
}
}
Risposta di esempio:
{
"Resource": {
"id": 237,
"name": "Carta Prepagata di Mario",
"situation": 1400,
"created": "2015-06-08 09:36:07",
"updated": "2015-06-08 09:37:35"
}
}
Puoi creare diversi conti. Per crearne uno passa un oggetto Resource all'endpoint:
POST /api/resources/
In caso non passi l'attributo situation questa verrà inizializzato a zero.
Ti verrà restituito l'oggetto appena creato in caso di successo.
Elimina un conto
Per eliminare un conto, sapendo il suo id, accedi all'endpoint:
DELETE /api/resources/{id}
In caso di successo ti verrà restituito un oggetto con code pari a 200.
Nota che tutti i pagamenti, Income e Outflow associati al conto NON verranno eliminati dal sistema. Verranno conservato con un resource_id nullo, quindi senza essere associati ad alcun conto.
Modifica un conto
Modifica il nome o la situazione di un conto inviando un oggetto Resource all'endpoint:
PUT /api/resources/{id}
Ti verrà restituito l'oggetto Resource in caso di successo o un Errore altrimenti.
Elenca tutti i movimenti
Richiesta:
POST /api/cashflows/?resource_id=5&access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/cashflows?resource_id=5
-X POST
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Risposta:
[
{
"type": "outflow",
"id": "615",
"date": "2015-06-08",
"amount": "800",
"arrival_id": null,
"credit_note_id": null,
"mean": null,
"causal": null,
"created": "2015-06-08",
"updated": "2015-06-08 09:36:45",
"note": "",
"domain_id": "254",
"resource": "Carta",
"resource_id": "237",
"Arrival": {...}
},
{...}
]
Per elencare tutti i movimenti, sia gli Income che i Outflow, ordinati dal più recente al più vecchio, è possibile utilizzare l'endpoint:
GET /api/cashflows/
Parametri
E' possibile passare in querystring i parametri:
| Parametro | Default | Descrizione | Esempio |
|---|---|---|---|
| resource_id | nessun filtro | Filtra solamente i movimenti riferiti ad uno specifico conto | 5 |
| from | 30 giorni fa | Filtra i movimenti successivi ad una certa data | 2015-01-01 |
| to | oggi | Filtra i movimenti precedenti ad una certa data | 2015-12-31 |
Restituisce
Restituisce un array di oggetti. Ogni oggetto è un movimento. L'attributo type indica il tipo di oggetto, e può essere pari a outflow oppure income, ad indicare se si tratta di uno o dell'altro. Dentro ogni oggetto saranno presenti anche gli oggetti associati.
Nel caso non siano presenti oggetti verrà restituito un array vuoto.
E' possibile visualizzare tutte le email inviate da Adamo e controllare se sono state visualizzate dal destinatario.
Oggetto Email
{
"id": 37,
"created": "2015-05-11 09:23:12",
"sender": "[email protected]",
"receiver": [
"[email protected]"
],
"subject": "La tua fattura #10",
"body": "",
"sent": "2015-05-11 09:24:00",
"seen": null
}
L'oggetto Email ha pochi atttributi al suo interno
| Attributo | Tipo | Descrizione |
|---|---|---|
| id | Integer | |
| sender | String (read-only) | Chi ha inviato questa email |
| receiver | Array | Uno o più indirizzi email destinatari |
| subject | String | Titolo |
| body | String | Corpo della email |
| sent | Datetime | Quando l'email è stata spedita |
| seen | Datetime | Quando questa email è stata visualizzata dal destinatario. |
Si noti che dal momento della creazione dell'oggetto Email al suo invio può passare un piccolo periodo di tempo, generalmente inferiore al minuto.
Quando il primo dei destinatari visualizza l'email inviata per la prima volta, l'attributo seen verrà valorizzato con la data di quell'istante.
Ottieni tutte le Email
Richiesta di esempio:
GET /api/emails?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/emails
-X GET
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
[
{
"Email": {
"id": 37,
"created": "2015-05-11 09:23:12",
"sender": "[email protected]",
"receiver": [
"[email protected]"
],
"subject": "La tua fattura #10",
"body": "",
"sent": "2015-05-11 09:24:00",
"seen": null
}
},
{...}
]
Con questo endpoint si possono elencare tutte le email già inviate.
HTTP Request
GET /api/emails
Restituisce
In caso di successo viene restituito un array di oggetti.
Ogni oggetto contiene al suo interno un Email.
In caso non ci sia nessuna Email memorizzata da mostrare viene restituito un array vuoto.
Ottieni una sola Email
Richiesta di esempio:
GET /api/emails/{id}?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/emails/{id}
-X GET
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
{
"Email": {
"id": 37,
"created": "2015-05-11 09:23:12",
"sender": "[email protected]",
"receiver": [
"[email protected]"
],
"subject": "La tua fattura, caro",
"body": "",
"sent": null,
"seen": null
}
}
Con questo endpoint si può ottenere una email dato il suo id.
HTTP Request
GET /api/emails/{id}
Restituisce
In caso di successo viene restituito un oggetto comprendente un Email.
In caso di errore, ad esempio se viene fornito un id non esistente, viene restituito un Errore.
Files
In diverse occasioni si può voler caricare su Adamo dei file, ad esempio quando si vuole allegare ad una spesa una fattura in pdf.
Questo può essere fatto creando un oggetto Upload. Quando viene caricato online un file, le API di Adamo rispondono con un oggetto comprendente le informazioni sul file appena caricato.
Caricare un file
Richiesta di esempio:
POST /api/uploads?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="path/to/file.png"
Content-Type: image/png
$ curl
https://app.adamogestionale.it/api/uploads
-X POST
-H "Authorization: Bearer {access_token}"
-F "file= path/to/file.png"
Risposta di esempio:
{
"Upload": {
"id": 180,
"real_name": "254\/aaac215441e3946158394d78d.png",
"name": "file.png",
"size": 191896,
"created": "2015-06-06 15:49:34",
"modified": "2015-06-06 15:49:34",
"mime": "image\/png",
"docket_id": null,
"revision_of": null,
"updated_by": 153,
"public": false
}
}
Per caricare un file è necessario inviare una richiesta multipart/form-data all'endpoint:
POST /api/uploads
Restituisce
In caso di successo verrà restituito un oggetto contente un oggetto Upload. Gli attributi dell'oggetto sono:
| Attributo | Tipo | Descrizione |
|---|---|---|
| id | Integer | |
| real_name | String (read-only) | Percorso del file pubblicamente accessibile se public è true |
| name | String | Nome del file assegnato dall'utente |
| size | Integer (read-only) | Peso del files in bytes |
| mime | String (read-only) | Tipo di file |
| docket_id | Integer | Id della cartella del file |
| public | Boolean. Default false | Se true può essere visibile a chiunque acceda al percorso realName. |
Modificare un file
Richiesta di modifica di un file:
PUT /api/uploads/{id}?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
$ curl
https://app.adamogestionale.it/api/uploads/{id}
-X PUT
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
{
"Upload": {
"name":"filename.png",
"public":true
}
}
Risposta di esempio:
{
"Upload": {
"id": 172,
"real_name": "254\/1a87404acf3cd3b240952c4a7.png",
"name": "filename.png",
"size": 1164408,
"created": "2015-05-30 10:17:01",
"modified": "2015-06-06 16:43:18",
"mime": "image\/png",
"docket_id": null,
"revision_of": null,
"updated_by": 153,
"public": true
}
}
Dato l'id del file puoi modificare alcuni dei suoi attributi.
| Attributo | Tipo |
|---|---|
| name | String |
| docket_id | Integer |
| public | Boolean |
Restituisce
In caso di successo viene restituito un oggetto contenente un oggetto Upload.
In caso di errore viene restituito un Errore.
Scaricare un file
Richiesta di download di un file:
GET /api/uploads/download/{id}?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
$ curl
https://app.adamogestionale.it/api/uploads/download/{id}
-X GET
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
E' possibile scaricare un file accedendo al suo indirizzo pubblico se l'attributo è false.
Altrimenti è possibile scaricarlo accedendo all'endpoint
GET /api/uploads/download/{id}
Restituisce
In caso di successo restituisce il file nel formato mime.
Visualizzare un file
Richiesta di download di un file:
GET /api/uploads/{id}?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
$ curl
https://app.adamogestionale.it/api/uploads
-X POST
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Risposta di esempio:
{
"Upload": {
"id": 164,
"real_name": "254\/8358e0673233389a410379fec.pdf",
"name": "file.pdf",
"size": 36155,
"created": "2015-01-18 21:42:00",
"modified": "2015-01-18 21:42:00",
"mime": "application\/pdf",
"docket_id": null,
"revision_of": null,
"updated_by": 153,
"public": false
}
}
Dato l'id di un oggetto Upload è possibile visualizzare tutte le informazioni su quest'oggetto.
Chiamando l'endpoint:
GET /api/uploads/{id}
Viene restituito un oggetto contente un oggetto Upload in caso di successo, altrimenti viene restituito un Errore.
Per ottenere il file puoi scaricare il file
Eliminare un file
Richiesta di eliminazione di un file:
DELETE /api/uploads/{id}?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
$ curl
https://app.adamogestionale.it/api/uploads/{id}
-X DELETE
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Risposta di esempio:
{
"code": "200",
"message": "File eliminato correttamente"
}
Per eliminare un file è necessario rivolgere una richiesta all'endpoint.
DELETE /api/uploads/{id}
In questo modo verrà eliminato l'oggetto Upload e cancellare in maniera definitiva il file dal sistema. Non si può annullare questa azione.
Restituisce
Restituisce un oggetto indicante code 200 in caso di successo, un Errore altrimenti.
Ottenere tutti i file
Richiesta di eliminazione di un file:
GET /api/uploads/?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/uploads/
-X GET
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Risposta di esempio:
[
{
"Upload": {
"id": 172,
"real_name": "254\/1a87404acf3cd3b240952c4a7.png",
"name": "test",
"size": 1164408,
"created": "2015-05-30 10:17:01",
"modified": "2015-06-06 16:43:18",
"mime": "image\/png",
"docket_id": null,
"revision_of": null,
"updated_by": 153,
"public": true
}
},
{...}
]
Per ottenere una lista di tutti i file presenti si può accedere a questo endpoint:
GET /api/uploads
In caso di successo verrà restituito un array di oggetti Upload. Se nessun Upload è stato trovato allora verrà restituito un array vuoto.
Report
Tramite i report è possibile ottenere una panoramica dell'andamento della propria impresa.
I Report aggregano ed elaborano i dati già salvati fornendo le informazioni richieste.
Crediti per cliente
Richiesta:
GET /api/reports/credits_by_customer?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/reports/credits_by_customer
-X GET
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Risposta:
{
"Customers": [
{
"id": "714",
"name": "Carletto",
"amount": 9488,
"Invoice": [
{
"id": "1758",
"customer_id": "714",
"created": "2015-05-16 09:52:30",
"updated": "2015-06-01 11:11:05",
"number": "2",
"date": "2015-05-15",
"customer_name": "Carletto",
"customer_address": "",
"customer_address_shipment": "",
"customer_fiscal": "",
"customer_vat_number": "",
"payment_method": "",
"payment_dues": "pers",
"payment_notes": "",
"notes": "",
"currency": "EUR",
"advance_id": null,
"net_amount": 200.0000,
"total_amount": 244.0000,
"vat_amount": "44.000",
"contribution_amount": 0.000,
"withholding_amount": 0.000,
"withholding_rate": null,
"withholding_on": null,
"contribution_text": "",
"contribution_rate": null,
"contribution_withholding": false,
"total_paid": 100.00,
"IncomeDue": [
{
"id": "36",
"due_date": "2015-04-01",
"amount": 244.00,
"description": null,
"invoice_id": "1758",
"created": "2015-05-18 13:54:31",
"updated": "2015-05-18 13:55:55"
}
],
"Income": [
{
"id": "1256",
"date": "2015-06-01",
"amount": 100.00,
"mean": null,
"invoice_id": "1758",
"receipt_id": null,
"causal": null,
"created": "2015-06-01 09:43:29",
"updated": "2015-06-01 09:43:29",
"refresh_balance": false,
"note": "",
"resource": null,
"resource_id": null
},
{...}
]
}
]
},
{
"id": "15",
"name": "Ermanno",
"amount": 549,
"Invoice": [
{
"id": "1767",
"customer_id": "15",
"created": "2015-05-23 09:23:48",
"updated": "2015-05-23 15:09:44",
"number": "3",
"date": "2015-05-23",
"customer_name": "Ermanno",
"customer_address": "",
"customer_address_shipment": "",
"customer_fiscal": null,
"customer_vat_number": null,
"payment_method": null,
"payment_dues": null,
"payment_notes": null,
"notes": null,
"currency": "EUR",
"net_amount": "450.0000",
"total_amount": "549.0000",
"vat_amount": "99.000",
"contribution_amount": "0.000",
"withholding_amount": "0.000",
"withholding_rate": null,
"withholding_on": null,
"contribution_text": null,
"contribution_rate": null,
"contribution_withholding": null,
"total_paid": null
"IncomeDue": [
],
"Income": [
]
}
]
}
]
}
Quando una fattura non è ancora stata del tutto pagata, quindi quando ha un total_paid inferiore a total_amount, il sistema la valuterà come non pagata e attribuirà un debito del cliente nei tuoi confronti. Tu quindi hai un credito nei confronti del cliente.
Per ottenere una lista dei crediti per ogni cliente si può utilizzare l'endpoint:
GET /api/uploads
Si noti che i clienti devono essere tra i Contatti. Quindi la fattura non pagata deve avere customer_id non nullo e che punta verso un valido Contatto perché questo venga conteggiato come credito.
Restituisce
Viene restituito in caso di successo un oggetto comprendente un array denominato Customers. All'interno dell'array sono elencati tutti i Contatti che hanno un credito nei tuoi confronti.
| Attributo | Tipo | Descrizione |
|---|---|---|
| id | Integer | identificativo del Contatto |
| name | String | nome del contatto |
| amount | Float | importo del credito |
All'interno dell'oggetto sono elencati, qualora presenti, tutti gli oggetti Invoice e Credit Note che hanno quel Contatto come cliente e che quindi contribuiscono al credito.
Aliquote
Su Adamo esistono diverse Aliquote IVA, associabili alle righe delle fatture in ingresso e uscita tramite l'attributo tax_id.
Elenco delle Aliquote
{
"Tax":
{
"id": 1,
"tax": 0.03,
"title": "3% - Imp speciale di bollo, art 24",
"fe_value": "N2"
}
}
Le Aliquote IVA sono chiamate Tax. Ogni Tax indica una possibile aliquota iva che può essere inserita sul sistema.
Gli attributi sono i seguenti:
| Attributo | Tipo | Descrizione |
|---|---|---|
| tax | Float | L'importo dell'aliquota |
| title | String | Il nome dell'aliquota che comparirà in fattura |
| fe_value | String | Il codice dell'aliquota che verrà inserito nell'XML della fattura |
Elenco delle aliquote presenti
Richiesta di Esempio:
POST /api/taxes/?access_token={access_token} HTTP/1.1
Host: app.adamogestionale.it
Content-Type: application/json
$ curl
https://app.adamogestionale.it/api/incomes/ -X GET
-H "Authorization: Bearer {access_token}"
-H "Content-Type: application/json"
Risposta di esempio:
[
{
"Tax": {
"id": 1,
"tax": 0.03,
"title": "3% - Imp speciale di bollo, art 24",
"fe_value": "N2"
}
},
{
"Tax": {
"id": 2,
"tax": 0.22,
"title": "22%",
"fe_value": null
}
},
...
]
Accedendo all'endpoint:
GET /api/taxes/
Si può vedere l'elenco delle aliquote presenti a sistema.
Errori
Errore di esempio:
{
"name": "rate limit exceeded",
"url": "\/api\/invoices?access_token={token}"
}
In caso di errore vengono restituiti uno dei seguenti codici come status code della richiesta HTTP.
| Codice | Significato |
|---|---|
| 400 | Bad Request -- La tua richiesta non può essere accettata |
| 401 | Unauthorized -- Le tue credenziali non sono valide |
| 403 | Forbidden -- Non sei autorizzato ad accedere a questo endpoint |
| 404 | Not Found -- Non è possibile trovare l'indirizzo richiesto |
| 405 | Method Not Allowed -- Il metodo che hai utilizzato non è valido |
| 406 | Not Acceptable -- Hai richiesto un formato che non è json |
| 429 | Too Many Requests -- Troppe richieste in poco tempo |
| 500 | Internal Server Error -- Si è verificato un problema con il nostro server |
| 503 | Service Unavailable -- Siamo temporaneamente in manutenzione. |
In alcuni casi, quando è possibile fornire una descrizione dell'errore, viene inviato un oggetto d'errore insiema alla risposta.
Questo comprende un attributo name che indica la descrizione dell'errore e l'url che si è tentato di accedere.