{
  "openapi": "3.1.0",
  "info": {
    "title": "Lidra SMM API",
    "version": "1.0.0",
    "description": "API de Lidra SMM. Todos los montos son enteros en centavos de pesos argentinos. Autenticación por API key en el header Authorization. Documentación completa: https://lidra.com.ar/desarrolladores",
    "contact": {
      "name": "Soporte de Lidra",
      "email": "soporte@lidra.com.ar"
    }
  },
  "servers": [
    {
      "url": "https://lidra.com.ar"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/links/detect": {
      "post": {
        "operationId": "detect_link",
        "summary": "Analizar un link",
        "description": "Lee un link de red social y devuelve de qué plataforma es, qué tipo de contenido, y qué métricas se le pueden comprar. Primer paso natural antes de buscar servicios.",
        "tags": [
          "Catálogo"
        ],
        "security": [
          {
            "bearerAuth": [
              "catalog:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "El link de la publicación o del perfil (Instagram, TikTok, YouTube…).",
                    "maxLength": 2000
                  }
                },
                "required": [
                  "url"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/v1/links/services": {
      "get": {
        "operationId": "services_for_link",
        "summary": "Servicios compatibles con un link",
        "description": "Dado un link, devuelve todos los servicios que se le pueden aplicar, con el precio del día en pesos. Es la forma más rápida de pasar de un link a algo comprable.",
        "tags": [
          "Catálogo"
        ],
        "security": [
          {
            "bearerAuth": [
              "catalog:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "El link para el que querés ver los servicios compatibles.",
            "schema": {
              "type": "string",
              "description": "El link para el que querés ver los servicios compatibles.",
              "maxLength": 2000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/services": {
      "get": {
        "operationId": "search_services",
        "summary": "Buscar servicios",
        "description": "Busca en el catálogo por plataforma, métrica, tipo de contenido o nombre. Devuelve el precio final en centavos de ARS por cada 1000 unidades.",
        "tags": [
          "Catálogo"
        ],
        "security": [
          {
            "bearerAuth": [
              "catalog:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "platform",
            "in": "query",
            "required": false,
            "description": "Filtrar por red social.",
            "schema": {
              "type": "string",
              "description": "Filtrar por red social.",
              "enum": [
                "instagram",
                "tiktok",
                "youtube",
                "facebook",
                "twitter",
                "spotify",
                "telegram",
                "twitch",
                "soundcloud",
                "linkedin",
                "discord",
                "otros"
              ]
            }
          },
          {
            "name": "metric",
            "in": "query",
            "required": false,
            "description": "Filtrar por métrica (seguidores, me gusta…).",
            "schema": {
              "type": "string",
              "description": "Filtrar por métrica (seguidores, me gusta…).",
              "enum": [
                "followers",
                "likes",
                "views",
                "comments",
                "shares",
                "subscribers",
                "plays",
                "saves",
                "members",
                "reach",
                "otros"
              ]
            }
          },
          {
            "name": "contentType",
            "in": "query",
            "required": false,
            "description": "Filtrar por tipo de contenido.",
            "schema": {
              "type": "string",
              "description": "Filtrar por tipo de contenido.",
              "enum": [
                "profile",
                "post",
                "video",
                "reel",
                "story",
                "channel",
                "track",
                "page",
                "group",
                "tweet",
                "otros"
              ]
            }
          },
          {
            "name": "query",
            "in": "query",
            "required": false,
            "description": "Búsqueda por nombre del servicio.",
            "schema": {
              "type": "string",
              "description": "Búsqueda por nombre del servicio.",
              "maxLength": 80
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Cuántos servicios devolver (1 a 100).",
            "schema": {
              "type": "integer",
              "description": "Cuántos servicios devolver (1 a 100).",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Desde qué posición, para paginar.",
            "schema": {
              "type": "integer",
              "description": "Desde qué posición, para paginar.",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/services/{serviceId}": {
      "get": {
        "operationId": "get_service",
        "summary": "Ver un servicio",
        "description": "Devuelve el detalle de un servicio: precio, mínimo, máximo y si admite reposición o entrega gradual.",
        "tags": [
          "Catálogo"
        ],
        "security": [
          {
            "bearerAuth": [
              "catalog:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "serviceId",
            "in": "path",
            "required": true,
            "description": "Identificador del servicio (empieza con \"svc_\").",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/quotes": {
      "post": {
        "operationId": "quote_order",
        "summary": "Cotizar un pedido",
        "description": "Calcula cuánto costaría un pedido sin crearlo ni cobrar nada. Usalo siempre antes de `create_order` para confirmarle el precio a la persona.",
        "tags": [
          "Catálogo"
        ],
        "security": [
          {
            "bearerAuth": [
              "catalog:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "serviceId": {
                    "type": "string",
                    "description": "Identificador del servicio a cotizar.",
                    "maxLength": 64
                  },
                  "quantity": {
                    "type": "integer",
                    "description": "Cantidad total que querés comprar.",
                    "minimum": 1,
                    "maximum": 100000000
                  },
                  "runs": {
                    "type": "integer",
                    "description": "Tandas de entrega gradual (dripfeed). Omitir para entrega de una vez.",
                    "minimum": 1,
                    "maximum": 1000
                  },
                  "intervalMinutes": {
                    "type": "integer",
                    "description": "Minutos entre tandas. Solo tiene sentido con `runs`.",
                    "minimum": 0,
                    "maximum": 10000
                  }
                },
                "required": [
                  "serviceId",
                  "quantity"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/v1/orders": {
      "post": {
        "operationId": "create_order",
        "summary": "Crear un pedido",
        "description": "Crea un pedido y COBRA el saldo de la billetera al instante. Confirmá el precio con `quote_order` antes de llamar a esto. El pedido vuelve en estado `pending`; el avance se consulta con `get_order`.",
        "tags": [
          "Pedidos"
        ],
        "security": [
          {
            "bearerAuth": [
              "orders:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "serviceId": {
                    "type": "string",
                    "description": "Identificador del servicio.",
                    "maxLength": 64
                  },
                  "link": {
                    "type": "string",
                    "description": "Link del perfil o la publicación que recibe el servicio.",
                    "maxLength": 2000
                  },
                  "quantity": {
                    "type": "integer",
                    "description": "Cantidad total a entregar.",
                    "minimum": 1,
                    "maximum": 100000000
                  },
                  "runs": {
                    "type": "integer",
                    "description": "Tandas de entrega gradual (dripfeed).",
                    "minimum": 1,
                    "maximum": 1000
                  },
                  "intervalMinutes": {
                    "type": "integer",
                    "description": "Minutos entre tandas.",
                    "minimum": 0,
                    "maximum": 10000
                  },
                  "comments": {
                    "type": "array",
                    "description": "Comentarios a publicar, uno por elemento (solo servicios de comentarios).",
                    "items": {
                      "type": "string",
                      "maxLength": 500
                    },
                    "maxItems": 1000
                  },
                  "clientId": {
                    "type": "string",
                    "description": "Cliente del CRM al que imputar el pedido.",
                    "maxLength": 64
                  },
                  "resellPriceArsCents": {
                    "type": "integer",
                    "description": "Lo que le cobrás a tu cliente, en centavos de ARS. Solo para tu control.",
                    "minimum": 0
                  },
                  "idempotencyKey": {
                    "type": "string",
                    "description": "Clave para que un reintento no duplique el pedido.",
                    "maxLength": 64
                  }
                },
                "required": [
                  "serviceId",
                  "link",
                  "quantity"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Clave única del pedido. Reintentar con la misma clave devuelve el pedido original en vez de cobrar de nuevo.",
            "schema": {
              "type": "string",
              "maxLength": 64
            }
          }
        ]
      },
      "get": {
        "operationId": "list_orders",
        "summary": "Listar pedidos",
        "description": "Devuelve tus pedidos, con filtros por estado, plataforma o cliente.",
        "tags": [
          "Pedidos"
        ],
        "security": [
          {
            "bearerAuth": [
              "orders:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filtrar por estado.",
            "schema": {
              "type": "string",
              "description": "Filtrar por estado.",
              "enum": [
                "pending",
                "processing",
                "completed",
                "partial",
                "canceled",
                "refunded",
                "failed"
              ]
            }
          },
          {
            "name": "platform",
            "in": "query",
            "required": false,
            "description": "Filtrar por red social.",
            "schema": {
              "type": "string",
              "description": "Filtrar por red social.",
              "enum": [
                "instagram",
                "tiktok",
                "youtube",
                "facebook",
                "twitter",
                "spotify",
                "telegram",
                "twitch",
                "soundcloud",
                "linkedin",
                "discord",
                "otros"
              ]
            }
          },
          {
            "name": "clientId",
            "in": "query",
            "required": false,
            "description": "Filtrar por cliente del CRM.",
            "schema": {
              "type": "string",
              "description": "Filtrar por cliente del CRM.",
              "maxLength": 64
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Cuántos pedidos devolver (1 a 100).",
            "schema": {
              "type": "integer",
              "description": "Cuántos pedidos devolver (1 a 100).",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Desde qué posición, para paginar.",
            "schema": {
              "type": "integer",
              "description": "Desde qué posición, para paginar.",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/orders/{orderId}": {
      "get": {
        "operationId": "get_order",
        "summary": "Ver un pedido",
        "description": "Devuelve un pedido con su estado, lo entregado y lo que falta.",
        "tags": [
          "Pedidos"
        ],
        "security": [
          {
            "bearerAuth": [
              "orders:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "required": true,
            "description": "Identificador del pedido.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/orders/status": {
      "post": {
        "operationId": "get_orders_status",
        "summary": "Estado de varios pedidos",
        "description": "Consulta hasta 100 pedidos de una sola vez. Es la forma correcta de seguir el avance de muchos pedidos sin gastar el límite de peticiones.",
        "tags": [
          "Pedidos"
        ],
        "security": [
          {
            "bearerAuth": [
              "orders:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "orderIds": {
                    "type": "array",
                    "description": "Identificadores de pedidos (hasta 100). Es la forma barata de seguir muchos pedidos a la vez.",
                    "items": {
                      "type": "string",
                      "maxLength": 64
                    },
                    "maxItems": 100
                  }
                },
                "required": [
                  "orderIds"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/v1/orders/{orderId}/cancel": {
      "post": {
        "operationId": "cancel_order",
        "summary": "Cancelar un pedido",
        "description": "Cancela un pedido que todavía no empezó a entregarse y reintegra el saldo. Si la entrega ya arrancó, no se puede: hay que abrir una consulta de soporte.",
        "tags": [
          "Pedidos"
        ],
        "security": [
          {
            "bearerAuth": [
              "orders:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "required": true,
            "description": "Identificador del pedido.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/orders/{orderId}/refill": {
      "post": {
        "operationId": "request_refill",
        "summary": "Pedir reposición",
        "description": "Pide la reposición de un pedido completado, si el servicio la admite (por ejemplo, seguidores que se cayeron). Se puede pedir una sola vez por pedido.",
        "tags": [
          "Pedidos"
        ],
        "security": [
          {
            "bearerAuth": [
              "orders:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "required": true,
            "description": "Identificador del pedido.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "get_refill_status",
        "summary": "Estado de la reposición",
        "description": "Devuelve si la reposición de un pedido está pedida, en curso, completada o rechazada.",
        "tags": [
          "Pedidos"
        ],
        "security": [
          {
            "bearerAuth": [
              "orders:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "required": true,
            "description": "Identificador del pedido.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/wallet": {
      "get": {
        "operationId": "get_balance",
        "summary": "Ver el saldo",
        "description": "Devuelve el saldo disponible en la billetera, en centavos de ARS.",
        "tags": [
          "Billetera"
        ],
        "security": [
          {
            "bearerAuth": [
              "wallet:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/wallet/transactions": {
      "get": {
        "operationId": "list_transactions",
        "summary": "Listar movimientos",
        "description": "Devuelve los movimientos de la billetera: recargas, cobros de pedidos, reintegros y ajustes.",
        "tags": [
          "Billetera"
        ],
        "security": [
          {
            "bearerAuth": [
              "wallet:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Cuántos movimientos devolver (1 a 100).",
            "schema": {
              "type": "integer",
              "description": "Cuántos movimientos devolver (1 a 100).",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/wallet/topups": {
      "post": {
        "operationId": "create_topup",
        "summary": "Generar una recarga",
        "description": "Crea un link de pago de Mercado Pago para cargar saldo. Devuelve la URL; el saldo se acredita recién cuando el pago se aprueba.",
        "tags": [
          "Billetera"
        ],
        "security": [
          {
            "bearerAuth": [
              "wallet:topup"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "amountArsCents": {
                    "type": "integer",
                    "description": "Cuánto cargar, en centavos de ARS (mínimo 50000, máximo 100000000).",
                    "minimum": 50000,
                    "maximum": 100000000
                  }
                },
                "required": [
                  "amountArsCents"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/v1/clients": {
      "get": {
        "operationId": "list_clients",
        "summary": "Listar clientes",
        "description": "Devuelve los clientes de tu CRM, con cuántos pedidos hizo cada uno y cuánto gastó.",
        "tags": [
          "Clientes"
        ],
        "security": [
          {
            "bearerAuth": [
              "clients:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "create_client",
        "summary": "Crear un cliente",
        "description": "Agrega un cliente a tu CRM para imputarle pedidos.",
        "tags": [
          "Clientes"
        ],
        "security": [
          {
            "bearerAuth": [
              "clients:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Nombre del cliente.",
                    "minLength": 1,
                    "maxLength": 120
                  },
                  "folderId": {
                    "type": "string",
                    "description": "Carpeta donde guardarlo. Si se omite, va a la carpeta por defecto.",
                    "maxLength": 64
                  },
                  "handle": {
                    "type": "string",
                    "description": "Usuario o arroba del cliente.",
                    "maxLength": 120
                  },
                  "notes": {
                    "type": "string",
                    "description": "Notas privadas tuyas.",
                    "maxLength": 2000
                  }
                },
                "required": [
                  "name"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/v1/folders": {
      "get": {
        "operationId": "list_folders",
        "summary": "Listar carpetas",
        "description": "Devuelve las carpetas con las que organizás tus clientes.",
        "tags": [
          "Clientes"
        ],
        "security": [
          {
            "bearerAuth": [
              "clients:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "create_folder",
        "summary": "Crear una carpeta",
        "description": "Crea una carpeta para agrupar clientes.",
        "tags": [
          "Clientes"
        ],
        "security": [
          {
            "bearerAuth": [
              "clients:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Nombre de la carpeta.",
                    "minLength": 1,
                    "maxLength": 80
                  }
                },
                "required": [
                  "name"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/v1/tickets": {
      "get": {
        "operationId": "list_tickets",
        "summary": "Listar consultas de soporte",
        "description": "Devuelve tus consultas de soporte con todos sus mensajes.",
        "tags": [
          "Soporte"
        ],
        "security": [
          {
            "bearerAuth": [
              "tickets:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "create_ticket",
        "summary": "Abrir una consulta de soporte",
        "description": "Abre una consulta de soporte, opcionalmente asociada a un pedido.",
        "tags": [
          "Soporte"
        ],
        "security": [
          {
            "bearerAuth": [
              "tickets:write"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "subject": {
                    "type": "string",
                    "description": "Asunto de la consulta.",
                    "minLength": 1,
                    "maxLength": 140
                  },
                  "body": {
                    "type": "string",
                    "description": "El mensaje.",
                    "minLength": 1,
                    "maxLength": 4000
                  },
                  "orderId": {
                    "type": "string",
                    "description": "Pedido al que se refiere la consulta, si aplica.",
                    "maxLength": 64
                  }
                },
                "required": [
                  "subject",
                  "body"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/v1/tickets/{ticketId}/replies": {
      "post": {
        "operationId": "reply_ticket",
        "summary": "Responder una consulta",
        "description": "Agrega un mensaje tuyo a una consulta existente. Si estaba cerrada, se reabre.",
        "tags": [
          "Soporte"
        ],
        "security": [
          {
            "bearerAuth": [
              "tickets:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "ticketId",
            "in": "path",
            "required": true,
            "description": "Identificador de la consulta.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "string",
                    "description": "Tu respuesta.",
                    "minLength": 1,
                    "maxLength": 4000
                  }
                },
                "required": [
                  "body"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/v1/me": {
      "get": {
        "operationId": "get_profile",
        "summary": "Ver tu perfil",
        "description": "Devuelve tu email, tu nombre y tu saldo.",
        "tags": [
          "Cuenta"
        ],
        "security": [
          {
            "bearerAuth": [
              "profile:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/status": {
      "get": {
        "operationId": "get_api_status",
        "summary": "Estado de la API",
        "description": "Confirma que la API key funciona y devuelve qué permisos tiene. No necesita ningún permiso.",
        "tags": [
          "Cuenta"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operación exitosa"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key generada en Mi cuenta → Desarrollador. Empieza con `lidra_sk_`. Requiere tener activo el modo desarrollador."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Código estable del error."
              },
              "message": {
                "type": "string",
                "description": "Explicación en castellano."
              },
              "details": {
                "type": "object",
                "additionalProperties": true
              },
              "docs": {
                "type": "string",
                "format": "uri"
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "error"
        ]
      }
    }
  },
  "x-scopes": {
    "catalog:read": true,
    "orders:read": true,
    "orders:write": true,
    "wallet:read": true,
    "wallet:topup": true,
    "clients:read": true,
    "clients:write": true,
    "tickets:read": true,
    "tickets:write": true,
    "profile:read": true
  }
}