> ## Documentation Index
> Fetch the complete documentation index at: https://developers.papelship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Descripción general de la User API

> Cree pedidos, sincronice su catálogo, envíe productos físicos y reaccione a eventos desde sus propios sistemas.

> [!NOTE]
>
> Para cobrar estos pedidos con tarjeta en su propio sitio, consulte [PapelPay](https://developers.papelship.com/es/papelpay/overview.md).

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`

> [!NOTE]
>
> 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:

```bash theme={"system"}
curl https://app.papelship.com/api/v1/me \
  -H "x-api-key: pk_live_your_key" \
  -H "x-store-hash: your_store_id"
```

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

> [!WARNING]
>
> 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.

| Área | Permiso | Cubre |
| :- | :- | :- |
| Pedidos | `orders` | `/invoices` |
| Productos | `products` | `/products` y todo lo que contiene |
| Categorías y grupos | `catalog` | `/categories`, `/groups` |
| Cupones | `coupons` | `/coupons` |
| Clientes y lista de bloqueo | `customers` | `/customers`, `/blacklist` |
| Envíos y gestión de pedidos | `fulfillment` | `/orders`, `/returns`, `/shipping` |
| Reseñas | `reviews` | `/reviews` |
| Preguntas sobre productos | `questions` | `/questions` |
| Tickets de soporte | `support` | `/tickets` |
| Suscripciones | `subscriptions` | `/subscriptions` |
| Afiliados | `affiliates` | `/affiliates` |
| Webhooks | `webhooks` | `/webhooks`, `/events` |
| Analíticas | `analytics` | `/analytics` (solo lectura) |
| Tienda | `store` | `/store`, `/payment-methods` (solo 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`.

```json Éxito theme={"system"}
{ "success": true, "invoice": { "id": "c35ffd-19a1b2c3d4e-8c7a20", "status": "pending" } }
```

```json Error theme={"system"}
{
  "success": false,
  "code": "VALIDATION_FAILED",
  "error": "customer_email must be a valid email address",
  "details": { "field": "customer_email" },
  "request_id": "req_7YbK2mQ9xP1cRt4v"
}
```

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](https://developers.papelship.com/es/user-api/errors.md) 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`:

```bash theme={"system"}
curl "https://app.papelship.com/api/v1/invoices?status=completed&limit=50&offset=100" \
  -H "x-api-key: pk_live_your_key" \
  -H "x-store-hash: your_store_id"
```

```json theme={"system"}
{
  "success": true,
  "invoices": [ ... ],
  "pagination": { "total": 342, "limit": 50, "offset": 100, "has_more": true }
}
```

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.

```bash theme={"system"}
curl -X POST https://app.papelship.com/api/v1/invoices \
  -H "x-api-key: pk_live_your_key" \
  -H "x-store-hash: your_store_id" \
  -H "Idempotency-Key: 6f1c8a52-4f0e-4b8e-9a7c-2d1b3e5f7a90" \
  -H "Content-Type: application/json" \
  -d '{ "customer_email": "buyer@example.com", "items": [{ "product_id": "a1B2c3D4e5F6" }] }'
```

* 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

| Límite | Valor | Encabezados |
| :- | :- | :- |
| Solicitudes por clave | 300 por minuto | `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (tiempo Unix) |
| Llamadas mensuales | Depende de su plan | `X-Quota-Limit` |

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

> [card] [Crear pedidos](https://developers.papelship.com/es/user-api/orders.md)
>
> Reciba pedidos desde su propio sitio o aplicación y envíe a los clientes al checkout.

> [card] [Webhooks](https://developers.papelship.com/es/user-api/webhooks.md)
>
> Reciba notificaciones cuando los pedidos se paguen, se cancelen o se reembolsen.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.