Saltar al contenido

Docs: API REST y MCP

La referencia para tiendas que integran PackMate en sus propios flujos: OpenAPI 3.1, autenticación, límites por plan, códigos de error, webhooks.

Dirección base
https://api.packmate.shop/api/v1
Abrir archivo OpenAPIConfigurar MCP

Inicio rápido

De la instalación a la primera petición. La misma clave funciona para REST y MCP.

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

  2. Generar clave API

    En la app, en «Settings → AI access». Las claves empiezan por pm_live_ o, para la sandbox, por pm_test_.

    pm_live_4f3a8b9c2d1e...
    Ejemplo
  3. 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_…'
  4. 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.

TemaQué se aplicaCómo se ve
Formato de claveDos 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.
pm_live_4f3a8b9c2d1e7f6a5b4c3d2e1f0a9b8c4f3a8b9c2d1e7f6a
Ejemplo
Formato del headerEnvía la clave en el header X-API-Key en cada petición. Un Bearer en Authorization no se acepta.
X-API-Key: pm_live_…
RotaciónGenera 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.
DELETE /api/v1/keys/:key_id
Response: 204 No Content
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.
scope: lesen | schreiben | irreversibel

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.

PlanPeticiones por minutoCorto plazo (burst)Simultáneas
Free601205
Basic12024010
Pro30060025
Business600120050
Custom2000acordadoacordado

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ódigoLadoSignificadoQué haces
400ClienteBad request — cuerpo o query mal formadoVerifica la forma de la petición contra el archivo OpenAPI.
401ClienteNo autorizado — clave API faltante o inválidaEnvía el header X-API-Key con una clave pm_live_ o pm_test_ válida.
402ClientePago requerido — límite del plan alcanzadoCambia de plan o espera al próximo ciclo. Usa «Ponerse al día» (bulk reconciliation) tras el cambio.
403ClienteProhibido — acceso denegadoComprueba 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.
404ClienteNo encontrado — el recurso no existeVerifica el ID. El pedido puede no estar sincronizado aún.
422ClienteNo procesable — validación semántica fallidaLee error.message — típicamente dimensiones faltantes o material inválido.
429ClienteDemasiadas peticiones — límite alcanzadoEspera según el header Retry-After. Ver la tabla «Límites por plan» arriba.
500ServidorError interno — fallo de nuestro ladoReintenta una vez; luego escribe a support@packmate.shop con el request_id del cuerpo del error.
503ServidorServicio no disponible — mantenimiento o fallo de base de datosReintenta 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.

TemaTipoQué hace PackMate
customers/redactRequeridoAnte 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_requestRequeridoUn cliente solicita una exportación de sus datos. PackMate la compila en 30 días.
shop/redactRequeridoShopify 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/uninstalledRequeridoLa 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/updateOpcionalProducto cambiado — PackMate refresca dimensiones y metafields en caché.
app/scopes_updateOpcionalScopes 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.