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

223 lines
12 KiB
Markdown

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