Con queste API potrai arricchire i dati del tuo CRM con molte delle informazioni che già trovi disponibili in Atoka. In particolare in questo tutorial vedremo come ottenere ragione sociale, settore ATECO di appartenenza, natura giuridica, sede legale, ricavi, dipendenti, sito web, contatti email e telefonici, ma il codice si può facilmente adattare per ottenere qualsiasi dato delle API a cui tu abbia accesso.

Avrai bisogno di:

  • Partita IVA e/o Codice Fiscale delle aziende nel tuo CRM
  • Un token per autenticare le chiamate effettuate. Se non sei in possesso di un token contatta il tuo commerciale di riferimento. Custodisci il token come una password: è unico e non cedibile.

Il processo di arricchimento si svolgerà in due passaggi

  • Faremo una chiamata utilizzando la partita iva e/o il codice fiscale per identificare quale sia la miglior corrispondenza all’interno dei nostri sistemi per i tuoi dati. Il risultato sarà univocamente identificato da un id di Atoka che potrai salvare nel tuo database per saltare questo passaggio nei futuri aggiornamenti dei dati. Importante: questa chiamata non consuma crediti.
  • Con una seconda chiamata alle nostre API, consumando un credito, possiamo utilizzare l’id Atoka precedentemente ottenuto per scaricare le informazioni arricchite sull’azienda.

Iniziamo!

