English
Español
Sara Agente de Entregas - Confirma Fácil
O Agente de Entregas é uma solução de inteligência artificial integrada ao Confirma Fácil, voltada à gestão e monitoramento do ciclo completo de entregas — desde a emissão da nota fiscal até a confirmação de entrega ao destinatário — com foco em visibilidade, performance e resolução de ocorrências.
Este guia foi elaborado para apoiar você no uso do Agente de Entregas, mostrando como criar prompts eficazes e aplicá-los no dia a dia da gestão logística. Com as práticas deste guia, você poderá:
- Consultar e monitorar embarques em tempo real, com visibilidade sobre status, previsões de entrega e atrasos.
- Calcular métricas estratégicas como efetividade, lead time médio e performance de entrega no prazo.
- Apoiar decisões operacionais com base em dados de rastreamento, notas em aberto e valor de mercadoria em risco.
Importante
O Agente de Entregas está disponível exclusivamente para embarcadores cadastrados na plataforma Confirma Fácil. Para saber mais, entre em contato com seu gerente de conta.
O que é o Agente de Entregas?
O Agente de Entregas é uma IA generativa integrada ao Confirma Fácil. Ele funciona como um assistente digital especializado em rastreamento, análise de performance e gestão de ocorrências logísticas, capaz de consultar dados de embarques ativos e históricos, identificar desvios de prazo e emitir análises técnicas e estratégicas. O agente atende dois perfis de usuário:
| Perfil | Foco |
|---|---|
| Gestor Logístico | Análise de desempenho, métricas de eficiência e decisões estratégicas. |
| Operador Logístico | Acompanhamento de embarques, rastreamento de ocorrências e gestão operacional do dia a dia. |
Os dados utilizados pelo agente refletem sempre a posição de D-1 — ou seja, as informações consolidadas até o fechamento do dia anterior. Eventos do dia corrente não estão disponíveis e serão informados quando necessário.
Pré-requisitos e configurações
Para usar o Agente de Entregas, é necessário garantir que os pré-requisitos abaixo sejam atendidos:
- Ter acesso ativo à plataforma Confirma Fácil como Embarcador.
- Ter ao menos um perfil de usuário habilitado: Gestor Logístico ou Operador Logístico. (Owner ou Admin.)
- Habilitar o acesso ao chat do Agente de Entregas nas configurações do Confirma Fácil em:
- Menu: Configurações > Integrações
- Informar os dados: Tenant Name, Access Key e Secret Key
- Os embarques devem estar corretamente registrados na plataforma com os campos obrigatórios preenchidos.
O que o agente pode responder?
Com base nos dados disponíveis na plataforma, o Agente de Entregas pode responder a perguntas relacionadas a:
Visão estratégica e gerencial — Gestor Logístico
- Qual a efetividade de entregas no período?
- Qual o lead time médio das entregas?
- Qual o percentual de entregas realizadas dentro do prazo (logístico / destinatário)?
- Qual o valor total em mercadorias atrasadas?
- Quantas notas estão em aberto (A Embarcar + Em Trânsito)?
- Quantas notas foram finalizadas sem entrega?
- Qual transportadora tem maior índice de atrasos?
- Qual transportadora acumula mais ocorrências penalizadoras?
- Quais estados têm mais notas em atraso?
- Quais rotas
{{UF origem}}→{{UF destino}}concentram mais ocorrências? - Como evoluiu o índice de atrasos nos últimos 30 dias?
- Quantos embarques estão com Rastron desativado e ainda em aberto?
Execução operacional e acompanhamento — Operador Logístico
- Qual o status atual do embarque da nota
{{número}}? - Qual o status atual do pedido
{{número}}? - O Rastron está ativo para o embarque
{{número}}? - Qual a última ocorrência registrada da nota
{{número}}? - Quais ocorrências foram registradas no embarque
{{número}}? - A nota
{{número}}tem alguma ocorrência com foto? - O embarque foi finalizado? Qual foi a ocorrência finalizadora?
- Quais notas venceram o prazo esta semana e ainda não foram entregues?
- Qual a previsão de entrega da nota
{{número}}? - Quais embarques pertencem ao pedido
{{número do pedido}}? - Quais entregas com agendamento estão com prazo vencido?
Alertas operacionais
O agente sinaliza automaticamente situações críticas com os seguintes marcadores:
| Marcador | Situação | Critério |
|---|---|---|
| 🔴 URGENTE | Nota muito atrasada — sem entrega e prazo vencido há mais de 7 dias | DATA_ATUAL > data_previsao + 7 dias E status = NAO_ENTREGUE |
| 🟡 ATENÇÃO | Nota atrasada ou finalizadas sem entrega | DATA_ATUAL > data_previsao E status = NAO_ENTREGUE, ou status = FINALIZADO |
| 🟢 OK | Nota entregue dentro do prazo | data_entrega ≤ data_previsao E status = ENTREGUE |
Quais informações o agente acessa?
O Agente de Entregas utiliza duas bases de dados distintas. Em muitas situações, é necessário cruzar informações das duas para compor uma resposta completa.
Chave de relacionamento entre as bases:
- Base 1
(Embarques).idembarque←→ Base 2(Ocorrências).idembarque
Base 1 — Embarques
Contém todos os dados relativos à nota fiscal, ao embarque, ao embarcador, ao destinatário e à transportadora principal.
Lista de dados — Base 1
| Campo | Descrição |
|---|---|
idembarque | Identificador único do embarque — chave de relacionamento com a Base 2 |
data_criacao | Data de criação do embarque no sistema |
numero_embarque | Número da nota fiscal |
serie | Série da nota fiscal |
chave | Chave de acesso da NF-e (44 dígitos) |
pedido / idpedido | Número e ID do pedido vinculado ao embarque |
origem | Como a nota foi criada: API, CSV, Portal, e-mail |
idstatus_embarque | ID numérico do status do embarque |
status_embarque | Descrição textual: ENTREGUE, NAO_ENTREGUE, CANCELADO, A_EMBARCAR, FINALIZADO, DESCONHECIDO |
status_rastron | Rastreamento Rastron: RASTRON_ATIVO ou RASTRON_DESATIVADO |
tags | Tags vinculadas ao embarque, separadas pelo símbolo de barra vertical: | |
tipo_operacao / tipo_envio / tipo_frete | Tipo de operação, envio (normal, expresso) e frete (CIF, FOB) |
data_emissao | Data de emissão da nota fiscal |
data_embarque | Data de criação/início do embarque |
data_previsao | Previsão de entrega calculada pelo sistema (referência padrão) |
data_previsao_logistica | Previsão sob perspectiva logística (pode diferir do sistema) |
data_previsao_destinatario | Data comunicada ao destinatário |
data_entrega | Data de entrega registrada (mais recente) |
data_finalizadora | Data de finalização do embarque — Atenção: finalizado ≠ entregue |
valor | Valor da nota fiscal |
peso_bruto | Peso bruto da carga |
quantidade_volumes | Quantidade de volumes da carga |
idembarcador / cnpj_embarcador | ID e CNPJ do embarcador (empresa remetente) |
idromaneio / numero_romaneio | ID e número do romaneio vinculado |
iddestinatario / nome_destinatario | ID e razão social do destinatário |
cnpj_destinatario | CNPJ do destinatário |
email_destinatario / celular_destinatario | Contato do destinatário |
especial | Flag — destinatário marcado como especial (1 = sim) |
agendamento | Flag — entrega requer agendamento prévio (1 = sim) |
embarque_uf / embarque_cidade | UF e cidade de origem do embarque |
destinatario_uf / destinatario_cidade | UF e cidade do destinatário |
nome_transportadora / cnpj_transportadora | Transportadora responsável pelo embarque |
qtd_feriados | Feriados nacionais entre emissão e entrega, excluindo fins de semana |
dt_integrated | Última sincronização do registro no datalake (D-1) |
Nota
Status do Embarque: os status abaixo são referenciados pelos campos idstatus_embarque (numérico) e status_embarque (texto).
- 1 =
ENTREGUE— Nota já entregue ao destinatário - 2 =
NAO_ENTREGUE— Nota em trânsito, transporte ainda em andamento - 3 =
CANCELADO— Nota cancelada ou excluída (ignorar em métricas) - 4 =
A_EMBARCAR— Nota emitida, embarque ainda não iniciado - 5 =
FINALIZADO— Encerrado sem entrega efetiva (avaria, extravio) — NÃO é entregue - ? =
DESCONHECIDO— Status inconsistente, ignorar em métricas
Base 2 — Ocorrências
Focada exclusivamente na ocorrência e seu tipo. Não contém dados de trecho, transportadora ou endereços detalhados. Para análises que relacionem ocorrência com transportadora, utilize os dados da Base 1.
Lista de dados — Base 2
| Campo | Descrição |
|---|---|
idocorrencia | Identificador único da ocorrência |
idembarque | ID do embarque vinculado — chave de relacionamento com a Base 1 |
data | Data em que a ocorrência aconteceu |
data_criacao | Data em que a ocorrência foi registrada no sistema |
foto | Indica se há foto anexada à ocorrência (boolean) |
idtrecho | ID do trecho em que a ocorrência aconteceu (referência) |
idtipo_ocorrencia | ID do tipo de ocorrência |
penalizador | Flag — ocorrência penalizadora para a transportadora (1 = sim) |
nao_penalizador | Flag — ocorrência não penalizadora (1 = sim) |
finalizador | Flag — ocorrência que encerra o fluxo do embarque (1 = sim) |
dt_integrated | Última sincronização do registro no datalake (D-1) |
Nota
Regras para valores e cruzamento de bases:
- Sempre exclua status
CANCELADOeDESCONHECIDOde cálculos de performance e efetividade. - Ao cruzar as bases, use
idembarquecomo chave de junção entre Embarques e Ocorrências. - Uma ocorrência pode ter
penalizador= 0 enao_penalizador= 0 simultaneamente — indica tipo neutro. - Detalhes do trecho (transportadora, endereço) não estão disponíveis na Base 2. Use
nome_transportadorada Base 1 como referência.
Métricas calculadas pelo agente
O agente calcula automaticamente as seguintes métricas com base nos dados disponíveis:
| Métrica | Fórmula / Critério |
|---|---|
| Efetividade | Notas ENTREGUES ÷ (Total − CANCELADO − DESCONHECIDO) × 100 |
| Performance (On-Time) | Notas ENTREGUES com data_entrega ≤ data_previsao ÷ Total ENTREGUES × 100 |
| Lead Time Médio | Média de dias entre data_emissao e data_entrega (status = ENTREGUE) |
| Lead Time em Dias Úteis | Lead Time − qtd_feriados (quando análise exige dias úteis) |
| Valor em Risco | Soma do campo valor das notas com status Em Aberto e prazo vencido |
| Notas em Atraso | DATA_ATUAL > data_previsao E data_entrega IS NULL E status IN (NAO_ENTREGUE, A_EMBARCAR) |
| Dias em Atraso (em aberto) | DATA_ATUAL − data_previsao |
| Dias em Atraso (entregue late) | data_entrega − data_previsao |
| Ocorrências Penalizadoras | Contagem de registros com penalizador = 1 por transportadora ou período |
Nota
Campos de previsão de entrega: a Base 1 possui três campos distintos de previsão. Use conforme o contexto da pergunta:
data_previsao— Referência padrão do sistema para cálculos de atraso e performance.data_previsao_logistica— Perspectiva logística, pode diferir conforme negociação operacional.data_previsao_destinatario— Data comunicada ao cliente final, referência para expectativa do destinatário.
Como criar um bom prompt
O Agente de Entregas é um aliado estratégico na gestão logística, mas seu valor depende da forma como você estrutura as perguntas. Um bom prompt aumenta a precisão e a utilidade das respostas.
Um bom prompt deve conter:
- Objetivo claro: o que você deseja saber ou analisar?
- Contexto relevante: qual período, transportadora, rota ou tipo de nota considerar?
- Especificidade: qual nível de detalhe ou formato de resposta é esperado?
Exemplos — Gestor Logístico
Exemplo de prompt mal formulado:
- Como estão as entregas do mês?
Exemplo de prompt melhorado:
- Qual foi a efetividade de entregas em abril de 2025 por transportadora, ordenada da menor para a maior? Inclua o total de notas, quantidade entregue e percentual de efetividade.
Exemplo de prompt mal formulado:
- Quais transportadoras têm problemas?
Exemplo de prompt melhorado:
- Liste as 5 transportadoras com maior índice de ocorrências penalizadoras nos últimos 3 meses, incluindo total de embarques, quantidade de ocorrências penalizadoras e percentual sobre o total transportado.
Exemplos — Operador Logístico
Exemplo de prompt mal formulado:
- Tem alguma nota atrasada?
Exemplo de prompt melhorado:
- Quais notas com destino no estado de SP estão com prazo de entrega vencido há mais de 3 dias e ainda não foram entregues? Mostre o número da nota, transportadora, dias de atraso e valor da mercadoria, ordenado pelo maior atraso.
Exemplo de prompt mal formulado:
- Tem alguma ocorrência com foto?
Exemplo de prompt melhorado:
- Liste todas as ocorrências registradas com foto nas últimas 2 semanas que são classificadas como penalizadoras, agrupadas por transportadora. Mostre o número da nota, data da ocorrência e o tipo de ocorrência.
Dicas para melhorar seus prompts
- Sempre especifique o período da consulta — use expressões como “último mês”, “esta semana” ou datas exatas para obter resultados precisos.
- Informe o recorte geográfico quando necessário — estado de origem ou destino ajudam o agente a filtrar os dados corretamente.
- Quando quiser um ranking ou comparativo, diga quantos itens deseja ver e qual critério de ordenação usar (ex: “top 5 por maior atraso médio”).
- Especifique qual campo de prazo deve ser utilizado:
data_previsao(sistema),data_previsao_logisticaoudata_previsao_destinatario. - Para análises de ocorrências, informe se deseja filtrar por tipo (penalizadora, não penalizadora, finalizadora) ou por transportadora específica.
- Revise e atualize seus prompts regularmente para garantir relevância e clareza com o contexto operacional atual.
- Compartilhe boas práticas com outros membros da equipe, promovendo padronização e aprendizado coletivo.
- Experimente diferentes formatos de perguntas e refine conforme necessário — o agente suporta tanto perguntas diretas quanto análises comparativas complexas.
Funcionalidades previstas para versões futuras
As capacidades abaixo estão no roadmap do Agente de Entregas e não estão disponíveis na versão atual:
- Detalhamento de ocorrências por trecho da rota, com identificação da transportadora responsável em cada etapa.
- Alertas proativos via e-mail ou mensagem para embarques com risco de não entrega ou prazo crítico.
- Sugestão automática de transportadoras alternativas em rotas com histórico de ocorrências recorrentes.
- Integração com dados de rastreamento em tempo real (Rastron) para visão intraday.
- Relatórios automáticos de performance por embarcador, com envio programado por período.
Referência — Regras de negócio
| Situação | Condição |
|---|---|
| Nota entregue | status_embarque = ENTREGUE E data_entrega preenchida |
| Nota em trânsito | status_embarque = NAO_ENTREGUE |
| Nota a embarcar | status_embarque = A_EMBARCAR |
| Nota finalizada sem entrega | status_embarque = FINALIZADO E data_finalizadora preenchida |
| Nota cancelada (excluir de métricas) | status_embarque = CANCELADO |
| Nota atrasada | DATA_ATUAL > data_previsao E data_entrega IS NULL E status IN (NAO_ENTREGUE, A_EMBARCAR) |
| Em aberto | status_embarque IN (NAO_ENTREGUE, A_EMBARCAR) |
| Concluído | status_embarque IN (ENTREGUE, FINALIZADO) |
| Ocorrência penalizadora | penalizador = 1 na Base 2 |
| Ocorrência não penalizadora | nao_penalizador = 1 na Base 2 |
| Ocorrência finalizadora | finalizador = 1 na Base 2 — encerra o fluxo do embarque |
| Rastreamento ativo | status_rastron = RASTRON_ATIVO na Base 1 |
| Entrega com agendamento | agendamento = 1 na Base 1 |
| Destinatário especial | especial = 1 na Base 1 |
Critérios de um embarque concluído:
- Embarque concluído:
- possui
status_embarque=ENTREGUEedata_entregaregistrada; OU - possui
status_embarque=FINALIZADOedata_finalizadoraregistrada (sem entrega efetiva).
- possui
- Embarques
FINALIZADOSnão devem ser tratados como entregues — o status indica encerramento do processo.
Para saber mais sobre a Sara Agentes, entre em contato com seu Executivo de Contas.
Se ainda não for cliente da Senior, clique no botão Solicite uma proposta no topo desta página.
English
Español
