Documentazione API Contabilità facile online (Json RPC v. 2.0)

Prima d’iniziare

Protocollo

Lo scambio dati è basato sul protocollo JSON-RPC v.2.0.

Per l’utilizzo con il linguaggio PHP scarica JsonRPC v2 client (zip).

Autenticazione

Per l’utilizzo delle API di Contabilità facile online l’utente deve disporre di un nome utente e di un token d’autenticazione.

URL API

URL a cui collegarsi per l’utilizzo delle API: https://api.contabilitafacileonline.it/api/APIjsonrpc2.php

Supporto

In caso di necessità richiedi supporto per l’utilizzo delle API contattandoci

• via email all’indirizzo api@contabilitafacile.it oppure
• chiamaci al 0481 091172.

Flusso di lavoro

Campi

• Le date devono avere il formato aaaa-mm-gg

  { 
  	"datadocumento":"2012-11-30" 
  }

• Il separatore dei decimale è il punto

  //es. 105789.2568

• I campi jolly non hanno un preciso formato. Questi campi vengono utilizzati per inviare dei campi personalizzati. In sede di richiesta della personalizzazione viene anche stabilita la formattazione con cui devono essere inviati i dati.

   'jolly' : 'campo1=valore1,campo2=valore2' //esempio di formattazione, ma non vincolante

• Ci sono campi il cui valore può essere letto dalle tabelle di conversione visibili nell’ambiente di Contabilità facile online .

Metodi di controllo

Test di connessione

Metodo: ping()

Metodo per testare la connessione alle API.

input JSON

{ 
"oggetto-input" 
}

JSON output

{ 
"pong": "oggetto-input"
}

Anagrafiche soggetti Clienti e Fornitori

Metodo: soggetto()

Input JSON

I dati inviati per l’inserimento dell’anagrafica di un soggetto sono divisi in 4 sezioni incapsulate in un array associativo multidimensionale:

La sezione principale (d’ora in poi denominata TESTATA del soggetto (T) ).

La sezione RAPPORTI (R[]): è un array di array associativi. Con un soggetto si possono avere tipologie di rapporto diverso (es. cliente, fornitore, ecc.). Per ogni tipologia viene inserito un array con i relativi dati. Deve essere inviato almeno un rapporto.

La sezione SEDI (S[]): è un array di array associativi. Un soggetto può avere più sedi (es. sede amministrativa, sede di spedizione, sede di fatturazione…). La sezione è facoltativa.

La sezione CONTATTI (C[]): è un array di array associativi. Per ogni soggetto possono essere inseriti più contatti (persone di riferimento) come ad esempio il responsabile vendite, amministratore,…
La sezione è facoltativa.

{
'ragionesociale': '', 
'cognome': '',
'nome': '',
'partitaiva': '',
'codicefiscale': '',
'tiposoggetto': '',
'jolly': '',
'sedi': [
	{
	'idsede': '',
	'tiposede': '',
	'insegna': '',
	'indirizzo': '',
	'cap': '',
	'comune': '',
	'localita': '',
	'provincia': '',
	'nazioneiso': '',
	'nazioneuic': '',
	'telefono': '',
	'fax': ''
	},
	{
	'idsede': '',
	'tiposede': '',
	'insegna': '',
	'indirizzo': '',
	'cap': '',
	'comune': '',
	'localita': '',
	'provincia': '',
	'nazioneiso': '',
	'nazioneuic': '',
	'telefono': '',
	'fax': ''
	},
	...],
'rapporti': [
	{
	'tiporapporto': '',
	'codicerapporto': '',
	'settore': '',
	'sedeinviodoc': '',
	'linguadoc': '',
	'email': '',
	'modpagamento': '',
	'banca': '',
	'iban': '',
	'swift': '',
	'jolly': ''
	},
	{
	'tiporapporto': '',
	'codicerapporto': '',
	'settore': '',
	'sedeinviodoc': '',
	'linguadoc': '',
	'email': '',
	'modpagamento': '',
	'banca': '',
	'iban': '',
	'swift': '',
	'jolly': ''
	},
	...], 
'contatti':[
	{
	'nome': '',
	'cognome': '',
	'ufficio': '',
	'ufficio2': '',
	'fax': '',
	'cellulare': '',
	'cellulare2': '',
	'email': '',
	'jolly': ''
	},
	{
	'nome': '',
	'cognome': '',
	'ufficio': '',
	'ufficio2': '',
	'fax': '',
	'cellulare': '',
	'cellulare2': '',
	'email': '',
	'jolly': ''
	},
	...] 
}

