Como usar a Reports API com o Laravel

Introdução

A Reports API da Vonage oferece análises de uso poderosas e filtráveis — este tutorial mostra como integrá-la ao Laravel para gerar relatórios síncronos e assíncronos. Assim, se você usa intensamente, por exemplo, a Voice API ou a Messages API, pode obter estatísticas no seu Painel de Controle da API da Vonage. No entanto, há limitações, pois você só pode acessar os registros dos últimos 30 dias. Como alternativa, você pode usar a Reports API, que disponibiliza endpoints de API para analisar seu uso com mais detalhes, adicionar parâmetros específicos para filtrar dados ou criar relatórios muito maiores de forma assíncrona. Em vez de 30 dias, você pode obter registros dos últimos 13 meses ou dos últimos 90 dias, caso esteja consultando dados de vídeo. Se quiser usar a Reports API, será cobrado de acordo com o número de registros retornados nos relatórios.

Depois de ler esta análise, talvez você já seja um usuário assíduo do Vonage que precise de um plano de preços personalizado: nesse caso, recomendamos entrar em contato com seu gerente de conta para solicitar um Plano Ilimitado. Nossa recomendação geral na hora de escolher um plano de preços é mudar para o Plano Ilimitado se você for consultar mais de 1 milhão de eventos por mês ou 12 milhões de registros por ano.

Neste artigo, vamos usar o Laravel para buscar esses dados, a título de exemplo.

Pré-requisitos

• Compositor

• PHP 8.2 ou superior

• Instalador do Laravel

• ngrok

• Um Account da API da Vonage

Instalando o Laravel

O instalador do Laravel utiliza o mecanismo do Composer create-project para criar código padrão. Crie um novo diretório na sua máquina de desenvolvimento e execute laravel install reports-api-demo. O instalador apresentará algumas opções — você pode selecionar as padrão aqui e ignorar a opção “Laravel Starter Kits”, já que queremos apenas demonstrar como lidamos com dados.

Configurando rotas

Para simplificar ao máximo, teremos três rotas que correspondem às três maneiras diferentes de implementar relatórios. Essas rotas serão as seguintes:

• Acesse um GET ponto final que gera um relatório síncrono que retorna para o seu aplicativo, e ele exibirá o resultado

• Acesse um GET ponto de extremidade que aciona uma POST solicitação à Vonage para um relatório assíncrono, com uma URL de retorno de chamada que será

• Um POST ponto de extremidade ao qual a Vonage responderá com seu relatório assíncrono

Opção 1: Criar um relatório síncrono

Acesse o seu routes/web.php diretório e adicione o seguinte código:

Route::get('/report', function () {
    $apiKey = '99913011';
    $apiSecret = 's09IJad98fa0t9j09ad8fa999';
    $url = 'https://api.nexmo.com/v2/reports/records';
    $dateStart = \Carbon\Carbon::now()->subMonth();
    $dateEnd = \Carbon\Carbon::now();

    $queryParams = [
       'product' => 'SMS',
       'direction' => 'outbound',
       'date_start' => $dateStart->format('Y-m-d\TH:i:s.vP'),
       'date_end' => $endDate->format('Y-m-d\TH:i:s.vP'),
       'account_id' => $apiKey,
     ];

    $response = Http::withBasicAuth($apiKey, $apiSecret)
       ->get($url, $queryParams);

    dd($response->json());
});

(Para os mais espertos entre vocês, sim, essas são chaves de API fictícias; sempre ocultem seus dados confidenciais!). Para ter uma ideia melhor de como lidar com suas variáveis de ambiente, dê uma olhada neste artigo do blog.

Em vez de usar controladores, estamos adicionando a lógica ao closure da rota. Ao acessar /report em seu aplicativo agora enviará uma solicitação à Reports API usando sua chave e seu segredo (você pode encontrá-los no seu Painel) e exibirá a resposta.

Nesta solicitação, o relatório nos apresentará apenas os eventos da SMS API, já que filtramos por esse produto nos parâmetros da consulta. Há muitas opções disponíveis nessa API para realizar consultas:

• SMS

• Voice (inclui In-App Voice, WEBSOCKET-CALL, VOICE-TTS, ASR, AMD)

• Messages API (WhatsApp, RCS, SMS, Viber, SMS)

• Análise de Números

• Verify

• In-App Messaging

• APIs de rede

• Video

