Negócio

Integracoes Externas

Documentacao das integracoes com servicos externos do AgrSis - pagamentos, geocodificacao, validacao de documentos, WhatsApp e email.

Integracoes Externas

O AgrSis integra com servicos externos para pagamentos, geocodificacao, validacao de documentos, notificacoes por WhatsApp e envio de emails. Todas as credenciais sao gerenciadas via tabela settings no banco de dados (grupo integrations), editaveis pelo painel admin em /settings.

ASAAS (Pagamentos)

Finalidade: Gateway de pagamentos para cobrar assinaturas da plataforma via PIX, Boleto bancario e Cartao de credito.

Service: App\Services\AsaasGatewayInterface: App\Contracts\PaymentGatewayInterface

Funcionalidades

Metodo	Descricao
`createCustomer()`	Cria cliente no ASAAS a partir do usuario (nome, email, CPF/CNPJ)
`createSubscription()`	Cria assinatura recorrente (MONTHLY, QUARTERLY, YEARLY) com billingType UNDEFINED
`cancelSubscription()`	Cancela assinatura no gateway
`generatePixPayment()`	Gera cobranca PIX com QR Code (imagem base64 + copia-e-cola)
`generateBoletoPayment()`	Gera boleto bancario com URL do boleto e data de vencimento
`generateCardPayment()`	Cobranca em cartao de credito (dados completos ou token para renovacao)
`refundPayment()`	Estorno total ou parcial de um pagamento
`getPaymentStatus()`	Consulta status de pagamento no gateway
`handleWebhook()`	Processa eventos do webhook (PAYMENT_CONFIRMED, PAYMENT_OVERDUE, PAYMENT_REFUNDED, etc.)

Ambientes

Ambiente	URL Base
Sandbox	`https://sandbox.asaas.com/api/v3`
Producao	`https://api.asaas.com/api/v3`

O ambiente e definido pela configuracao asaas_environment na tabela settings.

Configuracoes (tabela `settings`)

Chave	Descricao
`asaas_api_key`	Chave de API do ASAAS
`asaas_environment`	Ambiente: `sandbox` ou `production`
`asaas_webhook_token`	Token para validacao de webhooks recebidos
`asaas_enabled`	Ativar/desativar integracao (`true`/`false`)

Webhook

O ASAAS envia notificacoes automaticas de eventos de pagamento. Os eventos tratados:

Evento ASAAS	Status interno
`PAYMENT_CONFIRMED` / `PAYMENT_RECEIVED`	`paid`
`PAYMENT_OVERDUE`	`past_due`
`PAYMENT_DELETED` / `PAYMENT_RESTORED`	`cancelled`
`PAYMENT_REFUNDED`	`refunded`

Mapeamento de Status

Status ASAAS	Status interno
`CONFIRMED`, `RECEIVED`	`paid`
`PENDING`, `AWAITING_RISK_ANALYSIS`	`pending`
`OVERDUE`	`past_due`
`REFUNDED`, `REFUND_REQUESTED`	`refunded`
Outros	`failed`

ViaCEP (Busca de Endereco)

Finalidade: Buscar dados de endereco a partir do CEP (logradouro, bairro, cidade, UF, codigo IBGE).

Controller: App\Http\Controllers\Api\GeographyController (metodo de busca de CEP)

Detalhes

API publica e gratuita — sem necessidade de chave
Endpoint externo: https://viacep.com.br/ws/{cep}/json/
Validacao: CEP deve ter exatamente 8 digitos numericos
Tratamento de erro: ViaCEP retorna "erro": true quando CEP nao existe

Dados Retornados

Campo retornado	Campo interno
`cep`	`zip_code`
`logradouro`	`street`
`complemento`	`complement`
`bairro`	`neighborhood`
`localidade`	`city`
`uf`	`state`
`ibge`	`ibge_code`

Uso no Sistema

Utilizado nos formularios de cadastro de enderecos (produtores e fornecedores) para auto-preenchimento dos campos ao digitar o CEP.

OpenRouteService (Geocodificacao e Distancias)

Finalidade: Converter enderecos em coordenadas geograficas (latitude/longitude) para calculo de distancias e filtros de proximidade entre produtores e fornecedores.

Service: App\Services\GeocodingService

Detalhes

API gratuita com limites de requisicoes
URL base: https://api.openrouteservice.org
Timeout: 10 segundos por requisicao
Cache: Resultados cacheados por 24 horas (1440 minutos) com versionamento (v2)

Configuracao

A chave de API e configurada via variavel de ambiente:

ORS_API_KEY=sua_chave_aqui

Tratamento de Dados

O service possui logica avancada de normalizacao de enderecos para melhorar a precisao da geocodificacao:

Bairros ignorados: valores como "teste", "sem bairro", "nao informado", "n/a" sao descartados
Numeros ignorados: valores como "0", "s/n", "sem numero" sao descartados
Validacao de UF: mapeamento completo de siglas para nomes de estado

Como Obter uma Chave

Acesse https://openrouteservice.org/dev/#/signup
Crie uma conta gratuita
Gere uma API Key no dashboard
Configure a variavel ORS_API_KEY no .env

HubDev (Validacao de CPF/CNPJ)

Finalidade: Validacao de CPF (Pessoa Fisica) e CNPJ (Pessoa Juridica) junto a base da Receita Federal, retornando dados cadastrais oficiais.

Detalhes

API paga — consome creditos a cada validacao
Site: https://hubdodesenvolvedor.com.br
Gerenciamento: Credenciais vinculadas ao Thiago

