Agent skills
monitorando-entregas

Agent skill

monitorando-entregas

Consulta status de entregas, datas de embarque/faturamento, canhotos e devolucoes. USAR QUANDO (NFs JA FATURADAS): - Status: "NF 12345 foi entregue?", "status da entrega do Atacadao" - Datas de embarque: "que dia saiu?", "que dia embarcou?", "quando expediu?" - Datas de faturamento: "quando faturou?", "data da NF" - Datas de entrega: "quando chegou?", "foi entregue quando?" - Canhoto: "tem canhoto da NF?", "canhotos pendentes" - Devolucoes: "houve devolucao?", "NFs devolvidas" - Pendencias: "entregas pendentes", "NFs no CD", "entregas com problema" 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**

View SKILL.md on GitHub Repository

Stars 163

Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/monitorando-entregas

SKILL.md

Monitorando Entregas

Skill para consultar status de entregas, canhotos, devoluções e agendamentos.

Índice

Quando NÃO Usar Esta Skill
DECISION TREE - Qual Script Usar?
Regras de Negócio (Anti-Alucinação)
Scripts Disponíveis
Referência Cruzada
References

Quando NÃO Usar Esta Skill

Situação	Usar em vez desta
Pedido ainda não faturado	gerindo-expedicao
Rastrear NF/PO/pagamento no Odoo	rastreando-odoo
Criar separação de pedido	gerindo-expedicao
Análise completa da carteira (P1-P7)	analista-carteira (subagente)
Consultas SQL analíticas complexas	consultando-sql

DECISION TREE - Qual Script Usar?

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?", "quando expediu?")	`consultando_status_entrega.py`	`--nf 12345` (retorna `data_embarque`)
Data de faturamento ("quando faturou?", "data da NF")	`consultando_status_entrega.py`	`--nf 12345` (retorna `data_faturamento`)
Data de entrega ("quando chegou?", "foi entregue quando?")	`consultando_status_entrega.py`	`--nf 12345` (retorna `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_canhotos.py`	`--nf 12345`
Canhotos pendentes	`consultando_canhotos.py`	`--pendentes`
Devoluções abertas	`consultando_devolucoes.py`	`--abertas`
Devolução de NF específica	`consultando_devolucoes.py`	`--nf 12345`
Devoluções de cliente	`consultando_devolucoes_detalhadas.py`	`--cliente "Sendas"`
Produtos mais devolvidos	`consultando_devolucoes_detalhadas.py`	`--ranking`
Custo de devoluções	`consultando_devolucoes_detalhadas.py`	`--custo`
Agendamento de entrega	`consultando_agendamentos.py`	`--nf 12345`
Agendamentos do dia	`consultando_agendamentos.py`	`--data 2025-02-05`

Regras de Decisão (em ordem de prioridade)

Se pergunta sobre STATUS de entrega: → Use consultando_status_entrega.py → Exemplo: "NF 12345 foi entregue?" → --nf 12345
Se pergunta sobre CANHOTO: → Use consultando_canhotos.py → Exemplo: "tem canhoto da NF?" → --nf 12345
Se pergunta sobre DEVOLUÇÃO: → Use consultando_devolucoes.py → Exemplo: "houve devolução?" → --nf 12345
Se pergunta sobre AGENDAMENTO: → Use consultando_agendamentos.py → Exemplo: "quando está agendada?" → --nf 12345
Se pergunta sobre PROBLEMAS genéricos: → Use consultando_status_entrega.py --problemas → Inclui: nf_cd=True OU reagendar=True

Regras de Negócio (Anti-Alucinação)

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

Fórmulas CORRETAS (O que o agente DEVE usar)

Consulta	Fórmula SQL CORRETA
Entregas pendentes	`status_finalizacao IS NULL`
Entregas finalizadas	`status_finalizacao IS NOT NULL`
Entregas entregues	`status_finalizacao = 'Entregue'`
Entregas devolvidas	`status_finalizacao = 'Devolvida' OR teve_devolucao = True`
Entregas com problema	`nf_cd = True OR reagendar = True`

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)

