Funcionalidades Principais

Configuração de Banco de Dados: Suporte para MySQL, PostgreSQL e SQL Server
Configuração de Consulta SQL: Personalização da query para buscar pedidos
Integração com Entregas Expressas: Envio automático de pedidos via API
Monitoramento em Tempo Real: Polling configurável para verificar novos pedidos
Interface Intuitiva: Interface gráfica simples e fácil de usar

Instalação e Configuração

No painel da Entregas Expressas, vá até a aba "Integrações" e selecione a opção “Integrador - Entregas Expressas”.

Você verá a seguinte tela:

Explicando os campos:

Ativar Integrador: Marque esta opção para ativar a integração.
Token para colar no App: É o token para realizar a autenticação no aplicativo.
Coleta: Informe o endereço de coleta dos pedidos.
Forma de Pagamento: Escolha entre Faturado, Carteira Digital, etc.
Tipo de Veículo: Defina o tipo de transporte (Moto, Carro, etc.).
Categoria Padrão dos Pedidos: Tipo de entrega padrão (ex: Documentos, Alimentos).
Retorno ao local de coleta: Define se os pedidos através do integrador terão retorno ao local de coleta (se isso não for enviado na query).
Tempo para chamar entregador automaticamente: Define o tempo (em segundos) após confirmar o pedido para acionar um entregador automaticamente.

Após preencher os campos, clique em Salvar.

Em seguida Clique em Baixar Integrador e siga os passos da instalação.

Ao abrir o aplicativo pela primeira vez, será necessário realizar as configurações para o integrador poder buscar e enviar os pedidos.

Configuração do Banco de Dados

Para configurar o banco de dados basta clicar no botão de editar no card de Banco de Dados:

Será exibida uma janela com os seguintes campos, onde todos eles são obrigatórios:

Campo	Descrição	Tipo	Obrigatório
Tipo de Banco	Tipo do banco de dados	Dropdown (MySQL/PostgreSQL/SQL Server)	✅
Host	Endereço IP ou nome do servidor	Texto	✅
Porta	Porta de conexão do banco	Número	✅
Nome do Banco	Nome da base de dados	Texto	✅
Usuário	Usuário para conexão	Texto	✅
Senha	Senha do usuário	Texto	✅
Tempo entre buscas	Intervalo em segundos para verificar novos pedidos	Número (mín. 15s)	✅

Configuração por Tipo de Banco

MySQL

Porta padrão: 3306
Exemplo de Host: localhost ou 192.168.1.100

PostgreSQL

Porta padrão: 5432
Exemplo de Host: localhost ou 192.168.1.100

SQL Server

Porta padrão: 1433
Exemplo de Host: localhost ou 192.168.1.100
Disponível apenas no Windows

Configuração da Consulta SQL

Estrutura da Query

A consulta SQL deve retornar os dados dos pedidos que serão enviados para a Entregas Expressas. É necessário configurar três elementos:

Query SQL: Consulta que busca os pedidos
Coluna de ID único: Campo que identifica unicamente cada pedido (deve ser id)
Coluna de data: Campo que indica quando o pedido foi atualizado (recomenda-se usar updated_at)

Filtro de Data Obrigatório

IMPORTANTE: A query SQL DEVE incluir o filtro {dataUltimoPedido}para funcionar corretamente. Este filtro é substituído automaticamente pelo aplicativo com a data da última verificação, garantindo que apenas pedidos novos sejam enviados.

Exemplo de uso do filtro:

WHERE orders.updated_at > {dataUltimoPedido}

Por que é necessário:

Evita reenvio de pedidos já processados
Reduz a carga no banco de dados
Melhora a performance do aplicativo
Garante que apenas pedidos novos sejam enviados

Campos de Endereço (uma das opções obrigatória)

O backend aceita duas formas de informar o endereço:

Opção A - Campos Separados (Recomendado):

logradouro (obrigatório)
numero (obrigatório)
bairro (obrigatório)
cidade (obrigatório)
cep (obrigatório)

Opção B - Endereço Completo:

endereco_completo (obrigatório)

Campos Obrigatórios no SELECT

Campo	Descrição	Obrigatório	Exemplo
id	ID único do pedido	✅	`venda.id as id`
endereco_completo	Endereço completo (alternativa aos campos separados)	⚪	`CONCAT(logradouro.nome, ', ', entrega.numero, ' - ', bairro.nome, ', ', cidade.nome, ' - ', logradouro.cep) as endereco_completo`
logradouro	Nome da rua/avenida (obrigatório se não usar endereco_completo)	⚪	`logradouro.nome as logradouro`
numero	Número do endereço (obrigatório se não usar endereco_completo)	⚪	`entrega.numero as numero`
bairro	Nome do bairro (obrigatório se não usar endereco_completo)	⚪	`bairro.nome as bairro`
cidade	Nome da cidade (obrigatório se não usar endereco_completo)	⚪	`cidade.nome as cidade`
cep	CEP do endereço (obrigatório se não usar endereco_completo)	⚪	`logradouro.cep as cep`

