Integracao Odoo - Sistema de Fretes

ATENCAO: Esta skill eh para DESENVOLVIMENTO (criar/modificar integracoes). Para CONSULTAS e rastreamento de fluxos, use a skill rastreando-odoo.

Skill de desenvolvimento que documenta o processo completo de integracao com o Odoo ERP para lancamento de documentos fiscais (CTe) no sistema de fretes.

Quando Usar Este Skill

• Implementar novo fluxo de lançamento de documento fiscal no Odoo
• Criar integração para novo tipo de despesa/frete
• Modificar processo existente de lançamento
• Debugar problemas em lançamentos Odoo
• Entender o fluxo de 16 etapas

Arquitetura da Integração

Modelos Odoo Envolvidos

IDs Fixos do Odoo (Ambiente Produção)

PRODUTO_SERVICO_FRETE_ID = 29993          # Produto "SERVICO DE FRETE"
CONTA_ANALITICA_LOGISTICA_ID = 1186       # Centro de custo Logística
TEAM_LANCAMENTO_FRETE_ID = 119            # Equipe de lançamento
PAYMENT_PROVIDER_TRANSFERENCIA_ID = 30    # Forma pagamento
COMPANY_NACOM_GOYA_CD_ID = 4              # Empresa
PICKING_TYPE_CD_RECEBIMENTO_ID = 13       # Tipo recebimento CD

As 16 Etapas do Lançamento

Fase 1: Configuração do DFe (Etapas 1-5)

Etapa 1: Buscar DFe pela chave de acesso (44 dígitos)
         Modelo: l10n_br_ciel_it_account.dfe
         Ação: search_read
         Validação: status deve ser '04' (PO)

Etapa 2: Atualizar data de entrada e payment_reference
         Campos: l10n_br_date_in, payment_reference

Etapa 3: Definir tipo_pedido = 'servico'

Etapa 4: Atualizar linha com produto SERVICO DE FRETE
         Modelo: l10n_br_ciel_it_account.dfe.line
         Campos: product_id, analytic_distribution

Etapa 5: Atualizar vencimento
         Modelo: l10n_br_ciel_it_account.dfe.pagamento
         Campo: date_due

Fase 2: Purchase Order (Etapas 6-10)

Etapa 6: Gerar Purchase Order
         Método: action_gerar_po_dfe

Etapa 7: Configurar PO
         Campos: team_id, payment_provider_id, picking_type_id

Etapa 8: (Pulada) Impostos calculados automaticamente

Etapa 9: Confirmar PO
         Método: button_confirm

Etapa 10: Aprovar PO (se necessário)
          Método: button_approve
          Condição: state == 'to approve'

Fase 3: Invoice (Etapas 11-16)

Etapa 11: Criar Invoice
          Método: action_create_invoice

Etapa 12: Atualizar impostos
          Método: _compute_tax_totals

Etapa 13: Configurar Invoice
          Campos: invoice_date, payment_reference

Etapa 14: Recalcular impostos

Etapa 15: Confirmar Invoice
          Método: action_post

Etapa 16: Atualizar registro local
          Campos: odoo_dfe_id, odoo_purchase_order_id,
                  odoo_invoice_id, lancado_odoo_em,
                  lancado_odoo_por, status

Estrutura do Service de Lançamento

Campos Necessários no Modelo Local

Para qualquer entidade que será lançada no Odoo, adicionar:

# Integração Odoo
odoo_dfe_id = db.Column(db.Integer, nullable=True, index=True)
odoo_purchase_order_id = db.Column(db.Integer, nullable=True)
odoo_invoice_id = db.Column(db.Integer, nullable=True)
lancado_odoo_em = db.Column(db.DateTime, nullable=True)
lancado_odoo_por = db.Column(db.String(100), nullable=True)

# Status deve incluir 'LANCADO_ODOO'
status = db.Column(db.String(20), default='PENDENTE', nullable=False, index=True)

Estrutura do Service

