Saltar al contenido principal
Para cobrar estos pedidos con tarjeta en su propio sitio, consulte PapelPay.
La User API (llamada Store API en su panel) da a sus servidores el mismo control que tiene en el panel de la tienda: pedidos, productos, inventario, clientes, soporte, envíos y webhooks. URL base: https://app.papelship.com/api/v1
Las integraciones antiguas que llaman a https://app.papelship.com/api_user/api/v1 siguen funcionando. Use /api/v1 para el código nuevo.

Autentíquese

Cree una clave en Desarrolladores › Claves de API y envíela junto con el ID de su tienda en cada solicitud:
GET /me funciona con cualquier clave válida. Devuelve la tienda, los permisos de la clave y sus límites, así que úselo para probar su configuración.
Las claves actúan como el propietario de la tienda. Manténgalas en su servidor, nunca en código de navegador o móvil.

Permisos

Al crear una clave, elija Acceso total, Solo lectura o Personalizado. Con Personalizado, elige acceso de lectura o escritura por área. La escritura incluye la lectura. Las solicitudes GET requieren acceso de lectura; POST, PATCH, PUT y DELETE requieren acceso de escritura. Una clave sin el permiso adecuado recibe 403 INSUFFICIENT_SCOPE con el permiso faltante en required_scope. También puede limitar una clave a esta tienda, a una lista de direcciones IP o a una fecha de caducidad.

Respuestas

Cada respuesta es JSON con un indicador success.
Éxito
Error
Base su lógica en code, no en el mensaje. Cada respuesta tiene un encabezado X-Request-Id; inclúyalo cuando contacte con soporte. Consulte Errores para ver todos los códigos.

Convenciones

  • Importes: son enteros en unidades menores: price_cents: 2999 equivale a 29.99.
  • Fechas: están en ISO 8601 y en UTC.
  • ID: son ID públicos: hash IDs de productos, ID de pedidos como c35ffd-19a1b2c3d4e-8c7a20. Los registros de otras tiendas devuelven 404.
  • Registros creados: devuelven 201.

Paginación

Las listas aceptan limit (1 a 100, 25 por defecto) y offset, y devuelven un objeto pagination:
Las listas de afiliados usan un cursor en su lugar: devuelva next_cursor como cursor.

Reintentos seguros

Envíe un encabezado Idempotency-Key en las llamadas de creación (pedidos, reembolsos, envíos, productos, webhooks y otras marcadas en la referencia). Si la red falla, reintente con la misma clave y el mismo cuerpo: recibirá el primer resultado en lugar de un duplicado.
  • Las claves se conservan durante 24 horas.
  • Una respuesta repetida incluye el encabezado Idempotent-Replayed: true.
  • La misma clave con un cuerpo distinto devuelve 422 IDEMPOTENCY_KEY_REUSED.

Límites

Si supera un límite, recibe 429 con Retry-After. RATE_LIMITED se libera en menos de un minuto; STORE_API_MONTHLY_QUOTA_EXCEEDED se restablece el primer día del mes siguiente (UTC). Cada solicitud aparece en Desarrolladores › Solicitudes de API con su estado y duración.

Próximos pasos

Crear pedidos

Reciba pedidos desde su propio sitio o aplicación y envíe a los clientes al checkout.

Webhooks

Reciba notificaciones cuando los pedidos se paguen, se cancelen o se reembolsen.