Esempio inserimento soggetto (PHP, Javascript)

JSON output

// soggetto inserito
{
'code': '0',
'msg' : 'ok'
}
// Errore nei dati
{
'code': '-2',
'msg' : 'si sono verificati i seguenti errori: descrizione problema'
}
// Errore d'autenticazione
{
'code' : '-1', 
'msg' : 'auth error'
}

Riepilogo campi

Articoli di Magazzino

Metodo: articolo()

Input JSON

I dati inviati per l’inserimento dell’anagrafica di un soggetto sono divisi in 4 sezioni incapsulate in un array associativo multidimensionale:

La sezione principale (d’ora in poi denominata TESTATA dell’articolo (T) ).

La sezione FORNITORI (F[]): è un array di array associativi. Per la gestione degli intercambiabili è possibile inserire i codice che i fornitori utilizzano per identificare l’articolo. La sezione è facoltativa.

La sezione LOTTI (L[]): è un array di array associativi. Sezione per l’inserimento dei dati di riferimento dei lotti dell’articolo . La sezione è facoltativa.

{ 
'codarticolo': '',
'codbarre': '',
'categoria': '',
'sottocategoria': '',
'descarticolo': '',
'descarticoloest': '',
'unitmisura': '',
'prezzounitarticolo': '',
'aliquota': '',
'gestmagazzino': '',
'conto': '',
'jolly': '',
'fornitori': [
	{
	'tipoidfornitore': '',
	'idfornitore': '',
	'codartfornitore': '',
	'jolly': ''
	},
	{
	'tipoidfornitore': '',
	'idfornitore': '',
	'codartfornitore':'',
	'jolly': ''
	},
	...]
'lotti': [
	{
	'codlotto': '',
	'desclotto': '',
	'notelotto':'',
	'jolly': ''
	},
	{
	'codlotto': '',
	'desclotto': '',
	'notelotto':'',
	'jolly': ''
	},
	...]
}

Esempio inserimento articolo (PHP, Javascript)

JSON output

// articolo inserito
{
'code': '0',
'msg' : 'ok'
}
// Errore nei dati
{
'code': '-2',
'msg' : 'si sono verificati i seguenti errori: descrizione problema'
}
// Errore d'autenticazione
{
'code' : '-1', 
'msg' : 'auth error'
}

Riepilogo campi

Contabilità – Documenti/Operazioni

I dati inviati per l’inserimento di un documento od operazione sono divisi in 3 sezioni incapsulate in un array associativo multidimensionale:

La sezione principale (d’ora in poi denominata TESTATA del documento/operazione (T))

La sezione DETTAGLIO (D): è un array di array associativi in quanto ogni riga di dettaglio viene inserita come un record.

La sezione ZOCCOLO (Z): è un array di array associativi. In questa sezioni vengono inserite informazioni integrative come ad esempio le ritenute fiscali e ritenute previdenziali.

Fatture, Note di Accredito, Note di Addebito

La tipologia di fattura viene indicata dal valore del campo tipo. Di seguito viene specificato il valore che il campo deve assumere in base al tipo di documento inviato.

Metodo: documento()

Parametri input JSON

