🇧🇷 Demo de Integração com Z-API (WhatsApp) usando Spring Boot + Clean Architecture

Visão Geral

Este projeto é uma demo de integração com a Z-API, uma API para WhatsApp, construída com Spring Boot seguindo rigorosamente o padrão de Clean Architecture.

A aplicação expõe endpoints simples para:

Obter o QR Code de conexão da instância;
Desconectar a instância;
Obter dados do dispositivo conectado;
Enviar mensagens de texto, imagem e vídeo via WhatsApp;
Sincronizar e armazenar chats automaticamente da Z-API.

O projeto usa SQLite como banco de dados local, com uma tabela chats para armazenar informações de contatos/conversas.

Tecnologias Utilizadas

Java 17+
Spring Boot 3.2.x
Spring Data JPA
WebClient (chamadas HTTP reativas)
Z-API (integração com WhatsApp)
SQLite (banco de dados local)
Lombok (redução de boilerplate)
Maven (gerenciamento de dependências)
Arquitetura em camadas (Clean Architecture)

Arquitetura (Clean Architecture)

A estrutura segue uma separação clara de responsabilidades seguindo os princípios de Clean Architecture:

🎯 Domain Layer (Camada de Domínio)

Princípio: Esta camada não tem dependências de frameworks externos. Contém apenas lógica de negócio pura.

entities/ – Entidades de domínio (ex.: Chat)
repositories/ – Interfaces puras de repositórios (sem dependência de JPA/Spring)
usecases/ – Casos de uso (interactors) com lógica de negócio
- messages/ – Envio de texto, imagem e vídeo
- chats/ – Consulta e sincronização de chats
- instance/ – Operações da instância (QR Code, desconectar, dados do dispositivo)

🔧 Data Layer (Camada de Dados)

Princípio: Implementa as interfaces do domínio usando frameworks específicos (Spring, JPA, etc).

config/ – Configuração da Z-API
services/ – Serviço HTTP para comunicação com Z-API (ZApiHttpService)
repositories/ – Implementação dos repositórios
- ChatRepositoryJpa – Interface Spring Data JPA
- ChatRepositoryImpl – Adaptador que implementa a interface do domínio

Padrão Adapter: O ChatRepositoryImpl adapta o ChatRepositoryJpa (Spring Data) para a interface ChatRepository (Domain), mantendo o domínio independente de frameworks.

🎨 Presentation Layer (Camada de Apresentação)

controllers/ – Controllers REST (Spring MVC)
- MessagesController
- ChatsController
- InstanceController

Diagrama de Dependências

┌─────────────────────────────────────────────────┐
│           Presentation Layer                     │
│  (Controllers - REST API)                        │
└────────────────┬────────────────────────────────┘
                 │
                 ↓
┌─────────────────────────────────────────────────┐
│           Domain Layer                           │
│  (Entities, Use Cases, Repository Interfaces)    │
│  ⚠️ SEM DEPENDÊNCIAS DE FRAMEWORKS               │
└────────────────┬────────────────────────────────┘
                 ↑
                 │ implementa
                 │
┌─────────────────────────────────────────────────┐
│           Data Layer                             │
│  (Repository Impl, JPA, HTTP Services, Config)   │
│  ✅ USA Spring, JPA, WebClient                   │
└─────────────────────────────────────────────────┘

Endpoints Disponíveis

Messages (envio de mensagens)

Base path: /messages

POST /messages/send-text
Envia uma mensagem de texto.

{
  "phone": "5511999999999",
  "message": "Olá, mundo!"
}

POST /messages/send-image
Envia uma mensagem de imagem (com URL).

{
  "phone": "5511999999999",
  "image": "https://example.com/image.jpg",
  "caption": "Legenda da imagem"
}

POST /messages/send-video
Envia uma mensagem de vídeo (com URL).

{
  "phone": "5511999999999",
  "video": "https://example.com/video.mp4",
  "caption": "Legenda do vídeo"
}

Chats

Base path: /chats

