Atoka+ API

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 regNumbers e il tuo token in questo modo:

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

Possiamo anche usare solo la partita iva (parametro vat):

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

o solo il codice fiscale (parametro taxIds):

GET https://api.atoka.io/v2/companies?taxIds=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.

Crea un link ad Atoka nel tuo CRM

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.

Il pacchetto “Contacts”

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

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.

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

Il pacchetto “Groups”

Il pacchetto groups fornisce delle informazioni sui gruppi di aziende di cui fa parte questo soggetto.

Il pacchetto “Locations”

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

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.

Il pacchetto “Shares”

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

Il pacchetto “Socials”

Il pacchetto socials contiene informazioni riguardo gli account social legati all’azienda.

Il pacchetto “Technologies”

Il pacchetto technologies contiene informazioni riguardo alle tecnologie identificate nei siti web legati all’azienda.

Il pacchetto “Web”

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

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.