API de Posdata

Para qué sirve

La API pública te deja leer y escribir los datos de tu cuenta de Posdata desde tus propios sistemas:

Tu ERP o tu contabilidad

Lee ventas, documentos electrónicos, turnos de caja y reportes diarios para llevarlos a tu sistema.

Tu tienda en línea

Crea y edita productos (nombre, precios, categoría) y clientes desde tu sistema, y registra entradas y salidas de inventario.

Tu BI

Sincroniza de forma incremental con updated_since y cruza los datos con los de tus otras fuentes.

n8n, Zapier o Make

Reacciona a eventos (una venta completada, una factura emitida, un cierre de caja) con webhooks firmados.

Requisito: plan Pro

La API pública y los webhooks están incluidos en el plan Pro. Las API keys se crean en cuenta.posdata.so → Desarrolladores.

Si la cuenta deja de tener Pro, las keys no se borran: quedan en pausa (cada llamada responde 403 PLAN_REQUIRED) y vuelven a funcionar cuando la cuenta recupere el plan. Mira Autenticación.

Entornos

Entorno	URL base	Prefijo de la key
Producción	https://api.posdata.so/public/v1	pdk_live_
Pruebas	https://apidev.posdata.so/public/v1	pdk_test_

El entorno de pruebas usa datos de prueba y puede reiniciarse sin aviso: no guardes ahí nada que necesites conservar. Una key de un entorno no funciona en el otro; la API te lo dice con el error API_KEY_WRONG_ENVIRONMENT.

Qué necesitas saber antes de integrar

• Es servidor a servidor. La key nunca va en un navegador ni en una app: una petición con el header Origin se rechaza.
• La API ve lo que las cajas ya sincronizaron. Si una caja trabaja sin internet, sus ventas aparecen cuando se reconecta. GET /me te dice cuándo se sincronizó cada caja. Lee Cómo se sincroniza con las cajas antes de construir reportes.
• Montos en pesos colombianos enteros (sin decimales) y tarifas de impuesto en porcentaje entero (19 = 19 %). Fechas en ISO 8601 (UTC).
• Todo POST lleva Idempotency-Key, para que un reintento nunca cree algo dos veces.
• Todavía no publicamos el stock: el campo stock de los productos es null por ahora. El inventario se mueve con movimientos; mira por qué.

La API pública no es Agent Connect

Posdata tiene dos formas distintas de conectarse con software externo:

• API pública (esta documentación): para tus sistemas. Se autentica con una API key de cuenta, trabaja sobre la nube de Posdata y no necesita ninguna caja encendida. Requiere plan Pro.
• Agent Connect: para que un agente de IA (Claude, ChatGPT, Cursor…) opere Posdata en nombre de una persona, con sus mismos permisos. Está disponible en todos los planes, también en el gratuito. Conoce más en posdata.so.

Las credenciales no se mezclan: un token de agente no sirve en la API pública y una API key no sirve para Agent Connect.

Inicio rápidoTu primera llamada en cinco minutos.

WebhooksEventos firmados y cómo verificarlos.