In questo tutorial vedremo come utilizzare per la prima volta l’API di Company Search, per ricavare ragione sociale e sede legale di un’azienda data la sua partita IVA.

Risorse utili

  • Documentazione delle API di Company Search che utilizzeremo.
  • 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, e qui trovi informazioni più dettagliate sui crediti.

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?packages=base&regNumbers=02241890223&token=TOKEN&limit=10

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

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

o solo il codice fiscale (parametro taxIds):

GET https://api.atoka.io/v2/companies?packages=base&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, ha un solo elemento;
  • meta: contiene numero di risultati, ordine, limit ed offset.. Utili per paginare e ordinare;
  • id: è l’id che Atoka usa per identificare l’azienda, usato da molte altre API;
  • name, fullAddress: le informazioni che cercavamo!
  • base: contiene tutte le informazioni fornite dal package base, dettaglio dell’indirizzo, codice ATECO, natura giuridica, data di fondazione ed altro ancora.
{
    "items": [{
        "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": { ... }
        },
    }],
    "meta": {
        "count": 1,
        "limit": 1,
        "offset": 0,
        "ordering": "atoka"
    }
}

Ma quanto mi costa?

Ogni azienda con almeno un pacchetto di dati costa 1 credito. La richiesta nell’esempio consumerà 1 credito companies:* perché le API ci hanno restituito solo 1 azienda e abbiamo richiesto il pacchetto base (utilizzando package=base nella richiesta).

Atoka Trick

Nel caso in cui non ci interessino tutti i dettagli presenti nel pacchetto base come l’ATECO, possiamo evitare di spendere crediti non chiedendo il pacchetto base nella richiesta

GET https://api.atoka.io/v2/companies?vat=02241890223&token=TOKEN&limit=10  // costa 0 crediti
{
    "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"
    }
}

Per informazioni più dettagliate sul funzionamento dei crediti consulta la nostra documentazione.