GET /chats/get-chats
Sincroniza chats da Z-API e retorna todos os chats armazenados.

Comportamento:
1. Busca chats da API Z-API
2. Para cada chat retornado, verifica se já existe no banco (por lid ou phone)
3. Se não existir, cria e salva um novo registro
4. Retorna todos os chats do banco de dados
Nota: Em caso de erro na API, retorna apenas os chats do banco local.

Instance (instância Z-API / dispositivo)

Base path: /instance

GET /instance/me
Retorna dados do dispositivo/instância conectada.
GET /instance/disconnect
Desconecta a instância do WhatsApp.
GET /instance/qr-code
Retorna o QR Code para conectar o dispositivo ao WhatsApp.

Banco de Dados

O projeto utiliza SQLite com uma tabela principal:

Tabela `chats`

Coluna	Tipo	Descrição
`id`	STRING	UUID - chave primária
`name`	STRING	Nome do contato/chat
`phone`	STRING	Telefone (formato internacional recomendado)
`lid`	STRING	Identificador lógico usado pela integração

O banco é inicializado automaticamente na primeira execução, criando o arquivo database.sqlite na raiz do projeto via JPA/Hibernate.

Pré-requisitos

Java 17+ (JDK instalado)
Maven (para build e dependências)
Conta/configuração válida na Z-API (instanceToken, instanceId, clientToken)

Instalação

# Clonar o repositório
git clone https://github.com/joaoVictor-irrah/z-api-demo-java.git
cd z-api-demo-java

# Compilar o projeto
mvn clean install

Configuração

Copie o arquivo .env.example e renomeie para .env:

cp .env.example .env

Edite o arquivo .env ou configure as variáveis de ambiente:

Z_API_INSTANCE_ID=seu_instance_id
Z_API_INSTANCE_TOKEN=seu_instance_token
Z_API_CLIENT_TOKEN=seu_client_token

No Linux/macOS, exporte as variáveis:

export Z_API_INSTANCE_ID=seu_instance_id
export Z_API_INSTANCE_TOKEN=seu_instance_token
export Z_API_CLIENT_TOKEN=seu_client_token

No Windows (CMD):

set Z_API_INSTANCE_ID=seu_instance_id
set Z_API_INSTANCE_TOKEN=seu_instance_token
set Z_API_CLIENT_TOKEN=seu_client_token

Ou edite diretamente o src/main/resources/application.properties (não recomendado para produção).

Execução do Projeto

# Desenvolvimento
mvn spring-boot:run

# Ou executar o JAR compilado
mvn clean package
java -jar target/z-api-demo-java-1.0.0.jar

O servidor será iniciado na porta 3000 por padrão: http://localhost:3000

Fluxo Básico de Uso

Obter QR Code
- Chamar GET http://localhost:3000/instance/qr-code
- Escanear o QR Code com o WhatsApp do dispositivo.
Verificar dispositivo conectado
- Chamar GET http://localhost:3000/instance/me.
Sincronizar chats
- GET http://localhost:3000/chats/get-chats busca chats da Z-API e armazena no banco automaticamente.
Enviar mensagens
- POST http://localhost:3000/messages/send-text para texto
- POST http://localhost:3000/messages/send-image para imagem
- POST http://localhost:3000/messages/send-video para vídeo
Desconectar instância
- GET http://localhost:3000/instance/disconnect.

Estrutura de Pastas

