Inicio rápido
De la instalación a la primera petición. La misma clave funciona para REST y MCP.
Instalar PackMate en Shopify
Tras la aprobación en el App Store: haz clic en «Instalar». PackMate funciona en cada plan, puedes empezar en Free.
Generar clave API
En la app, en «Settings → AI access». Las claves empiezan por pm_live_ o, para la sandbox, por pm_test_.
Ejemplopm_live_4f3a8b9c2d1e...Primera petición
Con curl, fetch u otro cliente HTTP. El header X-API-Key autentica cada petición.
curl https://api.packmate.shop/api/v1/health \ -H 'X-API-Key: pm_live_…'Después: conectar MCP
La misma clave funciona para el servidor MCP. Cómo conectar tu aplicación de IA está en «Conexión IA».
Autenticación con clave API
PackMate usa claves API con el header X-API-Key. Las claves se guardan con hash SHA-256, valen para una sola tienda y se renuevan en un clic.
| Tema | Qué se aplica | Cómo se ve |
|---|---|---|
| Formato de clave | Dos prefijos: pm_live_ para producción, pm_test_ para la sandbox. Siguen 48 caracteres hexadecimales; el prefijo está en claro para reconocer la clave de un vistazo. | |
| Formato del header | Envía la clave en el header X-API-Key en cada petición. Un Bearer en Authorization no se acepta. | |
| Rotación | Genera una clave nueva en la app, cámbiala en tu cliente y revoca la antigua. Hasta 10 claves activas por tienda para un cambio escalonado. | |
| Permisos (scopes) | Cada clave lleva permisos (scopes). Claves nuevas: lesen (lectura) o lesen + schreiben (escritura); las claves más antiguas pueden llevar además irreversibel. Al crear la clave en la app eliges su fin; los permisos se derivan de él. Los permisos de staff de Shopify limitan además quién genera claves. | |
Límites por plan
Límites por minuto y para picos breves (burst). Los picos se suavizan con token bucket, los picos cortos no se bloquean. Los planes Custom acuerdan límites propios.
| Plan | Peticiones por minuto | Corto plazo (burst) | Simultáneas |
|---|---|---|---|
| Free | 60 | 120 | 5 |
| Basic | 120 | 240 | 10 |
| Pro | 300 | 600 | 25 |
| Business | 600 | 1200 | 50 |
| Custom | 2000 | acordado | acordado |
Al alcanzar el límite recibes una respuesta 429 con el header Retry-After. El header indica cuántos segundos esperar.
Códigos de error
Semántica HTTP estándar con cuerpos de error de PackMate. Cada error incluye un campo code legible por máquina y un mensaje legible.
| Código | Lado | Significado | Qué haces |
|---|---|---|---|
| 400 | Cliente | Bad request — cuerpo o query mal formado | Verifica la forma de la petición contra el archivo OpenAPI. |
| 401 | Cliente | No autorizado — clave API faltante o inválida | Envía el header X-API-Key con una clave pm_live_ o pm_test_ válida. |
| 402 | Cliente | Pago requerido — límite del plan alcanzado | Cambia de plan o espera al próximo ciclo. Usa «Ponerse al día» (bulk reconciliation) tras el cambio. |
| 403 | Cliente | Prohibido — acceso denegado | Comprueba que la tienda esté habilitada, que la clave tenga el permiso necesario y que no haya bloqueo de IA (peticiones de escritura de la IA: KI_BESTAETIGUNG_FEHLT). query_carrier_rates no consulta tarifas en tiempo real hoy. Las etiquetas DHL no se pueden crear a través de la API (DHL_LABEL_API_GESPERRT; las claves sin el permiso irreversibel reciben antes insufficient_scope); las creas en PackMate. |
| 404 | Cliente | No encontrado — el recurso no existe | Verifica el ID. El pedido puede no estar sincronizado aún. |
| 422 | Cliente | No procesable — validación semántica fallida | Lee error.message — típicamente dimensiones faltantes o material inválido. |
| 429 | Cliente | Demasiadas peticiones — límite alcanzado | Espera según el header Retry-After. Ver la tabla «Límites por plan» arriba. |
| 500 | Servidor | Error interno — fallo de nuestro lado | Reintenta una vez; luego escribe a support@packmate.shop con el request_id del cuerpo del error. |
| 503 | Servidor | Servicio no disponible — mantenimiento o fallo de base de datos | Reintenta con backoff exponencial. |
Webhooks
PackMate registra webhooks de Shopify: los obligatorios por RGPD y otros operativos. Shopify los firma todos con HMAC-SHA256; PackMate verifica la firma antes de procesarlos.
| Tema | Tipo | Qué hace PackMate |
|---|---|---|
| customers/redact | Requerido | Ante una solicitud de eliminación, PackMate sustituye el nombre y la dirección de las etiquetas de envío de los pedidos por «[redacted]», quita el enlace al PDF de la etiqueta y borra el correo guardado de solicitudes de acceso anteriores. Los cálculos de empaquetado no contienen datos de clientes y no cambian. |
| customers/data_request | Requerido | Un cliente solicita una exportación de sus datos. PackMate la compila en 30 días. |
| shop/redact | Requerido | Shopify lo envía unas 48 horas después de desinstalar. PackMate elimina entonces todos los datos de la tienda de su base de datos. |
| app/uninstalled | Requerido | La aplicación se desinstaló. PackMate marca la tienda como desinstalada, revoca sus claves API y finaliza la suscripción. Los datos se eliminan con shop/redact. |
| products/update | Opcional | Producto cambiado — PackMate refresca dimensiones y metafields en caché. |
| app/scopes_update | Opcional | Scopes obligatorios cambiados — PackMate registra el cambio. |
Shopify firma todos los webhooks con HMAC-SHA256. PackMate verifica la firma antes de procesarlos.
¿Listo? Genera una clave API en la app, en «Settings → AI access». La misma clave funciona para REST y MCP.