Introdução
No Odoo, um 'modelo' descreve como os dados são organizados e guardados na base de dados. Tudo o que manipula numa operação — desde encomendas de venda até movimentos de stock — está representado por um modelo que dita campos, relações e regras.
Compreender modelos é fundamental tanto para consultores funcionais como para desenvolvedores. São a espinha dorsal da arquitetura de dados do Odoo: definem campos, vínculos entre registos e a lógica de negócio que governa processos.
Neste artigo vamos analisar em detalhe um dos modelos mais utilizados do módulo de Inventário: stock.picking. Seja a criar módulos de armazém personalizados, a integrar sistemas externos ou a configurar processos, este modelo aparece em quase todas as operações de stock.
O que é o modelo stock.picking
O stock.picking representa uma transferência de mercadoria no Odoo. Cada registo corresponde a um movimento de produtos entre duas localizações e reúne toda a informação necessária para controlar essa operação no armazém.
Recebimentos, expedições e transferências internas são todos registados como stock.picking. Quando confirma uma entrega de uma venda, recebe mercadoria de uma compra ou desloca stock entre armazéns, está a criar ou a alterar um registo deste modelo.
O modelo é definido no módulo stock e é estendido por outros módulos através da herança de modelos do Odoo. O módulo de Vendas acrescenta campos relacionados com expedição; Compras traz fluxos de entrada; Produção amplia os movimentos para a linha de fabrico — cada módulo acrescenta apenas o que precisa, sem replicar a estrutura central.
stock.picking herda funcionalidades de comunicação (mail.thread e mail.activity.mixin). Na prática, isto permite registar histórico, adicionar mensagens no chatter e agendar atividades associadas às transferências.
Campos principais do modelo
A seguir estão os campos mais relevantes do modelo stock.picking. Conhecê‑los facilita a configuração, o desenvolvimento e a resolução de problemas em operações de armazém.
1. name
Tipo: Char. Identifica a referência da transferência, normalmente gerada por sequência (ex.: WH/OUT/00001). É o identificador visível no cabeçalho do documento e serve como referência principal do picking.
2. origin
Tipo: Char. Referência do documento de origem. Para uma expedição, costuma ser o número da encomenda de venda; para um recebimento, o da encomenda de compra. Ajuda a traçar o histórico da operação.
3. state
Tipo: Selection. Estado do picking. Valores comuns: Draft, Waiting Another Operation, Waiting, Ready, Done, Cancelled. O estado condiciona as ações disponíveis e resulta do estado dos movimentos associados.
4. picking_type_id
Tipo: Many2one (stock.picking.type). Define o tipo de operação — entrada, saída ou interna. É obrigatório e determina localizações padrão e comportamento do processo.
5. move_ids
Tipo: One2many (stock.move). Linhas de movimento que descrevem produto e quantidade a movimentar. São o núcleo do picking: reservas, disponibilidades e regras de transferência atuam sobre estes movimentos.
6. move_line_ids
Tipo: One2many (stock.move.line). Registos de detalhe: lotes, números de série, quantidades por localização/pacote. Essencial para picking detalhado, embalamento e validação final.
7. location_id
Tipo: Many2one (stock.location). Local de origem — onde os produtos são retirados. Campo obrigatório; para saídas costuma ser a localização de stock, para entradas a localização do fornecedor.
8. location_dest_id
Tipo: Many2one (stock.location). Local de destino — onde os produtos são colocados. Campo obrigatório; para saídas é tipicamente a localização do cliente, para entradas a localização de armazém.
9. partner_id
Tipo: Many2one (res.partner). Contacto associado — cliente em expedições, fornecedor em recebimentos. Usado na impressão de documentos e integração com operadores logísticos.
10. scheduled_date
Tipo: Datetime. Data planeada para executar a transferência. Utilizada para prioridades e planeamento; definir esta data ajusta a expectativa para todos os movimentos ligados.
11. date_deadline
Tipo: Datetime. Prazo associado à transferência. Vem frequentemente da encomenda de venda/compra e é usada para identificar entregas atrasadas e para promessas ao cliente.
12. date_done
Tipo: Datetime. Data em que a transferência foi validada (ou cancelada). É de leitura apenas e é preenchida automaticamente quando o picking é concluído.
13. priority
Tipo: Selection. Nível de prioridade do picking. A reserva de stock privilegia pickings com prioridade superior, útil para gerir encomendas urgentes.
14. move_type
Tipo: Selection. Política de expedição: As soon as possible (entrega parcial permitida) ou When all products are ready (tudo ou nada). Esta opção influencia quando o picking pode ser processado.
15. user_id
Tipo: Many2one (res.users). Utilizador responsável pela operação. Serve para atribuição de tarefas e gestão de carga de trabalho; por defeito usa o utilizador que cria o registo.
16. company_id
Tipo: Many2one (res.company). Empresa a que o picking pertence. Em ambientes multi‑empresa determina a titularidade e regras aplicáveis ao registo.
17. group_id
Tipo: Many2one (procurement.group). Grupo de procurement que liga movimentos relacionados — útil quando vários pickings derivam da mesma encomenda.
18. backorder_id
Tipo: Many2one (stock.picking). Quando um picking é parcialmente validado, o sistema cria um backorder para o restante; este campo aponta para o picking original.
19. backorder_ids
Tipo: One2many (stock.picking). Lista de backorders gerados a partir deste picking — permite gerir o trabalho que ficou pendente após validações parciais.
20. return_id
Tipo: Many2one (stock.picking). Se o picking foi criado como uma devolução, aqui liga‑se ao picking original — fundamental para rastrear processos de retorno.
21. note
Tipo: Html. Notas internas visíveis à equipa de armazém. Serve para instruções especiais, avisos de manuseamento ou informações operacionais.
22. signature
Tipo: Image. Assinatura capturada na validação da entrega. Funciona como prova de entrega e fica guardada como anexo.
23. is_signed
Tipo: Boolean. Calculado a partir do campo signature. Indica se a entrega foi assinada.
24. owner_id
Tipo: Many2one (res.partner). Proprietário dos produtos no momento da validação — útil em consignações ou quando o stock pertence a terceiros.
25. package_level_ids
Tipo: One2many (stock.package_level). Estrutura de embalamento quando se usa 'put in pack'. Agrupa as linhas de movimento em pacotes para expedição.
26. create_date
Tipo: Datetime. Data de criação do registo. Gerido automaticamente pelo Odoo como parte do modelo base.
27. write_date
Tipo: Datetime. Data da última modificação do registo. Gerido automaticamente pelo sistema.
28. active
Tipo: Boolean. Sinalizador de eliminação suave (archive). Quando falso, o registo fica inactivo sem ser apagado da base de dados.
Como este modelo entra nos fluxos de trabalho da empresa
1. Vendas e expedições
Ao confirmar uma encomenda de venda, o Odoo gera um delivery (stock.picking). O picking fica ligado à encomenda via origin; a equipa de armazém prepara, embala e valida — o estado progride de rascunho para pronto e depois concluído.
2. Compras e recebimentos
A confirmação de uma encomenda de compra cria um receipt. O picking gere a entrada de mercadoria do fornecedor para o armazém, com partner_id igual ao fornecedor; na validação as quantidades em stock são atualizadas.
3. Transferências internas
Movimentações entre locais ou armazéns geram pickings internos (picking_type_id com código 'internal'). Tanto origem como destino são localizações internas de stock.
4. Devoluções e backorders
No caso de devoluções de venda, gera‑se um picking de retorno ligado ao original via return_id. Se uma validação for parcial, o sistema cria backorders para o restante trabalho, listados em backorder_ids.
5. Produção e fabrico
Ordens de produção originam pickings para consumo de matérias‑primas e para entrada de produtos acabados. O módulo de MRP estende stock.picking para integrar estes fluxos na operação de fabrico.
Como os programadores estendem este modelo
Os programadores têm vários padrões para estender stock.picking, com a herança de modelos como a técnica principal.
Herança de modelos
Ao usar _inherit = 'stock.picking' cria‑se um módulo que acrescenta campos, sobrepõe métodos ou adiciona restrições. Esta abordagem mantém as alterações encapsuladas e facilita atualizações do Odoo.
Adicionar campos
Declare novos campos no modelo herdado usando o tipo apropriado: Char, Many2one, Boolean, Integer, Text, Selection. Considere a dependência por empresa (company_dependent) em ambientes multi‑empresa.
Extensões em Python
Sobreponha métodos como button_validate, action_assign ou _create_backorder para incluir lógica personalizada. Use super() para preservar o comportamento original e tenha cuidado com as transições de estado e a criação de movimentos.
Odoo Studio
O Odoo Studio permite adicionar campos sem código — ideal para ajustes rápidos como etiquetas ou notas. Porém, para lógica complexa ou integrações com transportadoras, os módulos personalizados são mais robustos e fáceis de gerir a longo prazo.
Boas práticas
- Ao criar pickings manualmente, defina sempre o picking_type_id. Este campo determina localizações padrão e comportamentos essenciais do processo.
- Registe a origem no campo origin para facilitar rastreio e auditoria: é uma peça-chave para reporting e troubleshooting.
- Em integrações via API, o modelo stock.picking está totalmente exposto. Crie movimentos através da relação move_ids e evite criar pickings vazios sem linhas de movimento.
- Use scheduled_date para planeamento: esta data orienta prioridades e afeta reservas de stock.
- Para campos personalizados, prefira prefixos x_ ou um prefixo do módulo para evitar colisões com futuras versões do Odoo.
Erros comuns
- Criar pickings sem definir picking_type_id pode gerar localizações por defeito incorretas e comportamento inesperado.
- Alterar move_ids depois da confirmação sem compreender o 'state machine' pode provocar inconsistências e falhas no fluxo.
- Esquecer partner_id em entregas prejudica a impressão de documentos e a integração com transportadoras.
- Sobrepor button_validate sem chamar super() pode interromper a criação de backorders e quebrar o funcionamento de outros módulos.
- Assumir que move_ids e move_line_ids estão sempre sincronizados é um erro — as move_lines só surgem ao reservar stock ou quando se usa picking detalhado.
Conclusão
O stock.picking é um elemento central no Inventário do Odoo: regista transferências, expedições e recebimentos. Dominar os seus campos e as formas como é estendido facilita a configuração, personalização e integração do sistema.
Seja a mapear processos de armazém como consultor funcional ou a desenvolver módulos como programador, um bom conhecimento do stock.picking evita retrabalho e reduz riscos operacionais.
Pronto para otimizar o seu armazém no Odoo
A Dasolo apoia empresas na implementação, personalização e optimização do Odoo. Temos especialização em integrações via API e desenvolvimento de módulos, com experiência profunda na arquitetura de dados e modelos como o stock.picking.
Se precisa de ajuda com a sua implementação Odoo, módulos personalizados de armazém ou integrações, podemos ajudar. Agende uma demonstração para discutir o seu projeto.