•Ednan Ferreira
Voltar ao Portfólio

Z-API Integration Service

Serviço de integração robusto para automação de WhatsApp utilizando a Z-API. Atua como um middleware inteligente que gerencia autenticação, sessões e expõe uma API simplificada para outros serviços.

O projeto implementa:

  • Proxy/Wrapper para Z-API

    Camada de abstração que simplifica o consumo da API oficial

  • Visualização de QRCode

    Interface gráfica para leitura e pareamento rápido de instâncias

  • Pareamento via Telefone

    Alternativa de conexão via código numérico para maior compatibilidade

  • Gestão de Instância

    Controle total sobre reinicialização e desconexão de sessões

  • Arquitetura Modular

    Backend Python estruturado com foco em manutenibilidade e escalabilidade

Python
FastAPI
React
Vite
Docker

Problema e Solução

Problema

Gerenciar conexões de WhatsApp em escala apresenta desafios:

  • Complexidade de autenticação com múltiplos tokens
  • Dificuldade em monitorar status de conexão em tempo real
  • Falta de interface visual para pareamento de novas sessões
  • Processos manuais para reiniciar instâncias travadas
  • Acoplamento direto com a API de terceiros em vários serviços

Solução

Um middleware dedicado e interface de gestão:

  • API Gateway centralizado para todas as operações de WhatsApp
  • Dashboard React para visualização de status e QRCode
  • Endpoints padronizados e documentados (Swagger UI)
  • Tratamento automático de erros e reconexão
  • Abstração completa da complexidade da Z-API

Benefícios

  • Estabilidade

    Redução drástica de quedas de conexão e timeouts

  • Manutenibilidade

    Código limpo e modular facilitando evoluções futuras

  • Operação Simplificada

    Qualquer usuário pode parear uma instância via QR Code

  • Segurança

    Tokens sensíveis isolados no backend via variáveis de ambiente

Destaques Técnicos

Proxy Inteligente Z-API

Desafio

Gerenciar tokens e endpoints da Z-API diretamente em múltiplos serviços gera acoplamento e complexidade.

Solução

Backend atua como um wrapper centralizado, gerenciando autenticação e expondo endpoints simplificados e padronizados para os clientes internos.

Centralização de lógica e segurança

Pareamento em Tempo Real

Desafio

Necessidade de uma interface simples para conectar novas instâncias do WhatsApp sem intervenção técnica.

Solução

Frontend React consome endpoint de QRCode em Base64 e atualiza status de conexão em tempo real, permitindo pareamento imediato pelo usuário final.

UX simplificada para operação técnica

Conexão via Código Telefônico

Desafio

Limitações de câmera ou preferência por pareamento via código numérico.

Solução

Implementação de fluxo alternativo de conexão utilizando código de pareamento via número de telefone, aumentando a flexibilidade de uso.

Acessibilidade e redundância de conexão

Gestão de Ciclo de Vida

Desafio

Instâncias travadas ou desconectadas exigiam reinicialização manual complexa.

Solução

Endpoints dedicados para Restart e Disconnect, permitindo recuperação rápida de falhas de conexão diretamente pela interface.

Resiliência e auto-recuperação

Stack Tecnológica

Backend - Python (FastAPI)

FastAPI0.109+

Framework moderno e de alta performance para construção de APIs com Python

HTTPXAsync

Cliente HTTP assíncrono para comunicação não-bloqueante com a Z-API

Pydanticv2

Validação de dados e serialização robusta

Uvicorn

Servidor ASGI de alta performance

Frontend - React

React

Biblioteca JavaScript para construção de interfaces de usuário

Vite

Build tool de próxima geração para desenvolvimento frontend rápido

Axios

Cliente HTTP baseado em promessas para o navegador

Infraestrutura

Docker

Containerização para garantir consistência entre ambientes

Z-API

Gateway de integração com WhatsApp

Fluxo de Operação

Ciclo de Conexão e Gerenciamento

1.

Frontend solicita status da conexão ao Backend

2.

Backend consulta Z-API e retorna estado (Conectado/Desconectado)

3.

Se desconectado, Frontend solicita QRCode em Base64

4.

Usuário lê o QRCode com o WhatsApp no celular

5.

Z-API confirma conexão via Webhook ou Polling

6.

Backend atualiza status e libera uso da API para envio de mensagens

Conceitos Aplicados

Clean Code

Estrutura modular e legível em todo o backend

Type Hints

Uso estrito de tipagem no Python para segurança

Async/Await

Comunicação não-bloqueante com APIs externas

Separation of Concerns

Divisão clara entre Services e Controllers

Environment Config

Gerenciamento seguro via variáveis de ambiente (.env)

Component-Based UI

Interface React modular e reutilizável

Voltar ao Portfólio