Isso é adequado para pequenos volumes de dados, mas o que acontece quando você precisa de milhões de linhas? É aí que entra o relatório assíncrono.

Opção 2: Criar relatórios assíncronos

Milhões de registros representariam uma carga excessiva tanto para o cliente quanto para o servidor. Portanto, você pode POST enviar uma solicitação com parâmetros de consulta de relatório no corpo JSON, incluindo uma URL de retorno para enviar um webhook assim que a operação for concluída. Como a Vonage precisará de um endpoint para o envio dos dados do relatório, você precisará expor seu aplicativo à Internet. A maneira mais rápida de fazer isso é usando o ngrok, que faz exatamente isso. Depois de instalar o ngrok, execute-o para expor seu aplicativo e anote a URL.

Precisamos de um endpoint para receber o relatório. Por enquanto, a título de demonstração, ele apenas gravará os dados no arquivo de log do aplicativo.

Route::post('/incoming', function (\Illuminate\Http\Request $request) {
   \Illuminate\Support\Facades\Log::info($request->json());
});

Em seguida, precisamos de um novo ponto de extremidade GET para iniciar a solicitação assíncrona:

Route::get('/async', function (\Illuminate\Http\Request $request) {
   $apiKey = '99913011';
   $apiSecret = 's09IJad98fa0t9j09ad8fa999';
   $url = 'https://api.nexmo.com/v2/reports';
   $dateStart = Carbon::now()->subMonth();
   $endDate = Carbon::now();

   $queryParams = [
       'product' => 'SMS',
       'direction' => 'outbound',
       'date_start' => $dateStart->format('Y-m-d\TH:i:s.vP'),
       'date_end' => $endDate->format('Y-m-d\TH:i:s.vP'),
       'account_id' => $apiKey,
   ];



   $response = Http::withBasicAuth($apiKey, $apiSecret)
       ->post($url, $queryParams);

   dd($response->json());
});

Substitua novamente sua chave e seu segredo da API pelos do seu painel de controle e substitua o callback_url campo pela sua URL do ngrok, além de /async adicionado para que o Vonage POST para o local correto. Acesse essa GET solicitação no seu navegador, e o relatório será acionado. É importante observar que os registros são cobrados por linha, portanto, certifique-se, ao testar essa implementação, de que não vai sobrecarregar os servidores com milhões de registros, caso você os tenha e esteja apenas seguindo estas instruções para fins de teste.

Eventualmente (dependendo do tamanho do relatório), você poderá acessar storage/logs/laravel.log e visualizar os dados do relatório assíncrono.

Como visualizar o status de um relatório assíncrono

Talvez seja uma boa ideia verificar se você não perdeu alguma chamada de retorno — por exemplo, se houve um erro de análise que fez com que o relatório fosse enviado para uma URL inválida. É recomendável verificar o status e, caso esteja concluído, baixar o relatório. Para isso, basta acessar o endpoint de verificação do relatório.

Route::get('/status', function (\Illuminate\Http\Request $request) {
   $apiKey = 'your-api-key';
   $apiSecret = 'your-api-secret';
   $requestId = 'aaaaaaaa-bbbb-cccc-dddd-0123456789ab';
   $url = 'https://api.nexmo.com/v2/reports/' . $requestId;

   $response = Http::withBasicAuth($apiKey, $apiSecret)
       ->get($url);

   dd($response->json());
});

A resposta fornecerá todas as informações de que você precisa. Desde que o request_status estiver SUCCESS, você pode extrair o link de download do download_report campo HAL.

"request_status": "SUCCESS",
"_links": {
    "self": {
         "href": "https://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-  0123456789ab"
          },
          "download_report": {
              "href": "https://api.nexmo.com/v3/media/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
           }
       }
}

Conclusão

E aí está: uma maneira totalmente assíncrona de consultar todas as suas comunicações na Cloud Platform! A possibilidade de consultar por ID de conta também oferece opções adicionais: se você for o usuário principal, utilizará sua chave de API. No entanto, você pode ser um revendedor de serviços de comunicação; nesse caso, agora tem a possibilidade de gerar relatórios personalizados por subconta. Isso também torna a funcionalidade especialmente útil para emitir faturas aos clientes como revendedor. Você também pode usar a Reports API para monitorar e identificar seus próprios padrões de solicitações potencialmente maliciosas e bloquear números usando a funcionalidade Fraud Defender.