class LancamentoXxxOdooService(LancamentoOdooService):
    """
    Service para lançar [entidade] no Odoo.
    Herda de LancamentoOdooService e adapta para [entidade].
    """

    def lancar_xxx_odoo(self, xxx_id: int, data_vencimento: date = None) -> Dict[str, Any]:
        """
        Executa lançamento completo no Odoo

        Returns:
            Dict com: sucesso, mensagem, dfe_id, purchase_order_id,
                      invoice_id, etapas_concluidas, auditoria, erro
        """
        # 1. Validações iniciais
        # 2. Buscar CTe vinculado
        # 3. Conectar no Odoo
        # 4. Executar 16 etapas
        # 5. Atualizar registro local
        # 6. Retornar resultado

Auditoria

Cada etapa deve ser registrada na tabela lancamento_frete_odoo_auditoria:

LancamentoFreteOdooAuditoria(
    frete_id=None,  # ou ID do frete
    despesa_extra_id=None,  # ou ID da despesa
    cte_id=cte_id,
    chave_cte=chave_cte,
    etapa=numero_etapa,
    etapa_descricao="Descrição da etapa",
    modelo_odoo='modelo.odoo',
    metodo_odoo='nome_metodo',  # se aplicável
    acao='search_read|write|execute_method|skip',
    status='SUCESSO|ERRO',
    mensagem="Mensagem descritiva",
    tempo_execucao_ms=tempo_ms,
    dfe_id=dfe_id,
    purchase_order_id=po_id,
    invoice_id=invoice_id
)

Pré-requisitos para Lançamento

1. CTe deve existir no Odoo com status '04' (PO)
2. CTe deve estar vinculado ao registro local
3. Data de vencimento deve estar definida
4. Usuário autenticado no sistema

Tratamento de Erros e Rollback

def _rollback_xxx_odoo(self, xxx_id: int, etapas_concluidas: int) -> bool:
    """
    Limpa campos Odoo em caso de erro (se não completou 16 etapas)
    """
    if status != 'LANCADO_ODOO' or etapas_concluidas < 16:
        xxx.odoo_dfe_id = None
        xxx.odoo_purchase_order_id = None
        xxx.odoo_invoice_id = None
        xxx.lancado_odoo_em = None
        xxx.lancado_odoo_por = None
        xxx.status = 'status_anterior'

Exemplos de Implementação

Frete (Referência Principal)

• Service: app/fretes/services/lancamento_odoo_service.py
• Route: app/fretes/routes.py - lancar_frete_odoo()

Despesa Extra (Implementação Recente)

• Service: app/fretes/services/lancamento_despesa_odoo_service.py
• Route: app/fretes/routes.py - lancar_despesa_odoo()

Checklist para Nova Integração

• Adicionar campos Odoo no modelo (odoo_dfe_id, odoo_purchase_order_id, etc.)
• Adicionar status LANCADO_ODOO no modelo
• Criar script de migração para novos campos
• Criar Service herdando de LancamentoOdooService
• Implementar método lancar_xxx_odoo() com 16 etapas
• Implementar método _rollback_xxx_odoo()
• Criar route POST para lançamento
• Criar route GET para auditoria
• Atualizar template com botão de lançamento e modal
• Adicionar JavaScript para chamada AJAX com progresso
• Testar em ambiente de desenvolvimento
• Documentar no CLAUDE.md

Conexão com Odoo

from app.odoo.utils.connection import get_odoo_connection

odoo = get_odoo_connection()
if not odoo.authenticate():
    raise Exception("Falha na autenticação com Odoo")

# Operações disponíveis:
odoo.search_read(modelo, filtros, fields, limit)
odoo.read(modelo, ids, fields)
odoo.write(modelo, ids, valores)
odoo.execute_method(modelo, metodo, args)

Guidelines

1. SEMPRE registrar auditoria de cada etapa
2. NUNCA pular etapas sem registrar na auditoria (usar status 'skip')
3. SEMPRE implementar rollback para limpeza em caso de erro
4. SEMPRE validar status do DFe antes de iniciar (deve ser '04')
5. NUNCA lançar documento que já foi lançado (verificar odoo_invoice_id)
6. SEMPRE usar transação para atualizar registro local no final
7. SEMPRE capturar tempo de execução de cada etapa para diagnóstico

Relacionado

Templates Disponiveis

Os templates em resources/ auxiliam na criacao de novas integracoes: