223 lines
12 KiB
Markdown
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.
|