{
  "openapi": "3.1.0",
  "info": {
    "title": "GuatemalaPhotoStock Agent API",
    "version": "1.0.0",
    "summary": "Catálogo de fotografía de stock de Guatemala para agentes automáticos.",
    "description": "API de solo lectura sobre el catálogo de GuatemalaPhotoStock, más los endpoints de checkout agéntico (ACP/UCP/x402). El catálogo está indexado en español. Existe también un servidor MCP equivalente en https://guatemalaphotostock.com/mcp",
    "contact": {
      "name": "GuatemalaPhotoStock",
      "email": "info@guatemalaphotostock.com",
      "url": "https://guatemalaphotostock.com"
    },
    "license": {
      "name": "Condiciones de licencia de imagen",
      "url": "https://guatemalaphotostock.com/purchase.agreement.php"
    }
  },
  "servers": [
    { "url": "https://guatemalaphotostock.com", "description": "Producción" }
  ],
  "tags": [
    { "name": "catálogo", "description": "Búsqueda y consulta de fotografías" },
    { "name": "commerce", "description": "Cotización y compra de licencias" }
  ],
  "paths": {
    "/api/search": {
      "get": {
        "operationId": "searchPhotos",
        "tags": ["catálogo"],
        "summary": "Buscar fotografías de Guatemala",
        "description": "Busca en títulos, descripciones y palabras clave. Los términos deben ir en español.",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Término de búsqueda en español.", "example": "volcán de agua" },
          { "name": "orientation", "in": "query", "schema": { "type": "string", "enum": ["landscape", "portrait", "square"] } },
          { "name": "gallery_id", "in": "query", "schema": { "type": "integer" } },
          { "name": "min_width", "in": "query", "schema": { "type": "integer" }, "description": "Ancho mínimo del original en píxeles." },
          { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["relevance", "newest", "popular"], "default": "relevance" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }
        ],
        "responses": {
          "200": {
            "description": "Resultados de búsqueda",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": { "type": "integer" },
                    "limit": { "type": "integer" },
                    "offset": { "type": "integer" },
                    "query": { "type": "string" },
                    "results": { "type": "array", "items": { "$ref": "#/components/schemas/PhotoSummary" } }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/api/photo/{photo_id}": {
      "get": {
        "operationId": "getPhoto",
        "tags": ["catálogo"],
        "summary": "Ficha completa de una fotografía",
        "parameters": [
          { "name": "photo_id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 10851 }
        ],
        "responses": {
          "200": {
            "description": "Datos completos con palabras clave, galerías y licencias",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhotoDetail" } } }
          },
          "404": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/api/galleries": {
      "get": {
        "operationId": "listGalleries",
        "tags": ["catálogo"],
        "summary": "Listar galerías públicas",
        "responses": {
          "200": {
            "description": "Galerías y tamaño del catálogo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "galleries": { "type": "array", "items": { "$ref": "#/components/schemas/Gallery" } },
                    "catalog": { "type": "object" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/licenses": {
      "get": {
        "operationId": "listLicenses",
        "tags": ["catálogo"],
        "summary": "Tipos de licencia disponibles",
        "responses": { "200": { "description": "Licencias del sitio", "content": { "application/json": {} } } }
      }
    },
    "/api/stats": {
      "get": {
        "operationId": "getStats",
        "tags": ["catálogo"],
        "summary": "Tamaño del catálogo",
        "responses": { "200": { "description": "Conteos", "content": { "application/json": {} } } }
      }
    },
    "/feed/products.json": {
      "get": {
        "operationId": "getProductFeed",
        "tags": ["commerce"],
        "summary": "Feed de productos licenciables",
        "description": "Catálogo de licencias con precios y disponibilidad en vivo, compatible con ACP y UCP.",
        "parameters": [
          { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["json", "jsonl"], "default": "json" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 500, "maximum": 5000 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } },
          { "name": "updated_since", "in": "query", "schema": { "type": "string", "format": "date" } }
        ],
        "responses": { "200": { "description": "Feed de productos", "content": { "application/json": {} } } }
      }
    },
    "/checkout_sessions": {
      "post": {
        "operationId": "createCheckoutSession",
        "tags": ["commerce"],
        "summary": "Crear una sesión de compra",
        "security": [ {}, { "bearerAuth": [] } ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["items"],
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": ["photo_id", "variant_id"],
                      "properties": {
                        "photo_id": { "type": "integer" },
                        "variant_id": { "type": "integer" },
                        "quantity": { "type": "integer", "minimum": 1, "default": 1 }
                      }
                    }
                  },
                  "buyer": {
                    "type": "object",
                    "properties": {
                      "email": { "type": "string", "format": "email" },
                      "name": { "type": "string" }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Sesión creada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } },
          "422": { "$ref": "#/components/responses/Problem" }
        }
      }
    },
    "/checkout_sessions/{session_id}": {
      "get": {
        "operationId": "getCheckoutSession",
        "tags": ["commerce"],
        "summary": "Consultar una sesión",
        "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ],
        "responses": {
          "200": { "description": "Sesión", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } },
          "404": { "$ref": "#/components/responses/Problem" }
        }
      },
      "post": {
        "operationId": "updateCheckoutSession",
        "tags": ["commerce"],
        "summary": "Actualizar comprador o items",
        "security": [ {}, { "bearerAuth": [] } ],
        "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ],
        "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } },
        "responses": { "200": { "description": "Sesión actualizada", "content": { "application/json": {} } } }
      }
    },
    "/checkout_sessions/{session_id}/complete": {
      "post": {
        "operationId": "completeCheckoutSession",
        "tags": ["commerce"],
        "summary": "Completar la compra",
        "description": "Acepta prueba de pago x402 en la cabecera X-PAYMENT, o un token delegado en payment_data.token. Sin pasarela activa devuelve 202 con payment_url.",
        "security": [ {}, { "bearerAuth": [] } ],
        "parameters": [
          { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "X-PAYMENT", "in": "header", "schema": { "type": "string" }, "description": "Payload x402 en base64." }
        ],
        "responses": {
          "200": { "description": "Compra completada", "content": { "application/json": {} } },
          "202": { "description": "Pendiente de pago humano", "content": { "application/json": {} } },
          "402": { "description": "Pago requerido (x402)", "content": { "application/json": {} } }
        }
      }
    },
    "/checkout_sessions/{session_id}/cancel": {
      "post": {
        "operationId": "cancelCheckoutSession",
        "tags": ["commerce"],
        "summary": "Cancelar una sesión abierta",
        "security": [ {}, { "bearerAuth": [] } ],
        "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ],
        "responses": { "200": { "description": "Sesión cancelada", "content": { "application/json": {} } } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Token opcional del comercio para operar el checkout." }
    },
    "responses": {
      "Problem": {
        "description": "Error",
        "content": {
          "application/problem+json": {
            "schema": {
              "type": "object",
              "properties": {
                "type": { "type": "string" },
                "title": { "type": "string" },
                "status": { "type": "integer" },
                "detail": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "PhotoSummary": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "title": { "type": "string" },
          "description": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "thumbnail": { "type": "string", "format": "uri" },
          "preview": { "type": "string", "format": "uri" },
          "width_px": { "type": "integer" },
          "height_px": { "type": "integer" },
          "orientation": { "type": "string", "enum": ["landscape", "portrait", "square"] },
          "megapixels": { "type": "number" },
          "format": { "type": "string" },
          "date_added": { "type": "string", "format": "date-time" },
          "featured": { "type": "boolean" }
        }
      },
      "PhotoDetail": {
        "allOf": [
          { "$ref": "#/components/schemas/PhotoSummary" },
          {
            "type": "object",
            "properties": {
              "keywords": { "type": "array", "items": { "type": "string" } },
              "galleries": { "type": "array", "items": { "$ref": "#/components/schemas/Gallery" } },
              "licensing": { "type": "array", "items": { "$ref": "#/components/schemas/LicenseOption" } },
              "price_from": { "type": "number" },
              "currency": { "type": "string" },
              "location": {
                "type": "object",
                "properties": {
                  "latitude": { "type": "number" },
                  "longitude": { "type": "number" }
                }
              }
            }
          }
        ]
      },
      "LicenseOption": {
        "type": "object",
        "properties": {
          "variant_id": { "type": "integer" },
          "name": { "type": "string" },
          "max_width_px": { "type": "integer" },
          "max_height_px": { "type": "integer" },
          "price": { "type": "number" },
          "price_minor": { "type": "integer" },
          "currency": { "type": "string" },
          "credits": { "type": "integer" },
          "license": { "type": "string" },
          "license_id": { "type": "integer" },
          "availability": { "type": "string" },
          "delivery": { "type": "string" }
        }
      },
      "Gallery": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "photo_count": { "type": "integer" }
        }
      },
      "CheckoutSession": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "object": { "type": "string" },
          "status": { "type": "string", "enum": ["ready_for_payment", "requires_human_payment", "completed", "canceled"] },
          "currency": { "type": "string" },
          "items": { "type": "array", "items": { "type": "object" } },
          "totals": { "type": "object" },
          "totals_minor": { "type": "array", "items": { "type": "object" } },
          "buyer": { "type": "object" },
          "payment_url": { "type": "string", "format": "uri" },
          "payment_methods": { "type": "array", "items": { "type": "object" } },
          "created_at": { "type": "string", "format": "date-time" }
        }
      }
    }
  }
}