# Wendoshop Developers: documentación completa > Documentación oficial de la API pública y el servidor MCP de Wendoshop. Este documento reúne las guías publicadas para consumo de asistentes de IA. La fuente definitiva de operaciones HTTP y esquemas sigue siendo el [contrato OpenAPI remoto](https://app.wendoshop.com/api/openapi). La fuente definitiva de servicio, OAuth, scopes, perfiles, herramientas y schemas MCP es el [catálogo MCP remoto](https://mcp.wendoshop.com/api/mcp/documentation). No se incluye una copia local de ninguna de las dos fuentes. Reglas críticas: cada credencial pertenece al contexto autorizado de una tienda; nunca se deben exponer tokens; y no se debe inferir información que no esté publicada. ## Introducción Fuente: https://docs-api-3ur.pages.dev/introduccion/ Conceptos base, alcance y modelo por tienda de la API pública de Wendoshop. La API pública de Wendoshop permite integrar catálogo, stock, categorías, órdenes, carritos abandonados y webhooks. El contrato vigente es **OpenAPI 3.1.0**, versión de API **1.0.0**. ### Una credencial por tienda Cada API key pertenece a una tienda. Todas las operaciones están aisladas por la tienda asociada al token: los recursos consultados o modificados se resuelven dentro de ese contexto. El servidor base se construye con el dominio público de la tienda: ```text https://{storeDomain} ``` Usá el dominio propio o el subdominio asignado a la tienda. En los ejemplos de esta documentación se usa el dominio reservado `store.example.com`. ### Recursos disponibles - Productos, stock, variantes e imágenes. - Categorías. - Órdenes, incluidas ventas externas. - Carritos abandonados. - Suscripciones de webhooks. Cada operación declara su scope requerido, nivel mínimo de API, respuestas y, cuando corresponde, efectos secundarios mediante extensiones `x-*`. > **Fuente de verdad:** > La [referencia API](https://docs-api-3ur.pages.dev/referencia-api/) carga el contrato publicado por Wendoshop en tiempo real. Si una guía y la referencia difieren, el contrato OpenAPI publicado es la fuente de verdad. --- ## Inicio rápido Fuente: https://docs-api-3ur.pages.dev/inicio-rapido/ Primera consulta autenticada a la API de Wendoshop con una API key de tienda. Esta guía muestra una consulta de solo lectura al catálogo. Necesitás una API key asociada a la tienda y el scope `products:read`. ### 1. Elegí el dominio de la tienda Las solicitudes se envían al dominio público de la tienda. Reemplazá `store.example.com` por el dominio correspondiente. ### 2. Enviá el token como Bearer ```bash curl --request GET \ --url 'https://store.example.com/api/v1/productos?limit=10&offset=0' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` No incluyas tokens en código fuente, repositorios, logs públicos ni variables expuestas al navegador. ### 3. Procesá la página La respuesta `200` contiene `data` y `meta`. `meta` informa `total`, `limit`, `offset` y `has_more`. ```json { "data": [], "meta": { "total": 0, "limit": 10, "offset": 0, "has_more": false } } ``` ### Próximo paso Revisá [autenticación](https://docs-api-3ur.pages.dev/autenticacion/), [scopes](https://docs-api-3ur.pages.dev/scopes-permisos/) y la [referencia completa](https://docs-api-3ur.pages.dev/referencia-api/) antes de implementar operaciones de escritura. --- ## Autenticación Fuente: https://docs-api-3ur.pages.dev/autenticacion/ Uso seguro de API keys de tienda mediante el esquema HTTP Bearer. Todas las operaciones usan autenticación HTTP Bearer. Enviá la API key en la cabecera `Authorization`: ```http Authorization: Bearer ``` ### Contexto de tienda Cada API key pertenece a una tienda. La credencial determina el aislamiento de datos para productos, categorías, órdenes, carritos y webhooks. ### Respuestas relacionadas - `401 Unauthorized`: token inválido, revocado, ausente o sin acceso vigente a la API. - `403 Forbidden`: el plan o los scopes del token no permiten ejecutar la operación. ```json { "error": "Unauthorized", "message": "API key inválida o no proporcionada" } ``` ### Manejo seguro - Guardá la API key solo en un entorno de servidor o gestor de secretos. - No la envíes a este sitio de documentación: la referencia está configurada en modo de solo lectura. - No la persistás en `localStorage`, cookies accesibles por JavaScript ni bundles del frontend. - Evitá imprimir la cabecera `Authorization` en logs. > **Atención:** > Las variables `PUBLIC_*` de Astro son públicas. `PUBLIC_API_SPEC_URL` contiene únicamente la URL pública del contrato; nunca agregues una API key en una variable con ese prefijo. El contrato no documenta el proceso de emisión, rotación o revocación de API keys. Esa guía está **pendiente** hasta que el comportamiento forme parte de la fuente de verdad. --- ## Scopes y permisos Fuente: https://docs-api-3ur.pages.dev/scopes-permisos/ Scopes requeridos por las operaciones documentadas en la API de Wendoshop. Cada operación declara sus permisos en la extensión `x-required-scopes`. El contrato actual contiene nueve scopes. | Scope | Uso confirmado | | --- | --- | | `products:read` | Leer productos, categorías e imágenes. | | `products:write_stock` | Sincronizar stock por SKU. | | `products:write` | Crear o actualizar productos, variantes, imágenes y categorías. | | `orders:read` | Listar y obtener órdenes. | | `orders:create` | Crear ventas externas. | | `orders:write` | Actualizar estado o seguimiento de órdenes. | | `carts:read` | Listar carritos abandonados. | | `webhooks:read` | Listar webhooks. | | `webhooks:write` | Crear, actualizar o eliminar webhooks. | ### Scope condicional de pagos `POST /api/v1/ordenes` requiere `orders:create`. Si `pago.estado` es `pagado`, también requiere `payments:write_external`, aunque este permiso condicional no aparece en la lista `x-required-scopes` de la operación: está confirmado por su descripción y su respuesta `403`. ### Denegación de acceso La API responde `403` cuando falta el scope requerido o el nivel del plan no habilita la operación. Consultá [planes y niveles de API](https://docs-api-3ur.pages.dev/planes-niveles-api/) para ver el nivel mínimo declarado. > **Nota:** > El contrato no documenta cómo solicitar, asignar o editar scopes de una credencial. Esa operación queda **pendiente de documentación**. --- ## Planes y niveles de API Fuente: https://docs-api-3ur.pages.dev/planes-niveles-api/ Niveles basic y advanced declarados por las operaciones de la API. La extensión `x-api-tier` define el nivel mínimo de cada operación. El contrato actual usa dos niveles: `basic` y `advanced`. ### Nivel basic Incluye 12 operaciones: lecturas de productos, categorías, órdenes e imágenes; sincronización de stock; y administración de webhooks. ### Nivel advanced Incluye 15 operaciones: escrituras de catálogo, variantes, imágenes y categorías; creación o actualización de órdenes; y lectura de carritos abandonados. La [referencia API](https://docs-api-3ur.pages.dev/referencia-api/) muestra `x-api-tier` en cada operación y es la lista definitiva. ### Límites confirmados por plan El único límite numérico por plan declarado en `x-plan-limits` corresponde a webhooks: | Nivel | Webhooks por tienda | | --- | ---: | | `basic` | 2 | | `advanced` | 10 | | `enterprise` | Sin límite numérico declarado (`null`) | ### Efectos secundarios confirmados Las operaciones de lectura no declaran efectos secundarios. Las operaciones siguientes sí los publican en `x-side-effects`: | Operación | Efectos declarados | | --- | --- | | Sincronizar stock por SKU | Actualiza stock de productos o variantes; puede emitir eventos de stock. | | Crear un producto | Crea el producto; puede crear una categoría por nombre; actualiza la galería; invalida caché pública. | | Actualizar un producto | Actualiza catálogo; puede reemplazar la galería; invalida caché pública. | | Crear o actualizar una variante | Crea o actualiza la variante y registra historial de producto. | | Agregar una imagen | Agrega la imagen y reordena la galería cuando se indica una posición. | | Reemplazar imágenes | Elimina y reemplaza la galería completa. | | Reordenar imágenes | Reordena la galería. | | Actualizar una imagen | Actualiza la imagen y puede reordenar la galería. | | Eliminar una imagen | Elimina la imagen y reordena la galería restante. | | Crear una categoría | Crea la categoría e invalida la caché de categorías. | | Actualizar una categoría | Actualiza la categoría e invalida la caché de categorías. | | Eliminar una categoría | Puede desasignar productos; elimina la categoría; invalida la caché de categorías. | | Crear una venta externa | Crea orden y pago externo; puede descontar stock; puede crear o actualizar comprador; encola eventos; puede notificar al seller o cliente. | | Actualizar una orden | Actualiza el estado operativo o el seguimiento. | | Registrar un webhook | Crea una suscripción durable y genera un secret de firma. | | Actualizar o eliminar un webhook | Actualiza o elimina la suscripción, respectivamente. | > **Sin supuestos comerciales:** > El contrato no publica precios, nombres comerciales de planes, límites generales de productos ni valores numéricos de rate limit. Esos datos quedan **pendientes** y no se infieren aquí. --- ## Paginación Fuente: https://docs-api-3ur.pages.dev/paginacion/ Paginación por limit y offset en listados de productos, órdenes y carritos. Los listados paginados usan `limit` y `offset` como parámetros de query. ```http GET /api/v1/productos?limit=50&offset=0 ``` | Parámetro | Valor confirmado | | --- | --- | | `limit` | Entero entre 1 y 200. Valor predeterminado: 50. | | `offset` | Entero mayor o igual a 0. Valor predeterminado: 0. | Este patrón está documentado en: - `GET /api/v1/productos` - `GET /api/v1/ordenes` - `GET /api/v1/carritos-abandonados` ### Metadatos de respuesta Los listados incluyen un objeto `meta` con `total`, `limit`, `offset` y `has_more`. ```json { "total": 134, "limit": 50, "offset": 50, "has_more": true } ``` Mientras `has_more` sea `true`, avanzá el offset por la cantidad solicitada. El contrato no declara paginación por cursor. --- ## Rate limits Fuente: https://docs-api-3ur.pages.dev/rate-limits/ Cómo detectar y manejar límites de solicitudes de la API de Wendoshop. Las operaciones documentan una respuesta `429` cuando se supera un límite por credencial, por tienda o por una ventana de ráfaga. ### Cabeceras de control | Cabecera | Significado confirmado | | --- | --- | | `X-RateLimit-Limit` | Menor límite efectivo por minuto entre credencial y tienda. | | `X-RateLimit-Remaining` | Solicitudes restantes en la ventana por minuto. | | `X-RateLimit-Reset` | Reinicio de la ventana como Unix timestamp en segundos. | | `X-RateLimit-Reason` | `credential_minute`, `store_minute`, `credential_burst` o `store_burst`. | | `Retry-After` | Segundos mínimos antes de reintentar. | ### Estrategia de reintento Ante un `429`, respetá `Retry-After` y evitá reintentar antes de ese intervalo. Considerá el motivo informado en `X-RateLimit-Reason` para distinguir límites por credencial, tienda o ráfaga. > **Límites numéricos pendientes:** > El contrato no publica cantidades por minuto ni tamaños de ráfaga. No asumas valores fijos: diseñá el cliente a partir de las cabeceras de cada respuesta. --- ## Errores Fuente: https://docs-api-3ur.pages.dev/errores/ Formato y códigos de error declarados por la API de Wendoshop. Los errores usan JSON y contienen al menos `error`; muchas respuestas también incluyen `message` y, en conflictos específicos, `codigo`. ```json { "error": "Forbidden", "message": "Tu token o plan no tiene acceso a este endpoint." } ``` ### Códigos documentados | Estado | Casos confirmados | | ---: | --- | | `400` | Parámetros, identificadores o bodies inválidos. | | `401` | Token ausente, inválido, revocado o sin acceso vigente. | | `402` | La tienda alcanzó su límite de productos al crear un producto. | | `403` | El plan o los scopes no permiten la operación. | | `404` | Recurso no encontrado dentro de la tienda del token. | | `409` | Duplicados, conflictos de stock, jerarquía, relaciones o idempotencia. | | `422` | Reglas de negocio o límites específicos no satisfechos. | | `429` | Límite por credencial, tienda o ráfaga superado. | | `500` | Fallo interno al crear o actualizar ciertos recursos. | No todas las operaciones declaran todos los estados. Consultá las respuestas de la operación concreta en la [referencia API](https://docs-api-3ur.pages.dev/referencia-api/). ### Recomendación de manejo Conservá el estado HTTP y el campo `codigo` cuando exista para decidir si el error es corregible, reintentable o requiere intervención. El contrato no define un catálogo global cerrado de valores para `codigo`; documentarlos de manera exhaustiva queda **pendiente**. --- ## Idempotencia Fuente: https://docs-api-3ur.pages.dev/idempotencia/ Uso de Idempotency-Key en sincronización de stock y creación de órdenes. El contrato declara la cabecera `Idempotency-Key` en dos operaciones: | Operación | Requisito | | --- | --- | | `PATCH /api/v1/productos` | Opcional. Sincroniza stock por SKU. | | `POST /api/v1/ordenes` | Obligatoria. Crea una venta externa. | La clave admite entre 1 y 200 caracteres y debe cumplir este patrón: ```text ^[A-Za-z0-9._~:+-]+$ ``` Usá una clave nueva y estable para cada operación lógica. Un ejemplo ficticio: ```http Idempotency-Key: order-pos-2026-000042 ``` ### Replay y conflictos Al crear una orden, una repetición completada puede devolver la respuesta original con: ```http Idempotent-Replayed: true ``` El cuerpo también informa `meta.idempotent_replay`. La API puede responder `409` si una clave se reutiliza con otro body o si la operación sigue en proceso. En la creación de órdenes, `409` también puede representar referencia duplicada o stock insuficiente. > **Nota:** > El contrato no declara cuánto tiempo se conservan las claves. La ventana de retención queda **pendiente de documentación**. --- ## Webhooks Fuente: https://docs-api-3ur.pages.dev/webhooks/ Registro, eventos, límites y manejo de secretos de webhooks. Los webhooks permiten registrar una URL pública y suscribirse a eventos habilitados por el nivel de API de la tienda. ### Operaciones - Listar webhooks: `webhooks:read`, nivel `basic`. - Crear, actualizar y eliminar: `webhooks:write`, nivel `basic`. Al crear un webhook, la URL debe ser HTTP(S), pública y superar las validaciones SSRF del servidor. ```json { "url": "https://integracion.example.com/events", "eventos": ["orden.creada", "stock.actualizado"] } ``` ### Eventos declarados El contrato enumera estos eventos, aunque su disponibilidad depende del nivel de API: - `orden.creada`, `orden.pagada`, `orden.cancelada` - `orden.preparando`, `orden.empaquetado`, `orden.lista_para_retirar` - `orden.enviada`, `orden.entregada`, `orden.envio_mayorista_actualizado` - `pago.reembolsado` - `stock.actualizado` - `contacto.creado` - `carrito.abandonado` - `devolucion.actualizada` - `producto.creado`, `producto.actualizado`, `variante.actualizada` ### Secret y límites Crear una suscripción genera un secret de firma. La respuesta lo devuelve **una sola vez**; el listado de webhooks nunca lo incluye. Guardalo inmediatamente en un gestor de secretos del servidor. El máximo declarado es 2 webhooks para `basic`, 10 para `advanced` y `null` para `enterprise`. > **Verificación de firma pendiente:** > El contrato confirma que existe un secret de firma, pero no define algoritmo, cabeceras, formato del payload, tolerancia temporal ni política de reintentos. No se documenta una implementación hasta que esos detalles se publiquen en la fuente de verdad. --- ## Changelog Fuente: https://docs-api-3ur.pages.dev/changelog/ Historial publicado de cambios en la API de Wendoshop. ### Estado actual La versión declarada por el contrato es **1.0.0** y usa OpenAPI **3.1.0**. ### Historial El contrato OpenAPI no incluye entradas de changelog, fechas de lanzamiento ni una política de versionado. El historial detallado queda **pendiente de publicación**. Mientras tanto, la [referencia API](https://docs-api-3ur.pages.dev/referencia-api/) siempre consume el contrato público vigente y refleja los cambios publicados sin copiar archivos entre repositorios.