Introdução
Um erro de API REST no Odoo acontece quando uma chamada HTTP dirigida a um endpoint REST falha. Embora o Odoo disponibilize por defeito XML-RPC e JSON-RPC, muitas implementações modernas usam APIs REST personalizadas construídas com controllers do próprio Odoo.
Os erros de REST são frequentes em cenários como:
- Arquitecturas Odoo headless
- Integrações de comércio eletrónico
- Aplicações móveis
- Conexões com plataformas externas
- Integrações mediadas por middleware
Ao contrário dos erros na interface, as falhas em APIs REST surgem normalmente como códigos de estado HTTP, por exemplo:
- 400 (Pedido Inválido)
- 401 (Não Autorizado)
- 403 (Proibido)
- 404 (Não Encontrado)
- 500 (Erro Interno do Servidor)
Este guia descreve as razões habituais para erros REST no Odoo e mostra como os diagnosticar e corrigir de forma prática.
O que é uma API REST no Odoo?
No Odoo, uma API REST é geralmente criada através de controllers, por exemplo:
from odoo import http
from odoo.http import request
class MyController(http.Controller):
@http.route('/api/order', type='json', auth='user', methods=['POST'])
def create_order(self, **kwargs):
# lógica aqui
return {"status": "success"}
As APIs REST dependem de vários elementos em conjunto:
- Métodos HTTP (GET, POST, PUT, DELETE)
- Mecanismos de autenticação
- Corpos JSON bem formados
- Roteamento correto
Se qualquer elo desta cadeia falhar, o Odoo devolve um erro na API REST.
Causas comuns de erros na API REST do Odoo
1. Falha de autenticação (401 Não Autorizado)
Quando a autenticação está ausente ou incorreta, o Odoo costuma devolver:
401 Não Autorizado
Motivos comuns:
- Token de API em falta
- Credenciais inválidas
- Sessão expirada
- Método de autenticação errado
2. Permissões insuficientes (403 Proibido)
Mesmo autenticado, o utilizador pode não ter direitos para executar a ação solicitada:
403 Proibido
Isto normalmente indica:
- Falta de direitos de acesso
- Permissões de grupo incorrectas
- Regras de registo que bloqueiam o acesso
3. Endpoint inválido (404 Não Encontrado)
Se a rota não existir, o servidor responde com:
404 Não Encontrado
Possíveis causas:
- URL incorreta
- Módulo não instalado
- Rota mal configurada
- Método HTTP incorreto
4. Payload inválido (400 Pedido Inválido)
Quando o corpo JSON está mal formado ou faltam dados obrigatórios:
400 Pedido Inválido
Exemplos:
- Campos obrigatórios em falta
- Tipos de dados errados
- IDs relacionais inválidos
5. Excepção no backend (500 Erro Interno do Servidor)
Se a lógica do controller lançar uma excepção inesperada:
500 Erro Interno do Servidor
É a falha mais comum em APIs REST.
Causas frequentes:
- Excepção Python não tratada
- Violação de constraints da base de dados
- Referência relacional inválida
- Campo obrigatório em falta
6. Problemas com tokens CSRF
Se csrf=True na rota e não for entregue um token válido, o pedido é bloqueado.
Para endpoints de API, é habitual usar csrf=False.
Como corrigir erros na API REST do Odoo
Passo 1 – Verifique o código de estado HTTP
O código fornece uma pista imediata sobre a natureza do erro:
- 400 → Problema no payload
- 401 → Problema de autenticação
- 403 → Problema de permissão
- 404 → Problema de rota
- 500 → Excepção no servidor
Passo 2 – Verifique a configuração da rota
Confirme os detalhes do @http.route:
@http.route('/api/order', type='json', auth='user', methods=['POST'])
Garanta que:
- O caminho URL está correcto
- O método HTTP corresponde ao pedido
- A definição de auth está adequada
- A configuração de CSRF é apropriada
Passo 3 – Valide o método de autenticação
Verifique:
- Os tokens de API são válidos
- Os cookies de sessão estão activos
- O tipo de autenticação correcto é usado (auth='user', auth='public', etc.)
Utilize um utilizador de integração dedicado em produção.
Passo 4 – Valide o payload antes de enviar
Antes de enviar pedidos:
- Inclua todos os campos obrigatórios
- Valide os IDs relacionais
- Confirme os tipos de dados correctos
- Evite null em campos obrigatórios
A validação estruturada na origem reduz muito os erros REST.
Passo 5 – Consulte os logs do servidor para erros 500
Para um 500, inspeccione os registos do Odoo no servidor.
Procure por:
Traceback (most recent call last):
O traceback normalmente revela a causa raiz verdadeira.
Passo 6 – Implemente tratamento de erros nos controllers
Em vez de deixar excepções chegarem sem controlo:
try:
# lógica
except Exception as e:
return {"error": str(e)}
Respostas de erro controladas tornam as integrações mais resilientes.
Como evitar erros na API REST do Odoo
- Use utilizadores de API dedicados
- Implemente validação de entrada antes de tocar no Odoo
- Adicione tratamento estruturado de excepções
- Evite lógica pesada dentro dos controllers
- Particione operações grandes em lotes
- Registe dados de pedidos e respostas
Num ambiente de integrações estruturadas, colocar uma camada de validação e transformação entre sistemas externos e o Odoo reduz drasticamente as falhas em APIs REST.
Como a Dasolo organiza integrações REST estáveis
Os erros REST no Odoo costumam nascer de cabeçalhos de autenticação inconsistentes, controllers mal configurados ou tratamento inadequado dos pedidos. Como estes endpoints ficam expostos a sistemas externos, pequenas falhas de validação podem provocar erros repetitivos.
Na Dasolo, tornamos integrações REST mais estáveis através de foco em:
- Autenticação segura baseada em tokens
- Lógica explícita nos controllers
- Validação rigorosa de pedidos e respostas
- Escopo de permissões bem definido
- Log estruturado de chamadas externas
Uma arquitectura REST disciplinada diminui a instabilidade e fortalece a resiliência do sistema a longo prazo.
Conclusão
O erro “REST API Error” no Odoo normalmente resulta de falhas de autenticação, payloads mal estruturados, conflitos de permissões ou excepções não tratadas no backend. Apesar de técnico, o erro geralmente aponta para lacunas na configuração do endpoint ou na validação dos dados.
Ao rever a implementação dos controllers, proteger os fluxos de autenticação e uniformizar o tratamento de erros, as equipas diminuem significativamente interrupções recorrentes. Uma camada de integração bem concebida garante comunicação fiável entre o Odoo e aplicações externas ao longo do tempo.