NAV
shell http

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:

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.
Mail 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

Mail

  {
      "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:

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:

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:

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.

Email

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.