Catálogo e ofertas
Liste e detalhe produtos e serviços, consulte preço e disponibilidade na origem. Os itens que a loja escolher aparecem no perfil dela e nas buscas do Grix.
GrixDesenvolvedores
Seu sistema, atendido pelo Grix
Você expõe os dados e as ferramentas do seu sistema por HTTPS. O Grix conduz o atendimento com conversa, voz e painel, e cada loja cliente autoriza a própria conexão.
O que dá para integrar
Uma integração atende todas as suas lojas clientes.
Seu sistema continua sendo a fonte de produtos, preços, regras e pedidos. O Grix entra com a inteligência do atendimento: conversa por texto e áudio, apresentação no painel e a coordenação das ações.
Cálculos e orçamentos
Simule preços com as regras do seu sistema — medidas, quantidades e composição — sem efeito comercial. O cliente confere o cálculo no painel antes de confirmar.
Registros e pedidos
Registre propostas e pedidos, obtenha documentos e consulte a situação na origem. Escrita só acontece com confirmação no fio da conversa e chave idempotente.
Apresentação no painel
Suas respostas voltam como dados estruturados e o Grix apresenta: opções, ficha do item, fotos, comparação, orçamento, horários, mapa e acompanhamento.
Eventos do seu sistema
Avise mudanças fora da conversa — cotação registrada, pedido atualizado, documento disponível. O aviso dispara uma consulta na origem; ele nunca é tomado como verdade.
Conhecimento da aplicação
Orientações, políticas e especificações do seu domínio entram no atendimento como dado delimitado, nunca como instrução para o atendente.
Como funciona
Da descrição à loja ativa, sem falar com a nossa equipe.
- 1Descreva sua aplicação. Exponha a descrição com as ferramentas, entradas, efeitos e prazos, seguindo o contrato HTTP v1.
- 2Publique com conformidade automática. O Grix lê a descrição e testa duas contas de sandbox — leitura, escrita idempotente e reconciliação. Versão aprovada é imutável.
- 3A loja autoriza a conta dela. Pelo seu link de instalação, a loja conecta, testa, escolhe as funções e ativa. Sem digitar identificadores, URLs ou capacidades.
- 4O Grix atende com seus dados. Consultas, cálculos e registros rodam na sua origem, com operações duráveis, medição de consumo e diagnóstico.
Protocolo HTTP v1
Cinco operações sobre HTTPS. Nada além disso.
Protocolo 1.1 · Contrato 1. Só HTTPS em endereço público, respostas de até 1 MB e prazo declarado por ferramenta (500 a 60.000 ms).
| Operação | Para quê |
|---|---|
GET /integracao/v1/descricao | Aplicação, versão e capacidades declaradas |
POST /integracao/v1/testar | Teste de conexão sem efeito comercial |
POST /integracao/v1/ferramentas/{id}/executar | Execução de ferramenta, com chave idempotente |
GET /integracao/v1/operacoes?ref= | Resultado de uma operação ainda em processamento |
POST /integracao/v1/eventos | Avisos de mudança fora do turno, assinados com HMAC-SHA256 |
Exemplo de descrição
{
"protocolo": "1.1",
"contrato": 1,
"aplicacao": "meusistema",
"versao": "1.0.0",
"ferramentas": [
{
"id": "meusistema_catalogo_buscar",
"capacidade": "catalogo.listar",
"descricao": "Busca produtos por termo.",
"efeito": "consulta",
"identidade": "visitante",
"entrada": {
"q": "string"
},
"saida": {
"itens": "lista"
},
"prazo_ms": 3000
}
]
}Comece pelo servidor de exemplo: ele implementa as cinco operações com consulta, cálculo, escrita idempotente e reconciliação. Rode com php -S localhost:8080 servidor-exemplo.php.
Capacidades do núcleo
Vocabulário comum, efeito fixo.
Capacidades comuns têm o efeito definido pelo núcleo e não podem ser redeclaradas com outro efeito. O que for específico do seu sistema vira ferramenta própria, com o identificador da aplicação como prefixo (por exemplo, meusistema_orcamento_simular).
| Capacidade | Efeito |
|---|---|
catalogo.listar | Consulta |
catalogo.detalhar | Consulta |
oferta.consultar | Consulta |
pedido.consultar | Consulta |
entrega.consultar | Consulta |
cliente.registrar | Escrita |
proposta.registrar | Escrita |
pedido.registrar | Escrita |
compra.encaminhar | Consulta |
orcamento.simular | Simulação |
documento.obter | Consulta |
conhecimento.consultar | Consulta |
disponibilidade.consultar | Consulta |
agendamento.criar | Escrita |
agendamento.remarcar | Escrita |
agendamento.cancelar | Escrita |
solicitacao.registrar | Escrita |
solicitacao.consultar | Consulta |
solicitacao.atualizar | Escrita |
solicitacao.cancelar | Escrita |
servico.consultar | Consulta |
Consulta e simulação não têm efeito comercial. Escrita exige proposta concreta confirmada no fio, identidade verificada quando houver dado privado e reconciliação antes de qualquer repetição.
Segurança e limites
As regras que valem para todas as integrações.
Credenciais protegidas
O segredo de cada loja fica no cofre do Grix (AES-256-GCM) e nunca aparece em conversas, eventos, respostas ou diagnósticos — nem para a nossa equipe. Eventos são assinados com HMAC-SHA256.
Identidade por operação
Cada ferramenta declara quem pode chamá-la: visitante, cliente verificado ou operacional. Pedido e dado privado só com vínculo verificável com o titular na origem.
Operações duráveis
Escritas viram operações com estado (pendente, concluida, incerta, aguardando_pessoa…). Sem reconciliação confiável, a pendência vai para uma pessoa — nunca repete no escuro.
Limites e medição
Tetos padrão de 1.000 operações e 100 escritas por dia em cada instalação. O consumo é medido em quatro dimensões e aparece no extrato da loja; retenção de 400 dias (medição) e 180 dias (eventos).
Versões são semânticas e imutáveis depois de publicadas: corrigiu o contrato, publicou versão nova. Capacidade ou permissão nova exige revalidação antes da ativação.
Documentação
Tudo o que você precisa, sem pedir acesso.
Guia da primeira integração
Do cadastro à aplicação publicada e à loja ativa, passo a passo.
Ler a documentaçãoContrato HTTP v1
As cinco operações do protocolo, as declarações de cada ferramenta e as regras que valem para todas.
Ler a documentaçãoReferência da API
Rotas da área do desenvolvedor, da gestão, do protocolo, erros, limites e retenção.
Ler a documentaçãoServidor de exemplo
Código PHP completo e comentado das cinco operações, pronto para rodar e adaptar ao seu sistema.
Baixar o exemplo (.php)Área do desenvolvedor
Crie sua conta e publique sua aplicação.
Cadastro, verificação e publicação são feitos por você, com a sua sessão. Nenhuma etapa pede conta administrativa nem intervenção da equipe do Grix.