# 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.

## Explora la documentación

[Inicio rápido](https://developers.posdata.so/inicio-rapido/)

[Crea tu API key y haz tu primera llamada en cinco minutos.](https://developers.posdata.so/inicio-rapido/)

[Autenticación](https://developers.posdata.so/autenticacion/)

[API keys de cuenta, permisos por recurso y entornos.](https://developers.posdata.so/autenticacion/)

[Cómo funciona el stock](https://developers.posdata.so/stock/)

[Niveles por bodega, conteos, salidas atómicas y el margen de la API.](https://developers.posdata.so/stock/)

[Webhooks](https://developers.posdata.so/webhooks/)

[Eventos firmados, cómo verificarlos y cómo reconciliar.](https://developers.posdata.so/webhooks/)

[Errores](https://developers.posdata.so/errores/)

[Cada código, qué significa y qué hacer. Ramifica por code.](https://developers.posdata.so/errores/)

[Idempotencia](https://developers.posdata.so/idempotencia/)

[Reintenta cualquier POST sin crear nada dos veces.](https://developers.posdata.so/idempotencia/)

[Paginación y filtros](https://developers.posdata.so/paginacion/)

[Cursores y sincronización incremental con updated_since.](https://developers.posdata.so/paginacion/)

[Referencia de la API](https://developers.posdata.so/referencia/)

[Todos los endpoints, parámetros, respuestas y ejemplos.](https://developers.posdata.so/referencia/)

[Cómo se sincroniza](https://developers.posdata.so/sincronizacion/)

[Qué ve la API de las cajas y los límites de la versión 1.](https://developers.posdata.so/sincronizacion/)

[Límites de uso](https://developers.posdata.so/limites/)

[Peticiones por minuto y cómo reaccionar a un 429.](https://developers.posdata.so/limites/)

[Postman e Insomnia](https://developers.posdata.so/herramientas/#postman-e-insomnia)

[La colección con todos los endpoints y los ambientes, lista para importar.](https://developers.posdata.so/herramientas/#postman-e-insomnia)

[Automatizaciones](https://developers.posdata.so/herramientas/#automatizaciones-n8n-make-y-zapier)

[n8n, Make o Zapier con sus pasos de HTTP y webhooks.](https://developers.posdata.so/herramientas/#automatizaciones-n8n-make-y-zapier)

## 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.

![n8n](/_astro/n8n-dark.CCzz8wK1.svg)![n8n](/_astro/n8n-white.l9RfABmg.svg)

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

Make

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

![Zapier](/_astro/zapier-earth.DWXVz0OG.svg)![Zapier](/_astro/zapier-all-frost.CmtTuJRK.svg)

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](https://developers.posdata.so/herramientas/#automatizaciones-n8n-make-y-zapier)). 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](https://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](https://developers.posdata.so/autenticacion/#si-la-cuenta-baja-de-plan).

## 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](https://developers.posdata.so/sincronizacion/) 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](https://developers.posdata.so/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](https://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.

---

Fuente: https://developers.posdata.so/ · Índice para agentes: https://developers.posdata.so/llms.txt