{ 
'rinvio' : 'NO', 
'tipodocumento': 'codice-tipo-documento', 
'unitaterritoriale': '', 
'dataregistrazione':'aaaa-mm-gg', 
'numerodocumento': 'n°-documento', 
'datadocumento': 'aaaa-mm-gg', 
'regsezionaleiva': '', 
'totaledocumento':'',
'tipoidsoggetto': '',
'idsoggetto':'', 
'modellocontabile':'', 
'modpagamento': '', 
'oneridiriscossione': '',  
'riferimentidoc':'',
'compextracdal': '', 
'compextracal': '', 
'jolly': '', 
'dettaglio' : [ 
	{ 
	'importo' : '', 
	'tipoimportoiva' : '', 
	'aliquota' : '',
	'soggettoritenuta': '', 
	'conto': '', 
	'settconto': '', 
	'jolly': ''
	},
	{ 
	'importo' : '', 
	'tipoimportoiva' : '', 
	'aliquota' : '',
	'soggettoritenuta': '', 
	'conto': '', 
	'settconto': '', 
	'jolly': ''
	},
	... ], 
'zoccolo' : [ 
	{ 
	'impritenutafiscale': '', 
	'percritenutafiscale' : '', 
	'totritenutafiscale' : '', 
	'impritenutafiscale': '', 
	'percritenutaprevid': '', 
	'totritenutaprevid':'', 
	'jolly':''
	},
	{ 
	'impritenutafiscale': '', 
	'percritenutafiscale' : '', 
	'totritenutafiscale' : '', 
	'impritenutafiscale': '', 
	'percritenutaprevid': '', 
	'totritenutaprevid':'', 
	'jolly':''
	}, 
	... ] 
}

Esempio inserimento fattura (PHP, Javascript)

JSON output

// documento inserito nella coda e coda elaborata totalmente
{
'code' : '0', 
'msg' : 'ok', 
'id' : 'MOAS..............................'//stringa identificativa
}
// documento inserito ed elaborato ma altri elementi nella coda sono in errore
{
'code' : '0', 
'msg' : 'ok, ma coda sincronizzazione con altri elementi in errore', 
'id' : 'MOAS..............................'//stringa identificativa
}
// Errore: documento in errore
{
'code' : '-3', 
'msg' : 'documento in errore', 
'id' : 'MOAS..............................' //stringa identificativa
}
// Errore: tipodocumento mancante o inesistente, l'elemento viene scartato
{
'code' : '-2', 
'msg' : 'tipodocumento errato o mancante'
}
// Errore d'autenticazione
{
'code' : '-1', 
'msg' : 'auth error'
}

Riepilogo campi

Incassi e Pagamenti, Corrispettivi, Ricevute Fiscali

La tipologia di operazione viene stabilita dal valore del campo tipo. Di seguito viene specificato il valore che il campo deve assumere in base al tipo di operazione inviata.

Metodo: documento()

input JSON

    { 
'rinvio' : 'NO', 
'tipodocumento': '30', 
'unitaterritoriale': '', 
'dataregistrazione': 'aaaa-mm-gg',
'numerodocumento': '', 
'datadocumento': 'aaaa-mm-gg', 
'regsezionaleiva': '', 
'totaledocumento': '',
'tipoidsoggetto' : '',
'idsoggetto':'', 
'modellocontabile':'',
'modpagamento': '',  
'riferimentidocumento': '', 
'compextracdal': '', 
'compextracal': '', 
'jolly': '', 
'dettaglio' : [ 
	{
   	'importo' : '', 
	'tipoimportoiva' : '', 
	'aliquota' : '', 
	'conto': '', 
	'settconto': '', 
	'jolly': ''
	},
	{
   	'importo' : '', 
	'tipoimportoiva' : '', 
	'aliquota' : '', 
	'conto': '', 
	'settconto': '', 
	'jolly': ''
	},... ] 
}

Esempio inserimento Corrispettivi (PHP, Javascript)

JSON output

// documento inserito nella coda e coda elaborata totalmente
{
'code' : '0', 
'msg' : 'ok', 
'id' : 'MOAS..............................'//stringa identificativa
}
// documento inserito ed elaborato ma altri elementi nella coda sono in errore
{
'code' : '0', 
'msg' : 'ok, ma coda sincronizzazione con altri elementi in errore', 
'id' : 'MOAS..............................'//stringa identificativa
}
// Errore: documento in errore
{
'code' : '-3', 
'msg' : 'documento in errore', 
'id' : 'MOAS..............................' //stringa identificativa
}
// Errore: tipodocumento mancante o inesistente, l'elemento viene scartato
{
'code' : '-2', 
'msg' : 'tipodocumento errato o mancante'
}
// Errore d'autenticazione
{
'code' : '-1', 
'msg' : 'auth error'
}