O Agente NÃO PODE Inventar:

Lead time se não calculado pelo script
Motivo de devolução sem consultar ocorrencia_devolucao
Status de agendamento sem consultar agendamentos_entrega
Previsão de entrega sem dados no sistema

Campos Importantes

Campo	Descrição
`entregue`	Boolean - True APENAS quando `status_finalizacao='Entregue'`. NÃO usar isoladamente para filtrar pendentes
`nf_cd`	Boolean - True = NF está fisicamente no CD. Pode ser NF que nunca saiu OU que saiu e voltou
`reagendar`	Boolean - True = cliente solicitou reagendamento
`teve_devolucao`	Boolean - True = houve devolução (mesmo que parcial)
`nova_nf`	Número da NF substituta (quando `status_finalizacao='Troca de NF'`)

Scripts Disponíveis

1. consultando_status_entrega.py

Consulta status de entregas com vários filtros.

bash

source .venv/bin/activate && python .claude/skills/monitorando-entregas/scripts/consultando_status_entrega.py [opções]

Parâmetros:

Param	Obrig	Descrição
`--nf`	Não	Número da NF (busca exata ou parcial)
`--cliente`	Não	Nome do cliente (busca parcial)
`--cnpj`	Não	CNPJ do cliente
`--transportadora`	Não	Transportadora
`--pendentes`	Não	Apenas entregas pendentes (status_finalizacao IS NULL)
`--entregues`	Não	Apenas entregas entregues
`--no-cd`	Não	Apenas NFs no CD (nf_cd=True)
`--reagendadas`	Não	Apenas reagendadas (reagendar=True)
`--problemas`	Não	Com problema (nf_cd=True OR reagendar=True)
`--de`	Não	Data inicial (YYYY-MM-DD)
`--ate`	Não	Data final (YYYY-MM-DD)
`--limite`	Não	Máximo de registros (default: 50)
`--formato`	Não	json ou tabela (default: json)

Retorno esperado:

json

{
  "sucesso": true,
  "total": 15,
  "entregas": [
    {
      "id": 1234,
      "numero_nf": "144533",
      "cliente": "ATACADAO SA",
      "status_finalizacao": null,
      "entregue": false,
      "nf_cd": false,
      "reagendar": false,
      "data_faturamento": "2025-01-15",
      "data_embarque": "2025-01-16",
      "data_entrega_prevista": "2025-01-20",
      "transportadora": "BRASPRESS",
      "municipio": "SAO PAULO",
      "uf": "SP"
    }
  ]
}

2. consultando_canhotos.py

Consulta canhotos de entregas.

bash

source .venv/bin/activate && python .claude/skills/monitorando-entregas/scripts/consultando_canhotos.py [opções]

Parâmetros:

Param	Obrig	Descrição
`--nf`	Não	Número da NF
`--pendentes`	Não	Apenas entregas sem canhoto
`--com-canhoto`	Não	Apenas entregas com canhoto
`--de`	Não	Data inicial
`--ate`	Não	Data final
`--limite`	Não	Máximo de registros

3. consultando_devolucoes.py

Consulta devoluções e ocorrências.

bash

source .venv/bin/activate && python .claude/skills/monitorando-entregas/scripts/consultando_devolucoes.py [opções]

Parâmetros:

Param	Obrig	Descrição
`--nf`	Não	Número da NF original
`--nfd`	Não	Número da NF de devolução
`--abertas`	Não	Apenas ocorrências abertas
`--cliente`	Não	Nome do cliente
`--de`	Não	Data inicial
`--ate`	Não	Data final
`--limite`	Não	Máximo de registros

4. consultando_agendamentos.py

Consulta agendamentos de entrega.

bash

source .venv/bin/activate && python .claude/skills/monitorando-entregas/scripts/consultando_agendamentos.py [opções]

Parâmetros:

