> 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/pt/api-publica-exoclick/api-manual-php-examples.md).

# Exemplos em PHP

## Visão geral

Todos os exemplos de código nesta seção usam as classes a seguir.

A classe Request usa **cURL** para fazer as solicitações à API.

A classe Response contém a resposta da API e informações do código de status retornado.

<details>

<summary>Classes 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;

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

            $this->_url = $url;

            // Definir o método
            $this->_method = $method;

            // Definir os parâmetros
            $this->_params = $params;
        }

        /**
         * Determinar o método da 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;
            }
        }

        /**
         * Adicionar cabeçalho de autorização
         *
         * @param   string  $type
         * @param   string  $token
         */
        public function setAuthorizationHeader($type, $token) {

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

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

        /**
         * Adicionar corpo à solicitação
         */
        private function addBody() {

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

                if(is_array($this->_params)) {
                    // Codificar o array em JSON
                    $this->_params = json_encode($this->_params);
                }

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

                // Adicionar um cabeçalho Content-length
                $this->_headers[] = 'Content-length: ' . strlen($this->_params);
            }
        }

        /**
         * Adicionar uma string de consulta à solicitação
         */
        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) {
                    // Comparar parâmetros com a URL usando padrão
                    foreach($this->_params as $param => $value) {
                        $this->_url = preg_replace('/{' . $param . '}/', $value, $this->_url);
                    }
                }
            }
        }

        /**
         * Enviar a solicitação
         */
        public function send() {

            // Inicializar solicitação cURL
            $this->_request = curl_init();

            // Retornar a resposta como uma string
            curl_setopt($this->_request, CURLOPT_RETURNTRANSFER, 1);

            // Adicionar uma string de consulta
            $this->addQueryString();

            // Definir a URL
            curl_setopt($this->_request, CURLOPT_URL, $this->_url);

            // Definir o método da solicitação
            $this->setMethod();

            // Adicionar um corpo
            $this->addBody();

            if(empty($this->_headers) == false) {
                // Definir os cabeçalhos
                curl_setopt($this->_request, CURLOPT_HTTPHEADER, $this->_headers);
            }

            // Desativar verificações SSL
            curl_setopt($this->_request, CURLOPT_SSL_VERIFYPEER, false);
            curl_setopt($this->_request, CURLOPT_SSL_VERIFYHOST, false);

            // Enviar a solicitação e armazenar o corpo
            $this->_response = new Response(curl_exec($this->_request));

            // Definir o código de status
            $this->_response->setStatusCode(curl_getinfo($this->_request, CURLINFO_HTTP_CODE));

            // Fechar a conexão
            curl_close($this->_request);
        }

        /**
         * Obter a resposta
         *
         * @return object
         */
        public function getResponse() {

            return $this->_response;
        }
    }

    class Response {

        /**
         * @var array
         */
        protected $_reason_phrases = array(
            //Informativo 1xx
            100 => "Continuar",
            101 => "Mudando de protocolo",

            // Sucesso 2xx
            200 => "OK",
            201 => "Criado",
            202 => "Aceito",
            203 => "Informação não autoritativa",
            204 => "Sem conteúdo",
            205 => "Redefinir conteúdo",
            206 => "Conteúdo parcial",

            // Redirecionamento 3xx
            300 => "Múltiplas escolhas",
            301 => "Movido permanentemente",
            302 => "Encontrado",
            303 => "Ver outro",
            304 => "Não modificado",
            305 => "Usar proxy",
            306 => "(Não utilizado)",
            307 => "Redirecionamento temporário",

            // Erro do cliente 4xx
            400 => "Pedido inválido",
            401 => "Não autorizado",
            402 => "Pagamento necessário",
            403 => "Proibido",
            404 => "Não encontrado",
            405 => "Método não permitido",
            406 => "Não aceitável",
            407 => "Autenticação de proxy necessária",
            408 => "Tempo limite da solicitação",
            409 => "Conflito",
            410 => "Indisponível",
            411 => "Comprimento necessário",
            412 => "Falha na pré-condição",
            413 => "Entidade da solicitação muito grande",
            414 => "URI da solicitação muito longa",
            415 => "Tipo de mídia não suportado",
            416 => "Intervalo solicitado não satisfatório",
            417 => "Falha na expectativa",

            // Erro do servidor 5xx
            500 => "Erro interno do servidor",
            501 => "Não implementado",
            502 => "Gateway inválido",
            503 => "Serviço indisponível",
            504 => "Tempo limite do gateway",
            505 => "Versão HTTP não suportada"
        );

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

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

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

            $this->_body = $body;
        }

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

            $this->_status_code = $status_code;
        }

        /**
         * Obter código de status
         *
         * @return  integer
         */
        public function getStatusCode() {

            return $this->_status_code;
        }

        /**
         * Obter corpo
         *
         * @return  string
         */
        public function getBody() {

            return $this->_body;
        }

        /**
         * Obter corpo decodificado em JSON
         *
         * @return  object|null
         */
        public function getBodyDecoded() {

            return json_decode($this->_body);
        }

        /**
         * Obter frase de motivo
         *
         * @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>

## Iniciar sessão

Há duas opções para solicitar a **login** rota:

* com nome de usuário e senha
* com token de API (token de acesso)

Exemplo de login com parâmetros de nome de usuário e senha.

```php
<?php

    // Incluir as classes Request e Response

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

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

    // Criar um novo objeto Request
    $request = new Request($url, 'POST', $params);

    // Enviar a solicitação
    $request->send();

    // Obter o objeto Response
    $response = $request->getResponse();

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

        // Recuperar os detalhes do token de sessão
        $token = $response->getBodyDecoded();

        print_r($token);
    }
    else {

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

### Exemplo de login com token de API (token de acesso)

```php
<?php

    // Incluir as classes Request e Response

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

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

    // Criar um novo objeto Request
    $request = new Request($url, 'POST', $params);

    // Enviar a solicitação
    $request->send();

    // Obter o objeto Response
    $response = $request->getResponse();

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

        // Recuperar os detalhes do token de sessão
        $token = $response->getBodyDecoded();

        print_r($token);
    }
    else {

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

## Autenticação

Cada solicitação a conteúdo relacionado ao usuário requer um **Autorização** cabeçalho a ser definido, com o valor contendo o tipo de token e o token de sessão recebido da solicitação de login da API.

Uma **/login** solicitação válida à API retornará o seguinte payload JSON.

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

