Integraciones: API y webhooks
Qué son las claves de API y los webhooks, para qué sirven y cómo se crean, prueban y revisan desde el panel y la app.
Revisado el 28 de octubre de 2026
Para qué sirve
Las integraciones conectan AtiendeFácil con otro sistema tuyo: la tienda online, el programa de facturación, una hoja de cálculo o una app hecha a tu medida. Son dos piezas, y se pueden usar por separado o juntas:
| Qué hace | Ejemplo | |
|---|---|---|
| Clave de API | Deja que tu sistema consulte tus pedidos, clientes, chats, citas, pagos y viajes; cambie el estado de un pedido y le asigne repartidor; apruebe pagos o registre cobros; edite los datos de un cliente; tome un chat o se lo devuelva al bot; mantenga tu catálogo y tu tasa al día, y le escriba a un cliente. | Tu tienda online marca el pedido como «En camino» y al cliente le llega el aviso por WhatsApp. |
| Webhook | AtiendeFácil avisa a tu sistema, al instante, cada vez que pasa algo. | Entra un pedido por WhatsApp y aparece solo en tu programa de facturación. |
Para usarlas hace falta alguien que programe la otra parte. Esta página explica lo que haces tú en el panel; lo técnico empieza en Empezar con la API y sigue en Webhooks, que es lo que le pasas a tu programador.
Panel web
App
Hace falta permiso para editar Ajustes. Quien solo puede verlos entra, pero no puede crear, cambiar ni probar nada.
Qué puedes conectar
| Si tienes… | La integración puede… | Para tu programador |
|---|---|---|
| Un inventario, una tienda online o un punto de venta | Mandar tu catálogo cada cierto tiempo, entero o solo lo que cambió: productos nuevos, precios, códigos de barras, existencias y agotados. La IA vende siempre con lo último, sin que nadie lo copie a mano, y cada línea de un pedido dice qué producto de tu sistema era. | Catálogo |
| Una caja o una tienda online que cobra | Registrar los cobros que entran por fuera del chat (efectivo, punto de venta, pago en la web), aprobar o rechazar comprobantes y reportar lo que entra al banco. El pedido se confirma solo y al cliente le llega el aviso. | Pedidos y pagos |
| Tu propia tasa de cambio | Fijar la tasa manual del negocio (o volver a la del BCV) para que el bot cotice con la misma que usas en caja. | Tasa de cambio |
| Un programa de facturación o contabilidad | Recibir cada pedido, pago o cita en cuanto pasa, sin que nadie lo transcriba. | Webhooks |
| Un sistema de seguimiento o de reparto | Mandar los pedidos en camino con el repartidor que toca, ponerle el costo al envío cuando lo cotizas tú, y escribirle al cliente que ya te escribió. | Pedidos y pagos |
| Un CRM o un equipo de atención | Enterarse al momento de que un chat necesita a una persona, ver el historial, tomar la conversación y devolvérsela al bot, y mantener al día los datos y las notas de cada cliente. | Clientes, conversaciones y mensajes |
| Un sistema de alertas (o alguien que vigile el negocio) | Avisar en cuanto se desconecta el WhatsApp, se pausa el bot, queda un pago por revisar o baja el saldo, para que nada se quede parado sin que te enteres. | Webhooks |
Todo lo que hace la integración pasa por las mismas reglas que el panel: un pago que aprueba confirma el pedido y le avisa al cliente, igual que si lo aprobaras tú, y queda firmado con el nombre de la clave («API · Tienda online»).
Claves de API
Pulsa Crear clave y ponle un nombre
El nombre es para ti, para reconocerla después: «Tienda online», «Contabilidad». Puedes tener hasta 10 claves activas.
Elige qué puede hacer
Acceso completo: Consulta y también actúa: crea pedidos, aprueba pagos, le escribe a los clientes y cambia el catálogo. Solo lectura: Solo consulta. No puede crear, cambiar ni borrar nada, ni escribirle a nadie. Para reportes y contabilidad. Dale a cada sistema lo justo: al de reportes le basta con leer. En el panel se elige en el mismo diálogo que el nombre; en la app, justo antes. El permiso no se cambia después: si hace falta otro, crea otra clave y revoca la anterior.
Cópiala y entrégasela a tu programador
La clave empieza por af_live_ y se enseña una sola vez. Después, en la lista solo se ven sus primeros caracteres. Si la pierdes, crea otra.
En la lista ves quién creó cada clave, cuándo, la última vez que se usó y, si es de solo lectura, la etiqueta Solo lectura. Una clave que lleva meses sin usarse probablemente sobra.
Webhooks
Pulsa Añadir webhook
Pega la dirección que te dio tu programador. Tiene que empezar por https:// y ser un dominio público. Puedes tener hasta 5 webhooks.
Elige de qué quieres que te avise
Los eventos van por grupos. Arriba salen los que tienen que ver con tu tipo de negocio; los demás, debajo. Marca solo lo que tu sistema vaya a usar.
Si tu programador te dio una clave para su servidor, ponla en Clave de acceso
Es opcional: solo hace falta si su servidor rechaza lo que llega sin esa clave. Está explicada más abajo, en «Clave de acceso».
Pulsa Probar
Se manda un aviso de prueba y ves al momento si tu sistema lo recibió. Si falla, debajo sale el motivo (por ejemplo, «No respondió en 10 segundos»).
Pásale el secreto de firma a tu programador
Con él su sistema comprueba que el aviso lo mandó AtiendeFácil y no otra persona. Se ve con Mostrar. Si se filtra, pulsa Cambiar secreto: el anterior deja de valer en el momento, así que avísale antes a tu programador.
Clave de acceso
Algunos servidores no dejan pasar nada que no traiga su propia clave. Para esos, cada webhook puede llevar una clave de acceso: AtiendeFácil la manda en cada aviso, en una cabecera fija. Se configura en la sección Clave de acceso al crear o editar el webhook, igual en el panel y en la app.
- Pega la clave que te dio tu programador. La cabecera en la que viaja es
x-api-key; cámbiala solo si él te dice otra. - Una vez guardada no se vuelve a mostrar: solo ves en qué cabecera viaja. Con Reemplazar pones otra y con Quitar el webhook deja de mandarla.
- No es lo mismo que el secreto de firma ni lo sustituye: la clave de acceso es de su servidor y sirve para que deje entrar el aviso; el secreto de firma es de AtiendeFácil y sirve para comprobar que el aviso es auténtico. Tu programador tiene que seguir verificando la firma.
Los avisos que hay
| Grupo | Aviso | Cuándo sale |
|---|---|---|
| Pedidos | Pedido nuevo | Un pedido deja de ser carrito: el cliente lo confirmó o se creó desde el panel. |
| Pedido cambió de estado | Pasó a confirmado, preparando, en camino, entregado, cancelado… | |
| Envío por cotizar | Un pedido espera que le pongan el costo del delivery para poder cobrarlo. | |
| Repartidor asignado | Se le asignó (o cambió) el repartidor a un pedido. | |
| Pagos | Pago recibido | Llegó un comprobante o se registró un cobro. |
| Pago aprobado o rechazado | Un pago se aprobó, se rechazó o pasó a revisión. | |
| Pago por revisar | Llegó un comprobante que nadie va a confirmar solo (sin banco conectado o el monto no cuadra): hay que aprobarlo o rechazarlo. | |
| Citas | Cita nueva | Se agendó una cita. |
| Cita cambió de estado | Confirmada, completada, cancelada o el cliente no vino. | |
| Cita reprogramada | Cambió la hora, la duración, el servicio o quién atiende. | |
| Cita borrada | La cita se eliminó. | |
| Clientes | Cliente nuevo | Escribió por primera vez o se creó a mano. |
| Cliente actualizado | Cambió su nombre, teléfono, documento, dirección, notas o si pidió que el bot no le responda. Trae qué cambió. | |
| Cliente borrado | Se borró un cliente (y con él sus pedidos y citas). | |
| Consultar un cliente en tu sistema | Es una consulta, no un aviso: cuando escribe alguien que todavía no está identificado, se le pregunta a tu sistema si lo conoce. Si responde con su nombre y su cédula, quedan en su ficha y el asistente no se los pide. | |
| Mensajes | Mensaje de un cliente | Cada mensaje que un cliente escribe por WhatsApp. |
| Mensaje enviado a un cliente | Cada mensaje que sale del negocio hacia un cliente y queda en su chat: del asistente, de una persona del equipo o de tu integración. Trae quién lo mandó. | |
| Viajes | Viaje nuevo | Se pidió un viaje. |
| Viaje cambió de estado | Aceptado, en camino, en curso, completado o cancelado. | |
| Viaje sin conductor | No quedó ningún conductor a quien ofrecerle el viaje (al pedirlo o después de que lo rechazaran): hay que asignarlo a mano. | |
| Catálogo | Producto nuevo | Se añadió un producto o servicio al catálogo (o se restauró uno borrado). |
| Producto editado | Cambió el nombre, el precio, el stock, el código de barras, la disponibilidad u otro dato. Incluye el stock que baja con cada venta. | |
| Producto borrado | Se quitó un producto o servicio del catálogo. | |
| Tasa de cambio | Tasa cambió | Cambió la tasa manual del negocio o pasó de tasa BCV a manual (o al revés). |
| Conversaciones | Un chat necesita a una persona | El cliente pidió hablar con alguien o el bot no pudo seguir. Trae el motivo. |
| Chat tomado a mano | Alguien del equipo tomó la conversación (desde el teléfono del negocio o por la API); el bot se calla ahí hasta que se la devuelvan. | |
| Chat devuelto al bot | La conversación que atendía una persona vuelve a atenderla el bot. | |
| Cuenta y WhatsApp | Bot pausado | El asistente dejó de responder: lo pausó el dueño o el sistema por riesgo para el número. |
| Bot reanudado | El asistente vuelve a responder. | |
| WhatsApp desconectado | Se cerró la sesión de WhatsApp: hay que volver a vincular el número. No avisa de las reconexiones de rutina. | |
| WhatsApp vinculado | El número volvió a quedar vinculado después de cerrarse la sesión (o se vinculó uno nuevo). | |
| Saldo bajo | Al negocio le queda poco saldo de tokens: si se acaba, el asistente deja de responder. |
En total son 32 avisos.
Los de Conversaciones y Cuenta y WhatsApp son los mismos avisos que te llegan a ti por WhatsApp o en la app: con ellos, tu CRM sabe al momento qué chat necesita a alguien, y tu sistema de alertas puede avisar a otra persona si se desconecta el WhatsApp o se está acabando el saldo.
Consultar un cliente en tu sistema funciona al revés que los demás: no te avisa de algo, le pregunta a tu sistema. Si ya tienes a tus clientes en otro programa (el de facturación, el punto de venta), márcalo y, cuando escriba alguien a quien le falta el nombre o la cédula, AtiendeFácil le pregunta a tu sistema por ese teléfono antes de contestar. Si lo conoce, sus datos quedan en la ficha y el asistente no se los pide. Si tu sistema no contesta en 4 segundos, el asistente sigue y los pide como siempre. Tu programador tiene que preparar la respuesta: está explicado en Webhooks.
Historial de envíos
En Historial de envíos está cada aviso de los últimos 30 días: si se entregó, cuántas veces se intentó y qué respondió tu sistema. Al abrir uno ves el contenido exacto que se mandó y puedes pulsar Reenviar.
| Estado | Qué significa |
|---|---|
| Entregado | Tu sistema lo recibió y respondió bien. |
| Reintentando | Tu sistema no respondió bien; se vuelve a intentar solo, esperando cada vez un poco más. |
| Falló | Se agotaron los intentos. Arregla el problema y pulsa Reenviar. |
Si se apaga solo
Si 10 avisos seguidos fallan del todo, el webhook se apaga solo y lo verás marcado con el motivo. Casi siempre es que el sistema del otro lado está caído o cambió de dirección. Cuando esté arreglado, vuelve a encenderlo con el interruptor.
Preguntas frecuentes
¿Puedo mandar mensajes masivos con la API?
No. Por la API solo se le puede escribir a un cliente que ya le escribió a tu negocio. Escribirle en frío a números que nunca escribieron es lo que hace que WhatsApp bloquee un número. Para difusión usa Mensajes programados.
¿Lo que hace la API queda registrado?
Sí. Los cambios hechos con una clave (por ejemplo, cambiar un pedido de estado) aparecen en la auditoría a nombre de la clave: «API · Tienda online».
¿Cambiar un pedido por la API hace lo mismo que el botón del panel?
Sí. Le llega el aviso al cliente, se imprime la comanda si toca y se ve en el panel y en la app al momento, igual que si lo hubieras hecho tú.
¿Cuesta saldo?
No. Consultar, cambiar pedidos y recibir webhooks no gasta tokens.