Param	Obrig	Descrição
`--nf`	Não	Número da NF
`--data`	Não	Data do agendamento (YYYY-MM-DD)
`--pendentes`	Não	Apenas agendamentos aguardando confirmação
`--confirmados`	Não	Apenas agendamentos confirmados
`--limite`	Não	Máximo de registros

5. consultando_devolucoes_detalhadas.py

Consulta devoluções detalhadas com entity resolution e análises agregadas.

bash

source .venv/bin/activate && python .claude/skills/monitorando-entregas/scripts/consultando_devolucoes_detalhadas.py [opções]

Parâmetros (modos mutuamente exclusivos):

Param	Obrig	Descrição
`--cliente`	Sim*	Histórico de devoluções por cliente (LIKE no nome_emitente)
`--produto`	Sim*	Produtos devolvidos (LIKE na descricao_produto_cliente ou descricao_produto_interno)
`--ranking`	Sim*	Top N produtos mais devolvidos (GROUP BY codigo_produto_interno)
`--custo`	Sim*	Custo total de devoluções (via despesas_extras.tipo_despesa='DEVOLUCAO')
`--de`	Não	Data início (YYYY-MM-DD)
`--ate`	Não	Data fim (YYYY-MM-DD)
`--limite`	Não	Máximo de registros (default: 50)
`--incluir-custo`	Não	Incluir custo (apenas com --cliente)
`--ordenar-por`	Não	'ocorrencias' ou 'quantidade' (apenas com --ranking, default: ocorrencias)

*Um dos 4 modos deve ser especificado.

Retorno esperado (modo --cliente):

json

{
  "sucesso": true,
  "modo": "cliente",
  "resumo": {
    "mensagem": "Historico de devolucoes de 12 NFDs do cliente 'Sendas'",
    "total_nfds": 12,
    "exibindo": 10,
    "valor_total_devolucoes": 45678.90,
    "custo_total": 3456.78,
    "cliente": "Sendas",
    "periodo": {"de": "2025-01-01", "ate": "2025-12-31"}
  },
  "nfds": [
    {
      "id": 123,
      "numero_nfd": "12345",
      "nome_emitente": "Sendas Distribuidora SA",
      "cnpj_emitente": "12.345.678/0001-99",
      "data_registro": "2025-01-15",
      "valor_total": 4567.89,
      "status": "REGISTRADA",
      "motivo": "AVARIA",
      "total_linhas": 3
    }
  ]
}

Retorno esperado (modo --ranking):

json

{
  "sucesso": true,
  "modo": "ranking",
  "resumo": {
    "mensagem": "Top 10 produtos mais devolvidos (ordenado por ocorrencias)",
    "criterio": "ocorrencias",
    "total_produtos": 10
  },
  "ranking": [
    {
      "produto_referencia": "PALMITO-400G",
      "descricao_produto_interno": "Palmito Inteiro 400g",
      "total_ocorrencias": 45,
      "qtd_total": 234.0,
      "total_nfds": 38,
      "total_clientes": 12
    }
  ]
}

Exemplos de Uso

Cenário 1: Status de NF específica

Pergunta: "NF 144533 foi entregue?"
Raciocínio: Pergunta sobre STATUS de NF → consultando_status_entrega.py
Comando: --nf 144533
Resultado: "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?"
Raciocínio: STATUS + CLIENTE → consultando_status_entrega.py
Comando: --cliente atacadao --pendentes
Resultado: "Encontrei 5 entregas pendentes do Atacadão: [lista com NFs]"

Cenário 3: Canhotos pendentes

Pergunta: "quais entregas não têm canhoto?"
Raciocínio: CANHOTO + pendentes → consultando_canhotos.py
Comando: --pendentes --limite 20
Resultado: "20 entregas sem canhoto registrado: [lista]"

Cenário 4: Devoluções abertas

Pergunta: "tem devolução aberta?"
Raciocínio: DEVOLUÇÃO + abertas → consultando_devolucoes.py
Comando: --abertas
Resultado: "3 ocorrências de devolução abertas: [detalhes]"

Cenário 5: Data de embarque

