Límites y versiones

Límites

Ruta	Límite
PUT /stock, GET /catalog, GET /orders, POST /orders/ack	60 por minuto
PATCH /catalog/mapping, POST /ping	30 por minuto

• Se cuentan por IP de origen. En las respuestas que pasan, X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset dicen cuánto queda. Un 429 trae Retry-After, con los segundos que hay que esperar.
• Lotes de hasta 500 ítems en existencia, cruce y confirmación.

Versiones

• /api/v1 es estable. Solo se agregan cosas: campos nuevos en respuestas, rutas nuevas, eventos nuevos y valores nuevos en enums. Ignora lo que no conozcas.
• Quitar o cambiar el significado de un campo, una ruta o un evento es /api/v2.
• Una ruta que se va a retirar responde con las cabeceras Deprecation y Sunset al menos 6 meses antes, y se anuncia en el changelog.

Seguridad

• Guarda la llave y el secreto del webhook como secretos del servidor; nunca en un navegador o una app móvil.
• Rótalos desde el panel del negocio si sospechas que se filtraron (el anterior deja de valer).
• Verifica la firma de cada webhook y rechaza timestamps de más de 5 minutos (cómo).
• ¿Encontraste una vulnerabilidad? Escribe a seguridad@papedir.com (no abras un issue público).