Files
Pdv-Pos/pdv/docs/API_CONTRACTS.md
T

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, brand e version do app, mais platform (android, linux, etc.).
  • cnpj seleciona o database via app_pdv_pos.config; username/password são credenciais de res.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) e company_id. O Odoo emite o cookie HTTP sid e retorna o session_id interno do Odoo; o app guarda ambos em armazenamento seguro e nunca persiste a senha.
  • Chamadas autenticadas seguintes enviam o cookie sid e o parâmetro session_id para 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 e AccessDenied invalida a sessão.
  • POST /pdv_pos/logout invalida 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/clientes recebe query no corpo do formulário e pesquisa em financeiro.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_pagamento consulta combinações ativas de adm.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_venda recebe checkout_key, items e payments como 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_required antes 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_vendas retorna 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, retorna product: 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/departamentos retorna departments: [{id, name}], ordenados pelo nome em ordem alfabética. O app mostra somente o nome; id serve para solicitar os produtos do departamento.
  • GET /pdv_pos/produtos_por_departamento?department_id=<id> retorna products do departamento selecionado, incluindo campos fornecidos por vexdep_busca_produtos e imagens; cada produto agora inclui também grade_id para 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/limit nesta 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_sigerp registra req.params e o corpo da requisição; isso pode incluir senha, sg_code ou 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_android també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 consulta usuario.coletor e 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.