Guia da primeira integração

Guia da primeira integração

Do cadastro à aplicação publicada e à loja ativa. A loja usa os termos do negócio; o Grix gerencia a IA.

Este guia cobre a direção Grix → seu sistema (o Grix atende com os dados da sua aplicação). Se o que você quer é o contrário — **seu sistema ler e receber dados da loja no Grix** — comece pela API pública v1: chaves com escopos criadas pela própria loja na área da loja, catálogo, pedidos, eventos e avisos assinados, sem publicar aplicação nem passar pela conformidade.

1. Crie a conta e a aplicação

1. Abra /desenvolvedores/ e crie a conta com seu nome, empresa, e-mail e senha. Se já tem conta no Grix, entre com ela e cadastre a empresa desenvolvedora. O vínculo é feito pela conta autenticada.
2. Crie sua aplicação: nome, identificador (slug único em minúsculas, números e sublinhado) e descrição. A mesma aplicação atende todas as lojas clientes; cada instalação tem dados e credenciais próprios.
3. Baixe o servidor de exemplo. Ele também está disponível publicamente em /desenvolvedores/documentacao/exemplo. Rode php -S localhost:8080 servidor-exemplo.php para testar diretamente. Configure GRIX_EXEMPLO_APLICACAO para o slug cadastrado. As contas de demonstração usam exemplo-conta-a e exemplo-conta-b; você pode trocar por GRIX_EXEMPLO_TOKEN_A e GRIX_EXEMPLO_TOKEN_B.

2. Descreva as capacidades

Edite o exemplo: troque o slug, liste as ferramentas no formato do contrato e exponha GET /integracao/v1/descricao. Exemplo de consulta, cálculo, escrita e evento estão no próprio arquivo. Os identificadores das ferramentas começam com <slug>_ e têm até 64 caracteres. simulada e sophiaerp são aplicações internas reservadas. Quando a ferramenta precisa de dados de teste específicos, declare teste_entrada na ferramenta com um objeto de parâmetros de sandbox.

3. Publique e rode a conformidade

1. Hospede o servidor em HTTPS público. Localhost serve para desenvolvimento direto; o Grix conecta somente a endereços públicos HTTPS.
2. Na sua aplicação em /desenvolvedores/, informe a URL base e as credenciais de duas contas distintas de teste. As credenciais são usadas na verificação e não são armazenadas nem devolvidas na resposta.
3. Clique em Verificar e publicar versão. O Grix busca a descrição e executa a conformidade: leitura em dois contextos, escrita idempotente e reconciliação quando declaradas, simulação e teste de conexão. A conformidade pode escrever nas contas de teste; use contas de sandbox.
4. As pendências aparecem por checagem. Somente após aprovação técnica a versão e a evidência automática de sandbox são registradas. O processo usa sua própria sessão, sem conta administrativa ou intervenção da equipe.
5. A versão é imutável. Para corrigir contratos ou mudar o endereço, atualize a versão no seu servidor e publique novamente.

A lista de versões e o link de instalação aparecem na sua aplicação. A URL verificada acompanha a versão, para a loja não precisar digitá-la.

4. Teste como uma loja

1. Compartilhe o link /painel/?integracao=<slug>. O dono entra na área da loja e abre Integrações, já com o sistema indicado. Quem ainda não tem loja pode cadastrá-la pelo fluxo público de cadastro do Grix.
2. Clique em Conectar. O sistema e a versão publicada são selecionados pela interface, sem digitar identificadores.
3. Informe a chave da conta fornecida pelo seu sistema e clique em Autorizar conta. O segredo fica no cofre da instalação.
4. Use Testar conexão, selecione as funções pelos nomes apresentados e indique se o sistema é a fonte dos produtos, preços e compras.
5. Clique em Ativar. Somente funções aprovadas no teste podem ser ativadas. A área da loja oferece pausa, reautorização, diagnóstico, desconexão e consumo. Mudança incompatível exige revalidação.

O aceite completo de cada aplicação verifica as jornadas das capacidades oferecidas. O piloto Sophia real e as condições comerciais da plataforma têm pendências próprias, descritas em plataforma-v1.md; a publicação técnica por um desenvolvedor não encerra essas pendências.

Diagnóstico rápido

Compatibilidade e descontinuação: versão semântica, aviso prévio antes de descontinuar, limites por plano. Detalhes de rotas e erros em referencia-api.md.