src/main/java/com/example/zapidemo/
├── domain/                              # CAMADA DE DOMÍNIO (sem dependências externas)
│   ├── entities/
│   │   └── Chat.java                   # Entidade de domínio
│   ├── repositories/
│   │   └── ChatRepository.java         # Interface pura (sem JPA)
│   └── usecases/
│       ├── messages/
│       │   ├── SendTextUseCase.java
│       │   ├── SendImageUseCase.java
│       │   └── SendVideoUseCase.java
│       ├── chats/
│       │   └── GetChatsUseCase.java    # Sincroniza chats da API
│       └── instance/
│           ├── GetMeUseCase.java
│           ├── DisconnectUseCase.java
│           └── GetQrCodeUseCase.java
│
├── data/                                # CAMADA DE DADOS (implementações com frameworks)
│   ├── config/
│   │   └── ZApiConfig.java             # Configuração Z-API
│   ├── repositories/
│   │   ├── ChatRepositoryJpa.java      # Interface Spring Data JPA
│   │   └── ChatRepositoryImpl.java     # Adaptador Domain → JPA
│   └── services/
│       └── ZApiHttpService.java        # WebClient para Z-API (get, getList, post)
│
├── presentation/                        # CAMADA DE APRESENTAÇÃO
│   └── controllers/
│       ├── MessagesController.java
│       ├── ChatsController.java
│       └── InstanceController.java
│
└── ZApiDemoApplication.java             # Classe principal Spring Boot

Componentes Importantes

ZApiHttpService

Serviço para comunicação com a Z-API via WebClient.

Métodos disponíveis:

get(endpoint) – Para respostas JSON em formato de objeto {...}
getList(endpoint) – Para respostas JSON em formato de array [...]
post(endpoint, data) – Para envio de dados via POST

GetChatsUseCase

Caso de uso que implementa a sincronização automática de chats:

Busca chats da Z-API usando zApiHttpService.getList("/chats")
Para cada chat retornado:
- Verifica se já existe no banco (por lid ou phone)
- Se não existir, cria novo registro com UUID e salva
Retorna todos os chats armazenados no banco

Observações

Este projeto segue Clean Architecture de forma rigorosa:
- Domain Layer é independente de frameworks
- Data Layer implementa interfaces do domínio usando Spring/JPA
- Presentation Layer expõe REST API
A sincronização de chats é automática ao chamar /chats/get-chats
Este projeto é uma port do projeto original em NestJS/TypeScript para Java/Spring Boot, mantendo a mesma arquitetura e funcionalidades.

🇺🇸 Z-API (WhatsApp) Integration Demo using Spring Boot + Clean Architecture

Overview

This project is a demo integration with Z-API, a WhatsApp API, built with Spring Boot strictly following the Clean Architecture pattern.

The application exposes simple endpoints to:

Get the instance connection QR Code;
Disconnect the instance;
Get device information of the connected WhatsApp;
Send basic text, image and video messages via WhatsApp;
Synchronize and store chats automatically from Z-API.

The project uses SQLite as a local database with a chats table to store contact/chat information.

Tech Stack

Java 17+
Spring Boot 3.2.x
Spring Data JPA
WebClient (reactive HTTP calls)
Z-API (WhatsApp integration)
SQLite (local database)
Lombok (boilerplate reduction)
Maven (dependency management)
Layered structure using Clean Architecture

Architecture (Clean Architecture)

The project structure follows clear separation of concerns following Clean Architecture principles:

🎯 Domain Layer

Principle: This layer has no external framework dependencies. Contains only pure business logic.

entities/ – Domain entities (e.g., Chat)
repositories/ – Pure interfaces (no JPA/Spring dependencies)
usecases/ – Use cases (interactors) with business logic
- messages/ – Send text, image, video
- chats/ – Fetch and synchronize chats
- instance/ – Instance operations (QR Code, disconnect, device data)

🔧 Data Layer

Principle: Implements domain interfaces using specific frameworks (Spring, JPA, etc).

config/ – Z-API configuration
services/ – HTTP service for Z-API communication (ZApiHttpService)
repositories/ – Repository implementations
- ChatRepositoryJpa – Spring Data JPA interface
- ChatRepositoryImpl – Adapter implementing domain interface

Adapter Pattern: ChatRepositoryImpl adapts ChatRepositoryJpa (Spring Data) to ChatRepository interface (Domain), keeping the domain framework-independent.

🎨 Presentation Layer

controllers/ – REST controllers (Spring MVC)
- MessagesController
- ChatsController
- InstanceController

Dependency Diagram