Riepilogo campi

Documenti Ciclo Merci

I dati inviati per l’inserimento di un documento sono divisi in 2 sezioni incapsulate in un array associativo multidimensionale:

La sezione principale (d’ora in poi denominata TESTATA del documento (T) ): dati principali.

La sezione DETTAGLIO (D[])

Preventivi, Ordini, Rapporti Intervento Tecnico, DDT

Metodo: documento

input JSON

    
{ 
'rinvio' : '', 
'tipodocumento': '', 
'unitaterritoriale': '', 
'numerodocumento': '', 
'datadocumento':'aaaa-mm-gg', 
'dataemissionedocumento':'aaaa-mm-gg',
'regsezionaleiva': '', 
'totaledocumento': '', 
'tipoidsoggetto':'',
'idsoggetto':'', 
'tipoidvenditore':'',
'idvenditore':'',
'modellocontabile': '', 
'modpagamento': '',
'modpagamentoold': '', 
'riferimentidoc': '',
'idsedefattura': '',
'competenze': '',
'compdata': '',
'compquota': '',
'compextracdal': '', 
'compextracal': '', 
'jolly': '', 
'dettaglio' : [ 
	{
	'codarticolo': '', 
	'codarticoloj1': '',
	'codarticoloj2': '',
	'codarticololotto': '',
	'codbarre' : '', 
	'descarticolo' : '', 
	'qtarticolo' : '', 
	'unitmisura' : '', 
	'prezzounitarticolo': '', 
	'scontoperc': '', 
	'importo' : '', 
	'caumagazzino': '', 
	'tipoimportoiva' : '', 
	'aliquota' : '', 
	'conto': '', 
	'settconto': '', 
	'jolly':''
	}, 
	{
	'codarticolo': '', 
	'codarticoloj1': '',
	'codarticoloj2': '',
	'codarticololotto': '',
	'codbarre' : '', 
	'descarticolo' : '', 
	'qtarticolo' : '', 
	'unitmisura' : '', 
	'prezzounitarticolo': '', 
	'scontoperc': '', 
	'importo' : '', 
	'caumagazzino': '', 
	'tipoimportoiva' : '', 
	'aliquota' : '', 
	'conto': '', 
	'settconto': '', 
	'jolly':''
	},
	... ] 
}

Esempio inserimento Corrispettivi (PHP, Javascript)

output JSON

// documento inserito nella coda e coda elaborata totalmente
{
'code' : '0', 
'msg' : 'ok', 
'id' : 'MOAS..............................'//stringa identificativa
}
// documento inserito ed elaborato ma altri elementi nella coda sono in errore
{
'code' : '0', 
'msg' : 'ok, ma coda sincronizzazione con altri elementi in errore', 
'id' : 'MOAS..............................'//stringa identificativa
}
// Errore: documento in errore
{
'code' : '-3', 
'msg' : 'documento in errore', 
'id' : 'MOAS..............................' //stringa identificativa
}
// Errore: tipodocumento mancante o inesistente, l'elemento viene scartato
{
'code' : '-2', 
'msg' : 'tipodocumento errato o mancante'
}
// Errore d'autenticazione
{
'code' : '-1', 
'msg' : 'auth error'
}

Riepilogo campi

Errori

Errore d’autenticazione:

{
'code' : '-1', 
'msg' : 'auth error'
}

Manca il tipo documento, quindi è impossibile inserirlo nel database:

{
'code' : '-2', 
'msg' : 'tipodocumento errato o mancante');
}

Documento inserito in coda, ma l’elaborazione della coda s’è fermata ad un certo punto per qualche problema:

{
'code' : '-3', 
'msg' : 'documento in errore', 
'id' : 'MOAS..............................' //stringa identificativa
}