Arquitetura

Esta página explica a arquitetura técnica do WCPOS para desenvolvedores e usuários avançados.

Sistema em Duas Partes

O WCPOS é projetado como um sistema em duas partes:

1. Plugin PHP: Hospedado em seu servidor, este é um plugin relativamente pequeno que estende a API REST do WooCommerce com endpoints específicos do POS.

2. Cliente JavaScript: Este roda localmente no seu navegador, no aplicativo de desktop ou nos aplicativos iOS/Android.

Você pode pensar nisso como dois mundos separados:

• O mundo PHP é onde a gestão de dados acontece usando WordPress e WooCommerce.
• O mundo JavaScript mantém uma cópia local, com suporte offline, dos dados da loja de que seus caixas precisam, otimizada para pesquisa rápida e resposta instantânea.

SVG not found

Sincronização de Dados

Alterado na v1.10.0

A v1.10.0 substitui a antiga camada de replicação por um motor de sincronização dedicado. O resumo abaixo é a versão curta — a explicação completa está em Como funciona o motor de sincronização.

O cliente é local-first: cada tela lê e grava no banco de dados local do dispositivo, e um motor de sincronização em segundo plano mantém esse banco de dados e o WooCommerce convergentes. O motor não espelha cegamente sua loja inteira — ele trabalha a partir do que suas telas realmente precisam:

• Detecção de mudanças: o POS consulta um registro leve de alterações com requisições condicionais; uma loja ociosa responde com um único 304 sem corpo.
• Demanda declarada: uma tela declara o que está exibindo, e o motor decide se isso exige uma requisição ou se já está atendido localmente.
• Cargas iniciais e faixas: uma carga inicial limitada do catálogo, uma janela de pedidos recentes e faixas de manutenção em momentos ociosos preenchem e verificam os dados locais em intervalos que você pode ajustar por dispositivo.
• Gravações duráveis: vendas e edições entram em fila localmente e são drenadas para o WooCommerce, com recuperação visível para tudo o que o servidor recusar.

O que é sincronizado: produtos e variações, categorias/tags/marcas, clientes, taxas de imposto, cupons (Pro) e pedidos. Os gateways de pagamento são buscados no momento do checkout.

Prós e Contras da Arquitetura

Bom 😊	Ruim 😟
A pesquisa de dados locais é instantânea	Manter os dados sincronizados é desafiador
Dados em cache disponíveis offline	Limitado pela API REST do WooCommerce
Capacidade de criar melhores aplicativos nativos para desktop, iOS e Android	Temas e hooks do WordPress não podem personalizar o aplicativo POS

Banco de Dados Local

O cliente armazena os dados em um banco de dados local em cada dispositivo — os aplicativos web e de desktop usam o armazenamento OPFS (Origin Private File System) executado em um worker, e os aplicativos móveis usam o mesmo formato em disco por meio de um mecanismo de sistema de arquivos. Todas as plataformas compartilham um único formato de armazenamento e as mesmas ferramentas de recuperação. Isso fornece:

• Persistência: Os dados sobrevivem a reinicializações do navegador e do dispositivo
• Desempenho: Consultas rápidas sem latência de rede — filtragem, ordenação e paginação são executadas dentro da camada de armazenamento, de modo que apenas a página visível de linhas chega à interface
• Navegação offline: Dados em cache permanecem acessíveis sem internet

Cada combinação de site + loja + operador de caixa recebe seu próprio banco de dados local, de modo que operadores e lojas nunca compartilham dados locais em um mesmo dispositivo. As atualizações nunca migram um banco de dados local no lugar — o aplicativo baixa novamente do servidor, que é sempre a cópia oficial.

Arquitetura de Checkout

O processo de checkout usa um iframe/webview que carrega a página de Pagamento do Pedido do WooCommerce. Esta abordagem:

• Aproveita gateways de pagamento existentes: Qualquer gateway de pagamento do WooCommerce pode funcionar no POS
• Mantém segurança: O processamento de pagamentos ocorre através da infraestrutura segura do WooCommerce
• Reduz complexidade: Não há necessidade de reimplementar integrações de gateways de pagamento

Extensões da API

O plugin PHP estende a API REST do WooCommerce com endpoints adicionais para funcionalidades específicas do POS, registrados sob os namespaces dedicados wcpos/v1 e wcpos/v2 — o wcpos/v2 carrega a superfície de sincronização da v1.10.0, e é por isso que as versões do aplicativo e do plugin são lançadas em conjunto. Veja API REST do WooCommerce para uma introdução.

O namespace wcpos/v2

A v1.10 introduz o namespace REST wcpos/v2. A sincronização vive aqui, e os serviços POS compartilhados que antes eram servidos por wcpos/v1 agora são servidos por wcpos/v2 (as rotas de serviço wcpos/v1 são pass-throughs para suas implementações v2). As rotas wcpos/v1 ainda são registradas para compatibilidade retroativa, mas estão congeladas — o cliente atual não as chama mais.

Pontos que importam se você integra com esses endpoints:

• As rotas v2 sempre são registradas. A antiga opção woocommerce_pos_sync_api_enabled foi removida; não existe mais uma flag que liga ou desliga a API.
• Endpoints públicos. wcpos/v2/site, wcpos/v2/ping e wcpos/v2/echo são públicos (usados para sondagem de capacidade e conectividade, incluindo os fallbacks de transporte para hosts restritivos).
• Pedidos têm o UUID como chave primária. A identidade do pedido na comunicação é o UUID; o campo legado wooOrderId foi aposentado do envelope de recuperação de pedidos. Os metadados do pedido são tipados na comunicação por meio de um único normalizador.
• O armazenamento de preços por item de linha está documentado para compatibilidade de sincronização com terceiros — veja Como as substituições de preço do POS são armazenadas.
• A ordenação padrão de produtos no POS agora é nome ascendente (anteriormente menu_order, id).
• Métodos legados removidos. Vários métodos legados do controlador API\Settings (por exemplo get_general_settings(), update_access_settings(), get_general_endpoint_args(), remove_license_transient()) foram removidos; o alias da classe permanece, mas esses métodos não.

O Pro espelha a divisão

O WCPOS Pro segue a mesma divisão V1/V2 — seus serviços compartilhados são promovidos para wcpos/v2, enquanto seus dados de pedido permanecem congelados na v1. A precificação de produtos por loja roda na faixa v2, e o escopo de loja do caixa é carregado nas gravações de pedidos, para que pedidos de várias lojas sejam precificados e tributados pela loja correta. Veja Pro.