PHPackages                             vagner-giraldino/z-api-laravel-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. vagner-giraldino/z-api-laravel-sdk

ActiveLibrary[API Development](/categories/api)

vagner-giraldino/z-api-laravel-sdk
==================================

SDK Profissional para integração Z-API no Laravel com foco em remarketing e botões.

v1.0.0(3mo ago)00MITPHPPHP ^8.0CI passing

Since Feb 1Pushed 3mo agoCompare

[ Source](https://github.com/VagnerGiraldinoJr/z-api-laravel-sdk)[ Packagist](https://packagist.org/packages/vagner-giraldino/z-api-laravel-sdk)[ RSS](/packages/vagner-giraldino-z-api-laravel-sdk/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (2)Versions (3)Used By (0)

Z-API Laravel SDK ✨
===================

[](#z-api-laravel-sdk-)

[![Tests](https://github.com/VagnerGiraldinoJr/z-api-laravel-sdk/actions/workflows/tests.yml/badge.svg)](https://github.com/VagnerGiraldinoJr/z-api-laravel-sdk/actions)[![Latest Stable Version](https://camo.githubusercontent.com/32d26f3a66b4739626cf345f78a849c7c707bfb3ede40a24dbbbce688f09a6c0/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f5661676e6572476972616c64696e6f4a722f7a2d6170692d6c61726176656c2d73646b)](https://github.com/VagnerGiraldinoJr/z-api-laravel-sdk/releases)[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)[![PHP Version](https://camo.githubusercontent.com/444db78f4c401a1acfa7b4c8827e144349277cfc73343bde1b7d46767f4e0d65/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e32253230253743253230382e33253230253743253230382e342d3737376262342e737667)](https://www.php.net/)[![Laravel Version](https://camo.githubusercontent.com/7e1d223572c8ad2428721fb5138501db9b0484a8fd2e7383eda9458028c3c2c1/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d3130253230253743253230313125323025374325323031322d6666326432302e737667)](https://laravel.com/)

---

🚀 Z-API Laravel SDK (Bridge)
============================

[](#-z-api-laravel-sdk-bridge)

O **Z-API Laravel SDK** é um "plugin" pronto para uso que simplifica a integração com a [Z-API](https://developer.z-api.io/) em ecossistemas Laravel, com suporte nativo a **Multi-tenancy** e foco total em estratégias de **remarketing interativo**.

### O que este SDK resolve:

[](#o-que-este-sdk-resolve)

- **Instalação Plug-and-Play**: Instale e saia enviando em menos de 2 minutos.
- **Abstração de Botões**: Enviar botões de ação (URL/Chamada) agora é uma simples chamada de método.
- **Webhook Handler Automático**: Rota de webhook pré-configurada que dispara eventos nativos do Laravel.
- **Multi-tenant Ready**: Alterne entre instâncias de clientes diferentes dinamicamente.

---

🛠️ Instalação
-------------

[](#️-instalação)

Como este é um pacote privado/profissional, adicione o repositório ao seu `composer.json`:

```
"repositories": [
    {
        "type": "vcs",
        "url": "https://github.com/seu-usuario/z-api-laravel-sdk"
    }
],
```

Depois, execute:

```
composer require sua-empresa/z-api-laravel-sdk
```

---

🧙 Wizard de Configuração
------------------------

[](#-wizard-de-configuração)

Após instalar, rode o comando para publicar as configurações e ativar o SDK:

```
php artisan zapi:install
```

No seu `.env`, configure as credenciais padrão (se necessário):

```
ZAPI_CLIENT_TOKEN=seu_token
ZAPI_INSTANCE_ID=sua_instancia
ZAPI_INSTANCE_TOKEN=seu_token_instancia
```

---

📱 Como Usar
-----------

[](#-como-usar)

### 1. Remarketing com Botões (Interatividade) - Usando DTOs ✨

[](#1-remarketing-com-botões-interatividade---usando-dtos-)

Ideal para recuperação de carrinho, promoções e retenção. Agora com **DTOs validados** e **Method Chaining**!

```
use SuaEmpresa\ZApi\Facades\ZApi;
use SuaEmpresa\ZApi\DTOs\Button;

// Enviando para um cliente específico (Multi-tenancy) usando DTOs e method chaining
ZApi::using($tenant->instance, $tenant->token, $tenant->cToken)
    ->sendButtons('5511999999999', 'Olá! Vimos que você esqueceu itens no carrinho. Temos um cupom de 10%!', [
        Button::url('cupom-10', 'Resgatar Desconto', 'https://loja.com/checkout'),
        Button::call('ajuda-vendedor', 'Falar com Atendente', '551133334444'),
    ]);
```

**Com delay (agendamento):**

```
// Envia a mensagem após 30 segundos usando method chaining
ZApi::using($tenant->instance, $tenant->token, $tenant->cToken)
    ->withDelay(30)
    ->sendButtons('5511999999999', 'Mensagem agendada!', [
        Button::url('oferta-limitada', 'Ver Oferta', 'https://loja.com/oferta-relampago'),
    ]);
```

**Método alternativo com arrays (mantém compatibilidade):**

```
// Ainda funciona com arrays simples para compatibilidade
ZApi::using($tenant->instance, $tenant->token, $tenant->cToken)
    ->sendButtons('5511999999999', 'Mensagem', [
        [
            "id" => "cupom-10",
            "type" => "URL",
            "url" => "https://loja.com/checkout",
            "label" => "Resgatar Desconto"
        ],
        [
            "id" => "ajuda-vendedor",
            "type" => "CALL",
            "phone" => "551133334444",
            "label" => "Falar com Atendente"
        ]
    ]);
```

### 2. Tratando Respostas (Webhooks)

[](#2-tratando-respostas-webhooks)

O SDK registra automaticamente a rota `POST: /zapi/webhook`. Basta configurá-la no painel da Z-API. Para agir quando o cliente clica em um botão, crie um **Listener**:

```
// app/Listeners/ProcessZApiInteraction.php

public function handle(ZApiMessageReceived $event)
{
    $payload = $event->payload;

    if ($payload['type'] == 'ButtonAction') {
        $buttonId = $payload['buttonId'];
        // Lógica de negócio aqui (ex: marcar lead no banco)
    }
}
```

---

⛓️ Method Chaining
------------------

[](#️-method-chaining)

O SDK suporta **method chaining fluente** para uma sintaxe elegante e intuitiva:

```
use SuaEmpresa\ZApi\Facades\ZApi;
use SuaEmpresa\ZApi\DTOs\Button;

// Encadeamento completo
$response = ZApi::using($instance, $token, $clientToken)
                ->withDelay(10)
                ->sendButtons('5511999999999', 'Mensagem', [
                    Button::url('btn-1', 'Clique aqui', 'https://example.com')
                ]);

// Todos os métodos de configuração retornam $this
$client = ZApi::using($instance, $token, $clientToken);  // Retorna ZClient
$client->withDelay(5);                                    // Retorna ZClient
$response = $client->sendButtons(...);                    // Retorna Response
```

### Método `withDelay()`

[](#método-withdelay)

Agenda o envio da mensagem para depois de X segundos:

```
// Envia após 60 segundos
ZApi::using($instance, $token, $clientToken)
    ->withDelay(60)
    ->sendButtons('5511999999999', 'Mensagem agendada', [...]);

// O delay é resetado após o envio
// A próxima mensagem será enviada imediatamente
ZApi::using($instance, $token, $clientToken)
    ->sendButtons('5511999999999', 'Mensagem imediata', [...]);
```

**Características:**

- ⏱️ Aceita valores em segundos (inteiro positivo)
- 🔄 Reseta automaticamente após cada envio
- ✅ Valores zero ou negativos são ignorados
- 🎯 Usa o parâmetro `delayMessage` da Z-API

### 🏢 Multi-Tenancy

[](#-multi-tenancy)

O SDK está preparado para ambientes multi-tenant. Cada chamada a `using()` configura as credenciais dinamicamente:

```
// Tenant 1
ZApi::using($tenant1->instance, $tenant1->token, $tenant1->clientToken)
    ->sendButtons(...);

// Tenant 2 - usa credenciais diferentes
ZApi::using($tenant2->instance, $tenant2->token, $tenant2->clientToken)
    ->sendButtons(...);
```

**⚠️ Nota sobre Facades:** Embora o ZClient seja registrado com `bind()` (não singleton) no service provider, facades do Laravel mantêm cache da instância resolvida durante uma requisição. Para isolamento completo em cenários multi-tenant complexos dentro da mesma requisição, considere usar injeção de dependência diretamente:

```
use SuaEmpresa\ZApi\Services\ZClient;

// Injeção de dependência garante nova instância
public function sendMessage(ZClient $client)
{
    $client->using($tenant->instance, $tenant->token, $tenant->clientToken)
           ->sendButtons(...);
}
```

---

🎯 Button DTO
------------

[](#-button-dto)

O SDK utiliza **DTOs (Data Transfer Objects)** para garantir que os botões sejam validados antes de serem enviados.

### Tipos de Botões

[](#tipos-de-botões)

#### Botão de URL

[](#botão-de-url)

```
use SuaEmpresa\ZApi\DTOs\Button;

$button = Button::url(
    id: 'btn-oferta',
    label: 'Ver Oferta',
    url: 'https://example.com/offer'
);
```

#### Botão de Chamada

[](#botão-de-chamada)

```
$button = Button::call(
    id: 'btn-ligar',
    label: 'Ligar Agora',
    phone: '551133334444'
);
```

### Validações Automáticas

[](#validações-automáticas)

O Button DTO valida automaticamente:

- ✓ Tipo de botão (URL ou CALL)
- ✓ Presença de URL para botões tipo URL
- ✓ Presença de telefone para botões tipo CALL
- ✓ Campos obrigatórios (id, type, label)

Se alguma validação falhar, uma `InvalidArgumentException` será lançada.

---

🧪 Testes
--------

[](#-testes)

Este pacote inclui uma suite completa de testes usando **Pest PHP**.

### Executando os Testes

[](#executando-os-testes)

```
# Todos os testes
./vendor/bin/pest

# Com relatório detalhado
./vendor/bin/pest --verbose

# Apenas testes unitários
./vendor/bin/pest tests/Unit
```

### Cobertura de Testes

[](#cobertura-de-testes)

Os testes cobrem:

- ✓ Validação do Button DTO (tipos, campos obrigatórios)
- ✓ Factory methods (Button::url(), Button::call())
- ✓ **Method chaining** (using(), withDelay())
- ✓ **Delay de mensagens** (withDelay, reset automático)
- ✓ Envio correto de JSON para Z-API com DTOs
- ✓ Backward compatibility com arrays
- ✓ Validação de headers (Client-Token)
- ✓ Tratamento de resposta de sucesso (200)
- ✓ Tratamento de erros HTTP (404, 500)
- ✓ Estrutura correta de botões (URL e CALL)
- ✓ Configuração dinâmica de instância/token
- ✓ Cenários de migração (mix de DTOs e arrays)

**Total: 30 testes, 65 assertions - Todos passando! ✅**

Para mais detalhes, consulte [tests/README.md](tests/README.md).

---

📄 Licença
---------

[](#-licença)

Este SDK foi desenvolvido para uso interno e por parceiros. Todos os direitos reservados.

---

### Dica de ouro:

[](#dica-de-ouro)

Para testar os webhooks localmente, use o **Expose** ou **Ngrok** para criar um túnel para o seu domínio local e coloque a URL no painel da Z-API!

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance81

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity40

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 51.4% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

100d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/2819d869b4e7c56055e870169c779ad1388d8bd3147889ba9ab9983219c15a7a?d=identicon)[vgiraldino](/maintainers/vgiraldino)

---

Top Contributors

[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (18 commits)")[![VagnerGiraldinoJr](https://avatars.githubusercontent.com/u/134798623?v=4)](https://github.com/VagnerGiraldinoJr "VagnerGiraldinoJr (17 commits)")

### Embed Badge

![Health badge](/badges/vagner-giraldino-z-api-laravel-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/vagner-giraldino-z-api-laravel-sdk/health.svg)](https://phpackages.com/packages/vagner-giraldino-z-api-laravel-sdk)
```

###  Alternatives

[skagarwal/google-places-api

Google Places Api

1913.0M8](/packages/skagarwal-google-places-api)[dcblogdev/laravel-microsoft-graph

A Laravel Microsoft Graph API (Office365) package

168285.5k1](/packages/dcblogdev-laravel-microsoft-graph)[vluzrmos/slack-api

Wrapper for Slack.com WEB API.

102589.1k3](/packages/vluzrmos-slack-api)[smodav/mpesa

M-Pesa API implementation

16363.7k1](/packages/smodav-mpesa)[jasara/php-amzn-selling-partner-api

A fluent interface for Amazon's Selling Partner API in PHP

1344.8k1](/packages/jasara-php-amzn-selling-partner-api)[grantholle/powerschool-api

A Laravel package to make interacting with PowerSchool less painful.

1715.6k1](/packages/grantholle-powerschool-api)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)