Conectar tu POS

Hay dos formas de usar papedir con un punto de venta. Elige una antes de programar nada.

Camino	Cuándo	Qué haces
Usar el POS de papedir	Quieres un solo sistema	Nada que integrar: mostrador, domicilio y mesa, caja por turno, reportes e inventario ya vienen en papedir
Conectar tu POS	Tu POS sigue siendo el sistema del negocio	Tu POS manda la existencia y recibe los pedidos de papedir (esta guía)

Cuando conectas tu POS, los dos flujos van en sentidos contrarios:

Tu POS ──PUT /stock (existencia absoluta)──▶ papedir
Tu POS ◀── webhook order.created ──────────── papedir

Qué puedes hacer hoy

• Sí: mandar la existencia, leer el catálogo, cruzar productos por SKU y recibir cada pedido por webhook firmado o por el feed GET /orders.
• Todavía no: crear o editar productos, crear pedidos en papedir desde tu POS, ni el modo bidireccional. Los eventos de pedido tampoco traen datos personales del cliente.
• Las ventas de mostrador de tu POS llegan a papedir solo como cambio de existencia.

Pasos

1. Activa el módulo. Pide al equipo de papedir el módulo «Inventario externo». Después verás Ajustes → Integraciones en tu panel.
2. Crea una llave en Llaves de API, con los scopes que vas a usar (stock:write, catalog:read, orders:read). Se muestra una sola vez. Verifícala con POST /ping (Primeros pasos).
3. Prueba el webhook con webhook.site. Copia tu URL https://webhook.site/…, pégala en Webhook, activa «Integración activa» y genera el secreto de firma. Crea un pedido de prueba en el POS de papedir: en unos 5 segundos verás el POST en webhook.site y el aviso como entregado en Entregas.
4. Monta tu receptor. Verifica la firma sobre el cuerpo crudo, deduplica por id, guarda el evento y responde 2xx en menos de 10 s (código en Webhooks). Para probar desde tu computador necesitas un túnel con URL https pública (por ejemplo cloudflared tunnel --url http://localhost:3000): papedir no llama a localhost ni a redes privadas.
5. Cruza el catálogo por SKU con GET /catalog y PATCH /catalog/mapping.
6. Manda la existencia con PUT /stock: completa la primera vez, luego solo lo que cambia. Detalle en Inventario externo.

Regla de oro: responde 2xx al order.created (o haz ack) antes de mandar la existencia que ya incluye esa venta; si no, papedir la resta dos veces hasta tu siguiente envío.

Si algo falla

Empieza por Entregas en el panel: cada aviso muestra su estado, intentos y la respuesta de tu servidor.

Qué ves	Qué hacer
No aparece nada en Entregas	Activa la integración, guarda la URL y genera el secreto
No deja guardar la URL	Debe ser https, pública y sin usuario ni clave
Aviso fallido con 301 o 302	papedir no sigue redirecciones: usa la URL final
Aviso fallido con 401	La firma no coincide: usa el cuerpo crudo y el secreto vigente
Aviso fallido por tiempo agotado	Responde 2xx de inmediato y procesa después
Aviso en dead (8 intentos)	Corrige el receptor y usa «Reenviar» en Entregas

Los códigos de la API están en Errores; incluye el request_id si pides ayuda.