Conecta tu sistema con la API de Klopi

La API de Klopi deja que otro sistema trabaje con tu negocio en Klopi: tu tienda en línea crea el cliente y le emite la factura electrónica al vender, tu sistema de pedidos registra el pago, tu ERP lee las facturas del mes. Cada sistema entra con su propia API key, que dice qué puede hacer y hasta cuándo.

Casi siempre, quien te pide «una API key» es la persona que desarrolla tu otro sistema. Tú la creas en Klopi, eliges sus permisos y se la pasas por un medio privado. Esa persona encuentra todo lo demás en la documentación.

Antes de empezar

• El adicional Desarrolladores activo, sobre el plan Klopi. Con él aparece Desarrolladores en Configuración → Más ajustes. Si no lo ves, revisa cómo agregar un adicional.
• Ser Propietario o Administrador.
• Saber qué va a hacer la integración: solo leer, crear facturas en borrador, emitirlas, registrar pagos… Así le das solo los permisos que necesita.

Crea una API key

Los permisos

Permiso	Qué deja hacer
Ver contactos / Crear y editar contactos	Leer, crear, actualizar y eliminar clientes y proveedores
Ver productos / Crear y editar productos	Leer, crear, actualizar y desactivar productos y servicios
Ver facturas	Leer facturas y notas, su estado ante la DIAN y descargar el PDF y el XML
Crear borradores de factura	Crear, editar y eliminar borradores, sin enviarlos a la DIAN
Emitir facturas	Enviar facturas y notas a la DIAN y por correo al cliente. Cada emisión gasta un documento de tu plan
Crear notas	Crear borradores de notas crédito y débito
Ver pagos / Registrar pagos	Leer pagos, registrar abonos y crear links de pago
Administrar webhooks	Crear y cambiar los webhooks por código

Administra tus keys

En la lista ves de cada key sus permisos, cuándo vence, cuándo se usó por última vez y desde qué dirección. Desde cada fila puedes:

• Editar el nombre, la descripción, los permisos o el vencimiento. El cambio aplica de inmediato.
• Regenerar: crea un secreto nuevo con los mismos permisos. El anterior deja de funcionar en ese momento; actualiza la integración con el nuevo.
• Revocar: la key deja de funcionar para siempre. Su historial de uso se conserva.

Puedes tener hasta 20 keys activas. Klopi te avisa en la lista cuando una está por vencer.

Revisa el uso

En la pestaña Uso ves cuántas peticiones lleva tu negocio en el mes frente a su cupo, el porcentaje con error, los endpoints más usados y el historial de peticiones. Filtra por estado, método, key o fechas, y abre una petición para ver qué se envió y qué respondió Klopi. Las claves y los secretos nunca aparecen en el historial.

Para quien desarrolla el otro sistema

En Desarrolladores → Documentación → Abrir la documentación está la referencia completa: cada endpoint con sus parámetros y ejemplos en cURL, JavaScript y Python, los errores, la idempotencia, los límites y los webhooks. Desde ahí se puede Copiar en Markdown para dársela a un asistente de inteligencia artificial, o descargar el archivo OpenAPI para Postman o Insomnia.

Lo esencial:

• La URL base es https://api.klopi.co/v1 y la key va en la cabecera Authorization: Bearer klp_live_….
• Cada key actúa sobre los datos reales del negocio: no hay un modo de pruebas aparte.
• Cada key puede hacer 120 peticiones por minuto y 20 por segundo; el negocio tiene además un cupo al mes.
• Registrar un pago exige una cabecera Idempotency-Key, para que un reintento no lo registre dos veces.
• Emitir una factura por la API gasta un documento del plan, igual que desde la app.
• Si una factura se queda en camino o la DIAN la rechaza, la integración puede reintentarla, con las mismas reglas que el botón Reintentar de la app: nunca sale dos veces con el mismo número.
• Una factura emitida no se borra por la API, igual que en la app: se anula con una nota crédito. La documentación lo explica en «Anular o corregir una factura».

Preguntas frecuentes

¿Qué hago si una key se filtró?

Revócala o regénerala de inmediato desde la lista. En Uso puedes revisar qué peticiones se hicieron con ella y desde qué dirección.

¿Quién aparece como autor de lo que crea la integración?

En el historial de cambios de Klopi, lo que se crea o cambia por la API aparece a nombre de la key: «API key Tienda en línea».

¿Mi integración puede anular una factura?

Sí, como lo pide la DIAN: con una nota crédito por el total, que la integración crea y emite sobre la factura. La factura no desaparece; queda anulada, con su número y su nota al lado, y el número no se vuelve a usar. Si tienes un webhook, tu otro sistema recibe el aviso invoice.cancelled.

¿La API sirve si mi cuenta queda en solo lectura?

Sí, para consultar. Mientras la suscripción no se renueve, cualquier intento de crear o cambiar algo responde con un error que lo explica.