Documentação Ponto Maré
Pacote Android: com.gelsonschikorski.pontomare
Versão de referência: 1.0.0+19
Contato: contato.pontomare@gmail.com
O Ponto Maré é um sistema de ponto de venda para lojas. Ele foi desenvolvido para auxiliar no cadastro de produtos, controle de estoque, registro de vendas, controle de caixa, acompanhamento de pagamentos, impressão de cupons e etiquetas, backups e configurações operacionais do estabelecimento.
Esta documentação apresenta uma visão geral do aplicativo e descreve as principais funcionalidades disponíveis para o usuário.
Links importantes
Aviso
O Ponto Maré é um aplicativo independente desenvolvido por Gelson Schikorski. Ele não substitui orientação contábil, fiscal, jurídica ou administrativa profissional.
O usuário é responsável por conferir os dados cadastrados, valores de produtos, registros de vendas, pagamentos, estoque, caixa, relatórios e comprovantes gerados pelo aplicativo.
Parte dos dados pode ser armazenada localmente no dispositivo. Por isso, recomenda-se manter backups atualizados e proteger o acesso ao aparelho.
Visão geral do aplicativo
O Ponto Maré organiza as operações da loja em módulos acessados pelo menu lateral:
- Caixa: acompanhamento e registro de entradas e saídas do caixa.
- Venda: tela principal do ponto de venda, onde produtos são adicionados e vendas são finalizadas.
- Vendas: histórico de vendas, detalhes, impressão de cupom e desfazer venda.
- Produtos: cadastro, edição, busca, estoque, preços, custos, cores e impressão de etiquetas.
- Pagamentos: listagem e filtro dos pagamentos registrados.
- Configurações: formas de pagamento, maquininhas, tema, som, impressão, logo, backup, restauração, assinatura, conta e senha de administrador.
- Produtos Remotos: catálogo remoto opcional para criar ou vincular produtos locais e importar quantidades.
- Logs: registros técnicos do sistema, protegidos por senha de administrador.
Conta, login e acesso
Para acessar o Ponto Maré, o usuário utiliza uma conta com e-mail e senha.
Na tela inicial é possível entrar com uma conta existente, criar uma nova conta, alternar entre login e cadastro, informar e-mail, senha e confirmação de senha, além de visualizar mensagens de erro quando houver falha de autenticação.
Assinatura e período de teste
O Ponto Maré possui controle de acesso por assinatura. A assinatura pode ser validada por serviços como Google Play no Android e por fluxo externo em plataformas desktop, conforme a configuração disponível.
Quando o usuário possui acesso liberado, o aplicativo abre normalmente. Quando o período de teste termina ou a assinatura não está ativa, o aplicativo exibe uma tela informando que a assinatura é necessária.
Na tela de assinatura, o usuário pode visualizar o plano disponível, assinar pelo fluxo de compra, restaurar compras quando disponível e sair da conta. O app também pode exibir um aviso quando o período de teste estiver próximo do fim.
Menu e navegação
Depois do login e da validação de acesso, o usuário entra na área principal do aplicativo.
O menu pode aparecer como uma barra lateral expandida, uma barra compacta ou uma gaveta, dependendo do tamanho da tela. Isso permite uso em telas maiores, como desktop/tablet, e também em telas menores.
O menu também oferece ações rápidas, como fazer backup do banco de dados, sair da conta e navegar entre módulos.
Módulo Caixa
O módulo Caixa reúne registros financeiros do dia, incluindo entradas manuais, saídas manuais e vendas.
Na tela de caixa, o usuário pode visualizar registros, selecionar uma data, avançar ou voltar um dia, limpar o filtro, filtrar vendas por forma de pagamento, cadastrar entradas ou saídas manuais, ver detalhes e excluir registros quando permitido.
Registros manuais de caixa
Ao cadastrar ou editar um registro manual, o usuário informa tipo do registro, valor, indicação de entrada ou saída, observação e data/hora quando o registro já existe.
Esses registros são úteis para anotar movimentações que não vieram diretamente de uma venda, como reforço de caixa, retirada, despesa, sangria ou ajuste.
Horário de alternância do caixa
Nas configurações, o usuário pode definir o horário de alternância do caixa. Esse horário determina quando os registros passam a ser considerados como parte do dia seguinte.
Por exemplo: se configurado para 02:00, ao visualizar o caixa de 30/12, o sistema considera registros de 02:00 do dia 30/12 até 01:59 do dia 31/12. Esse recurso é útil para lojas que encerram o expediente depois da meia-noite.
Módulo Venda
O módulo Venda é a tela principal do PDV. Nele, o usuário pode informar ou ler o código de um produto, buscar produtos manualmente, adicionar produtos à venda, visualizar itens, ver detalhes, remover unidades, acompanhar o total em tempo real, excluir a venda em andamento e finalizar a venda.
Regras da venda em andamento
A venda em andamento é mantida pelo aplicativo até ser finalizada ou excluída. Isso ajuda a recuperar o fluxo caso o app seja fechado durante uma operação.
Produtos sem estoque não podem ser adicionados à venda. Quando uma venda é finalizada, o estoque e os registros financeiros são atualizados conforme os produtos e pagamentos informados.
Busca de produtos durante a venda
Quando o operador não sabe o código do produto, pode abrir a busca de produtos para localizar produtos cadastrados e escolher um item para adicionar à venda.
Finalização da venda
Ao finalizar uma venda, o app abre o diálogo de pagamento. Nessa etapa, o usuário pode conferir subtotal, desconto, total e valor pago, aplicar desconto, adicionar pagamentos, definir valores, selecionar forma de pagamento, selecionar maquininha quando necessário, informar observações, marcar impressão de cupom e concluir a venda.
Quando os pagamentos não cobrem o total da venda, o app exibe um aviso e pede confirmação antes de finalizar com pagamento insuficiente.
Módulo Vendas
O módulo Vendas apresenta o histórico das vendas registradas. Na listagem, o usuário pode visualizar vendas concluídas, abrir detalhes, editar informações permitidas quando a venda ainda for editável, imprimir cupom e desfazer venda.
Ao abrir uma venda, o app mostra os produtos e pagamentos relacionados. Quando a venda ainda pode ser editada, o usuário pode ajustar detalhes permitidos. Quando não pode, a tela funciona como consulta.
Módulo Produtos
O módulo Produtos é usado para cadastrar, editar, buscar e controlar produtos locais da loja.
Na tela de produtos, o usuário pode cadastrar produto local, buscar por texto, mostrar ou ocultar produtos sem estoque, visualizar produtos em tabela, imprimir etiqueta, editar produto e excluir produto com confirmação por senha de administrador.
Cadastro e edição de produto
O cadastro de produto possui campos como código, quantidade, nome, preço, custo, observação e cores.
O campo de código local não representa necessariamente o código final completo digitado pelo usuário. O usuário informa ou sugere apenas a parte editável do código; o aplicativo monta e valida o código final no padrão EAN-8. Quando o produto já existe, o código não pode ser alterado.
Código local, EAN-8 e código de barras
O Ponto Maré trabalha com códigos no padrão EAN-8, que possui 8 dígitos. Esse formato permite gerar códigos compatíveis com leitura por código de barras em etiquetas.
- Primeiro dígito: indica a faixa do código e ajuda o sistema a diferenciar produtos locais de produtos remotos.
- Dígitos centrais: representam a parte numérica do produto que o usuário consegue informar ou sugerir.
- Último dígito: é o checksum do EAN-8, calculado automaticamente pelo aplicativo.
Se o usuário deixar o código em branco, o sistema gera automaticamente um código local disponível. Se informar uma parte do código, ela é tratada como sugestão para formar um EAN-8 válido. O último dígito não deve ser informado manualmente.
Estoque, preço, custo e cores
O estoque é controlado pela quantidade cadastrada e pelas movimentações realizadas em vendas ou importações. O produto possui preço de venda e custo, e o custo pode ser protegido por senha de administrador para evitar exposição de informações sensíveis.
O produto também pode ser associado a cores cadastradas. O seletor de cores permite ver cores existentes, selecionar cores para o produto, criar novas cores e usar seletor visual.
Etiquetas
Produtos podem ser impressos em formato de etiqueta. Ao cadastrar um produto novo, o usuário pode marcar a opção de imprimir etiqueta após salvar. Em produtos já cadastrados, a ação de impressão fica disponível no próprio produto.
Módulo Pagamentos
O módulo Pagamentos lista pagamentos registrados nas vendas. Ele permite filtrar pagamentos por forma de pagamento, maquininha, data inicial e data final.
Esses filtros ajudam a conferir valores recebidos por período, por tipo de pagamento e por dispositivo. Ao selecionar um pagamento, o usuário pode abrir a venda relacionada para conferir detalhes.
Formas de pagamento
Nas configurações, o usuário pode gerenciar formas de pagamento. O app já cria algumas formas padrão, como Dinheiro, PIX, Débito, Crédito à vista e Crédito parcelado.
Cada forma de pagamento pode indicar se exige ou não uma maquininha. O usuário pode selecionar, criar, editar ou deletar formas quando permitido, além de definir a forma de pagamento padrão para novas vendas.
Maquininhas e dispositivos
O app permite cadastrar dispositivos ou maquininhas para associar aos pagamentos. Cada dispositivo possui nome, observação e status ativo/inativo.
O usuário pode criar, editar ou deletar uma maquininha quando possível, além de definir uma maquininha padrão. Quando uma forma de pagamento exige dispositivo, a seleção de maquininha aparece no fluxo de pagamento.
Pagamento padrão
Nas configurações, é possível definir forma de pagamento padrão e maquininha padrão. Essas opções são usadas automaticamente ao finalizar uma venda, facilitando o fluxo quando a loja utiliza sempre a mesma forma de pagamento ou a mesma maquininha.
Produtos Remotos
O módulo Produtos Remotos é um recurso opcional para trabalhar com um catálogo remoto vinculado à conta do usuário. Essa tela pode ficar oculta quando o recurso estiver desativado na configuração remota do aplicativo.
Esse módulo pode ser usado para cadastrar e atualizar produtos remotos, buscar produtos, exibir ou ocultar arquivados e sem estoque, criar produtos locais a partir de produtos remotos, vincular produtos remotos a produtos locais, importar quantidades pendentes, executar ações em lote e arquivar ou restaurar produtos.
Diferença entre produto local e produto remoto
Produto local é armazenado no banco de dados do dispositivo e usado diretamente nas vendas. Produto remoto é armazenado em servidor, associado à conta do usuário, e pode servir como fonte para criar produto local, vincular ao produto local ou importar quantidade pendente.
Exemplo de uso fora da loja
Um caso comum para produtos remotos é o cadastro fora da loja. O lojista pode cadastrar produtos em outro dispositivo antes de levar a mercadoria para o sistema principal da loja.
- O lojista está fora da loja, como em casa, no depósito ou no fornecedor.
- Ele cadastra os produtos como produtos remotos em um dispositivo secundário.
- Cada produto remoto já fica com nome, código, preço, custo, observação e quantidade pendente.
- Quando a mercadoria chega à loja, o usuário abre o Ponto Maré no dispositivo principal.
- Na tela de Produtos Remotos, importa os produtos para a base local.
- Depois da importação, os produtos ficam prontos para venda no sistema local da loja.
Esse fluxo ajuda a separar o trabalho de cadastro do atendimento no caixa e reduz a chance de produtos ficarem fisicamente na loja sem cadastro, etiqueta ou preço definido.
Ações em lote e assistente de vinculação
Ao selecionar vários produtos remotos, o app pode exibir uma barra de ações em lote. Produtos sem vínculo podem ser criados como produtos locais; produtos vinculados e com quantidade pendente podem ter quantidades importadas; produtos não aplicáveis são ignorados para aquela ação.
Quando o app precisa vincular um produto remoto a um produto local, ele pode exibir um assistente para comparar informações e resolver diferenças entre dados remotos e locais, como nome, preço, custo, observação ou código.
Impressão
O Ponto Maré possui recursos de impressão para cupons e etiquetas. As configurações permitem escolher método de impressão, impressora, tamanho do papel, tipo de impressão, quantidade, pré-visualização em PDF, medidas da etiqueta, cabeçalho e rodapé do cupom, uso de logo e suporte a fonte tipo B em alguns fluxos ESC/POS.
Métodos e tipos de impressão
O app possui suporte a impressão por Bluetooth, USB, Sistema (somente PDF) e Comando LP (Unix/Linux).
Os tipos de impressão disponíveis incluem PDF ESC/POS imagem-bytes, Raw ESC/POS bytes e Raw TSPL bytes. O app permite selecionar tamanhos de papel de 58 mm, 72 mm e 80 mm.
Cupons e etiquetas
Para cupons de venda, o usuário pode configurar cabeçalho, rodapé, inclusão de logo, impressão após finalizar venda e reimpressão pelo histórico. Para etiquetas, pode configurar largura, altura, intervalo, quantidade e tipo de impressão compatível.
Logo da loja
Nas configurações, o usuário pode definir uma logo da loja. A logo pode ser usada na interface e em alguns tipos de impressão, conforme a configuração selecionada. O usuário pode alterar, remover e visualizar a logo configurada.
Tema, aparência e feedback sonoro
O app permite escolher o tema visual. Dependendo da configuração disponível, o usuário pode alternar entre tema claro, tema escuro e tema do sistema.
O Ponto Maré também pode tocar sons de feedback em operações de sucesso, erro e aviso. Nas configurações, o usuário pode ativar ou desativar esse comportamento.
Senha de administrador
Algumas áreas ou ações são protegidas por senha de administrador. No primeiro uso, antes de qualquer configuração personalizada, a senha padrão é admin. Recomenda-se trocar essa senha nas configurações antes de liberar o uso para operadores da loja.
A senha pode ser solicitada para excluir produtos, acessar logs, limpar logs, visualizar informações sensíveis como custo de produto e deletar conta.
Backups e restauração
O Ponto Maré possui recursos para backup e restauração do banco de dados. Nas configurações, o usuário pode ver e atualizar a data do último backup, fazer backup manualmente, restaurar backup, importar arquivo, otimizar bancos de dados e compartilhar logs com desenvolvedores.
O backup manual envia uma cópia dos dados para o armazenamento configurado e reduz o risco de perda de informações em caso de troca de aparelho, falha no dispositivo, exclusão acidental ou reinstalação.
Na restauração, recomenda-se conferir se o backup escolhido corresponde à loja e ao período desejado, pois a restauração pode substituir dados locais.
Logs do sistema
O módulo Logs registra eventos técnicos e ações importantes do aplicativo. O acesso é protegido por senha de administrador.
O usuário autorizado pode visualizar logs paginados, filtrar por texto, tipo de log e data, além de limpar logs mediante senha. Tipos de logs incluem erro, aviso, informação, debug e ação.
Status da assinatura
Nas configurações, o usuário pode abrir o diálogo de status da assinatura. Essa tela pode mostrar status da assinatura, provedor, data de início, data de expiração, dias restantes e se o acesso ao app está liberado ou bloqueado.
Status possíveis incluem período de teste, ativa, expirada e cancelada.
Exclusão de conta
O usuário pode acessar a opção Deletar conta nas configurações. Antes de abrir a confirmação de exclusão, o app solicita a senha de administrador.
A exclusão informa que a ação é permanente, os dados nos servidores e a conta serão removidos, a assinatura ativa pode ser perdida, dados locais podem continuar no dispositivo e, para removê-los, o usuário deve desinstalar o app ou limpar os dados do Ponto Maré no sistema operacional.
Dados salvos no dispositivo
O Ponto Maré utiliza banco de dados local para armazenar informações operacionais, como produtos, códigos, cores, preços, custos, vendas, itens vendidos, pagamentos, formas de pagamento, maquininhas, registros de caixa, preferências, configurações de impressão, logo da loja e logs do sistema.
Esses dados ficam no dispositivo e podem permanecer mesmo após a exclusão da conta online. Para remover os dados locais, o usuário deve desinstalar o aplicativo ou limpar os dados do Ponto Maré nas configurações do sistema operacional.
Dados remotos e serviços online
Alguns recursos dependem de serviços online, como Supabase, Firebase Analytics, Firebase Crashlytics, Firebase Remote Config e Google Play Billing.
Os dados operacionais do PDV são principalmente locais. Recursos em nuvem são usados para autenticação, assinatura, backups, produtos remotos e configurações, mas isso não significa que todas as vendas e movimentações locais sejam sincronizadas em tempo real entre dispositivos.
Recursos que podem depender de internet incluem login, cadastro, validação de assinatura, compra e restauração de assinatura, produtos remotos, backup remoto, restauração de backup, configurações remotas e envio de logs para suporte.
Permissões do Android
No Android, o Ponto Maré pode solicitar permissões como Internet, Bluetooth e Localização aproximada ou precisa. A permissão de localização pode ser necessária para busca de dispositivos Bluetooth próximos, mas o app não usa essa permissão para rastrear localização do usuário.
As permissões podem ser gerenciadas nas configurações do sistema operacional.
Requisitos e compatibilidade
O Ponto Maré é um aplicativo Flutter com suporte principal para Android e também estrutura para outras plataformas, conforme build e distribuição configurados.
- Pacote Android:
com.gelsonschikorski.pontomare - SDK mínimo: Android API 26
- Target SDK: Android API 35
Compatibilidade com impressoras depende do modelo, método de conexão, permissões, drivers, sistema operacional, papel, comandos suportados e tipo de impressão selecionado.
Recomendações de uso
- Cadastre corretamente produtos, preços e custos.
- Confira o total antes de finalizar vendas.
- Use formas de pagamento e maquininhas coerentes com a operação real.
- Faça backups com frequência.
- Proteja a senha de administrador.
- Não compartilhe a conta com pessoas não autorizadas.
- Verifique periodicamente se a impressão está funcionando.
- Mantenha o aplicativo atualizado.
- Mantenha o dispositivo protegido com senha ou biometria.
Sugestão de fluxo inicial para uma loja
- Criar conta ou entrar com uma conta existente.
- Conferir o status da assinatura ou período de teste.
- Acessar configurações.
- Cadastrar formas de pagamento.
- Cadastrar maquininhas/dispositivos.
- Definir pagamento padrão.
- Configurar tema e feedback sonoro.
- Configurar impressão.
- Inserir logo da loja.
- Cadastrar produtos.
- Testar impressão de etiqueta.
- Fazer uma venda de teste.
- Testar impressão de cupom.
- Conferir caixa, vendas e pagamentos.
- Fazer o primeiro backup.
Política de privacidade e termos
Para informações sobre coleta, uso, armazenamento, compartilhamento e exclusão de dados, consulte a Política de Privacidade do Ponto Maré.
Para regras de uso, responsabilidades do usuário, assinatura, limitações e condições gerais, consulte os Termos de Uso do Ponto Maré.