Para crear y actualizar negocios en el Kanban mediante programación, utilice la API REST de Papo. Con autenticación por clave secreta (Bearer token) y la clave pública de la cuenta, puede enviar solicitudes que crean tarjetas, mueven oportunidades entre etapas y marcan resultados, integrando el embudo de ventas con sistemas externos sin intervención manual.
La API de Papo expone operaciones de escritura para el Kanban, permitiendo trabajar con embudos, etapas y tarjetas del CRM. Esto permite sincronizar un ERP, una landing page o una herramienta de pago con el embudo de ventas, manteniendo las oportunidades siempre actualizadas.
Resumen de la integración con el Kanban
| Etapa | Acción | Detalle importante |
|---|---|---|
| 1. Obtener las claves | Generar la clave secreta (sk_live_…) y copiar la clave pública (pk_live_…) en el panel de Papo. |
La clave secreta aparece una única vez; guárdela en un lugar seguro. |
| 2. Autenticar las llamadas | Incluir el header Authorization: Bearer sk_live_… en todas las solicitudes de escritura. |
La clave pública puede enviarse en el header X-Papo-Public-Key (opcional). |
| 3. Conocer embudos y etapas | Listar los embudos del Kanban y sus etapas para obtener los identificadores necesarios. | La respuesta de la API trae los identificadores usados en las próximas llamadas. |
| 4. Crear o mover tarjetas | Enviar la operación para crear una tarjeta en una etapa, mover una tarjeta de un contacto a otra etapa o marcar resultado. | Cada operación procesa una acción; para muchos registros, automatice el envío en bucle. |
| 5. Validar la respuesta | La API devuelve success: true y los datos de la tarjeta o del listado. |
En caso de error, el cuerpo de la respuesta trae código y mensaje para corrección. |
Qué permite hacer la API en el Kanban
Con los endpoints del Kanban, puede programáticamente:
- Listar los embudos disponibles y sus etapas, con nombre y posición.
- Listar las tarjetas del CRM.
- Listar todas las tarjetas ganadas, para informes de ventas cerradas.
- Crear una tarjeta en una etapa, opcionalmente vinculada a un contacto existente.
- Mover la tarjeta de un contacto a otra etapa del embudo.
- Marcar tarjetas como ganadas o como perdidas.
- Crear un embudo Kanban con etapas estándar o personalizadas.
Estas operaciones permiten que el embudo refleje automáticamente lo que sucede fuera de Papo, como una compra confirmada, una reunión agendada o un registro proveniente del sitio web.
Cómo funciona la autenticación y las llamadas
Toda llamada que modifica datos exige la clave secreta de la cuenta. Debe enviarse como token Bearer en el header Authorization o, alternativamente, en el header X-Papo-Secret-Key. La clave pública puede acompañar la solicitud en el header X-Papo-Public-Key; su uso es opcional, pero, si se envía, debe corresponder a la misma cuenta de la clave secreta.
La URL base de la API es https://app.papo.global/api/v1. A partir de ella, los endpoints de Kanban aceptan los verbos HTTP adecuados para crear, mover, actualizar y listar. Como la documentación completa detalla los paths, parámetros y campos aceptados, recomendamos consultar la referencia oficial de la API antes de codificar.
Para validar que sus claves están funcionando, puede llamar al endpoint GET /api/v1/me, que devuelve los datos de la cuenta. El patrón de autenticación es el mismo usado en los otros endpoints:
curl https://app.papo.global/api/v1/me \
-H "Authorization: Bearer sk_live_…" \
-H "X-Papo-Public-Key: pk_live_…"
La respuesta exitosa incluye success: true y el objeto data con la información de la cuenta.
Flujo típico de integración con sistemas externos
Un script en Python, Node.js o una automatización en herramientas como n8n puede ejecutar el ciclo completo del embudo:
- Listar los embudos y etapas para obtener los identificadores de cada columna.
- Crear una tarjeta en la etapa inicial, vinculándola a un contacto si es necesario.
- Mover la tarjeta a una nueva etapa cuando ocurra un evento externo — por ejemplo, pago confirmado o reunión agendada.
- Marcar la tarjeta como ganada o perdida cuando la oportunidad se complete.
- Listar las tarjetas ganadas para alimentar informes, dashboards o sistemas de BI.
Como la API es REST y utiliza JSON, cualquier lenguaje con soporte HTTP funciona. Los detalles de payload y campos de cada operación están en la documentación oficial.
Para quién está indicada esta integración
- Empresas que captan oportunidades en sistemas externos, como landing pages, ERPs o e‑commerce, y desean que ingresen automáticamente en el embudo de Papo.
- Operaciones que necesitan mover tarjetas según eventos de pago, como pasarelas o plataformas de cobro, sin abrir el CRM manualmente.
- Equipos de BI y datos que quieren extraer tarjetas ganadas y valores para dashboards en tiempo real.
- Equipos de TI que construyen integraciones personalizadas entre Papo y herramientas internas, usando la API como puente entre el embudo de ventas y el resto de la operación.
Preguntas frecuentes
¿Necesito usar la clave pública en todas las llamadas?
No. La clave pública es opcional, pero, si se envía en el header X-Papo-Public-Key, debe corresponder a la misma cuenta de la clave secreta.
¿Cómo sé qué etapas existen en mi embudo?
Liste los embudos del Kanban a través de la API. La respuesta devuelve las etapas de cada embudo con sus identificadores, usados para crear o mover tarjetas.
¿Puedo crear una tarjeta ya vinculada a un contacto?
Sí. La creación de tarjeta permite vincular opcionalmente a un contacto existente, manteniendo el historial y los datos del cliente asociados a la oportunidad.
¿La API permite actualizar el valor de una tarjeta?
La API expone operaciones de escritura para tarjetas del Kanban. Los campos exactos que pueden actualizarse, incluidos valores, están detallados en la documentación oficial de la API.
¿Es posible marcar una tarjeta como ganada o perdida a través de la API?
Sí. La API permite marcar tarjetas como ganadas y como perdidas, además de listar todas las tarjetas ganadas para informes y dashboards.
¿Necesito programar o puedo usar herramientas de automatización?
Puede usar cualquier lenguaje con soporte HTTP o herramientas de automatización como n8n, ejecutando las llamadas en secuencia según el flujo deseado.
Lea también
- Cómo usar la API de Papo para crear y actualizar contactos en masa
- Cómo recibir eventos en tiempo real de Papo vía Webhook (outbound)
El primer usuario es gratuito y no requiere tarjeta de crédito.