Gestire liste di aziende

Novità! Puoi gestire direttamente nelle API le tue liste di aziende. In questa sezione del tutorial ti mostreremo le principali funzionalità disponibili.

Prima di cominciare: Identifica i tuoi utenti

Per garantire l’accesso ad una determinata lista solo al suo proprietario, o a chi è stato esplicitamente garantito l’accesso, è necessario che all’interno della chiamata sia inviato anche il parametro 'appUserId' contenente l’identificativo dell’utente della tua applicazione.

Creiamo il nostro primo utente:

$ curl -XPOST https://api.atoka.io/v2/app/users/andrea_sd -d 'token=TOKEN' -d 'name=Andrea'
{"item":{"appUserId":"andrea_sd","name":"Andrea"}}

Questo utente sarà visibile al solo token che l’ha creato.

Crea la tua prima lista

Il nostro collega Andrea (id interno 'andrea_sd') vuole creare una lista dei suoi clienti e aggiungere alcune note alla lista.

$ curl -XPOST https://api.atoka.io/v2/lists \
  -d 'token=TOKEN' \
  -d 'appUserId=andrea_sd' \
  -d 'name=clienti' \
  -d 'items=6da785b3adf2,443395eaf81e,32bbc5e1c8cf' \
  -d 'extraData={"note": "lista clienti, bozza"}' \
  -d 'type=company'

{
  "item": {
    "id": "24",
   "name": "clienti",
    "extraData": {"note": "lista clienti, bozza"},
    "listLength": 3,
    "owner": {
       "application": "default application",
       "id": "andrea_sd",
       "name": "Andrea"
    },
    "type": "company"
  }
}

Abbiamo quindi creato una lista chiamata "clienti", con all'interno 3 aziende, a cui abbiamo aggiunto anche alcuni dati (la data di aggiornamento). Extra data è infatti un oggetto json in cui l’utente può salvare (e successivamente cercare) dati da associare alla lista che sono caratteristici del proprio use case. Ora possiamo utilizzare la nostra lista nella Company Search utilizzando il parametro 'lists' con valore l’id della nostra lista.

https://api.atoka.io/v2/companies?lists=24&token=TOKEN&appUserId=andrea_sd
  "items": [{
	"id": "6da785b3adf2",
	"name": "SPAZIODATI S.R.L.",
	"fullAddress": "Via Adriano Olivetti, 13, 38122, Trento (TN)",
       "country": "it"
  },/* omesso */]

 

Inoltre in ogni ricerca effettuata puoi chiedere di evidenziare le aziende che sono contenute nelle tue liste, utilizzando il parametro 'showLists'.

https://api.atoka.io/v2/companies?showLists=true&municipalities=Trento&packages=base&token=TOKEN&appUserId=andrea_sd
  "items": [{
	"id": "6da785b3adf2",
	"name": "SPAZIODATI S.R.L.",
	"fullAddress": "Via Adriano Olivetti, 13, 38122, Trento (TN)",
       "country": "it",
       "base": {...},
       "lists": [{ 
         "id": 24,
         "name": "clienti",
         "extraData": {"note": "lista clienti, bozza"}
  },/* omesso */]

 

Modifica una lista

È passato un po' di tempo, la lista dei clienti (fortunatamente) si è arricchita e Andrea vorrebbe aggiornare la lista nelle API.
Aggiunge i due nuovi clienti con il parametro 'add', toglie il cliente che ha perso con 'remove' e aggiorna anche le note usando sempre 'extraData':

$ curl -XPUT https://api.atoka.io/v2/lists/24 \
  -d 'token=TOKEN' \
  -d 'appUserId=andrea_sd' \
  -d 'add=96cc7194709d,ed4ae53967a2' \
  -d 'remove=32bbc5e1c8cf' \
  -d 'extraData={"updated": "2017-12-20"}'

{
  "item": {
    "id": "24",
    "name": "clienti",
    "extraData": {"note": "lista clienti - pronta"},
    "listLength": 4,
    "owner": {
       "application": "default application",
       "id": "andrea_sd",
       "name": "Andrea"
    },
    "type": "company"
  }
}

 

Condividi una lista

Ora Andrea è pronto a condividere la lista di clienti con il collega Davide, che utilizza anche lui lo stesso token ma ha un appUserId diverso (vad_sd). Può farlo tramite questa API:

$ curl -XPUT https://api.atoka.io/v2/lists/24/permissions/user/vad_sd \
  -d 'token=TOKEN' \
  -d 'appUserId=andrea_sd' \
  -d 'permission=read'

{
  "item": {
    "user": {
       "appUserId": "vad_sd",
       "name": "Davide"
    },
    "permission": "read",
    "key": "a0cc4fc59dcd41f5956e55512706fedf",
    "details": {
       "read": true,
       "write": false,
       "manage": false
    }
  }
}

Può scegliere di associare diversi permessi organizzati in maniera piramidale a Davide:

  • read (sola lettura),
  • write (lettura/scrittura)
  • manage (lettura/scrittura/cancellazione/condivisione con altri, più tutti i precedenti)