Introdução
O Erro JSONRPC do Odoo surge quando uma chamada feita ao Odoo através do protocolo JSON‑RPC falha. Este protocolo é a espinha dorsal das comunicações do cliente web do Odoo e de muitas integrações modernas.
Ao contrário do XML‑RPC, o JSON‑RPC é frequentemente utilizado em:
- Interações do front-end web
- Integrações à medida
- Implementações headless do Odoo
- Sincronização com sistemas externos
Quando algo falha numa chamada JSON‑RPC, o Odoo devolve uma resposta de erro que normalmente aparece como:
RPC_ERROR: Odoo Server Error
Ou em respostas de API como um objeto de erro JSON.
Este guia descreve o significado dos erros JSONRPC no Odoo e apresenta passos práticos para os corrigir.
O que é JSON-RPC no Odoo?
JSON‑RPC (JavaScript Object Notation Remote Procedure Call) permite que clientes invoquem métodos do Odoo via HTTP usando cargas JSON.
Um pedido JSON‑RPC típico inclui campos que identificam o método, parâmetros e um id de correlação.
{
"jsonrpc": "2.0",
"method": "call",
"params": {
"service": "object",
"method": "execute_kw",
"args": [
"database_name",
2,
"password",
"res.partner",
"search",
[[["is_company", "=", true]]]
]
},
"id": 1
}
Se o backend encontrar uma exceção, o Odoo responde com um objecto de erro em JSON detalhando o problema.
Causas comuns de erros JSONRPC no Odoo
1. Falha de autenticação
Isto acontece quando o pedido inclui:
- Credenciais inválidas
- Base de dados incorreta
- Sessão expirada
O Odoo rejeita a chamada.
Problemas de autenticação estão entre as causas mais frequentes de falhas JSONRPC.
2. Chamada de método inválida
Quando o payload JSON refere-se a:
- Um modelo que não existe
- Um método inexistente
- Argumentos de método incorretos
O backend levanta uma exceção que é devolvida como erro JSONRPC.
3. Campos obrigatórios em falta
Se uma operação de create ou write omite campos obrigatórios, o Odoo lança um erro de validação que aparece na resposta JSON.
Exemplo:
{
"name": "Order 001"
}
Se partner_id for obrigatório → erro.
4. Restrições de permissões
Se o utilizador da API não tiver permissão para a ação solicitada, o Odoo devolve um erro relacionado com acesso em formato JSON.
Isto acontece frequentemente em ambientes de produção onde utilizadores de integração têm permissões limitadas.
5. IDs relacionais inválidos
Enviar um ID inexistente para um campo Many2one faz o backend disparar uma exceção.
Exemplo:
{
"partner_id": 99999
}
Se o ID 99999 não existir → erro JSONRPC.
6. Violação de constraints da base de dados
Erros como:
- Valor duplicado viola constraint de unicidade
- Falha em constraint de chave estrangeira
- Constraint de not null
Podem surgir nas respostas JSONRPC.
7. Timeout do servidor ou operação pesada
Cargas grandes ou operações em massa podem ultrapassar limites de tempo, sobretudo em integrações de alto volume.
Como resolver um erro JSONRPC no Odoo
Passo 1 – Analise a resposta de erro JSON
A maior parte das respostas JSONRPC inclui:
- Tipo de erro
- Mensagem de erro
- Traceback
Leia com atenção os detalhes da exceção no backend.
Passo 2 – Verifique a autenticação
Confirme que:
- O nome da base de dados está correcto
- O ID do utilizador ou token de sessão é válido
- A password ou chave de API está correcta
- O utilizador está activo
Passo 3 – Valide a estrutura do payload
Antes de enviar pedidos:
- Assegure que os campos obrigatórios existem
- Valide os IDs relacionais
- Evite valores nulos em campos obrigatórios
- Garanta tipos de dados correctos
Uma validação estruturada antes do envio evita muitas falhas em tempo de execução.
Passo 4 – Revise as permissões
Verifique que o utilizador de integração tem:
- Permissão de leitura
- Permissão de escrita
- Permissão de criação
- Permissão de eliminação
consoante a ação requerida.
Passo 5 – Teste na interface do Odoo
Tente reproduzir a mesma operação manualmente no Odoo.
Se falhar na UI, o problema costuma ser de dados ou permissões.
Passo 6 – Consulte os logs do servidor
Se a resposta JSON for genérica, inspeccione os logs do Odoo para obter o traceback completo.
Como evitar erros JSONRPC
- Use utilizadores de API exclusivos
- Valide dados antes de os enviar
- Registe os pedidos e respostas
- Implemente tratamento de erros estruturado na integração
- Evite enviar operações em massa num único pedido
- Teste fluxos de integração em ambiente de staging
Em ambientes Odoo orientados por API, colocar uma camada intermédia de validação e transformação entre sistemas externos e o Odoo reduz drasticamente as falhas JSONRPC.
Como a Dasolo melhora a comunicação JSONRPC
Muitas vezes os erros JSONRPC resultam de sessões inconsistentes, payloads malformados ou lógica server‑side não validada. Como o JSONRPC suporta grande parte das interacções web do Odoo, pequenas falhas de configuração podem causar erros repetidos no front‑end.
Na Dasolo, fortalecemos a estabilidade JSONRPC através de:
- Validação estruturada dos pedidos
- Gestão controlada de sessões
- Padrões claros de tratamento de exceções
- Exposição segura dos endpoints
- Registo abrangente das chamadas de API
Um quadro de comunicação consistente reduz erros inesperados em tempo de execução e aumenta a fiabilidade da plataforma.
Conclusão
O “Erro JSONRPC” no Odoo costuma sinalizar que uma exceção no backend interrompeu a troca entre cliente e servidor. Apesar de a mensagem poder parecer genérica, normalmente aponta para problemas na formatação do pedido, autenticação ou lógica server‑side.
Ao rever cuidadosamente a estrutura das APIs, validar entradas e implementar tratamento de erros previsível, os desenvolvedores evitam interrupções recorrentes. Uma camada de comunicação bem desenhada garante interacções mais estáveis e eficientes nos ambientes Odoo.