Autenticación
Autenticación
La clave con permisos ES la credencial. Cada endpoint pide el permiso mínimo, y cada rechazo trae un código estable.
La clave como credencial
La API se autentica con una clave por tienda que mandás en cada pedido:
Authorization: Bearer mdt_live_...- El formato es
mdt_live_(producción) omdt_test_(pruebas) seguido de 43 caracteres. - Del lado nuestro solo guardamos el hash de la clave, nunca la clave. Por eso se muestra una sola vez, al crearla.
- Una clave actúa sobre una sola tienda. Si tu integrador trabaja con varias tiendas, cada una te da la suya.
- La clave es un secreto de servidor. No la pongas en una app de cliente ni en el navegador.
Permisos (scopes)
Cada clave lleva solo los permisos que elegís al crearla. Si un endpoint pide un permiso que la clave no tiene, la respuesta es 403 INSUFFICIENT_SCOPE y nombra el permiso que falta. Elegí lo mínimo.
| Permiso | Qué habilita | Estado |
|---|---|---|
products:read | Leer productos, variantes y categorías | Disponible |
inventory:read | Leer niveles de stock y el kardex (movimientos) | Disponible |
inventory:write | Fijar o ajustar stock | Disponible |
prices:write | Escribir precios de variante y sobreescrituras de lista de precios | Disponible |
orders:read | Leer pedidos para facturar | Disponible |
products:write | Crear y editar productos y variantes | Próximamente |
webhooks:manage | Administrar endpoints de webhooks | Próximamente |
Lista de IP
Opcional pero muy recomendado: limitá la clave a una o varias IP (o rangos CIDR). Una clave robada no sirve desde otra IP. Un pedido desde una IP no permitida es 403 IP_NOT_ALLOWED. Si no cargás ninguna, la clave funciona desde cualquier lado.
Vencimiento y rotación
- Las claves vencen. Si no ponés fecha, vencen a los 12 meses. Una clave vencida es
401 API_KEY_EXPIRED. - Te avisamos por mail 30 días antes del vencimiento, con los pasos para rotar.
- Para rotar sin cortar el servicio: creá una clave nueva, cambiala en tu sistema, y recién ahí revocá la vieja.
- La revocación es inmediata: en el próximo pedido la clave vieja es
401 API_KEY_REVOKED.
Errores
Todo rechazo tiene la forma { "ok": false, "code": "...", "message": "...", "details"?: ... }. Ramificá siempre por code (es el contrato y no cambia), nunca por el mensaje (es en inglés y puede reescribirse).
| code | HTTP | Significado |
|---|---|---|
API_KEY_INVALID | 401 | Falta la clave o tiene mal formato |
API_KEY_WRONG_ENVIRONMENT | 401 | Clave de otro entorno (live contra test) |
API_KEY_REVOKED / API_KEY_EXPIRED | 401 | Clave revocada o vencida |
IP_NOT_ALLOWED | 403 | IP fuera de la lista de la clave |
PLAN_REQUIRED | 403 | La tienda no tiene acceso a la API en su plan |
INSUFFICIENT_SCOPE | 403 | La clave no tiene el permiso del endpoint |
VALIDATION_ERROR | 422 | El cuerpo no pasó validación (ver details) |
RATE_LIMITED / CONCURRENCY_LIMITED | 429 | Pasaste el ritmo o el máximo en vuelo (ver Retry-After) |
PARTNER_API_BUSY | 503 | API saturada; reintentá tras Retry-After |
SKU_AMBIGUOUS | 409 | Más de una variante con ese SKU; usá variantId o código de barras |
VARIANT_NOT_FOUND | 404 | Ninguna variante coincide con la referencia |
Los rechazos por ítem de una escritura en lote (por ejemplo STOCK_CHANGED, INSUFFICIENT_STOCK, VARIANT_NOT_TRACKED) no frenan toda la llamada: vienen en results[], por fila. Lo vemos en Sincronizar tu ERP. La lista completa de códigos está en la referencia.