> For the complete documentation index, see [llms.txt](https://docs.exoclick.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.exoclick.com/api/it/api-pubblica-di-exoclick/api-manual-php-examples.md).

# Esempi PHP

## Panoramica

Tutti gli esempi di codice in questa sezione usano le seguenti classi.

La classe Request usa **cURL** per effettuare le richieste all'API.

La classe Response contiene la risposta dell'API e le informazioni sul codice di stato restituito.

<details>

<summary>Classi Request e Response</summary>

```php
class Request {

        /**
         * @var resource
         */
        protected $_request;

        /**
         * @var integer
         */
        protected $_method;

        /**
         * @var string
         */
        protected $_url;

        /**
         * @var array
         */
        protected $_headers = array(
            'Content-type: application/json'
        );

        /**
         * @var string|array
         */
        protected $_params;

        /**
         * @var object Response
         */
        protected $_reponse;

        /**
         * Costruttore
         *
         * @param   string      $url
         * @param   string      $method
         * @param   array       $params
         */
        public function __construct($url, $method, $params = array()) {

            $this->_url = $url;

            // Imposta il metodo
            $this->_method = $method;

            // Imposta i parametri
            $this->_params = $params;
        }

        /**
         * Determina il metodo Request
         *
         * @param   string  $method
         */
        private function setMethod() {

            switch($this->_method) {
                case 'GET':
                    break;
                case 'POST':
                    curl_setopt($this->_request, CURLOPT_POST, 1);
                    break;
                case 'PUT':
                    curl_setopt($this->_request, CURLOPT_CUSTOMREQUEST, 'PUT');
                    break;
                case 'DELETE':
                    curl_setopt($this->_request, CURLOPT_CUSTOMREQUEST, 'DELETE');
                    break;
            }
        }

        /**
         * Aggiungi l'intestazione di autorizzazione
         *
         * @param   string  $type
         * @param   string  $token
         */
        public function setAuthorizationHeader($type, $token) {

            $authorization = $type . ' ' . $token;

            $this->_headers[] = 'Authorization: ' . $authorization;
        }

        /**
         * Aggiungi il body alla richiesta
         */
        private function addBody() {

            if($this->_method != 'GET' && empty($this->_params) == false) {

                if(is_array($this->_params)) {
                    // Codifica l'array in JSON
                    $this->_params = json_encode($this->_params);
                }

                curl_setopt($this->_request, CURLOPT_POSTFIELDS, $this->_params);

                // Aggiungi un'intestazione Content-length
                $this->_headers[] = 'Content-length: ' . strlen($this->_params);
            }
        }

        /**
         * Aggiungi una stringa di query alla richiesta
         */
        private function addQueryString() {

            if($this->_method == 'GET' && is_array($this->_params) && count($this->_params) > 0) {

                $query_string = '?';

                foreach($this->_params as $param => $value) {

                    $query_string = $query_string . $param . '=' . $value . '&';
                }

                trim($query_string, '&');

                $this->_url = $this->_url . $query_string;
            }
            else {

                if(is_array($this->_params) && count($this->_params) > 0 && strpos($this->_url, '{') !== false) {
                    // Abbina i parametri all'URL
                    foreach($this->_params as $param => $value) {
                        $this->_url = preg_replace('/{' . $param . '}/', $value, $this->_url);
                    }
                }
            }
        }

        /**
         * Invia la richiesta
         */
        public function send() {

            // Inizializza la richiesta cUrl
            $this->_request = curl_init();

            // Restituisci la risposta come stringa
            curl_setopt($this->_request, CURLOPT_RETURNTRANSFER, 1);

            // Aggiungi una stringa di query
            $this->addQueryString();

            // Imposta l'URL
            curl_setopt($this->_request, CURLOPT_URL, $this->_url);

            // Imposta il metodo della richiesta
            $this->setMethod();

            // Aggiungi un body
            $this->addBody();

            if(empty($this->_headers) == false) {
                // Imposta le intestazioni
                curl_setopt($this->_request, CURLOPT_HTTPHEADER, $this->_headers);
            }

            // Disabilita i controlli SSL
            curl_setopt($this->_request, CURLOPT_SSL_VERIFYPEER, false);
            curl_setopt($this->_request, CURLOPT_SSL_VERIFYHOST, false);

            // Invia la richiesta e memorizza il body
            $this->_response = new Response(curl_exec($this->_request));

            // Imposta il codice di stato
            $this->_response->setStatusCode(curl_getinfo($this->_request, CURLINFO_HTTP_CODE));

            // Chiudi la connessione
            curl_close($this->_request);
        }

        /**
         * Ottieni la risposta
         *
         * @return object
         */
        public function getResponse() {

            return $this->_response;
        }
    }

    class Response {

        /**
         * @var array
         */
        protected $_reason_phrases = array(
            //Informativi 1xx
            100 => "Continua",
            101 => "Cambio protocollo",

            // Successi 2xx
            200 => "OK",
            201 => "Creato",
            202 => "Accettato",
            203 => "Informazioni non autorevoli",
            204 => "Nessun contenuto",
            205 => "Reimposta contenuto",
            206 => "Contenuto parziale",

            // Reindirizzamento 3xx
            300 => "Scelte multiple",
            301 => "Spostato permanentemente",
            302 => "Trovato",
            303 => "Vedi altro",
            304 => "Non modificato",
            305 => "Usa proxy",
            306 => "(Non usato)",
            307 => "Reindirizzamento temporaneo",

            // Errore del client 4xx
            400 => "Richiesta non valida",
            401 => "Non autorizzato",
            402 => "Pagamento richiesto",
            403 => "Vietato",
            404 => "Non trovato",
            405 => "Metodo non consentito",
            406 => "Non accettabile",
            407 => "Autenticazione proxy richiesta",
            408 => "Timeout della richiesta",
            409 => "Conflitto",
            410 => "Non più disponibile",
            411 => "Lunghezza richiesta",
            412 => "Precondizione fallita",
            413 => "Entità richiesta troppo grande",
            414 => "URI della richiesta troppo lungo",
            415 => "Tipo di media non supportato",
            416 => "Intervallo richiesto non soddisfacibile",
            417 => "Aspettativa fallita",

            // Errore del server 5xx
            500 => "Errore interno del server",
            501 => "Non implementato",
            502 => "Gateway non valido",
            503 => "Servizio non disponibile",
            504 => "Timeout del gateway",
            505 => "Versione HTTP non supportata"
        );

        /**
         * @var integer
         */
        protected $_status_code;

        /**
         * @var string
         */
        protected $_body;

        /**
         * Costruttore
         *
         * @param   string      $body
         */
        public function __construct($body) {

            $this->_body = $body;
        }

        /**
         * Costruttore
         *
         * @param   string      $status_code
         */
        public function setStatusCode($status_code) {

            $this->_status_code = $status_code;
        }

        /**
         * Ottieni il codice di stato
         *
         * @return  integer
         */
        public function getStatusCode() {

            return $this->_status_code;
        }

        /**
         * Ottieni il body
         *
         * @return  string
         */
        public function getBody() {

            return $this->_body;
        }

        /**
         * Ottieni il body decodificato in JSON
         *
         * @return  object|null
         */
        public function getBodyDecoded() {

            return json_decode($this->_body);
        }

        /**
         * Ottieni la reason phrase
         *
         * @return string|boolean
         */
        public function getReasonPhrase() {

            if(array_key_exists($this->_status_code, $this->_reason_phrases)) {

                return $this->_reason_phrases[$this->_status_code];
            }
            else {

                return false;
            }
        }
    }
```

</details>

## Accedi

Ci sono due opzioni per richiedere la **login** route:

* con username e password
* con token API (token di accesso)

Esempio di login con parametri username e password.

```php
<?php

    // Includi le classi Request e Response

    $url = 'https://api.example.com/v2/login';

    $params = array(
        'username'  => 'sample_username',
        'password'  => 'sample_password'
    );

    // Crea un nuovo oggetto Request
    $request = new Request($url, 'POST', $params);

    // Invia la richiesta
    $request->send();

    // Ottieni l'oggetto Response
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        // Recupera i dettagli del token di sessione
        $token = $response->getBodyDecoded();

        print_r($token);
    }
    else {

        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody() . PHP_EOL;
    }
?>
```

### Esempio di login con token API (token di accesso)

```php
<?php

    // Includi le classi Request e Response

    $url = 'https://api.example.com/v2/login';

    $params = array(
            'api_token'  => 'sample_token_2bb447abb71b69368901a....'
        );

    // Crea un nuovo oggetto Request
    $request = new Request($url, 'POST', $params);

    // Invia la richiesta
    $request->send();

    // Ottieni l'oggetto Response
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        // Recupera i dettagli del token di sessione
        $token = $response->getBodyDecoded();

        print_r($token);
    }
    else {

        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody() . PHP_EOL;
    }
?>
```

## Autenticazione

Ogni richiesta a contenuti relativi all'utente richiede un **Autorizzazione** intestazione da impostare, con un valore contenente il tipo di token e il token di sessione ricevuti dalla richiesta di login API.

Una valida **/login** richiesta all'API restituirà il seguente payload JSON.

```json
{
  "token": "",
  "type": "",
  "expires_in": 0
}
```

Il **Token di sessione** deve essere incluso in tutte le successive richieste all'API per contenuti relativi all'utente.

Il **type** deve essere anteposto al token, separato da un singolo spazio.

```
Bearer 4e63518d383d8fcaefb516fe708b893727463031
```

Il **expires\_in** è il tempo, in secondi, per cui il token sarà valido. Quando questo tempo scade, sarà necessario ottenere un nuovo token tramite la richiesta /login.

### Esempio di recupero e impostazione dell'intestazione di autorizzazione con username e password

```php
<?php

    // Includi le classi Request e Response

    // Login
    $url = 'https://api.example.com/v2/login';

    $params = array(
        'username'  => 'sample_username',
        'password'  => 'sample_password'
    );

    // Crea un nuovo oggetto Request
    $request = new Request($url, 'POST', $params);

    // Invia la richiesta
    $request->send();

    // Ottieni l'oggetto Response
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        // Recupera i dettagli del token di sessione
        $token = $response->getBodyDecoded();

        // Ottieni le campagne
        $url = 'https://api.example.com/v2/campaigns';

        // Crea un nuovo oggetto Request
        $request = new Request($url, 'GET');

        // Imposta l'intestazione di autorizzazione
        $request->setAuthorizationHeader($token->type, $token->token);

        // Invia la richiesta
        $request->send();

        // Ottieni l'oggetto Response
        $response = $request->getResponse();

        if($response->getStatusCode() == 200) {

            // Recupera le campagne
            $campaigns = $response->getBodyDecoded();

            foreach($campaigns->result as $campaign) {
                // Mostra i nomi delle campagne
                echo $campaign->name . PHP_EOL;
            }
        }
        else {
            // Errore della richiesta delle campagne
            echo $response->getStatusCode() . PHP_EOL;
            echo $response->getReasonPhrase() . PHP_EOL;
            echo $response->getBody();
        }
    }
    else {
        // Login non valido
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>
```

### Esempio di recupero e impostazione dell'intestazione di autorizzazione con token API

```php
<?php

    // Includi le classi Request e Response

    // Login
    $url = 'https://api.example.com/v2/login';

    $params = array(
        'api_token'  => 'sample_token_2bb447abb71b69368901a....'
    );

    ...

?>
```

## Collezioni

Quello che segue è un esempio di richiesta per ottenere la **Browser** collezione.

```php
<?php

    // Includi le classi Request e Response

    $url = 'https://api.example.com/v2/collections/browsers';

    // Crea un nuovo oggetto Request
    $request = new Request($url, 'GET');

    // Imposta l'intestazione di autorizzazione recuperata dalla richiesta di login precedente
    $request->setAuthorizationHeader($token->type, $token->token);

    // Invia la richiesta
    $request->send();

    // Ottieni l'oggetto Response
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $browsers = $response->getBodyDecoded();

        foreach($browsers as $browser) {

            echo $browser->id . ': ' . $browser->name . PHP_EOL;
        }
    }
    else {
        // Collezione non trovata
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>
```

## Statistiche

Quello che segue è un esempio di richiesta dell'inserzionista per **statistics/a/date**.

Nel caso in cui **additional\_group\_by** il valore sia definito, la richiesta sarà raggruppata per il campo principale della route e per quello/i aggiuntivo/i.

### Esempio di statistiche per data filtrate per ID campagna 1234.

```php
<?php

    // Includi le classi Request e Response

    $url = 'https://api.example.com/v2/statistics/a/date';

    // Specifica l'id campagna
    $params = array(
       'campaignid'  => 1234
    );

    $request = new Request($url, 'GET', $params);

    // Imposta l'intestazione di autorizzazione, recuperata dalla richiesta di login precedente
    $request->setAuthorizationHeader($token->type, $token->token);

    // Invia la richiesta
    $request->send();

    // Ottieni l'oggetto risposta
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {

            echo $statistic->ddate . ': ' . $statistic->value . PHP_EOL;
        }
    }
    else {
        // Statistiche della campagna non trovate
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>
```

### Esempio di statistiche per data con raggruppamento aggiuntivo per campagna.

```php
<?php

    // Includi le classi Request e Response

    $url = 'https://api.example.com/v2/statistics/a/date';

    // Specifica l'id campagna
    $params = array(
       'additional_group_by'  => 'campaign'
    );

    $request = new Request($url, 'GET', $params);

    // Imposta l'intestazione di autorizzazione, recuperata dalla richiesta di login precedente
    $request->setAuthorizationHeader($token->type, $token->token);

    // Invia la richiesta
    $request->send();

    // Ottieni l'oggetto risposta
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo $statistic->ddate . ' - ' . $statistic->idcampaign . ': ' . $statistic->value . PHP_EOL;
        }
    }
    else {
        // Statistiche della campagna non trovate
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>
```

post /statistics/a/global

Ottieni statistiche globali dell'inserzionista

### Esempio 1 di statistiche globali

Esempio di richiesta di statistiche globali.

Solo il `group_by` parametro è obbligatorio. I valori predefiniti per gli altri parametri si possono trovare [Qui](https://api.exoclick.com/v2/docs/#!/47statistics/post_statistics_a_global).

Si noti che le route delle statistiche globali (`statistics/a/global`, `statistics/p/global`) hanno un formato di parametri diverso.

```php
<?php

    // Includi le classi Request e Response

    $url = 'https://api.example.com/v2/statistics/a/global';

    // Specifica il group_by
    $params = [
        "group_by" => ["date"]
    ];

    $request = new Request($url, 'POST', $params);

    // Imposta l'intestazione di autorizzazione, recuperata dalla richiesta di login precedente
    $request->setAuthorizationHeader($token->type, $token->token);

    // Invia la richiesta
    $request->send();

    // Ottieni l'oggetto risposta
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo 'Data: ' . $statistic->group_by->date->date . ' -  Impressioni: ' . $statistic->impressions .' - Costo: ' .  $statistic->cost . PHP_EOL;
        }
    }
    else {
        // Statistiche della campagna non trovate
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>
```

### Esempio 2 di statistiche globali

Ottieni statistiche per data includendo i totali sommati.

```php
<?php

    // Includi le classi Request e Response

    $url = 'https://api.example.com/v2/statistics/a/global';

    // Specifica l'id campagna
    $params = [
        "filter" => [
            "date_from" => "2019-01-10",
            "date_to" => "2019-01-31",
        ],
        "totals" => 1,
        "group_by" => ["date"]
    ];

    $request = new Request($url, 'POST', $params);

    // Imposta l'intestazione di autorizzazione, recuperata dalla richiesta di login precedente
    $request->setAuthorizationHeader($token->type, $token->token);

    // Invia la richiesta
    $request->send();

    // Ottieni l'oggetto risposta
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo 'Data: ' . $statistic->group_by->date->date . ' -  Impressioni: ' . $statistic->impressions .' - Costo: ' .  $statistic->cost . PHP_EOL;
        }

        echo 'Costo totale:' . $statistics->result_total->cost . PHP_EOL;
    }
    else {
        // Statistiche della campagna non trovate
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>
```

### Esempio 3 di statistiche globali

Ottieni statistiche per campagna e paese filtrate per una data specifica ordinate per impressioni.

```php
<?php

    // Includi le classi Request e Response

    $url = 'https://api.example.com/v2/statistics/a/global';

    $params = [
        "filter" => [
            "date_from" => "2019-01-30",
            "date_to" => "2019-01-30",
        ],
        "group_by" => ["country_iso", "campaign_id"],
        "order_by" => [
            ["field" => "impressions", "order" => "desc"]
        ]
    ];


    $request = new Request($url, 'POST', $params);

    // Imposta l'intestazione di autorizzazione, recuperata dalla richiesta di login precedente
    $request->setAuthorizationHeader($token->type, $token->token);

    // Invia la richiesta
    $request->send();

    // Ottieni l'oggetto risposta
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo 'Paese: ' . $statistic->group_by->country_iso->country_iso . ' -  ID campagna: ' . $statistic->group_by->campaign_id->id .' - Costo: ' .  $statistic->cost . PHP_EOL;
        }
    }
    else {
        // Statistiche della campagna non trovate
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>
```

### Esempio 4 di statistiche globali

Ottieni statistiche dell'editore per zona e paese filtrate per un sistema operativo specifico.

```php
<?php

    // Includi le classi Request e Response

    $url = 'https://api.example.com/v2/statistics/p/global';

    $params = [
        "filter" => [
            "date_from" => "2019-01-30",
            "date_to" => "2019-01-30",
            "operating_system_id" => [11, 12]
        ],
        "group_by" => ["zone_id", "country_iso"]
    ];


    $request = new Request($url, 'POST', $params);

    // Imposta l'intestazione di autorizzazione, recuperata dalla richiesta di login precedente
    $request->setAuthorizationHeader($token->type, $token->token);

    // Invia la richiesta
    $request->send();

    // Ottieni l'oggetto risposta
    $response = $request->getResponse();

    if($response->getStatusCode() == 200) {

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo ' ID zona:' . $statistic->group_by->zone_id->id . ' - Paese: ' . $statistic->group_by->country_iso->country_iso .' - Ricavi: ' .  $statistic->revenue . PHP_EOL;
        }
    }
    else {
        // Statistiche della campagna non trovate
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.exoclick.com/api/it/api-pubblica-di-exoclick/api-manual-php-examples.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.