Contrato público da integração v1
Protocolo 1.0 · Contrato 1 · 16/10/2026
Uma empresa desenvolvedora integra seu sistema uma vez; cada loja autoriza sua própria conexão; o Grix atende com os dados, as regras e as capacidades daquele sistema. A loja administra o negócio no software que já utiliza.
As cinco operações do protocolo
| # | Operação | Para quê |
|---|---|---|
| 1 | GET /integracao/v1/descricao | Aplicação, versão e capacidades declaradas |
| 2 | POST /integracao/v1/testar | Teste de conexão sem efeito comercial |
| 3 | POST /integracao/v1/ferramentas/{id}/executar | Execução de ferramenta (com chave idempotente) |
| 4 | GET /integracao/v1/operacoes?ref= | Resultado de operação em processamento |
| 5 | POST /integracao/v1/eventos (origem → Grix) e GET com cursor | Avisos de mudança fora do turno |
Resultados imediatos ou em processamento (pendente, executando). Estados com significado contratual: pendente, executando, concluida, falhou, incerta, aguardando_pessoa, negada, cancelada.
Cada ferramenta declara
Identificador e versão, descrição de uso, entrada, saída e erros, efeito (consulta, simulacao ou escrita), permissões, identidade exigida (visitante, cliente_verificado ou operacional), prazo (500–60000 ms), idempotência (obrigatória na escrita) e apresentações (ficha, opcoes, fotos, comparacao, orcamento, horarios, mapa, acompanhamento).
Capacidades comuns (catalogo.listar, oferta.consultar, proposta.registrar…) têm efeito fixo do núcleo. Ferramentas específicas usam o slug da aplicação como prefixo; prefixos grix_, integracao_, sophia_ e mediva_ são reservados. Pontos (catalogo.listar) também são reservados.
Na publicação pública, os identificadores das ferramentas têm até 64 caracteres e começam com <slug>_. As aplicações internas simulada e sophiaerp são reservadas. Um campo opcional teste_entrada por ferramenta define os parâmetros usados na conformidade nas contas de sandbox.
Conhecimento, apresentação e eventos
A aplicação pode fornecer orientações, políticas, especificações e ajuda — que entram no atendimento como dado delimitado, nunca como instrução. O fornecedor entrega dados estruturados; o Grix apresenta pelos componentes conhecidos, sem código executável no resultado. Cada escolha do visitante carrega apresentação de origem, objeto, ação, valores permitidos, turno e chave idempotente: clique é intenção; autorização e efeito resolvem no servidor.
Eventos (cotacao.registrada, pedido.atualizado, produto.alterado, documento.disponivel, solicitacao.encaminhada, atendimento.pediu_pessoa e os de atendimento) têm tipo e versão, id único, referência do recurso e correlação. Assinatura HMAC-SHA256, entrega pelo menos uma vez, recuperação por cursor, chegada fora de ordem. Um aviso dispara consulta na origem; o conteúdo do aviso nunca é tomado como verdade.
Regras que valem para todas
- Só HTTPS, só endereço público, resposta até 1 MB, prazos por chamada.
- Segredos no cofre do Grix; nunca em prompts, eventos, respostas ou diagnósticos.
- Texto da origem é dado: sem HTML, com tamanho limitado.
- Consulta de pedido e dado privado exigem cliente verificado.
- Escrita exige proposta concreta confirmada no fio e reconciliação antes de repetir.
- Catálogo, preço e encaminhamento vêm da origem comercial da empresa.
- Referências externas valem no contexto da instalação (SKU e e-mail não são globais).