Esta skill deve ser usada quando o usuario pergunta sobre entregas ja faturadas: "NF 12345 foi entregue?", "status da entrega do Atacadao", "que dia embarcou?", "quando faturou?", "tem canhoto?", "houve devolucao?", ou precisa de datas de embarque, faturamento, entrega e canhotos. Nao usar para pedidos ainda nao faturados (usar gerindo-expedicao), rastrear NF no Odoo (usar rastreando-odoo), ou visao 360 completa do pedido (usar subagente raio-x-pedido). - Canhoto: "tem canhoto da NF?", "canhotos pendentes" - Devolucoes: "houve devolucao?", "NFs devolvidas", "produtos mais devolvidos" - Pendencias: "entregas pendentes", "NFs no CD", "entregas com problema" - Custo devolucao: "quanto custou as devolucoes?"
NAO USAR QUANDO (ANTES de faturar): - Pedidos em carteira/separacao → usar **gerindo-expedicao** - Estoque, disponibilidade → usar **gerindo-expedicao** - Criar separacao → usar **gerindo-expedicao** - Rastrear NF no Odoo → usar **rastreando-odoo**
Rafael-21090 estrellas27 feb 2026
Ocupación
Categorías
Productividad e Integración
Contenido de la habilidad
Skill para consultar status de entregas, canhotos, devoluções e agendamentos pós-faturamento.
⚠️ IMPORTANTE: Esta skill possui EXATAMENTE 3 scripts. NÃO tente executar scripts que não estão listados abaixo.
Script
Arquivo
Função
Status de entregas
consultando_status_entrega.py
Status, datas, canhotos, filtros por NF/cliente/período
Devoluções básicas
consultando_devolucoes.py
NFDs com ocorrências (abertas, por NF/cliente)
Devoluções detalhadas
consultando_devolucoes_detalhadas.py
4 modos: por cliente, produto, ranking, custo
Mapeamento Rápido
Se a pergunta menciona...
Use este script
Com estes parâmetros
Status de NF específica
consultando_status_entrega.py
--nf 12345
Status por cliente/CNPJ
consultando_status_entrega.py
--cliente "Atacadao" ou --cnpj 123...
Data de embarque ("que dia saiu?", "quando embarcou?")
consultando_status_entrega.py
--nf 12345 → campo data_embarque
Data de faturamento ("quando faturou?", "data da NF")
consultando_status_entrega.py
--nf 12345 → campo data_faturamento
Data de entrega ("quando chegou?", "foi entregue quando?")
consultando_status_entrega.py
--nf 12345 → campo data_hora_entrega_realizada
Entregas pendentes
consultando_status_entrega.py
--pendentes
Entregas no CD
consultando_status_entrega.py
--no-cd
Entregas reagendadas
consultando_status_entrega.py
--reagendadas
Entregas entregues (período)
consultando_status_entrega.py
--entregues --de 2025-01-01 --ate 2025-01-31
Canhoto de NF
consultando_status_entrega.py
--nf 12345 → campo canhoto_arquivo
Canhotos pendentes
consultando_status_entrega.py
--entregues → filtrar onde canhoto_arquivo é null
Entregas com problema
consultando_status_entrega.py
--problemas
Devoluções abertas
Regras de Decisão (em ordem de prioridade)
Se pergunta sobre STATUS de entrega ou DATAS (embarque/faturamento/entrega):
→ Use consultando_status_entrega.py
Se pergunta sobre CANHOTO:
→ Use consultando_status_entrega.py (campo canhoto_arquivo no retorno)
→ Se canhoto_arquivo é null → "sem canhoto registrado"
→ Se canhoto_arquivo tem valor → "canhoto disponível"
Se pergunta sobre DEVOLUÇÃO (ocorrência/status/NFD):
→ Use consultando_devolucoes.py
Se pergunta sobre ANÁLISE de devoluções (ranking, custo, histórico por cliente/produto):
→ Use consultando_devolucoes_detalhadas.py com o modo adequado
Se pergunta sobre AGENDAMENTO:
→ Dados de agendamento estão em consultando_status_entrega.py (campos data_agenda, reagendar, motivo_reagendamento)
→ Para agendamentos detalhados, usar consultando-sql com tabela agendamentos_entrega
Se pergunta sobre PROBLEMAS genéricos:
→ Use consultando_status_entrega.py --problemas
→ Inclui: nf_cd=True OU reagendar=True
Regras CRÍTICAS (Anti-Alucinação)
R1: FIDELIDADE AO OUTPUT DOS SCRIPTS
OBRIGATÓRIO:
- Reportar EXATAMENTE os valores retornados pelo script
- Usar EXATAMENTE os nomes de campos do JSON de retorno
- Citar numeros (total, valores) do campo "resumo" quando disponivel
- Formatar datas como DD/MM/YYYY (converter de YYYY-MM-DD do script)
- Formatar valores monetarios como R$ X.XXX,XX
PROIBIDO:
- Inventar dados que NAO estao no output do script
- Inferir status a partir de campos booleanos isolados (usar status_finalizacao)
- Arredondar ou estimar valores — usar exatamente o que o script retorna
- Adicionar contexto ou explicacao que nao tem base nos dados retornados
R2: status_finalizacao — Valores Válidos
Valor
Significado
NULL
Em andamento/pendente - NF ainda não finalizada
Entregue
NF entregue com sucesso ao cliente
Cancelada
Entrega cancelada (NF não será entregue)
Devolvida
Cliente devolveu a mercadoria
Troca de NF
NF substituída por outra (ver campo nova_nf)
Sinistro
Perda/extravio da mercadoria
nao_finalizado
NF saiu do monitoramento sem conclusão
R3: Fórmulas CORRETAS
Consulta
Fórmula
Flag no script
Entregas pendentes
status_finalizacao IS NULL
--pendentes
Entregas entregues
status_finalizacao = 'Entregue'
--entregues
Entregas devolvidas
status_finalizacao = 'Devolvida' OR teve_devolucao = True
—
Entregas com problema
nf_cd = True OR reagendar = True
--problemas
Com canhoto
canhoto_arquivo IS NOT NULL
—
R4: O Agente PODE Afirmar
Status atual da entrega (baseado em status_finalizacao)
Se tem canhoto (baseado em canhoto_arquivo IS NOT NULL)
Data de entrega (baseado em data_hora_entrega_realizada)
Se está no CD (baseado em nf_cd = True)
Se precisa reagendar (baseado em reagendar = True)
Ranking de produtos devolvidos (baseado no output de --ranking)
Custo de devoluções (baseado no output de --custo)
R5: O Agente NÃO PODE Inventar
Lead time ou prazo de entrega se não calculado pelo script
Motivo de devolução sem consultar ocorrencia_devolucao (usar consultando_devolucoes.py)
Previsão de entrega sem dados no campo data_entrega_prevista
Custo de devolução sem executar consultando_devolucoes_detalhadas.py --custo
Status de agendamento detalhado sem consultar tabela agendamentos_entrega
R6: Campos com Semântica Especial
Campo
Descrição
⚠️ Cuidado
entregue
Boolean - True quando status_finalizacao='Entregue'
NÃO usar isoladamente para filtrar pendentes
nf_cd
Boolean - NF fisicamente no CD
Pode ser NF que nunca saiu OU que voltou
reagendar
Boolean - cliente solicitou reagendamento
—
teve_devolucao
Boolean - houve devolução (mesmo parcial)
—
nova_nf
NF substituta
Só presente quando status_finalizacao='Troca de NF'
canhoto_arquivo
Caminho do arquivo do canhoto
null = sem canhoto, valor = tem canhoto
Scripts Disponíveis
1. consultando_status_entrega.py
Consulta status de entregas com vários filtros. Script principal — cobre status, datas, canhotos e agendamentos básicos.
Parâmetros de modo (UM obrigatório, mutuamente exclusivos):
Param
Descrição
--cliente "Nome"
Histórico de devoluções por cliente
--produto "nome"
Produtos devolvidos (ILIKE)
--ranking
Top N produtos mais devolvidos
--custo
Custo total de devoluções (via despesas_extras)
Parâmetros gerais:
Param
Descrição
--de
Data início (YYYY-MM-DD)
--ate
Data fim (YYYY-MM-DD)
--limite
Max resultados (default: 50)
--incluir-custo
Incluir custo (apenas com --cliente)
--ordenar-por
'ocorrencias' ou 'quantidade' (apenas com --ranking)
Retorno por modo:
Modo
Campo principal
Conteúdo
--cliente
nfds
Lista de NFDs + resumo com total/valor
--produto
linhas
Linhas de devolução + resumo com qtd/clientes
--ranking
ranking
Top N com total_ocorrencias, qtd_total, total_clientes
--custo
breakdown_mensal
Custo total + breakdown por mês
Tratamento de Resultados
Quando o Script Retorna "sucesso": false
1. Reportar o erro ao usuario: "Nao consegui consultar: {erro}"
2. NAO inventar dados alternativos
3. Sugerir: "Verifique se o numero da NF/nome do cliente esta correto"
Quando o Script Retorna "total": 0 (sem resultados)
1. Dizer claramente: "Nao encontrei entregas com os filtros aplicados"
2. Sugerir filtros alternativos:
- Se buscou por NF → "Verifique o numero da NF"
- Se buscou por cliente → "O nome exato pode ser diferente. Tente parte do nome"
- Se buscou pendentes → "Nao ha entregas pendentes no momento"
3. NAO inventar dados ou resultados aproximados
Quando total > exibindo (resultados truncados)
1. Informar: "Encontrei {total} entregas, mostrando as {exibindo} mais recentes"
2. Sugerir refinar filtros (período, NF específica) se total for muito grande
Formatação de Resposta
- Datas: converter YYYY-MM-DD → DD/MM/YYYY (padrão brasileiro)
- Valores: R$ com separador de milhar (.) e decimal (,)
- Status null: dizer "pendente" ou "em andamento" (NÃO dizer "null")
- Canhoto null: dizer "sem canhoto registrado" (NÃO dizer "null")
- Listas: numerar NFs quando houver múltiplas
Exemplos de Uso
Cenário 1: Status de NF específica
Pergunta: "NF 144533 foi entregue?"
Script: consultando_status_entrega.py --nf 144533
Resposta: "A NF 144533 está pendente (em andamento). Data de embarque: 16/01/2025."
Cenário 2: Entregas pendentes do Atacadão
Pergunta: "tem entrega pendente do Atacadão?"
Script: consultando_status_entrega.py --cliente atacadao --pendentes
Resposta: "Encontrei 5 entregas pendentes do Atacadão: [lista com NFs]"
Cenário 3: Canhoto de NF
Pergunta: "tem canhoto da NF 144533?"
Script: consultando_status_entrega.py --nf 144533
Resposta (se canhoto_arquivo != null): "Sim, canhoto registrado para a NF 144533."
Resposta (se canhoto_arquivo == null): "Não, NF 144533 não tem canhoto registrado."
Cenário 4: Devoluções abertas
Pergunta: "tem devolução aberta?"
Script: consultando_devolucoes.py --abertas
Resposta: "3 ocorrências de devolução abertas: [detalhes com NFD, cliente, categoria]"
Cenário 5: Ranking de produtos devolvidos
Pergunta: "quais produtos são mais devolvidos?"
Script: consultando_devolucoes_detalhadas.py --ranking --limite 10
Resposta: "Top 10 produtos mais devolvidos: 1. Palmito 400g (45 ocorrências)..."
Cenário 6: Custo de devoluções em período
Pergunta: "quanto custaram as devoluções em janeiro?"
Script: consultando_devolucoes_detalhadas.py --custo --de 2025-01-01 --ate 2025-01-31
Resposta: "Custo total de devoluções em janeiro: R$ 12.345,67 (15 despesas, 8 NFDs)"
Cenário 7: Data de embarque
Pergunta: "que dia saiu a NF 144533?"
Script: consultando_status_entrega.py --nf 144533
Resposta: "A NF 144533 saiu (embarcou) em 16/01/2025."