ConnectWiz + API e webhooks
Integração no arA API que a gente vende é a API que a gente usa
A plataforma inteira está especificada em um único contrato OpenAPI a partir do qual o nosso próprio painel e o nosso app mobile são gerados — sem endpoint escondido, sem documentação desatualizada. Em cima disso: chaves de API do Commerce com escopo, gatilhos de webhook protegidos e fluxos que chamam os seus sistemas.
Desenvolvedores
O que faz, exatamente
Um contrato oficial
Um único documento OpenAPI 3 especifica a plataforma; os nossos próprios clientes TypeScript são gerados a partir dele — a documentação não consegue desandar em relação à realidade porque a realidade é construída a partir da documentação.
Chaves de API do Commerce
Chaves emitidas pelo tenant com escopos explícitos — leitura do catálogo, leitura de pedidos, escrita de pedidos — movem a sua própria vitrine ou o seu app no mesmo motor de pedidos, com os preços sempre resolvidos no servidor.
Webhooks de entrada, protegidos
Cada gatilho de webhook de fluxo tem URL e segredo próprios, verificação HMAC sobre o corpo cru e proteção contra replay. Um payload pode nomear uma pessoa; nunca pode conduzir as entranhas do fluxo.
Saída pelos fluxos
O passo REST chama os seus sistemas exatamente nos momentos que você desenha no canvas — pedido feito, consentimento concedido, agendamento marcado.
Por dentro
As decisões de design da API, com todas as letras
Preço nunca vem do cliente
Uma requisição de pedido diz o quê e quantos — nome e preço são lidos do catálogo naquele instante, no servidor, e gravados no item como uma foto congelada. Uma requisição adulterada não consegue inventar desconto.
Recursos antes das chamadas
Cada superfície de integração publica um contrato de recursos — ela casa por telefone, lista pedidos de visitante, cria pedidos? — e chamar além de um “não” declarado estoura na hora, em vez de falhar lá no fundo.
Erros que querem dizer alguma coisa
O transporte distingue “não autorizado” de “serviço fora do ar” — então “a loja está inacessível” nunca aparece como “este cliente nunca comprou nada”. Erro com nome é a diferença entre uma API e um jogo de adivinhação.
Webhooks à prova de replay
Todo evento que entra reivindica uma chave única num registro de idempotência antes do processamento — uma entrega repetida ou reenviada morre na camada de banco de dados, não na sua automação.
Chaves com hash, segredos com escopo
As chaves de API são guardadas como hash, e só o hash e os escopos são resolvíveis na porta — uma linha de banco vazada não nomeia workspace nenhum e não destrava nada além dos escopos dela.
Rascunho e confirmação são explícitos
A criação de pedido recebe um parâmetro de confirmação explícito — a API pública assume confirmado, e os fluxos do painel conseguem deixar rascunhos em espera — então “isso é real?” é um campo, não uma convenção.
Configuração
Como se conecta
Emita uma chave
Crie uma chave de API do Commerce com escopo no painel; revogue com a mesma facilidade.
Ligue um webhook
Crie um fluxo com gatilho de webhook; assine as requisições com o segredo dele.
Chame de volta para fora
Adicione passos REST onde os seus sistemas precisam ficar sabendo.
Melhor em conjunto
Com o que se combina
Flows
Os gatilhos de webhook disparam fluxos; os passos REST chamam os seus sistemas de volta nos momentos que você desenha — automação de entrada e de saída dividem um canvas só.
Commerce
O catálogo e o motor de pedidos por trás da API são os mesmos que a loja no chat e a IA usam — uma só verdade de pedido, quatro portas.
A sua própria vitrine
Já tem time rodando vitrine headless na Commerce API hoje — o caminho que a página do Shopify recomenda com honestidade enquanto o conector nativo é construído.
Segurança e garantias
As garantias chatas
HMAC sobre o corpo bruto
A verificação do webhook assina o corpo cru da requisição com um segredo por gatilho e compara em tempo constante — a interpretação do conteúdo só acontece depois da prova.
Payload é dado, nunca comando
Um payload de webhook pode se referir a uma pessoa; nunca pode conduzir as entranhas de um fluxo, reescrever prompts ou invocar ferramentas. A fronteira entre dado e instrução é de arquitetura, não de comportamento.
Limite de taxa em toda porta
Os endpoints públicos passam pelo controle de vazão padrão, e os limites de leitura são cortados no servidor — um cliente mal comportado degrada a si mesmo, não a plataforma.
As letras miúdas, sem rodeios
Limites, com todas as letras
Ainda sem stream completo de eventos
Um feed genérico de webhook do tipo “assine tudo” não existe — hoje os eventos de saída acontecem por passos de fluxo. Está escrito aqui para nenhuma conversa de vendas precisar insinuar o contrário.
Leituras limitadas, de propósito
As leituras devolvem até 100 linhas com cursor — a API foi feita para integração operacional, não para exportação em massa. Necessidade de volume é conversa, não brecha.
Conectado com honestidade vale mais do que conectado com estardalhaço.
Cada integração aqui está descrita pelo que ela realmente faz — direção, propriedade dos dados e limites inclusos.