Per cercare aziende data una partita iva e/o codice fiscale è sufficiente interrogare l’endpoint companies con il parametro vat (partita iva), taxIds` (codice fiscale) e il tuo token in questo modo:

GET https://api.atoka.io/v2/companies?vat=02241890223&taxIds=02241890223&token=TOKEN&limit=10

Possiamo anche usare solo una tra partita iva e codice fiscale se non siamo a conoscenza di entrambi: per esempio se abbiamo solo la partita iva procederemo come questa chiamata

GET https://api.atoka.io/v2/companies?vat=02241890223&token=TOKEN&limit=10

La risposta, modificata per brevità, contiene:

  • items: è la lista dei risultati (aziende) che in questo caso, cercando per Partita IVA e/o Codice Fiscale, ha un solo elemento
  • id: è l’id che Atoka usa per identificare l’azienda
  • meta: contiene numero di risultati, ordine, limit ed offset.. Utili per paginare e ordinare
{
    "items": [{
        "id": "6da785b3adf2",
        "name": "SPAZIODATI S.R.L.",
        "country": "it",
        "fullAddress": "Via Adriano Olivetti, 13, 38122, Trento (TN)"
    }],
    "meta": {
        "count": 1,
        "limit": 1,
        "offset": 0,
        "ordering": "atoka"
    }
}

Ora che abbiamo l’id dell’azienda in Atoka, possiamo salvarlo nel nostro CRM per futuri aggiornamenti dei dati. Salvandolo possiamo evitare di fare la chiamata precedente, salvo ovviamente modifiche nei dati di input (piva e codice fiscale).

Effettuiamo ora la chiamata per avere tutte le informazioni disponibili sull’azienda:

GET https://api.atoka.io/v2/companies/6da785b3adf2?token=TOKEN
{
    "item": {
        "id": "6da785b3adf2",
        "name": "SPAZIODATI S.R.L.",
        "country": "it",
        "fullAddress": "Via Adriano Olivetti, 13, 38122, Trento (TN)",
        "base": {
            "legalName": "SPAZIODATI S.R.L.",
            "startup": false,
            "taxId": "02241890223",
            "vat": "02241890223",
            "active": true,
            "founded": "2012-02-13",
            "ateco": [{
                "code": "62.01.00",
                "description": "Produzione di software non connesso all'edizione",
                "rootCode": "J"
            }],
            "legalForms": [ ... ],
            "registeredAddress": { ... }
        },
        "web": {
            "description": "SpazioDati works on...",
            "feeds": [ ... ],
            "keywords": [ ... ],
            "languages": [ ... ],
            "logo": " ... ",
            "websites": [{
                "active": true,
                "url": "http://www.spaziodati.eu"
            }, {
                "active": true,
                "url": "http://www.blog.atoka.io"
            }, ... ]
        }
    }
}

Come puoi vedere i dati sono organizzati per “pacchetti” (base, web, ..): nell’esempio ne facciamo vedere solo alcuni di esempio, puoi consultare qui la lista completa dei pacchetti e delle informazioni che ognuno include. Abbiamo evidenziato quelli che ci interessa visualizzare nel nostro CRM: la ragione sociale, l’indirizzo, il codice ATECO e il sito web, ma ovviamente tutti gli altri campi che vedrai nei risultati possono essere utilizzati per l’arricchimento.

Usando le API Atoka+ è molto semplice creare un link ad Atoka per ogni azienda presente nel tuo CRM o ERP. Ti consigliamo di renderlo visibile e cliccabile dai tuoi utenti, in modo che possano raggiungere la scheda Atoka dell’azienda con dati sempre freschi ed aggiornati con un semplice click. Per farlo basta utilizzare il valore del campo id ottenuto dalle API e sostituirlo a questo indirizzo Atoka:

https://atoka.io/it/companies/-/<id>/

Per esempio utilizzando il risultato della chiamata illustrata precedentemente si otterebbe il seguente URL:

https://atoka.io/it/companies/-/6da785b3adf2/

Ma quanto mi costa?

Ogni azienda di cui chiedi il dettaglio dei dati consuma 1 credito. Nell’esempio vediamo che la prima chiamata non costa nessun credito, mentre la seconda costa 1 credito. Se chiami più volte le API anche per lo stesso soggetto consumerai 1 credito ogni volta.

Quali pacchetti ho a disposizione?

Qui puoi trovare la lista completa dei pacchetti e dei dati che essi contengono. Per ogni pacchetto sono indicate le informazioni che Atoka fornisce ed eventuali filtri applicabili, i quali possono essere utilizzati in modo analogo all’esempio del codice fiscale precedentemente illustrato. I pacchetti desiderati vengoni invece richiesti tramite il parametro packages. Ad esempio

GET https://api.atoka.io/v2/companies?active=true&packages=base,contacts&token=TOKEN&limit=10

Chiederà i pacchetti base e contacts delle prime 10 aziende risultanti. Alcuni pacchetti sono composti da informazioni annidate e sono indicati con un “.” e.g registeredAddress.distance mentre le liste sono indicate con “[]” e.g. ateco[].

Alcuni sono inoltre marcati con il simbolo ⚠️ ciò indica che per accedere a questi dati é necessario un accordo con il nostro provider dati e di conseguenza saranno automaticamente esclusi dalle risposte di Atoka nel caso il tuo token non sia configurato per utilizzarle. Se vuoi avere accesso a questi dati puoi richiederlo al tuo contatto vendite.

Il pacchetto “Base”

Il pacchetto base fornisce una panoramica ad alto livello dell’azienda cercata.

Campi disponibili Descrizione Tipologia dei dati Filtri applicabili
active L’azienda è attiva? true / false active
ateco[] Informazioni riguardanti il codice ATECO 2007 di una azienda lista di oggetti -
ateco[].code Codice ATECO 2007 riclassificato in modo da rappresentare in modo più accurato l’attività dell’azienda (il più specifico) stringa ateco, atecoExclude
ateco[].description Una breve descrizione del codice ATECO 2007 stringa -
ateco[].rootCode La classe del codice ATECO 2007 stringa -
cciaa Insieme a rea costituisce le informazioni identificative fornite dalla Camera di Commercio (questo è il codice provincia REA, e.g. “RM” per “Roma”) stringa regNumbers, ccia
rea Insieme a cciaa costituisce le informazioni identificative fornite dalla Camera di Commercio (REA é l’acronimo di Repertorio Economico Amministrativo) stringa regNumbers
founded Quando l’azienda ha iniziato la sua attività yyyy-mm-dd ageMin, ageMax, foundedFrom, foundedTo, age, ageUnknown
gov L’azienda è una pubblica amministrazione? true / false gov
govCode Codice identificativo della Pubblica Amministrazione stringa govCodes
govType La classificazione ufficiale ISTAT (se la compagnia è una PA) stringa govTypes, govTypesExclude
inGroup L’azienda è parte di un gruppo? true / false -
legalClass Classificazione della forma giuridica dell’azienda (e.g. “Società Di Capitale”) stringa legalClasses, legalClassesExclude
legalForms Classificazione della forma giuridica dell’azienda (e.g. “Società Di Capitale”) lista di oggetti -
legalForms[].level Il primo livello corrisponde a legalClass, l’utilizzo di questo campo è deprecato stringa -
legalForms[].name Classificazione della forma giuridica dell’azienda (e.g. “Società Di Capitale”) stringa legalForms
nace Codice NACE (il più specifico) lista di oggetti -
nace[].code Codice NACE (il più specifico) stringa -
nace[].description Una breve descrizione del codice NACE stringa -
nace[].rootCode La radice del codice NACE stringa -
noRea L’azienda é una no rea? true / false noRea
pec[] Lista degli indirizzi di posta elettronica certificata (PEC) associati a questa azienda stringa -
registeredAddress.distance La distanza della sede legale rispetto alle coordinate fornite numero distance
registeredAddress.fullAddress Indirizzo completo della sede legale stringa -
registeredAddress.hamlet Frazione della sede legale stringa -
registeredAddress.lat Latitudine della sede legale numero lat
registeredAddress.latlonPrecision Precisione della latitudine e longitudine numero -
registeredAddress.lon Longitudine della sede legale numero lon
registeredAddress.macroregion La macroregione (e.g. “Sud”) della sede legale stringa macroregions, macroregionsExclude, anyAddress
registeredAddress.municipality Comune della sede legale stringa municipalities, municipalitiesExclude, anyAddress
registeredAddress.postcode Codice postale della sede legale stringa postcodes, postcodesExclude, anyAddress
registeredAddress.province Provincia della sede legale stringa provinces, provincesExclude, anyAddress
registeredAddress.provinceCode Codice della provincia della sede legale stringa -
registeredAddress.region Regione della sede legale stringa regions, regionsExclude, anyAddress
registeredAddress.state Stato della sede legale stringa -
registeredAddress.streetName Nome della strada della sede legale stringa -
registeredAddress.streetNumber Numero civico della sede legale stringa -
registeredAddress.toponym Toponimo descrittivo dell’indirizzo (e.g. “via”, “piazza”, ect.) della sede legale stringa -
signs Le insegne che identificano un’azienda lista di oggetti signs, signsQuery
signs[].sign L’insegna che identifica un’azienda stringa -
startup L’azienda è una startup? true / false startup
taxId Il codice fiscale dell’azienda stringa taxIds, regNumbers
vat La partita IVA di un’azienda stringa vat, regNumbers

Il pacchetto “Contacts”

Il pacchetto contacts fornisce delle informazioni di contatto dell’azienda cercata.

Campi disponibili Descrizione Tipologia dei dati Filtri applicabili
emails Lista di indirizzi email dell’azienda lista di oggetti -
emails[].address Indirizzo email stringa -
emails[].type Categoria dell’indirizzo email "administration", "info", "management", "marketing", "purchases", "sales", "support", "technician", ... emails
emails[].verified L’indirizzo esiste ed è in grado di ricevere messaggi true / false -
fax[] Lista di numeri fax associati all’azienda lista di stringhe -
phones Lista di recapiti telefonici dell’azienda lista di oggetti -
phones[].fullAddress Indirizzo completo del luogo associato al numero di telefono stringa -
phones[].locationId Identificatore del luogo associato al numero di telefono stringa -
phones[].number Numero telefonico associato all’azienda stringa -
phones[].source La fonte dalla quale proviene il numero di telefono "phone books", "web" -
phones[].verified Il numero di telefono è stato verificato tramite un controllo incrociato tra diverse fonti o meno? true / false -

Il pacchetto “Economics”

Il pacchetto economics fornisce informazioni economiche di carattere generale sull’azienda cercata, come ad esempio il bilancio e il numero di dipendenti.

Campi disponibili Descrizione Tipologia dei dati Filtri applicabili
balanceSheets Bilanci associati all’azienda lista di oggetti -
balanceSheets[].currency La valuta utilizzata nel bilancio stringa -
balanceSheets[].date La data di chiusura del bilancio data -
balanceSheets[].latest Questo è l’ultima voce disponibile? true / false -
balanceSheets[].revenue Ricavi numero revenueMin, revenueMax, revenueUnknown
balanceSheets[].revenueTrend Trend ricavi numero revenueTrends
balanceSheets[].year Anno di chiusura del bilancio numero -
capitalStock.value L’ammontare del capitale sociale o azionario di una azienda: più specificatamente comprende il capitale nominale (o autorizzato) che é l’ammontare di capitale sociale che l’azienda é autorizzata dai suoi documenti costituzionali ad emettere ad azionisti. numero -
employees Dati relativi ai dipendenti associati all’azienda lista di oggetti -
employees[].date Data relativa al valore di dipendenti data -
employees[].latest Questo è il dato relativo ai dipendenti più recente true / false -
employees[].value Numero totale di dipendenti numero employeesMin, employeesMax, employeesUnknown
employees[].year Anno di questa informazione numero -
public La compagnia è quotata in borsa? true / false -

Il pacchetto “Entities”

Il pacchetto entities fornisce delle informazioni estratte automaticamente da varie fonti e documenti come per esempio siti web, profili social, dichiarazioni di incorporazioni, etc. Ogni entità è rappresentata da un’etichetta e da un URL Wikipedia che può essere utilizzato per avere maggiori informazioni (incluse traduzioni in lingue straniere) tramite Wikidata o DBpedia.

Le entità sono inoltre suddivise in base alla lingua : de, it, fr, pt ed en. Ogni gruppo di informazioni è fornito come una lista la cui chiave è la lingua (per esempio de[].name ofr[].score)e contiene i seguenti campi

Campi disponibili Descrizione Tipologia dei dati Filtri applicabili
language La lingua (de, fr, it ..) oggetto -
language[].name Il nome della entità stringa -
language[].score Probabilità che tale entità sia associata a questa azienda numero -
language[].uri Wikipedia/DBpedia URI unico rappresentante questa entità stringa entities

Il pacchetto “Locations”

Il pacchetto locations fornisce informazioni geografiche di carattere generale sull’azienda e alle sue sedi locali.

Campi disponibili Descrizione Tipologia dei dati Filtri applicabili
anyAddress.macroregions[] Le macroregioni (e.g. “Sud”) in cui si trova almeno una sede dell’azienda lista di stringhe macroregions, macroregionsExclude, anyAddress
anyAddress.municipalities[] Le municipalità in cui si trova almeno una sede dell’azienda lista di stringhe municipalities, municipalitiesExclude, anyAddress
anyAddress.postcodes[] I codici postali in cui si trova almeno una sede dell’azienda lista di stringhe postcodes, postcodesExclude, anyAddress
anyAddress.provinces[] Le province in cui si trova almeno una sede dell’azienda lista di stringhe provinces, provincesExclude, anyAddress
anyAddress.regions[] Le regioni in cui si trova almeno una sede dell’azienda lista di stringhe regions, regionsExclude, anyAddress
count Il numero totale di sedi secondarie (non inclusa la sede principale dell’azienda) number -
totalCount Il numero totale di sedi (inclusa la sede principale dell’azienda) stringa -
items Lista delle prime 10 sedi locali dell’azienda lista di oggetti -
items[].id Id univoco del luogo riutilizzabile in tutte le API di Atoka stringa -
items[].address.distance La distanza della sede rispetto alle coordinate fornite numero distance
items[].address.fullAddress Indirizzo completo stringa -
items[].address.hamlet Frazione della sede locale stringa -
items[].address.lat Latitudine della sede locale numero lat
items[].address.latlonPrecision Precisione della latitudine e longitudine della sede locale numero -
items[].address.lon Longitudine della sede locale numero lon
items[].address.macroregion La macroregione (e.g. “Sud”) della sede locale stringa -
items[].address.municipality Comune della sede locale stringa -
items[].address.postcode Codice postale della sede locale stringa -
items[].address.province Provincia della sede locale stringa -
items[].address.provinceCode Codice della provincia della sede locale stringa -
items[].address.region Regione della sede locale stringa regions, regionsExclude, anyAddress
items[].address.state Stato della sede locale stringa -
items[].address.streetName Nome della strada della sede locale stringa -
items[].address.streetNumber Numero civico della sede locale stringa -
items[].address.toponym Toponimo descrittivo dell’indirizzo (e.g. “via”, “piazza”, ect.) della sede locale stringa -

Il pacchetto “People”

Il pacchetto people contiene la lista dei ruoli ricoperti da persone o aziende all’interno dell’azienda cercata. Sono fornite le informazioni al massimo per i primi 10 ruoli dell’azienda.

Campi disponibili Descrizione Tipologia dei dati Filtri applicabili
count Numero delle persone per le cui é conosciuta la posizione all’interno dell’azienda numero -
items Lista di persone lista di oggetti -
items[].birthDate Data di nascita della persona che ricopre la posizione stringa -
items[].cLevels[] Le posizioni C-level sono le posizioni dirigenziali di alto livello o di livello più elevato in un’azienda. Ad esempio, un CEO (Chief Executive Officer) svolge un lavoro di livello C stringa -
items[].emails[].address Indirizzo email stringa -
items[].emails[].verified L’indirizzo email esiste ed è in grado di ricevere messaggi true / false -
items[].familyName Cognome della persona che ricopre la posizione stringa -
items[].gender Sesso della persona che ricopre la posizione stringa -
items[].givenName Nome della persona che ricopre la posizione stringa -
items[].id Atoka ID della persona che ricopre la posizione stringa -
items[].name Nome della posizione ricoperta da questa persona stringa -
roles[].name Nome della posizione stringa -
roles[].since Data di inizio della posizione data -

Il pacchetto “Shares”

Il pacchetto shares contiene informazioni di carattere generale sulle partecipazioni dell’azienda.

Campi disponibili Descrizione Tipologia dei dati Filtri applicabili
beneficialOwnerOf Lista dei beneficiari effettivi lista di oggetti -
beneficialOwnerOf[].active Il beneficiario effettivo è attivo? true / false -
beneficialOwnerOf[].id Atoka ID del beneficiario effettivo stringa -
beneficialOwnerOf[].legalName Nome legale del beneficiario effettivo stringa -
beneficialOwnerOf[].name Nome del beneficiario effettivo stringa -
beneficialOwners Lista dei beneficiari effettivi lista di oggetti -
beneficialOwners[].active Il beneficiario effettivo è attivo? (valido se company=true true / false -
beneficialOwners[].company Il beneficiario dell’azienda è un’azienda o una persona? true / false -
beneficialOwners[].id Atoka ID del beneficiario effettivo stringa -
beneficialOwners[].legalName Nome legale del beneficiario effettivo (valido se company=true) stringa -
beneficialOwners[].name Nome del beneficiario effettivo stringa -
shareholders Lista di shareholders lista di oggetti -
shareholders[].active L’azienda beneficiaria è attiva? (valido se company=true) true / false -
shareholders[].amount Quantità possedute numero -
shareholders[].company Il beneficiario dell’azienda è un’azienda o una persona? true / false -
shareholders[].id Atoka ID dell’azienda o della persona in possesso dello share stringa -
shareholders[].lastUpdate L’ultima volta che la posizione é stata aggiornata data -
shareholders[].legalName Nome legale dell’azienda beneficiaria (valido se company=true) stringa -
shareholders[].name Nome del beneficiario effettivo stringa -
shareholders[].ratio Percentuale posseduta numero -
shareholders[].typeOfRight La tipologia di diritti esercitati sull’azienda stringa -
sharesOwned Lista di shares possedute lista di oggetti -
sharesOwned[].active L’azienda di cui possiede partecipazioni è attiva? true / false -
sharesOwned[].amount Valore delle partecipazioni possedute numero -
sharesOwned[].id Atoka ID dell’azienda di cui possiede partecipazioni stringa -
sharesOwned[].lastUpdate L’ultima volta che i dati della partecipazione sono stati aggiornati. data -
sharesOwned[].legalName Nome legale dell’azienda di cui possiede partecipazioni stringa -
sharesOwned[].name Nome dell’azienda di cui possiede partecipazioni stringa -
sharesOwned[].ratio Percentuale posseduta numero -
sharesOwned[].typeOfRight La tipologia di diritti esercitati sullo share stringa -

Il pacchetto “Web”

Il pacchetto web contiene informazioni di carattere generale sulla presenza in internet dell’azienda.

Campi disponibili Descrizione Tipologia dei dati Filtri applicabili
description Descrizione dell’azienda stringa -
feeds[] RSS feeds correlati a questa azienda stringa -
history Storia dell’azienda (se presente) stringa -
keywords[] Parole chiave che descrivono l’azienda e le sue attività. Queste sono parole dichiarate dall’azienda stessa nel HTML tag META keywords e description stringa -
languages[] Lista delle lingue “parlate” dall’azienda nel web; questa informazione può provenire sia dal sito web che da social networks o da altre risorse online. Le lingue sono rappresentate dal loro codice ISO 639-1 stringa -
logo Logo dell’azienda stringa -
slogan Motto dell’azienda stringa -
websites Lista di siti web associati all’azienda lista di oggetti -
websites[].active Il sito web è attivo o no? true / false -
websites[].confidence Probabilità che il sito web sia associato all’azienda numero -
websites[].url URL del sito web stringa websitesDomains
websitesContent[] Parti rilevanti del contenuto del sito ottenute in seguito alla ricerca di testo all’interno del sito web. stringa websitesContent, websitesContentTag, websitesContentTagStart, websitesContentTagEnd
wikipediaUri La pagina Wikipedia dell’azienda stringa -

Risorse utili

  • JS Fiddle con il codice per il tutorial, il riquadro in basso a destra è funzionante, inserite il vostro token, cliccate vai…
  • Qui puoi controllare i crediti disponibili e consumati sul tuo token.

Contattaci subito per provare Atoka

Altre informazioni sui dati Atoka

Quali Dati

I numeri, le fonti, i casi d’uso.

Atoka Enterprise API

I Big Data a portata di mano.

Tutorial Enterprise API

Una guida rapida per usare al meglio le nostre API.

Struttura dei dati

L’architettura, fonti e contenuti, gli output di esempio.