O **O token de sessão** deve ser incluído em todas as solicitações subsequentes de conteúdo relacionado ao usuário para a API.

O **type** deve ser prefixado ao token, separado por um único espaço.

```
Bearer 4e63518d383d8fcaefb516fe708b893727463031
```

O **expires\_in** é o tempo, em segundos, durante o qual o token será válido. Quando esse tempo expirar, será necessário obter um novo token por meio da solicitação /login.

### Exemplo de obtenção e definição do cabeçalho de autorização com nome de usuário e senha

```php
<?php

    // Incluir as classes Request e Response

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

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

    // Criar um novo objeto Request
    $request = new Request($url, 'POST', $params);

    // Enviar a solicitação
    $request->send();

    // Obter o objeto Response
    $response = $request->getResponse();

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

        // Recuperar os detalhes do token de sessão
        $token = $response->getBodyDecoded();

        // Obter campanhas
        $url = 'https://api.example.com/v2/campaigns';

        // Criar um novo objeto Request
        $request = new Request($url, 'GET');

        // Definir o cabeçalho de autorização
        $request->setAuthorizationHeader($token->type, $token->token);

        // Enviar a solicitação
        $request->send();

        // Obter o objeto Response
        $response = $request->getResponse();

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

            // Recuperar as campanhas
            $campaigns = $response->getBodyDecoded();

            foreach($campaigns->result as $campaign) {
                // Exibir os nomes das campanhas
                echo $campaign->name . PHP_EOL;
            }
        }
        else {
            // Erro na solicitação de campanhas
            echo $response->getStatusCode() . PHP_EOL;
            echo $response->getReasonPhrase() . PHP_EOL;
            echo $response->getBody();
        }
    }
    else {
        // Login inválido
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>
```

### Exemplo de obtenção e definição do cabeçalho de autorização com token de API

```php
<?php

    // Incluir as classes Request e Response

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

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

    ...

?>
```

## Coleções

A seguir está um exemplo de uma solicitação para obter a **Navegadores** coleção.

```php
<?php

    // Incluir as classes Request e Response

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

    // Criar um novo objeto Request
    $request = new Request($url, 'GET');

    // Definir o cabeçalho de autorização recuperado da solicitação de login anterior
    $request->setAuthorizationHeader($token->type, $token->token);

    // Enviar a solicitação
    $request->send();

    // Obter o objeto Response
    $response = $request->getResponse();

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

        $browsers = $response->getBodyDecoded();

        foreach($browsers as $browser) {

            echo $browser->id . ': ' . $browser->name . PHP_EOL;
        }
    }
    else {
        // Coleção não encontrada
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>
```

## Estatísticas

A seguir está um exemplo de uma solicitação do anunciante para **statistics/a/date**.

No caso de **additional\_group\_by** o valor estar definido, a solicitação será agrupada pelo campo principal da rota e pelo(s) campo(s) extra(s).

### Exemplo de estatísticas por data filtradas pelo ID da campanha 1234.

