Integrador Entregas Expressas

O Integrador Entregas Expressas é um aplicativo desktop que permite integrar pedidos de qualquer banco de dados com o Entregas Expressas.

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:

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:

1. Query SQL: Consulta que busca os pedidos

2. Coluna de ID único: Campo que identifica unicamente cada pedido (deve ser id)

3. 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

Campos Opcionais no SELECT

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}