ConnectWiz + API y webhooks
Integración activaLa API que vendemos es la API que usamos
Toda la plataforma está especificada en un único contrato OpenAPI del que se generan nuestro propio panel y nuestra app móvil: sin endpoints en la sombra y sin documentación que se desvía. Encima de él: claves de la Commerce API con permisos acotados, disparadores de webhook protegidos y flujos que llaman a sus sistemas.
Desarrolladores
Qué hace, exactamente
Un único contrato de referencia
Un solo documento OpenAPI 3 especifica la plataforma y nuestros propios clientes de TypeScript se generan a partir de él: la documentación no puede desviarse de la realidad porque la realidad se construye desde la documentación.
Claves de la Commerce API
Claves emitidas por el inquilino con permisos explícitos (lectura de catálogo, lectura de pedidos, escritura de pedidos) que mueven su propia tienda o su propia app sobre el mismo motor de pedidos, con los precios siempre resueltos en el servidor.
Webhooks entrantes, protegidos
Cada disparador de webhook de un flujo tiene su propia URL y su propio secreto, verificación HMAC sobre el cuerpo en crudo y protección contra reenvíos. Un payload puede nombrar a una persona; jamás puede dirigir el funcionamiento interno del flujo.
Salida a través de los flujos
El paso REST llama a sus sistemas exactamente en los momentos que usted dibuja en el lienzo: pedido realizado, consentimiento concedido, reserva hecha.
Por dentro
Nuestras posturas de diseño de API, dichas en claro
Los precios nunca vienen del cliente
Una petición de pedido dice qué y cuántos: el nombre y el precio se leen del catálogo en ese momento, en el servidor, y se escriben en la línea como una instantánea. Una petición manipulada no puede inventarse un descuento.
Capacidades antes que llamadas
Cada superficie de integración publica un contrato de capacidades (¿sabe identificar por teléfono?, ¿listar pedidos de invitados?, ¿crear pedidos?) y llamar más allá de un «no» declarado lanza un error de inmediato, en lugar de fallar en algún punto profundo.
Errores que significan algo
El transporte distingue «no autorizado» de «servicio caído», así que «la tienda no responde» no se muestra nunca como «este cliente no ha comprado nada». Los errores con nombre son la diferencia entre una API y un juego de adivinanzas.
Webhooks a prueba de reenvíos
Cada evento entrante reclama una clave única en un registro de idempotencia antes de procesarse: una entrega reintentada o reenviada muere en la capa de base de datos, no dentro de su automatización.
Claves con hash, secretos acotados
Las claves de API se guardan como hashes y en la puerta solo se pueden resolver el hash y los permisos: una fila filtrada de la base de datos no nombra ningún espacio de trabajo ni abre nada más allá de sus permisos.
Los borradores y las confirmaciones son explícitos
Crear un pedido exige un parámetro de confirmación explícito (la API pública confirma por defecto y los flujos del panel pueden dejar borradores), así que «¿esto es real?» es un campo, no una convención.
Configuración
Cómo se conecta
Emita una clave
Cree en el panel una clave de la Commerce API con permisos acotados; revocarla cuesta lo mismo.
Conecte un webhook
Cree un flujo con disparador por webhook y firme las peticiones con su secreto.
Devuelva la llamada
Añada pasos REST allí donde sus sistemas necesiten enterarse.
Mejor en conjunto
Con qué se combina
Flujos
Los disparadores por webhook arrancan flujos; los pasos REST devuelven la llamada a sus sistemas en los momentos que usted dibuja: la automatización de entrada y la de salida comparten un mismo lienzo.
Comercio
El catálogo y el motor de pedidos que hay detrás de la API son los mismos que usan la tienda del chat y la IA: una sola verdad de pedido, cuatro puertas.
Su propia tienda
Hoy hay equipos con tiendas headless funcionando sobre la Commerce API: es el camino que la página de Shopify recomienda, sin adornos, mientras se construye el conector nativo.
Seguridad y garantías
Las garantías aburridas
HMAC sobre el cuerpo en crudo
La verificación del webhook firma el cuerpo en crudo de la petición con un secreto propio de cada disparador y compara en tiempo constante: solo se interpreta el contenido después de la prueba.
Los payloads son datos, nunca órdenes
El payload de un webhook puede referirse a una persona; jamás puede dirigir el funcionamiento interno de un flujo, reescribir prompts ni invocar herramientas. La frontera entre datos e instrucciones es de arquitectura, no de comportamiento.
Límites de frecuencia en todas las puertas
Los endpoints públicos van con la limitación estándar y los topes de lectura se recortan en el servidor: un cliente que se porta mal se degrada a sí mismo, no a la plataforma.
La letra pequeña, sin adornos
Los límites, por escrito
Todavía sin canal de eventos masivo
No existe un flujo de webhooks genérico al que suscribirse para todo: hoy los eventos de salida se emiten desde los pasos de un flujo. Lo decimos aquí para que ninguna llamada comercial tenga que insinuar otra cosa.
Lecturas acotadas, por diseño
Las lecturas devuelven hasta 100 filas con cursor: la API está hecha para integración operativa, no para exportaciones masivas. Una necesidad de volumen se habla, no se cuela por un resquicio.
Preguntas frecuentes sobre la API y los webhooks
Respuestas directas
Encontrará más en las Preguntas frecuentes, o pregúntenos directamente.
Conectar con honestidad vale más que conectar con ruido.
Cada integración de esta página se describe por lo que realmente hace: dirección, propiedad de los datos y límites incluidos.