{"openapi":"3.1.0","info":{"title":"Mi Super API","version":"1.0.0","summary":"Catálogo, stock y ventas de un comercio que usa Mi Super.","description":"API REST de Mi Super, el sistema de gestión para kioscos, almacenes y distribuidoras de Argentina. Cada clave es de UN negocio (una sucursal es otro negocio) y se crea desde Configuración → Integraciones, con permiso de lectura o de escritura. Está incluida en el plan Distribuidora.\n\nMontos en pesos argentinos (ARS) con IVA incluido; fechas en milisegundos desde 1970 (UTC). Los errores siguen el RFC 9457 (`application/problem+json`) y traen `codigo` (estable, para comparar) y `ayuda` (qué hacer).","contact":{"name":"Mi Super","url":"https://www.misuper.ar/contact"},"termsOfService":"https://www.misuper.ar/legal/terminos"},"externalDocs":{"description":"Guía para desarrolladores y agentes","url":"https://www.misuper.ar/desarrolladores#api"},"servers":[{"url":"https://www.misuper.ar/api/v1","description":"Producción"}],"security":[{"claveApi":[]}],"tags":[{"name":"Negocio","description":"A quién pertenece la clave."},{"name":"Productos","description":"Catálogo, precios y stock."},{"name":"Ventas","description":"Ventas registradas en el punto de venta."}],"paths":{"/negocio":{"get":{"operationId":"verNegocio","tags":["Negocio"],"summary":"Ver el negocio y el permiso de la clave","description":"Devuelve el negocio al que pertenece la clave y si es de lectura o de escritura. Usala primero para probar que la clave funciona.","responses":{"200":{"description":"El negocio y la clave.","content":{"application/json":{"schema":{"type":"object","required":["negocio","clave"],"properties":{"negocio":{"type":"object","required":["id","nombre"],"properties":{"id":{"type":"string","format":"uuid","description":"Id del negocio."},"nombre":{"type":["string","null"],"description":"Nombre del comercio."}}},"clave":{"type":"object","required":["nombre","permiso"],"properties":{"nombre":{"type":"string","description":"El nombre que se le puso a la clave al crearla."},"permiso":{"$ref":"#/components/schemas/Permiso"}}}}},"example":{"negocio":{"id":"0b7f9a52-1c1d-4e0f-8d8a-3c2b1a0f9e8d","nombre":"Kiosco Don Pedro"},"clave":{"nombre":"ERP central","permiso":"lectura"}}}}},"401":{"description":"Falta la clave o es inválida o revocada. Códigos posibles: `clave_faltante`, `clave_invalida`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}},"403":{"description":"El plan del negocio no incluye la API (plan Distribuidora). Códigos posibles: `plan_sin_api`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}},"429":{"description":"Límite de pedidos: 60 por minuto por clave. Respetar `Retry-After`. Códigos posibles: `limite_de_pedidos`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}},"headers":{"Retry-After":{"description":"Segundos a esperar antes de reintentar.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"Falla del servidor, no del pedido: reintentar. Códigos posibles: `error_interno`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}}}}},"/productos":{"get":{"operationId":"listarProductos","tags":["Productos"],"summary":"Listar o buscar productos","description":"Devuelve el catálogo del negocio ordenado por nombre, de a páginas. Filtra por parte del nombre (`buscar`) o por código de barras exacto (`codigo_barras`). Los productos dados de baja no vienen salvo `incluir_inactivos=true`.","parameters":[{"name":"pagina","in":"query","required":false,"description":"Número de página, desde 1.","schema":{"type":"integer","minimum":1,"maximum":10000,"default":1}},{"name":"por_pagina","in":"query","required":false,"description":"Resultados por página, de 1 a 200.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"buscar","in":"query","required":false,"description":"Parte del nombre o del código de barras.","schema":{"type":"string","maxLength":100}},{"name":"codigo_barras","in":"query","required":false,"description":"Código de barras exacto, de 6 a 14 dígitos. También encuentra su otra forma (UPC-A de 12 ↔ EAN-13).","schema":{"type":"string","pattern":"^\\d{6,14}$"}},{"name":"incluir_inactivos","in":"query","required":false,"description":"`true` para incluir los productos dados de baja.","schema":{"type":"string","enum":["true","false"],"default":"false"}}],"responses":{"200":{"description":"Una página de productos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginaDeProductos"},"example":{"datos":[{"id":"7c1e2b1a-4f3d-4b8e-9a0c-2d5f6e7a8b9c","nombre":"Alfajor triple chocolate","codigo_barras":"7790580123456","precio":1200,"costo":780,"stock_actual":36,"stock_minimo":12,"categoria":"Golosinas","activo":true,"updated_at":1758585600000,"unidad_venta":"unidad"}],"pagina":1,"por_pagina":50,"total":1}}}},"400":{"description":"Algún parámetro no es válido. Códigos posibles: `parametros_invalidos`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}},"401":{"description":"Falta la clave o es inválida o revocada. Códigos posibles: `clave_faltante`, `clave_invalida`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}},"403":{"description":"El plan del negocio no incluye la API (plan Distribuidora). Códigos posibles: `plan_sin_api`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}},"429":{"description":"Límite de pedidos: 60 por minuto por clave. Respetar `Retry-After`. Códigos posibles: `limite_de_pedidos`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}},"headers":{"Retry-After":{"description":"Segundos a esperar antes de reintentar.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"Falla del servidor, no del pedido: reintentar. Códigos posibles: `error_interno`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}}}}},"/productos/{id}":{"get":{"operationId":"verProducto","tags":["Productos"],"summary":"Ver un producto","description":"Devuelve un producto del negocio por su id, con precio, costo y stock actuales.","parameters":[{"name":"id","in":"path","required":true,"description":"El id del producto (uuid), como viene en `listarProductos`.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"El producto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaProducto"},"example":{"producto":{"id":"7c1e2b1a-4f3d-4b8e-9a0c-2d5f6e7a8b9c","nombre":"Alfajor triple chocolate","codigo_barras":"7790580123456","precio":1200,"costo":780,"stock_actual":36,"stock_minimo":12,"categoria":"Golosinas","activo":true,"updated_at":1758585600000,"unidad_venta":"unidad"}}}}},"401":{"description":"Falta la clave o es inválida o revocada. Códigos posibles: `clave_faltante`, `clave_invalida`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}},"403":{"description":"El plan del negocio no incluye la API (plan Distribuidora). Códigos posibles: `plan_sin_api`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}},"404":{"description":"No existe o es de otro negocio. Códigos posibles: `no_encontrado`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}},"429":{"description":"Límite de pedidos: 60 por minuto por clave. Respetar `Retry-After`. Códigos posibles: `limite_de_pedidos`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}},"headers":{"Retry-After":{"description":"Segundos a esperar antes de reintentar.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"Falla del servidor, no del pedido: reintentar. Códigos posibles: `error_interno`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}}}},"patch":{"operationId":"actualizarProducto","tags":["Productos"],"summary":"Cambiar precio, costo, nombre, categoría, stock mínimo o alta/baja","description":"Cambia solo los campos que vienen; los demás quedan como estaban. El stock no se cambia desde acá: se ajusta con `ajustarStock`, que deja el movimiento registrado. Requiere una clave de escritura.","parameters":[{"name":"id","in":"path","required":true,"description":"El id del producto (uuid), como viene en `listarProductos`.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"description":"Al menos un campo.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"nombre":{"type":"string","minLength":1,"maxLength":200,"description":"Nombre que se ve en el punto de venta."},"precio":{"type":"number","exclusiveMinimum":0,"maximum":10000000000,"description":"Precio de venta en pesos, IVA incluido. Se redondea a centavos."},"costo":{"type":"number","minimum":0,"maximum":10000000000,"description":"Costo en pesos. Se redondea a centavos."},"stock_minimo":{"type":"number","minimum":0,"maximum":1000000,"description":"Por debajo de esto el sistema avisa que hay que reponer. En la unidad del producto (hasta 3 decimales en kg/l/m)."},"categoria":{"type":"string","minLength":1,"maxLength":60,"description":"Categoría (por ejemplo, Golosinas o Bebidas)."},"activo":{"type":"boolean","description":"`false` da de baja el producto (no se borra); `true` lo reactiva."},"unidad_venta":{"type":"string","enum":["unidad","kg","l","m"],"description":"En qué se vende: por unidad, kilo, litro o metro. En kg/l/m el precio es el de 1 kilo/litro/metro."}}},"example":{"precio":1350}}}},"responses":{"200":{"description":"El producto actualizado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespuestaProducto"},"example":{"producto":{"id":"7c1e2b1a-4f3d-4b8e-9a0c-2d5f6e7a8b9c","nombre":"Alfajor triple chocolate","codigo_barras":"7790580123456","precio":1350,"costo":780,"stock_actual":36,"stock_minimo":12,"categoria":"Golosinas","activo":true,"updated_at":1758585600000,"unidad_venta":"unidad"}}}}},"400":{"description":"El cuerpo no es JSON o algún campo no es válido. Códigos posibles: `json_invalido`, `datos_invalidos`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}},"401":{"description":"Falta la clave o es inválida o revocada. Códigos posibles: `clave_faltante`, `clave_invalida`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}},"403":{"description":"El plan del negocio no incluye la API (plan Distribuidora), o la clave es de solo lectura. Códigos posibles: `plan_sin_api`, `permiso_insuficiente`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}},"404":{"description":"No existe o es de otro negocio. Códigos posibles: `no_encontrado`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}},"409":{"description":"Reactivarlo chocaría con otro producto activo con el mismo código de barras. Códigos posibles: `conflicto`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}},"429":{"description":"Límite de pedidos: 60 por minuto por clave. Respetar `Retry-After`. Códigos posibles: `limite_de_pedidos`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}},"headers":{"Retry-After":{"description":"Segundos a esperar antes de reintentar.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"Falla del servidor, no del pedido: reintentar. Códigos posibles: `error_interno`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}}}}},"/productos/{id}/stock":{"post":{"operationId":"ajustarStock","tags":["Productos"],"summary":"Sumar o restar stock","description":"Registra una entrada (cantidad positiva, por ejemplo mercadería que llegó) o una salida (negativa, por ejemplo rotura). El stock no baja de 0 y el movimiento queda en el historial del producto. Requiere una clave de escritura.","parameters":[{"name":"id","in":"path","required":true,"description":"El id del producto (uuid), como viene en `listarProductos`.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["cantidad"],"properties":{"cantidad":{"type":"number","minimum":-1000000,"maximum":1000000,"description":"Cuánto sumar (positivo) o restar (negativo), en la unidad del producto: unidades enteras, o kilos/litros/metros con hasta 3 decimales (0.25 = 250 g). No puede ser 0."},"motivo":{"type":"string","maxLength":200,"description":"Por qué: se ve en el historial del producto."}}},"example":{"cantidad":24,"motivo":"Llegó el pedido de la distribuidora"}}}},"responses":{"200":{"description":"El stock antes y después del ajuste.","content":{"application/json":{"schema":{"type":"object","required":["producto_id","stock_anterior","stock_actual"],"properties":{"producto_id":{"type":"string","format":"uuid","description":"El producto ajustado."},"stock_anterior":{"type":"number","description":"Stock antes del ajuste."},"stock_actual":{"type":"number","description":"Stock después del ajuste (nunca menor a 0)."}}},"example":{"producto_id":"7c1e2b1a-4f3d-4b8e-9a0c-2d5f6e7a8b9c","stock_anterior":36,"stock_actual":60}}}},"400":{"description":"El cuerpo no es JSON o la cantidad no es válida. Códigos posibles: `json_invalido`, `datos_invalidos`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}},"401":{"description":"Falta la clave o es inválida o revocada. Códigos posibles: `clave_faltante`, `clave_invalida`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}},"403":{"description":"El plan del negocio no incluye la API (plan Distribuidora), o la clave es de solo lectura. Códigos posibles: `plan_sin_api`, `permiso_insuficiente`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}},"404":{"description":"No existe o es de otro negocio. Códigos posibles: `no_encontrado`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}},"429":{"description":"Límite de pedidos: 60 por minuto por clave. Respetar `Retry-After`. Códigos posibles: `limite_de_pedidos`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}},"headers":{"Retry-After":{"description":"Segundos a esperar antes de reintentar.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"Falla del servidor, no del pedido: reintentar. Códigos posibles: `error_interno`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}}}}},"/ventas":{"get":{"operationId":"listarVentas","tags":["Ventas"],"summary":"Listar ventas con sus renglones","description":"Devuelve las ventas del negocio, de la más nueva a la más vieja, con los productos de cada una. Sin `desde`, las de los últimos 7 días. Sirve para pasar las ventas a otro sistema o armar reportes.","parameters":[{"name":"pagina","in":"query","required":false,"description":"Número de página, desde 1.","schema":{"type":"integer","minimum":1,"maximum":10000,"default":1}},{"name":"por_pagina","in":"query","required":false,"description":"Resultados por página, de 1 a 200.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"desde","in":"query","required":false,"description":"Desde esta fecha, en milisegundos desde 1970. Sin `desde`, los últimos 7 días.","schema":{"type":"integer","minimum":0}},{"name":"hasta","in":"query","required":false,"description":"Hasta esta fecha, en milisegundos desde 1970. Tiene que ser posterior a `desde`.","schema":{"type":"integer","minimum":0}},{"name":"estado","in":"query","required":false,"description":"Solo las completadas o solo las anuladas.","schema":{"type":"string","enum":["completada","anulada"]}}],"responses":{"200":{"description":"Una página de ventas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginaDeVentas"},"example":{"datos":[{"id":"5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d","fecha":1758585600000,"total":2400,"metodo_pago":"efectivo","estado":"completada","descuento":0,"monto_efectivo":null,"detalle":[{"producto_id":"7c1e2b1a-4f3d-4b8e-9a0c-2d5f6e7a8b9c","cantidad":2,"precio_unitario":1200,"subtotal":2400,"descuento":0}]}],"pagina":1,"por_pagina":50,"total":1,"desde":1757980800000}}}},"400":{"description":"Algún parámetro no es válido. Códigos posibles: `parametros_invalidos`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}},"401":{"description":"Falta la clave o es inválida o revocada. Códigos posibles: `clave_faltante`, `clave_invalida`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}},"403":{"description":"El plan del negocio no incluye la API (plan Distribuidora). Códigos posibles: `plan_sin_api`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}},"429":{"description":"Límite de pedidos: 60 por minuto por clave. Respetar `Retry-After`. Códigos posibles: `limite_de_pedidos`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}},"headers":{"Retry-After":{"description":"Segundos a esperar antes de reintentar.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"Falla del servidor, no del pedido: reintentar. Códigos posibles: `error_interno`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problema"}}}}}}}},"components":{"securitySchemes":{"claveApi":{"type":"http","scheme":"bearer","bearerFormat":"msk_ + 40 caracteres","description":"Authorization: Bearer msk_... — se crea en Configuración → Integraciones y se muestra una sola vez."}},"schemas":{"Problema":{"type":"object","description":"Error en formato Problem Details (RFC 9457), con `codigo` y `ayuda`.","required":["type","title","status","detail","codigo","ayuda"],"properties":{"type":{"type":"string","format":"uri","description":"Dónde está documentado este error."},"title":{"type":"string","description":"Resumen del tipo de error."},"status":{"type":"integer","description":"El mismo código HTTP de la respuesta."},"detail":{"type":"string","description":"Qué pasó en este pedido en particular."},"instance":{"type":"string","description":"La ruta pedida."},"codigo":{"$ref":"#/components/schemas/CodigoError"},"ayuda":{"type":"string","description":"Qué hacer para resolverlo."},"error":{"type":"string","description":"Igual a `detail` (compatibilidad con el resto de la aplicación)."}}},"CodigoError":{"type":"string","description":"`clave_faltante` (401): Falta la clave de API. `clave_invalida` (401): Clave de API inválida o revocada. `plan_sin_api` (403): El plan del negocio no incluye la API. `permiso_insuficiente` (403): La clave es de solo lectura. `limite_de_pedidos` (429): Demasiados pedidos. `json_invalido` (400): El cuerpo no es JSON. `datos_invalidos` (400): Datos inválidos. `parametros_invalidos` (400): Parámetros inválidos. `no_encontrado` (404): No encontrado. `conflicto` (409): Conflicto con otro dato. `ruta_inexistente` (404): Esa ruta no existe. `error_interno` (500): Error interno.","enum":["clave_faltante","clave_invalida","plan_sin_api","permiso_insuficiente","limite_de_pedidos","json_invalido","datos_invalidos","parametros_invalidos","no_encontrado","conflicto","ruta_inexistente","error_interno"]},"UnidadVenta":{"type":"string","enum":["unidad","kg","l","m"],"description":"En qué se vende: por unidad, por kilo, por litro o por metro. En kg/l/m el precio es el de 1 kilo/litro/metro y las cantidades tienen hasta 3 decimales."},"Permiso":{"type":"string","enum":["lectura","escritura"],"description":"`lectura` solo consulta; `escritura` además cambia precios y stock."},"Producto":{"type":"object","required":["id","nombre","codigo_barras","precio","costo","stock_actual","stock_minimo","categoria","activo","updated_at","unidad_venta"],"properties":{"id":{"type":"string","format":"uuid"},"nombre":{"type":"string"},"codigo_barras":{"type":["string","null"],"description":"EAN-13, UPC-A u otro; null si no tiene."},"precio":{"type":"number","description":"Precio de venta en pesos, IVA incluido (de 1 kilo/litro/metro si se vende así)."},"costo":{"type":"number","description":"Costo en pesos."},"stock_actual":{"type":"number","description":"En la unidad del producto (hasta 3 decimales en kg/l/m)."},"stock_minimo":{"type":"number"},"unidad_venta":{"$ref":"#/components/schemas/UnidadVenta"},"categoria":{"type":"string"},"activo":{"type":"boolean","description":"false si está dado de baja."},"updated_at":{"type":"integer","description":"Última modificación, en milisegundos desde 1970."}}},"RespuestaProducto":{"type":"object","required":["producto"],"properties":{"producto":{"$ref":"#/components/schemas/Producto"}}},"RenglonDeVenta":{"type":"object","required":["producto_id","cantidad","precio_unitario","subtotal","descuento"],"properties":{"producto_id":{"type":"string","format":"uuid"},"cantidad":{"type":"number","description":"Unidades, o kilos/litros/metros con hasta 3 decimales."},"precio_unitario":{"type":"number","description":"Precio cobrado por unidad (o por kilo/litro/metro), en pesos."},"subtotal":{"type":"number","description":"Lo cobrado por el renglón, en pesos."},"descuento":{"type":"number","description":"Descuento del renglón, en porcentaje."}}},"Venta":{"type":"object","required":["id","fecha","total","metodo_pago","estado","descuento","monto_efectivo","detalle"],"properties":{"id":{"type":"string","format":"uuid"},"fecha":{"type":"integer","description":"Milisegundos desde 1970."},"total":{"type":"number","description":"Total cobrado en pesos."},"metodo_pago":{"type":"string","enum":["efectivo","debito","credito","qr","mercadopago","transferencia","tarjeta","mixto","fiado"]},"estado":{"type":"string","enum":["completada","anulada"]},"descuento":{"type":"number","description":"Descuento de la venta, en porcentaje."},"monto_efectivo":{"type":["number","null"],"description":"Solo en una venta mixta: la parte en efectivo."},"detalle":{"type":"array","items":{"$ref":"#/components/schemas/RenglonDeVenta"}}}},"PaginaDeProductos":{"type":"object","required":["datos","pagina","por_pagina","total"],"properties":{"datos":{"type":"array","items":{"$ref":"#/components/schemas/Producto"}},"pagina":{"type":"integer"},"por_pagina":{"type":"integer"},"total":{"type":"integer","description":"Cantidad de resultados en todas las páginas."}}},"PaginaDeVentas":{"type":"object","required":["datos","pagina","por_pagina","total","desde"],"properties":{"datos":{"type":"array","items":{"$ref":"#/components/schemas/Venta"}},"pagina":{"type":"integer"},"por_pagina":{"type":"integer"},"total":{"type":"integer","description":"Cantidad de resultados en todas las páginas."},"desde":{"type":"integer","description":"La fecha desde la que se buscó (la pedida o la de hace 7 días)."}}}}}}