12 KiB
Contratos de API
Ainda não há contrato de operações de negócio confirmado para o PDV. Os contratos de health check e login Odoo 7 estão definidos abaixo e aguardam homologação no servidor real.
O app oferece interfaces AuthRepository e ConnectionTester; ambas têm
implementações para Odoo 7. Nenhum endpoint de catálogo ou venda foi presumido.
API dedicada do PDV
Foi selecionada a implementação de endpoints próprios no módulo pdv_pos.
O primeiro contrato é o health check público e sem dados sensíveis:
GET /pdv_pos/health- Sucesso HTTP 200:
{"status":"ok","api_version":1} - Não requer autenticação e não retorna dados da empresa, usuário ou banco.
- O app envia essa chamada pelo botão Testar conexão e só considera sucesso quando o status HTTP e o contrato JSON forem válidos.
O código do controller foi adicionado ao módulo pdv_pos e o cliente não
segue redirecionamentos. A rota ainda precisa ser instalada/homologada em um
servidor Odoo 7 real. Esse contrato identifica a versão da API PDV, não a
versão principal do Odoo.
Login e sessão Odoo 7
O endpoint combinado replica apenas o fluxo pertinente do Coletor — validar a licença do dispositivo e autenticar o operador — em uma única chamada:
POST /pdv_pos/logar- Formulário:
cnpj,username,password,serial,model,brandeversiondo app, maisplatform(android,linux, etc.). cnpjseleciona o database viaapp_pdv_pos.config;username/passwordsão credenciais deres.users.- No Android, o controller exige serial/model/brand, valida a licença do
dispositivo com tipo
3(PDV) e inicia a sessão web Odoo após a validação. - Fora do Android, o controller pula a validação de licença para permitir desenvolvimento desktop; ainda exige credenciais válidas do Odoo.
- Sucesso JSON contém
status,user(id,name) ecompany_id. O Odoo emite o cookie HTTPside retorna osession_idinterno do Odoo; o app guarda ambos em armazenamento seguro e nunca persiste a senha. - Chamadas autenticadas seguintes enviam o cookie
side o parâmetrosession_idpara restaurar a sessão Odoo 7. - Cada endpoint protegido verifica a presença de usuário e database na sessão,
sem forçar um novo
common.login; o RPC Odoo valida a credencial eAccessDeniedinvalida a sessão. POST /pdv_pos/logoutinvalida a sessão; o app envia ambos os valores.
Os tipos de licença 3 foram adicionados aos modelos locais valida.dispositivo
e centrais contrecf.mobile, mantendo Coletor (1) e Comanda (2) separados.
O controller ainda precisa ser instalado e homologado, inclusive contra o
serviço central de licenças.
O app Android usa DeviceInfo.id, model e brand, seguindo o Coletor. É
necessário confirmar em POS reais se DeviceInfo.id é estável e exclusivo o
suficiente para representar o dispositivo/licença.
platform é informado pelo cliente e pode ser falsificado. Portanto, o fluxo
sem licença deve ser usado somente para desenvolvimento; não é prova confiável
de que a requisição veio de um sistema operacional não Android.
Inspeção do backend Odoo 7 (código encontrado, ainda não homologado)
Clientes e opções de pagamento (Fase 4)
Foram criadas duas consultas autenticadas no controller PDV:
POST /pdv_pos/clientesrecebequeryno corpo do formulário e pesquisa emfinanceiro.cliente, limitada a 50 resultados da empresa padrão do usuário. A resposta inclui nome e documento mascarado; o documento completo não sai do Odoo nem é colocado na URL.GET /pdv_pos/formas_pagamentoconsulta combinações ativas deadm.condicao.forma, incluindo forma e condição de pagamento. A resposta é dinâmica; os IDs/tipos retornados não são fixados no app.
Na interface, os tipos Odoo são agrupados em quatro ações: Dinheiro (01),
PIX (17, 20, 23), Cartão de Crédito (03) e Cartão de Débito (04). Se
o servidor retornar mais de uma condição para um grupo, o app pede a escolha
entre as condições disponíveis.
O app permite distribuir o valor entre várias parcelas/formas, sem exceder o total. Valores em dinheiro são registrados como recebidos na tela; PIX e cartões permanecem pendentes até confirmação pela API do POS, cujo contrato ainda não foi fornecido. A finalização de dinheiro usa o endpoint descrito abaixo. O app exibe número/série da nota e oferece retorno para iniciar nova venda; a impressão depende da API/SDK do POS.
Finalização de venda NFC-e (implementada no addon; pendente de homologação)
POST /pdv_pos/finalizar_vendarecebecheckout_key,itemsepaymentscomo JSON no corpo do formulário; também aceita cliente e CPF/CNPJ opcional.- O endpoint obtém empresa e local padrão da sessão, resolve em lote as
locações/embalagens dos produtos, cria pedido com itens e condições, calcula
parcelas, valida e chama
pedcap_button_faturar_pedido_nfce, aguardando o retorno do Odoo/SEFAZ. O app bloqueia as ações durante a chamada e mostra um indicador de finalização. - Só aceita formas de pagamento dinheiro (
01) até integrar a API do POS. Confere no servidor que as condições estão ativas e que a soma recebida é igual ao total. - A
checkout_keyé usada para localizar o mesmo pedido em uma repetição após timeout, evitando criar outro pedido na mesma sessão de pagamento. - Se o parâmetro do estoque exigir CPF/CNPJ e não houver cliente, o servidor
retorna
customer_cpf_requiredantes de criar o pedido. O app solicita o documento e repete a chamada. - Se houver uma NFC-e vinculada ao pedido, o checkout retorna sucesso qualquer que seja o estado da nota; a resposta traz número/série, estado, número do pedido e uma mensagem fiscal segura, sem traceback. Notas offline são identificadas como “Emitida em Contingência”. Sem nota vinculada, o app libera nova tentativa e mostra uma mensagem de erro, sem permanecer travado.
- O DANFE/NFC-e ainda não é enviado para impressão. A integração escolhida é a API/SDK da impressora do POS, cujo contrato/modelo precisa ser fornecido.
Histórico de vendas
GET /pdv_pos/historico_vendasretorna os pedidos de venda (tipo = V) do vendedor associado ao usuário autenticado, nos estados validado (V) ou faturado (F). Se o pedido não tiver vendedor, só é incluído quando foi criado pelo usuário autenticado. O vendedor é determinado no servidor, não aceito como parâmetro do app.- Cada registro contém número do pedido, data de emissão, nome do cliente quando houver, total e estado. Pedidos faturados abrem uma confirmação de reimpressão; a execução da impressão continua pendente da API/SDK do POS.
Leitura de código de barras
- O botão de câmera lê o código e consulta
GET /pdv_pos/produto_por_codigo_barra. O endpoint resolve o código de barras cadastrado para uma grade e devolve o produto com os dados do catálogo de venda; quando não houver correspondência disponível no catálogo, retornaproduct: null. - Ao encontrar o item, o app adiciona uma unidade ao carrinho; caso contrário, informa o código lido que não foi encontrado.
- As imagens do catálogo são redimensionadas no servidor para até 50 px no maior lado, preservando a proporção.
Foi encontrado o módulo api_sigerp, com controller em /apsg e métodos
api_logar, api_executar e api_revalidar_token. O script de teste do
módulo usa, como exemplo de chamadas, GET /apsg/api_logar com os parâmetros
usuario, senha e sg_code; as operações seguintes usam
/apsg/api_executar com token no header Authorization. O refresh usa
/apsg/api_revalidar_token com o parâmetro token.
Esses detalhes são evidência do código legado, não um contrato aprovado para
o PDV. O login legado depende de sg_code, que contém base, duração do token e uma
frase secreta codificados. O campo CNPJ/identificador do app não aparece
associado a esse valor. O fluxo genérico também não fornece um endpoint
anônimo de saúde: a ação tabela=teste é executada depois da autenticação.
O módulo vendas_externas contém métodos de modelo, não controllers HTTP
específicos do PDV:
vexdep_busca_departamentos(data_sinc_departamento)devolve departamentos alterados com código, descrição e departamento pai.vexdep_busca_produtos(company_id, data_sic_prod, foto)devolve grades de produtos alteradas com código, descrição, departamento, preço e saldo; a foto é opcional. O método depende do local configurado no estoque.
O login agora mantém em memória o company_id padrão retornado por res.users
em um objeto de sessão, para os casos de uso do catálogo. Isso não define uma
seleção de empresa quando o usuário tem múltiplas empresas.
Ainda é necessário confirmar como esses métodos devem ser expostos/chamados, quais permissões são necessárias, o formato de datas, paginação e o contrato da instalação real.
Os métodos atuais recebem timestamps de sincronização e não oferecem
offset/limit. O de produtos procura alterações em todo o estoque local
configurado, portanto não se deve chamá-lo como catálogo paginado sem adaptar
o contrato ou definir cache incremental e carga inicial.
Catálogo Odoo 7 (Fase 2)
Por decisão do responsável, a primeira versão retorna todo o catálogo, sem paginação:
GET /pdv_pos/departamentosretornadepartments: [{id, name}], ordenados pelo nome em ordem alfabética. O app mostra somente o nome;idserve para solicitar os produtos do departamento.GET /pdv_pos/produtos_por_departamento?department_id=<id>retornaproductsdo departamento selecionado, incluindo campos fornecidos porvexdep_busca_produtose imagens; cada produto agora inclui tambémgrade_idpara criar as linhas de pedido sem nova busca por produto.- O Odoo usa a empresa padrão do usuário autenticado e o local de venda configurado em Estoque/Vendas Externas.
- A data de sincronização vazia significa carga inicial completa. Não há
offset/limitnesta versão; rever após medir o tamanho e desempenho do catálogo real.
Backend legado: autenticação e seleção de base
No backend Odoo 7, o helper valida.controller.MySock autentica via
xmlrpc/common.login(database, user, password). O helper também contém um modo
opcional que consulta um arquivo app.config para mapear CNPJ para database,
mas não foi encontrado um uso desse modo no fluxo de api_sigerp ou em
vendas_externas. Portanto, esse código não confirma que o CNPJ do PDV deve
ser usado para selecionar a base.
O endpoint PDV usa o mapeamento configurado em app_pdv_pos.config; a
entrada ainda precisa ser configurada e confirmada no ambiente de homologação.
Bloqueios de segurança encontrados
- O controller
api_sigerpregistrareq.paramse o corpo da requisição; isso pode incluir senha,sg_codeou token. - O JWT criado pelo código inclui a senha do usuário no payload, que não é criptografado pelo formato JWT.
- Estado de autenticação e dados do usuário ficam em atributos mutáveis da instância do controller; o isolamento entre requisições precisa ser verificado.
- Nenhum contrato ou implementação Odoo 19 foi encontrado nesta inspeção.
coletor_androidtambém registra parâmetros com credenciais e monta uma consulta de autenticação por interpolação de strings. O PDV não reutiliza essas partes, não consultausuario.coletore não devolve hash de senha.
Por esses motivos, o app não foi conectado diretamente ao controller api_sigerp
nem copiou o SQL de login do Coletor. O endpoint dedicado usa a sessão web Odoo.
Antes de conectar dados reais, documentar para cada operação a URL/rota, método, autenticação, headers, parâmetros, exemplos de request/response, erros, timeout, permissões, idempotência e paginação. Os adaptadores Odoo 7 e Odoo 19 devem implementar o contrato comum definido após essa confirmação.