API pública · REST + webhooks · Plan Pro

Conecta tus sistemas con Posdata

Una API REST servidor a servidor y webhooks firmados para llevar ventas, productos, clientes y stock entre el POS de tu negocio y tu ERP, tu tienda en línea, tu BI o tus automatizaciones. Funciona 24/7, aunque ninguna caja esté encendida.

Empieza en 5 minutos Referencia de la API

Inicio rápido

Crea tu API key y haz tu primera llamada en cinco minutos.

Autenticación

API keys de cuenta, permisos por recurso y entornos.

Cómo funciona el stock

Niveles por bodega, conteos, salidas atómicas y el margen de la API.

Webhooks

Eventos firmados, cómo verificarlos y cómo reconciliar.

Errores

Cada código, qué significa y qué hacer. Ramifica por code.

Idempotencia

Reintenta cualquier POST sin crear nada dos veces.

Paginación y filtros

Cursores y sincronización incremental con updated_since.

Referencia de la API

Todos los endpoints, parámetros, respuestas y ejemplos.

Cómo se sincroniza

Qué ve la API de las cajas y los límites de la versión 1.

Límites de uso

Peticiones por minuto y cómo reaccionar a un 429.

Postman e Insomnia

La colección con todos los endpoints y los ambientes, lista para importar.

Automatizaciones

n8n, Make o Zapier con sus pasos de HTTP y webhooks.

Se conecta con tus automatizaciones

La API y los webhooks son HTTP estándar: cualquier plataforma que haga peticiones HTTP o reciba webhooks puede usarlos, sin instalar nada.

Llama a la API con el nodo HTTP Request y recibe los webhooks con el nodo Webhook.

Llama a la API con el módulo HTTP y recibe los webhooks con un webhook personalizado.

Llama a la API y recibe los webhooks con Webhooks by Zapier.

Hoy no hay una app oficial de Posdata en n8n, Make ni Zapier: la conexión usa sus pasos genéricos de HTTP y webhooks (cómo configurarlos). Las marcas pertenecen a sus dueños; su mención no implica respaldo.

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 y clientes desde tu sistema, consulta el stock disponible por bodega y registra salidas que nunca comprometen más de lo disponible.

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 (con o sin facturación electrónica). 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.
El stock se lleva por bodega en la nube cuando todas las cajas del negocio tienen la versión de Posdata que lo soporta; mientras tanto, stock es null. Las ventas en las cajas nunca se rechazan, así que la API reserva un margen para ellas. Lee Cómo funciona el stock.

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 (con o sin facturación electrónica).
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.