{
  "openapi": "3.1.0",
  "info": {
    "title": "NAO API",
    "version": "0.1.0",
    "description": "API abierta de NAO, el marketplace de México hecho para bots (fase 1: Guadalajara). Sin llave. Las mismas capacidades están en el servidor MCP https://nao-gdl.vercel.app/api/mcp. Demo de NAO: todos los pedidos son de prueba, no se cobra nada y nadie entrega nada. Los negocios son de ejemplo.",
    "contact": {
      "url": "https://nao-gdl.vercel.app/agentes"
    }
  },
  "servers": [
    {
      "url": "https://nao-gdl.vercel.app"
    }
  ],
  "paths": {
    "/api/v1/productos": {
      "get": {
        "operationId": "buscar_productos",
        "summary": "Buscar productos",
        "description": "Con colonia o cp solo devuelve lo que sí llega ahí (tienditas: 2 km con repartidor de colonia).",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Texto libre: 'leche', 'tenis'."
          },
          {
            "name": "categoria",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "hogar",
                "moda",
                "cafe-cocina",
                "electronica",
                "papeleria",
                "abarrotes",
                "bebidas",
                "panaderia",
                "botanas",
                "limpieza",
                "frutas-verduras",
                "mascotas"
              ]
            }
          },
          {
            "name": "colonia",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "example": "Santa Tere"
          },
          {
            "name": "cp",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "example": "44600"
          },
          {
            "name": "precio_max",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "vendedor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "id o slug del vendedor/tiendita"
          },
          {
            "name": "limite",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Resultados",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Busqueda"
                }
              }
            }
          },
          "400": {
            "description": "Error en español",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/productos/{id}": {
      "get": {
        "operationId": "ver_producto",
        "summary": "Ver producto",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "id (p-...) o slug"
          }
        ],
        "responses": {
          "200": {
            "description": "Producto",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Producto"
                }
              }
            }
          },
          "404": {
            "description": "Error en español",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tienditas": {
      "get": {
        "operationId": "buscar_tienditas_cerca",
        "summary": "Tienditas que entregan en tu colonia",
        "parameters": [
          {
            "name": "colonia",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cp",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tienditas ordenadas por distancia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Error en español",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tienditas/{id}": {
      "get": {
        "operationId": "ver_tiendita",
        "summary": "Ficha y catálogo de una tiendita o vendedor",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "id (t-.../v-...) o slug"
          }
        ],
        "responses": {
          "200": {
            "description": "Tiendita",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Error en español",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/pedidos": {
      "post": {
        "operationId": "crear_pedido",
        "summary": "Crear pedido de PRUEBA (sin cobro)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NuevoPedido"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Pedido creado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pedido"
                }
              }
            }
          },
          "400": {
            "description": "Error en español",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error en español",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Error en español",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/pedidos/{id}": {
      "get": {
        "operationId": "estado_pedido",
        "summary": "Estado de un pedido",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "NAO-XXXXXX"
          }
        ],
        "responses": {
          "200": {
            "description": "Pedido",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pedido"
                }
              }
            }
          },
          "404": {
            "description": "Error en español",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "Producto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "nombre": {
            "type": "string"
          },
          "descripcion": {
            "type": "string"
          },
          "categoria": {
            "type": "string"
          },
          "precio_mxn": {
            "type": "number"
          },
          "moneda": {
            "type": "string",
            "const": "MXN"
          },
          "disponible": {
            "type": "boolean"
          },
          "stock": {
            "type": "integer"
          },
          "imagen": {
            "type": "string",
            "format": "uri"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "vendedor": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "nombre": {
                "type": "string"
              },
              "tipo": {
                "type": "string",
                "enum": [
                  "vendedor",
                  "tiendita"
                ]
              },
              "colonia": {
                "type": "string"
              },
              "url": {
                "type": "string"
              }
            }
          },
          "entrega": {
            "type": "object",
            "description": "Tipo, costo, radio y si llega a tu colonia."
          },
          "demo": {
            "type": "boolean"
          }
        }
      },
      "Busqueda": {
        "type": "object",
        "properties": {
          "aviso": {
            "type": "string"
          },
          "ubicacion": {
            "type": [
              "object",
              "null"
            ]
          },
          "total": {
            "type": "integer"
          },
          "resultados": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Producto"
            }
          },
          "siguiente_paso": {
            "type": "string"
          }
        }
      },
      "NuevoPedido": {
        "type": "object",
        "required": [
          "productos"
        ],
        "properties": {
          "productos": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "items": {
              "type": "object",
              "required": [
                "producto_id"
              ],
              "properties": {
                "producto_id": {
                  "type": "string"
                },
                "cantidad": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 20,
                  "default": 1
                }
              }
            }
          },
          "colonia": {
            "type": "string",
            "example": "Santa Tere"
          },
          "codigo_postal": {
            "type": "string",
            "example": "44600"
          },
          "referencia": {
            "type": "string"
          },
          "notas": {
            "type": "string"
          },
          "agente": {
            "type": "string",
            "example": "Claude"
          },
          "comprador": {
            "type": "string",
            "description": "Código del panel de la persona; si falta, va al panel demo."
          }
        }
      },
      "Pedido": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "estado": {
            "type": "string",
            "enum": [
              "recibido",
              "confirmado",
              "en_camino",
              "entregado",
              "cancelado"
            ]
          },
          "prueba": {
            "type": "boolean",
            "const": true
          },
          "total_mxn": {
            "type": "number"
          },
          "envio_mxn": {
            "type": "number"
          },
          "subtotal_mxn": {
            "type": "number"
          },
          "productos": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "seguimiento": {
            "type": "string",
            "format": "uri"
          },
          "panel_del_comprador": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    }
  }
}