Pergunta: "que dia saiu a NF 144533?"
Raciocínio: Pergunta sobre DATA DE EMBARQUE → consultando_status_entrega.py
Comando: --nf 144533
Resultado: "A NF 144533 saiu (embarcou) em 16/01/2025."

Cenário 6: Data de faturamento

Pergunta: "quando faturou a NF do Atacadão loja 183?"
Raciocínio: DATA DE FATURAMENTO + CLIENTE → resolver grupo primeiro, depois consultando_status_entrega.py
Comando: --cliente "Atacadao 183"
Resultado: "Encontrei 3 NFs do Atacadão 183. Faturamento: NF 144533 em 15/01/2025, NF 144534 em 16/01/2025..."

Cenário 7: Data de entrega realizada

Pergunta: "quando chegou a NF 144533?"
Raciocínio: DATA DE ENTREGA REALIZADA → consultando_status_entrega.py
Comando: --nf 144533
Resultado: "A NF 144533 foi entregue em 20/01/2025 às 14:32."

Referência Cruzada

Skill	Quando usar em vez desta
gerindo-expedicao	Pedidos antes de faturar, estoque, separação
rastreando-odoo	Rastrear NF/PO/pagamento no Odoo
consultando-sql	Consultas analíticas complexas (agregações, rankings)
analista-carteira	Análise completa da carteira com decisões P1-P7

References (sob demanda)

Gatilho na Pergunta	Reference a Ler	Motivo
"status de devolução"	`references/devolucoes.md`	Fluxo completo de devolução
"categorias de ocorrência"	`references/devolucoes.md`	Valores válidos de categoria/subcategoria
"como funciona agendamento"	`references/agendamentos.md`	Fluxo de agendamento e confirmação
"tabelas relacionadas"	`references/tables.md`	Relacionamentos entre tabelas

Tabelas do Domínio

Tabela	Descrição	FK principal
`entregas_monitoradas`	Status principal de cada NF	-
`agendamentos_entrega`	Histórico de agendamentos	`entrega_id → entregas_monitoradas.id`
`nf_devolucao`	NFs de devolução recebidas	`entrega_monitorada_id → entregas_monitoradas.id`
`nf_devolucao_linha`	Linhas/produtos da NFD	`nf_devolucao_id → nf_devolucao.id`
`ocorrencia_devolucao`	Ocorrências/tratativa	`nf_devolucao_id → nf_devolucao.id`

Maintainer

majiayu000 Core maintainer

Source details

Full Name: majiayu000/claude-skill-registry
Branch: main
Path in repo: skills/other/other/monitorando-entregas
License: MIT License

Featured Tools

Join Our Newsletter

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31

Explore

Didn't find tool you were looking for?

Search AI Tools

Install this agent skill to your Project

SKILL.md

Monitorando Entregas

Índice

Quando NÃO Usar Esta Skill

DECISION TREE - Qual Script Usar?

Mapeamento Rápido

Regras de Decisão (em ordem de prioridade)

Regras de Negócio (Anti-Alucinação)

status_finalizacao - Valores Válidos

Fórmulas CORRETAS (O que o agente DEVE usar)

O Agente PODE Afirmar:

O Agente NÃO PODE Inventar:

Campos Importantes

Scripts Disponíveis

1. consultando_status_entrega.py

2. consultando_canhotos.py

3. consultando_devolucoes.py

4. consultando_agendamentos.py

5. consultando_devolucoes_detalhadas.py

Exemplos de Uso

Cenário 1: Status de NF específica

Cenário 2: Entregas pendentes do Atacadão

Cenário 3: Canhotos pendentes

Cenário 4: Devoluções abertas

Cenário 5: Data de embarque

Cenário 6: Data de faturamento

Cenário 7: Data de entrega realizada

Referência Cruzada

References (sob demanda)

Tabelas do Domínio

Recommended Agent Skills

agent-ops-spec

agent-ops-state

agent-ops-spec

agent-ops-testing

agent-ops-testing

agent-ops-state