Campos Opcionais no SELECT

Campo	Descrição	Obrigatório	Exemplo
estado	Estado/UF	⚪	`'SP' as estado`
latitude	Latitude do endereço	⚪	`entrega.latitude as latitude`
longitude	Longitude do endereço	⚪	`entrega.longitude as longitude`
complemento	Complemento do endereço	⚪	`entrega.complemento as complemento`
valor_pedido	Valor total do pedido	⚪	`venda.valortotal as valor_pedido`
forma_pagamento	Forma de pagamento	⚪	`GROUP_CONCAT(formapagamento.nome) as forma_pagamento`
retorno_necessario	Se o pedido precisa de retorno	⚪	`true as retorno_necessario`
cliente	Nome do cliente	⚪	`pessoa.nome as cliente`
telefone	Telefone do cliente	⚪	`CONCAT(entrega.ddd, entrega.telefone) as telefone`
entregador_cpf	CPF do entregador	⚪	`pe.cpf as entregador_cpf`
entregador_email	Email do entregador	⚪	`contato.contato as entregador_email`

Exemplo de Configuração

Exemplo de Query Completa

SELECT 
 orders.id as id,
 customers.name as cliente,
 customers.phone as telefone,
 delivery_addresses.street as logradouro,
 delivery_addresses.number as numero,
 delivery_addresses.neighborhood as bairro,
 delivery_addresses.city as cidade,
 delivery_addresses.state as estado,
 delivery_addresses.zip_code as cep,
 delivery_addresses.complement as complemento,
 delivery_addresses.latitude as latitude,
 delivery_addresses.longitude as longitude,
 orders.total_amount as valor_pedido,
 payments.payment_method as forma_pagamento,
CASE
WHEN orders.return_required = 1 THEN true
ELSE false
END as retorno_necessario,
 drivers.cpf as entregador_cpf,
 drivers.email as entregador_email,
 orders.updated_a AS updated_at
FROM
 orders
INNER JOIN customers ON orders.customer_id = customers.id
INNER JOIN delivery_addresses ON orders.delivery_address_id = delivery_addresses.id
INNER JOIN payments ON orders.payment_id = payments.id
LEFT JOIN order_drivers ON orders.id = order_drivers.order_id
LEFT JOIN drivers ON order_drivers.driver_id = drivers.id
WHERE
 orders.status = 'pending_delivery'
AND orders.payment_status = 'paid'
AND orders.updated_at > {dataUltimoPedido}
ORDER BY
 orders.updated_at DESC

Configuração do Entregas Expressas

Token de Acesso

Para integrar com a plataforma Entregas Expressas, é necessário obter um token de acesso válido.

Ele é o valor do campo Token para colar no App.

Integração pronta para o uso

Após esse passo o integrador estará pronto para buscar e enviar os pedido para o Entregas Expressas!

Assim que ativar "Enviar Pedidos", os pedidos começarão a ser buscados e enviados para o Entregas Expressas.

Problemas Comuns

1. Erro de Conexão com Banco

Verifique se o servidor está acessível
Confirme as credenciais de acesso
Teste a conexão antes de ativar o envio

2. Erro na Query SQL

Verifique a sintaxe da query
Confirme se as colunas obrigatórias estão presentes
Verifique se o filtro {dataUltimoPedido} está presente na query
Teste a query diretamente no banco de dados

3. Erro de Validação de Endereço

Erro: "O campo logradouro é obrigatório quando endereco_completo não está presente"
Solução: Use endereco_completo OU forneça todos os campos separados (logradouro, numero, bairro, cidade, cep)

4. Pedidos Não Sendo Enviados

Verifique se o switch está ativado
Confirme se há novos pedidos no banco
Verifique o intervalo de verificação
Verifique se a query está correta

5. Erro de Endereço Não Encontrado

Erro: "Endereço não encontrado"
Solução: Forneça latitude/longitude ou verifique se o endereço está correto e dentro da área de entrega no Entregas Expressas.

6. Problemas com Filtro de Data

Problema: Aplicativo enviando todos os pedidos repetidamente
Causa: Filtro {dataUltimoPedido} não está presente na query
Solução: Adicione o filtro na cláusula WHERE da query
Exemplo: WHERE orders.updated_at > {dataUltimoPedido}

Integrador Entregas Expressas