```php
<?php

    // Incluir as classes Request e Response

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

    // Especificar o ID da campanha
    $params = array(
       'campaignid'  => 1234
    );

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

    // Definir o cabeçalho de autorização, recuperado da solicitação de login anterior
    $request->setAuthorizationHeader($token->type, $token->token);

    // Enviar a solicitação
    $request->send();

    // Obter o objeto de resposta
    $response = $request->getResponse();

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

        $statistics = $response->getBodyDecoded();

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

            echo $statistic->ddate . ': ' . $statistic->value . PHP_EOL;
        }
    }
    else {
        // Estatísticas da campanha não encontradas
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>
```

### Exemplo de estatísticas por data com agrupamento adicional por campanha.

```php
<?php

    // Incluir as classes Request e Response

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

    // Especificar o ID da campanha
    $params = array(
       'additional_group_by'  => 'campaign'
    );

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

    // Definir o cabeçalho de autorização, recuperado da solicitação de login anterior
    $request->setAuthorizationHeader($token->type, $token->token);

    // Enviar a solicitação
    $request->send();

    // Obter o objeto de resposta
    $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 {
        // Estatísticas da campanha não encontradas
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>
```

post /statistics/a/global

Obter estatísticas globais do anunciante

### Exemplo 1 de estatísticas globais

Exemplo de solicitação de estatísticas globais.

Apenas o `group_by` parâmetro é obrigatório. Os valores padrão dos outros parâmetros podem ser encontrados [aqui](https://api.exoclick.com/v2/docs/#!/47statistics/post_statistics_a_global).

Observe que as rotas de estatísticas globais (`statistics/a/global`, `statistics/p/global`) têm formatos de parâmetros diferentes.

```php
<?php

    // Incluir as classes Request e Response

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

    // Especificar o group_by
    $params = [
        "group_by" => ["date"]
    ];

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

    // Definir o cabeçalho de autorização, recuperado da solicitação de login anterior
    $request->setAuthorizationHeader($token->type, $token->token);

    // Enviar a solicitação
    $request->send();

    // Obter o objeto de resposta
    $response = $request->getResponse();

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

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo 'Data: ' . $statistic->group_by->date->date . ' -  Impressões: ' . $statistic->impressions .' - Custo: ' .  $statistic->cost . PHP_EOL;
        }
    }
    else {
        // Estatísticas da campanha não encontradas
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>
```

### Exemplo 2 de estatísticas globais

Obter estatísticas por data, incluindo totais somados.

```php
<?php

    // Incluir as classes Request e Response

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

    // Especificar o ID da campanha
    $params = [
        "filter" => [
            "date_from" => "2019-01-10",
            "date_to" => "2019-01-31",
        ],
        "totals" => 1,
        "group_by" => ["date"]
    ];

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

    // Definir o cabeçalho de autorização, recuperado da solicitação de login anterior
    $request->setAuthorizationHeader($token->type, $token->token);

    // Enviar a solicitação
    $request->send();

    // Obter o objeto de resposta
    $response = $request->getResponse();

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

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo 'Data: ' . $statistic->group_by->date->date . ' -  Impressões: ' . $statistic->impressions .' - Custo: ' .  $statistic->cost . PHP_EOL;
        }

        echo 'Custo total:' . $statistics->result_total->cost . PHP_EOL;
    }
    else {
        // Estatísticas da campanha não encontradas
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>
```

### Exemplo 3 de estatísticas globais

Obter estatísticas por campanha e país filtradas por data específica, ordenadas por impressões.

```php
<?php

    // Incluir as classes 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);

    // Definir o cabeçalho de autorização, recuperado da solicitação de login anterior
    $request->setAuthorizationHeader($token->type, $token->token);

    // Enviar a solicitação
    $request->send();

    // Obter o objeto de resposta
    $response = $request->getResponse();

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

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo 'País: ' . $statistic->group_by->country_iso->country_iso . ' -  ID da campanha: ' . $statistic->group_by->campaign_id->id .' - Custo: ' .  $statistic->cost . PHP_EOL;
        }
    }
    else {
        // Estatísticas da campanha não encontradas
        echo $response->getStatusCode() . PHP_EOL;
        echo $response->getReasonPhrase() . PHP_EOL;
        echo $response->getBody();
    }
?>
```

### Exemplo 4 de estatísticas globais

Obter estatísticas do publisher por zona e país filtradas por sistema operacional específico.

```php
<?php

    // Incluir as classes 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);

    // Definir o cabeçalho de autorização, recuperado da solicitação de login anterior
    $request->setAuthorizationHeader($token->type, $token->token);

    // Enviar a solicitação
    $request->send();

    // Obter o objeto de resposta
    $response = $request->getResponse();

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

        $statistics = $response->getBodyDecoded();

        foreach($statistics->result as $statistic) {
            echo ' ID da zona:' . $statistic->group_by->zone_id->id . ' - País: ' . $statistic->group_by->country_iso->country_iso .' - Receita: ' .  $statistic->revenue . PHP_EOL;
        }
    }
    else {
        // Estatísticas da campanha não encontradas
        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/pt/api-publica-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.