ConnectWiz + API e Webhooks
Integração em produçãoA API que vendemos é a API que usamos
A plataforma inteira está especificada num só contrato OpenAPI, a partir do qual são gerados o nosso próprio painel e a app móvel — sem endpoints na sombra, sem documentação a afastar-se da realidade. Por cima disso: chaves da Commerce API com âmbito definido, gatilhos de webhook protegidos e flows que chamam os seus sistemas.
Programadores
O que faz — ao certo
Um só contrato de referência
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 se pode afastar da realidade porque a realidade é construída a partir da documentação.
Chaves da Commerce API
Chaves emitidas pelo tenant, com âmbitos explícitos — catálogo em leitura, encomendas em leitura, encomendas em escrita — movem a sua própria loja ou app sobre o mesmo motor de encomendas, com os preços sempre resolvidos do lado do servidor.
Webhooks de entrada, protegidos
Cada gatilho de webhook de um flow tem o seu próprio URL e segredo, verificação HMAC sobre o corpo em bruto e proteção contra replay. Um payload pode nomear uma pessoa; nunca consegue conduzir o interior do flow.
Saída pelos flows
O passo REST chama os seus sistemas exatamente nos momentos que desenhar na tela — encomenda feita, consentimento dado, marcação criada.
Por dentro
Posições de desenho da API, declaradas
Os preços nunca vêm do cliente
Um pedido de encomenda diz o quê e quantos — o nome e o preço são lidos do catálogo nesse momento, do lado do servidor, e escritos na linha como um instantâneo. Um pedido adulterado não consegue inventar um desconto.
Capacidades antes das chamadas
Cada superfície de integração publica um contrato de capacidades — consegue corresponder por telefone, listar encomendas de convidados, criar encomendas? — e chamar para lá de um «não» declarado rebenta logo, em vez de falhar lá muito ao fundo.
Erros que querem dizer alguma coisa
O transporte distingue «não autorizado» de «serviço em baixo» — para que «a loja está inacessível» nunca apareça como «este cliente nunca comprou nada». Os erros com nome são a diferença entre uma API e um jogo de adivinhas.
Webhooks à prova de replay
Cada evento de entrada reclama uma chave única num registo de idempotência antes de ser processado — uma entrega repetida ou reproduzida morre na camada da base de dados, não na sua automação.
Chaves com hash, segredos com âmbito
As chaves de API são guardadas como hashes, e à porta só o hash e os âmbitos são resolúveis — uma linha de base de dados que vaze não nomeia nenhum workspace nem abre nada para lá dos seus âmbitos.
Rascunhos e confirmações são explícitos
A criação de encomendas recebe um parâmetro de confirmação explícito — a API pública assume confirmada, os flows do painel podem preparar rascunhos — para que «isto é a sério?» seja um campo e não uma convenção.
Configuração
Como se liga
Emita uma chave
Crie no painel uma chave da Commerce API com âmbito definido; revogue-a com a mesma facilidade.
Ligue um webhook
Crie um flow com um gatilho de webhook; assine os pedidos com o segredo dele.
Chame de volta para fora
Acrescente passos REST onde os seus sistemas precisem de ser avisados.
Melhor em conjunto
Com o que se combina
Flows
Os gatilhos de webhook iniciam flows; os passos REST chamam os seus sistemas de volta nos momentos que desenhar — a automação de entrada e a de saída partilham uma só tela.
Commerce
O motor de catálogo e de encomendas por trás da API é o mesmo que a loja no chat e a IA usam — uma só verdade de encomendas, quatro portas.
A sua própria loja
Há equipas a operar lojas headless sobre a Commerce API hoje — o caminho que a página do Shopify recomenda sem rodeios enquanto o conector nativo não está pronto.
Segurança e garantias
As garantias aborrecidas
HMAC sobre o corpo em bruto
A verificação de webhooks assina o corpo em bruto do pedido com um segredo próprio de cada gatilho e compara em tempo constante — só há interpretação depois da prova.
Os payloads são dados, nunca comandos
O payload de um webhook pode referir uma pessoa; nunca consegue conduzir o interior de um flow, reescrever prompts ou invocar ferramentas. A fronteira entre dados e instruções é arquitetural, não comportamental.
Limites de débito em todas as portas
Os endpoints públicos andam na limitação padrão, e os limites de leitura são travados do lado do servidor — um cliente mal comportado degrada-se a si próprio, não à plataforma.
As letras pequenas, sem rodeios
Limites, declarados
Ainda sem mangueira de eventos
Um feed de webhooks genérico, do género subscrever-tudo, não está construído — hoje os eventos de saída acontecem através de passos de flow. Fica dito aqui, para que nenhuma chamada comercial tenha de dar a entender o contrário.
Leituras com limite, por desenho
As leituras devolvem até 100 linhas, com cursor — a API foi construída para integração operacional, não para exportação em massa. Necessidades em massa são uma conversa, não uma brecha.
Ligado com honestidade vale mais do que ligado com alarido.
Cada integração aqui está descrita pelo que faz na realidade — direção, propriedade dos dados e limites incluídos.