Configuracao

HUB_DEV_TOKEN=seu_token_aqui
HUB_DEV_ATIVO=true    # false em desenvolvimento/testes para economizar creditos

Uso no Sistema

Validacao no cadastro de produtores (CPF ou CNPJ)
Validacao no cadastro de fornecedores (CNPJ)
Validacao de responsaveis (CPF)

Importante: Em ambiente de desenvolvimento, manter HUB_DEV_ATIVO=false para nao consumir creditos desnecessariamente.

Z-API (WhatsApp)

Finalidade: Envio de notificacoes via WhatsApp para produtores, fornecedores e administradores.

Service: App\Services\WhatsAppService

Funcionalidades

Metodo	Descricao
`send()`	Envia mensagem de texto para um numero. Suporta link opcional
`sendNotification()`	Envia notificacao formatada com titulo em negrito e link
`formatNotification()`	Formata mensagem no padrao `AgrSis - Titulo` + mensagem + link

Configuracoes (tabela `settings`)

Chave	Descricao
`whatsapp_enabled`	Ativar/desativar envio (`true`/`false`)
`whatsapp_api_url`	URL base da API Z-API (ex: `https://api.z-api.io/instances`)
`whatsapp_api_token`	Client Token de autenticacao
`whatsapp_instance_id`	ID da instancia Z-API

Detalhes Tecnicos

Endpoint de envio: {url}/{instanceId}/send-text
Header de autenticacao: Client-Token
Timeout: 15 segundos
Normalizacao de telefone: adiciona prefixo 55 automaticamente para numeros com 10 ou 11 digitos
Gerenciamento: Credenciais vinculadas ao Thiago via https://app.z-api.io

Tipos de Notificacao

As notificacoes enviadas por WhatsApp sao configuradas por tipo de evento no painel admin (/settings > Notificacoes). Exemplos:

Nova proposta recebida
Proposta aceita/rejeitada
Cotacao publicada
Atualizacoes de pagamento

Teste

O admin pode testar o envio diretamente pelo painel em /settings:

POST /api/v1/admin/settings/test-whatsapp
Body: { "to": "5534999999999" }

SMTP (Email)

Finalidade: Envio de emails transacionais (verificacao de conta, recuperacao de senha, notificacoes).

Configuracoes (tabela `settings`)

Chave	Descricao
`smtp_host`	Servidor SMTP (padrao: `smtp-relay.brevo.com`)
`smtp_port`	Porta SMTP (padrao: `587`)
`smtp_username`	Usuario de autenticacao
`smtp_password`	Senha de autenticacao
`smtp_encryption`	Tipo de criptografia: `tls` ou `ssl`
`smtp_from_address`	Email remetente (padrao: `noreply@agrsis.com`)
`smtp_from_name`	Nome do remetente (padrao: `AgrSis`)

Detalhes Tecnicos

As configuracoes SMTP sao carregadas dinamicamente do banco de dados (tabela settings) e aplicadas em tempo de execucao pelo AdminSettingsController::reloadSmtpFromSettings(). Isso permite que o admin altere credenciais SMTP sem necessidade de deploy.

O recarregamento:

Limpa cache do SettingsService
Reconfigura o mailer SMTP do Laravel via Config::set()
Reseta a instancia do mail.manager para forcar nova conexao

Teste

O admin pode testar o envio diretamente pelo painel em /settings:

POST /api/v1/admin/settings/test-email
Body: { "to": "email@exemplo.com" }

Resumo de Configuracoes

Variaveis de Ambiente (`.env`)

Variavel	Integracao	Obrigatoria
`ORS_API_KEY`	OpenRouteService	Sim (para geocodificacao)
`HUB_DEV_TOKEN`	HubDev	Sim (para validacao CPF/CNPJ)
`HUB_DEV_ATIVO`	HubDev	Sim (controle de ativacao)

Configuracoes no Banco (`settings`)

As demais integracoes (ASAAS, WhatsApp, SMTP) sao configuradas via tabela settings e editaveis pelo painel admin, sem necessidade de alterar variaveis de ambiente ou reiniciar containers.

Grupo	Integracoes
`integrations`	ASAAS (api_key, environment, webhook_token, enabled)
`integrations`	WhatsApp (api_url, api_token, instance_id, enabled)
`integrations`	SMTP (host, port, username, password, encryption, from_address, from_name)

Arquivos Principais

Caminho	Descricao
`apps/api/app/Services/AsaasGateway.php`	Gateway de pagamentos ASAAS
`apps/api/app/Contracts/PaymentGatewayInterface.php`	Interface do gateway de pagamentos
`apps/api/app/Services/GeocodingService.php`	Geocodificacao via OpenRouteService
`apps/api/app/Services/WhatsAppService.php`	Envio de mensagens via Z-API
`apps/api/app/Services/SettingsService.php`	Gerenciamento de configuracoes do banco
`apps/api/app/Http/Controllers/Api/AdminSettingsController.php`	Endpoints de configuracao e testes
`apps/api/app/Http/Controllers/Api/GeographyController.php`	Busca de CEP via ViaCEP
`apps/api/app/Services/SubscriptionService.php`	Orquestracao de assinaturas (usa AsaasGateway)

Edit this pageorReport an issue

Cotacoes (Orders)

Documentacao completa do modulo de cotacoes/licitacoes da plataforma AgrSis.

Notificacoes

Sistema de notificacoes multicanal com 36 tipos, configuracao global e preferencias individuais por usuario.