┌─────────────────────────────────────────────────┐
│           Presentation Layer                     │
│  (Controllers - REST API)                        │
└────────────────┬────────────────────────────────┘
                 │
                 ↓
┌─────────────────────────────────────────────────┐
│           Domain Layer                           │
│  (Entities, Use Cases, Repository Interfaces)    │
│  ⚠️ NO FRAMEWORK DEPENDENCIES                    │
└────────────────┬────────────────────────────────┘
                 ↑
                 │ implements
                 │
┌─────────────────────────────────────────────────┐
│           Data Layer                             │
│  (Repository Impl, JPA, HTTP Services, Config)   │
│  ✅ USES Spring, JPA, WebClient                  │
└─────────────────────────────────────────────────┘

Available Endpoints

Messages

Base path: /messages

POST /messages/send-text
Sends a text message.

{
  "phone": "5511999999999",
  "message": "Hello, world!"
}

POST /messages/send-image
Sends an image message (via URL).

{
  "phone": "5511999999999",
  "image": "https://example.com/image.jpg",
  "caption": "Image caption"
}

POST /messages/send-video
Sends a video message (via URL).

{
  "phone": "5511999999999",
  "video": "https://example.com/video.mp4",
  "caption": "Video caption"
}

Chats

Base path: /chats

GET /chats/get-chats
Synchronizes chats from Z-API and returns all stored chats.

Behavior:
1. Fetches chats from Z-API
2. For each returned chat, checks if it already exists in database (by lid or phone)
3. If it doesn't exist, creates and saves a new record
4. Returns all chats from the database
Note: In case of API error, returns only chats from local database.

Instance (Z-API / device)

Base path: /instance

GET /instance/me
Returns information about the connected device/instance.
GET /instance/disconnect
Disconnects the WhatsApp instance.
GET /instance/qr-code
Returns the QR Code for pairing the WhatsApp device.

Database

The project uses SQLite with a main table:

Table `chats`

Column	Type	Description
`id`	STRING	UUID - primary key
`name`	STRING	Contact/chat name
`phone`	STRING	Phone number (international format recommended)
`lid`	STRING	Logical identifier used by the integration

The database is initialized automatically at startup, creating the database.sqlite file at the project root via JPA/Hibernate.

Requirements

Java 17+ (JDK installed)
Maven (for build and dependencies)
A valid Z-API account/configuration (instanceToken, instanceId, clientToken)

Installation

# Clone the repository
git clone https://github.com/joaoVictor-irrah/z-api-demo-java.git
cd z-api-demo-java

# Build the project
mvn clean install

Configuration

Copy .env.example and rename to .env:

cp .env.example .env

Edit the .env file or set environment variables:

Z_API_INSTANCE_ID=your_instance_id
Z_API_INSTANCE_TOKEN=your_instance_token
Z_API_CLIENT_TOKEN=your_client_token

On Linux/macOS, export the variables:

export Z_API_INSTANCE_ID=your_instance_id
export Z_API_INSTANCE_TOKEN=your_instance_token
export Z_API_CLIENT_TOKEN=your_client_token

On Windows (CMD):

set Z_API_INSTANCE_ID=your_instance_id
set Z_API_INSTANCE_TOKEN=your_instance_token
set Z_API_CLIENT_TOKEN=your_client_token

Or edit src/main/resources/application.properties directly (not recommended for production).

Running the Project

# Development
mvn spring-boot:run

# Or run the compiled JAR
mvn clean package
java -jar target/z-api-demo-java-1.0.0.jar

The server will start on port 3000 by default: http://localhost:3000

Basic Usage Flow

Get QR Code
- Call GET http://localhost:3000/instance/qr-code
- Scan the QR Code with your WhatsApp app.
Check connected device
- Call GET http://localhost:3000/instance/me.
Synchronize chats
- GET http://localhost:3000/chats/get-chats fetches chats from Z-API and stores them automatically.
Send messages
- POST http://localhost:3000/messages/send-text for text
- POST http://localhost:3000/messages/send-image for image
- POST http://localhost:3000/messages/send-video for video
Disconnect instance
- Call GET http://localhost:3000/instance/disconnect.

