Integração Shopify

A Alkax disponibiliza uma aplicação Shopify alojada em commerce.alkax.io. A configuração da integração começa num projeto de programador Alkax, não num ecrã independente de configuração do comerciante.

O projeto de programador é o limite do tenant. Um projeto pode ligar várias lojas Shopify e cada ligação de loja seleciona o ambiente Sandbox ou de Produção do projeto.

Ligar uma loja

Abra a Consola de programadores e selecione o projeto a que deve pertencer a loja Shopify.
Abra Comércio eletrónico → Shopify.
Introduza o domínio *.myshopify.com da loja.
Escolha Sandbox ou Produção.
Escolha Ligar loja.
Conclua a instalação/autorização Shopify em commerce.alkax.io.

A Alkax cria uma transferência de ligação de curta duração. O serviço Shopify partilhado resgata-a depois da autenticação Shopify e associa a loja a:

DeveloperProject.Id   -> tenant identity
DeveloperEnvironment  -> Sandbox or Production execution/billing context
Shopify shop domain   -> connected store

Uma loja só pode ter uma associação ativa a um projeto Alkax de cada vez.

O que é configurado automaticamente

Os programadores não copiam uma chave de API Alkax para a Shopify. Após uma associação bem-sucedida, a Alkax emite uma credencial exclusiva da integração para o projeto/ambiente selecionado e devolve-a apenas ao serviço partilhado commerce.alkax.io.

As chamadas da integração Shopify utilizam, assim, a mesma atribuição de projeto/ambiente, os mesmos limites e o mesmo percurso de faturação que o tráfego normal da Plataforma de programadores.

A credencial permanece no servidor. Nunca é incluída numa extensão de checkout, numa extensão de conta de cliente ou numa resposta ao navegador.

Preenchimento automático de endereços

O preenchimento automático de endereços é a capacidade base da Shopify. A extensão de checkout chama o serviço partilhado com um token de sessão Shopify. O serviço resolve a loja para o respetivo tenant do projeto e chama:

GET /api/v1/addresses/suggestions?q=<query>&countryCode=<optional>&limit=5
X-Alkax-Key: <managed project/environment credential>

As sugestões provêm da pesquisa de endereços da própria Alkax. A introdução manual de endereços Shopify continua disponível se a Alkax estiver temporariamente indisponível.

A disponibilidade das extensões de endereço no checkout está sujeita aos requisitos atuais da Shopify relativos ao plano de checkout, dados protegidos de clientes e acesso à rede.

Seguimento opcional de encomendas

O seguimento de encomendas é ativado por loja ligada em Consola de programadores → Comércio eletrónico → Shopify.

Quando um programador seleciona Ativar seguimento:

A Alkax marca o seguimento como pedido para essa ligação projeto/loja.
O processo abre a aplicação Shopify instalada.
A Shopify pede à loja que conceda o âmbito opcional read_orders.
commerce.alkax.io comunica essa aprovação à integração canónica do projeto.
Os novos webhooks orders/create podem criar entregas Alkax no âmbito do projeto.
A extensão de estado de encomendas da conta de cliente pode mostrar o estado da entrega Alkax depois de verificar que o cliente com sessão iniciada é titular da encomenda. O seguimento é ocultado em sessões anónimas ou quando a Shopify não consegue verificar a titularidade.

Desativar o seguimento na Consola de programadores tem efeito na ligação canónica mesmo que a permissão Shopify ainda não tenha sido revogada manualmente. A aplicação instalada também pode revogar o acesso a encomendas que deixou de ser utilizado.

Serviço partilhado com vários tenants

Alkax Developer Project
  └── E-commerce
       └── Shopify
            ├── store-a.myshopify.com -> Sandbox
            └── store-b.myshopify.com -> Production
                         |
                         v
                commerce.alkax.io
             shared Shopify runtime
                         |
              tenant = DeveloperProject.Id
                         |
                         v
                  Alkax platform

A base de dados da aplicação Alkax é responsável pela ligação canónica e pelo estado das funcionalidades. A base de dados do serviço Shopify é responsável apenas pelo estado operacional Shopify: sessões OAuth, a associação resolvida ao tenant, recibos de webhooks e correspondências entre encomendas Shopify e entregas Alkax.

Os registos operacionais incluem os identificadores do projeto e do ambiente para tornar a atribuição ao tenant explícita e auditável.

Segurança da ligação

O projeto cria um token de transferência aleatório e de curta duração. A Alkax guarda apenas o seu hash. O serviço Shopify guarda a transferência apenas durante o tempo necessário para concluir o OAuth Shopify, resgatando-a depois através de um endpoint Alkax autenticado por serviço.

O resgate é único. A ativação bem-sucedida elimina a transferência e cria automaticamente a credencial de projeto/ambiente utilizada por essa ligação de loja.

Desinstalar uma loja Shopify ou eliminar os seus dados chama o plano de controlo Alkax, marca a ligação canónica como desligada, desativa o seguimento e revoga a credencial de integração.

Identidade da entrega e novas tentativas

Cada encomenda Shopify é mapeada de forma determinística utilizando o domínio da loja e o Shopify Order GID. A integração utiliza valores Alkax estáveis de idempotência/ativação e guarda os IDs de webhooks Shopify, para que as novas tentativas Shopify e Alkax não criem entregas duplicadas.

Quando a Shopify não fornece coordenadas de destino, a integração pode resolver um Plus Code Alkax incorporado no endereço selecionado. Se não existirem coordenadas nem um código Alkax utilizável, a encomenda é registada como awaiting_address; não é criada uma entrega em 0,0.

Configuração para responsáveis pela manutenção

A implementação encontra-se em integrations/shopify/ e é implementada separadamente do frontend web principal.

Configuração de execução necessária:

DATABASE_URL=postgresql://...
SHOPIFY_API_KEY=...
SHOPIFY_API_SECRET=...
SHOPIFY_APP_URL=https://commerce.alkax.io
SCOPES=

ALKAX_API_URL=https://<alkax-api-host>
ALKAX_SHOPIFY_SERVICE_KEY=<shared service identity>

A implementação da API Alkax tem de configurar os valores correspondentes:

ShopifyIntegration:AppUrl=https://commerce.alkax.io
ShopifyIntegration:ServiceKey=<same shared service identity>

Validação local:

cd integrations/shopify
npm install
npm run prisma:generate
npm test
npm run typecheck
npm run build

Consulte Plataforma de programadores e Delivery Intelligence para os contratos de projeto, quota e entrega subjacentes.

Ligar uma loja​

O que é configurado automaticamente​

Preenchimento automático de endereços​

Seguimento opcional de encomendas​

Serviço partilhado com vários tenants​

Segurança da ligação​

Identidade da entrega e novas tentativas​

Configuração para responsáveis pela manutenção​