# 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=` 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.