Folder Structure

src/main/java/com/example/zapidemo/
├── domain/                              # DOMAIN LAYER (no external dependencies)
│   ├── entities/
│   │   └── Chat.java                   # Domain entity
│   ├── repositories/
│   │   └── ChatRepository.java         # Pure interface (no JPA)
│   └── usecases/
│       ├── messages/
│       │   ├── SendTextUseCase.java
│       │   ├── SendImageUseCase.java
│       │   └── SendVideoUseCase.java
│       ├── chats/
│       │   └── GetChatsUseCase.java    # Synchronizes chats from API
│       └── instance/
│           ├── GetMeUseCase.java
│           ├── DisconnectUseCase.java
│           └── GetQrCodeUseCase.java
│
├── data/                                # DATA LAYER (framework implementations)
│   ├── config/
│   │   └── ZApiConfig.java             # Z-API configuration
│   ├── repositories/
│   │   ├── ChatRepositoryJpa.java      # Spring Data JPA interface
│   │   └── ChatRepositoryImpl.java     # Domain → JPA adapter
│   └── services/
│       └── ZApiHttpService.java        # WebClient for Z-API (get, getList, post)
│
├── presentation/                        # PRESENTATION LAYER
│   └── controllers/
│       ├── MessagesController.java
│       ├── ChatsController.java
│       └── InstanceController.java
│
└── ZApiDemoApplication.java             # Spring Boot main class

Important Components

ZApiHttpService

Service for Z-API communication via WebClient.

Available methods:

get(endpoint) – For JSON responses in object format {...}
getList(endpoint) – For JSON responses in array format [...]
post(endpoint, data) – For sending data via POST

GetChatsUseCase

Use case that implements automatic chat synchronization:

Fetches chats from Z-API using zApiHttpService.getList("/chats")
For each returned chat:
- Checks if it already exists in database (by lid or phone)
- If it doesn't exist, creates new record with UUID and saves
Returns all chats stored in database

Notes

This project follows Clean Architecture rigorously:
- Domain Layer is framework-independent
- Data Layer implements domain interfaces using Spring/JPA
- Presentation Layer exposes REST API
Chat synchronization is automatic when calling /chats/get-chats
This project is a port of the original NestJS/TypeScript project to Java/Spring Boot, maintaining the same architecture and functionality.

License

MIT

Author

JoaoMadeiraxyz

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.idea		.idea
src/main		src/main
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
database.sqlite		database.sqlite
dependency-tree.txt		dependency-tree.txt
pom.xml		pom.xml

Folders and files

Latest commit

History

Repository files navigation

🇧🇷 Demo de Integração com Z-API (WhatsApp) usando Spring Boot + Clean Architecture

Visão Geral

Tecnologias Utilizadas

Arquitetura (Clean Architecture)

🎯 Domain Layer (Camada de Domínio)

🔧 Data Layer (Camada de Dados)

🎨 Presentation Layer (Camada de Apresentação)

Diagrama de Dependências

Endpoints Disponíveis

Messages (envio de mensagens)

Chats

Instance (instância Z-API / dispositivo)

Banco de Dados

Tabela chats

Pré-requisitos

Instalação

Configuração

Execução do Projeto

Fluxo Básico de Uso

Estrutura de Pastas

Componentes Importantes

ZApiHttpService

GetChatsUseCase

Observações

🇺🇸 Z-API (WhatsApp) Integration Demo using Spring Boot + Clean Architecture

Overview

Tech Stack

Architecture (Clean Architecture)

🎯 Domain Layer

🔧 Data Layer

🎨 Presentation Layer

Dependency Diagram

Available Endpoints

Messages

Chats

Instance (Z-API / device)

Database

Table chats

Requirements

Installation

Configuration

Running the Project

Basic Usage Flow

Folder Structure

Important Components

ZApiHttpService

GetChatsUseCase

Notes

License

Author

Contributing

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Tabela `chats`

Table `chats`

Packages