{
    "openapi": "3.1.0",
    "info": {
        "title": "Recasound Agent API",
        "version": "1.0.0",
        "description": "Catálogo y contratación programática de infraestructura de audio de Recasound. La API expone productos agent_visible aunque no formen parte de la web humana; solo los productos agent_orderable pueden contratarse.",
        "contact": {
            "email": "info@recasound.es",
            "url": "https://recasound.es/"
        },
        "x-guidance": "Discover products, pricing and availability first. Use POST /quotes for a technical quote when required, then POST /orders with the selected product and parameters. The order endpoint returns HTTP 402 with PAYMENT-REQUIRED before any service is provisioned. Provisioning occurs only after x402 verification and settlement."
    },
    "servers": [
        {
            "url": "https://recasound.es/api/v1"
        }
    ],
    "externalDocs": {
        "description": "Arquitectura y estado de implementación",
        "url": "https://www.recasound.es/"
    },
    "tags": [
        {
            "name": "Discovery",
            "description": "Catálogo, precios y disponibilidad."
        },
        {
            "name": "Orders",
            "description": "Pedidos de agentes protegidos por Bearer y confirmados mediante x402 v2."
        },
        {
            "name": "Services",
            "description": "Estado, consumo y ciclo de vida de un servicio provisionado."
        }
    ],
    "paths": {
        "/health": {
            "get": {
                "tags": [
                    "Discovery"
                ],
                "operationId": "getHealth",
                "summary": "Comprueba la disponibilidad de la API",
                "responses": {
                    "200": {
                        "description": "API disponible",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Health"
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/products": {
            "get": {
                "tags": [
                    "Discovery"
                ],
                "operationId": "listProducts",
                "summary": "Lista los productos de audio",
                "responses": {
                    "200": {
                        "description": "Catálogo machine-readable",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProductList"
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/products/{product_id}": {
            "get": {
                "tags": [
                    "Discovery"
                ],
                "operationId": "getProduct",
                "summary": "Obtiene un producto concreto",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ProductId"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Producto",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "ok",
                                        "product"
                                    ],
                                    "properties": {
                                        "ok": {
                                            "const": true
                                        },
                                        "product": {
                                            "$ref": "#/components/schemas/Product"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": []
            }
        },
        "/pricing": {
            "get": {
                "tags": [
                    "Discovery"
                ],
                "operationId": "getPricing",
                "summary": "Devuelve precios y modalidad de cobro",
                "responses": {
                    "200": {
                        "description": "Precios actuales y productos en preparación",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Pricing"
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/availability": {
            "get": {
                "tags": [
                    "Discovery"
                ],
                "operationId": "getAvailability",
                "summary": "Indica qué se puede contratar ahora",
                "responses": {
                    "200": {
                        "description": "Disponibilidad por producto",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Availability"
                                }
                            }
                        }
                    }
                },
                "security": []
            }
        },
        "/quotes": {
            "post": {
                "tags": [
                    "Discovery"
                ],
                "operationId": "createQuote",
                "summary": "Calcula una cotización parametrizada sin crear un pedido",
                "description": "Devuelve el precio exacto en USDC, su desglose y la caducidad de la cotización. Los productos pueden seguir con agent_orderable=false mientras se valida la activación comercial.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/OptionalIdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/QuoteRequest"
                            },
                            "example": {
                                "product_id": "instant-stream",
                                "parameters": {
                                    "duration_hours": 2,
                                    "max_listeners": 25,
                                    "bitrate_kbps": 128,
                                    "transfer_gb": 1.5
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Cotización exacta",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/QuoteResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "409": {
                        "$ref": "#/components/responses/Conflict"
                    },
                    "422": {
                        "$ref": "#/components/responses/InvalidRequest"
                    }
                }
            }
        },
        "/orders": {
            "post": {
                "tags": [
                    "Orders"
                ],
                "operationId": "createOrder",
                "summary": "Solicita un producto mediante pago machine-to-machine",
                "security": [],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "product_id",
                                    "email",
                                    "station_name"
                                ],
                                "properties": {
                                    "product_id": {
                                        "type": "string",
                                        "description": "Identificador real del producto del catálogo de agentes.",
                                        "example": "instant-stream"
                                    },
                                    "billing": {
                                        "type": "string",
                                        "enum": [
                                            "monthly",
                                            "annual",
                                            "one_time",
                                            "quote"
                                        ],
                                        "default": "one_time",
                                        "description": "Modalidad aceptada por el producto."
                                    },
                                    "quantity": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 1,
                                        "default": 1
                                    },
                                    "contact_name": {
                                        "type": "string",
                                        "maxLength": 120
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email"
                                    },
                                    "station_name": {
                                        "type": "string",
                                        "maxLength": 120
                                    },
                                    "parameters": {
                                        "type": "object",
                                        "description": "Parámetros técnicos que procesa el producto, como duration_hours, max_listeners y bitrate_kbps.",
                                        "additionalProperties": true
                                    },
                                    "metadata": {
                                        "type": "object",
                                        "additionalProperties": {
                                            "type": "string",
                                            "maxLength": 200
                                        }
                                    }
                                },
                                "additionalProperties": false
                            },
                            "example": {
                                "product_id": "instant-stream",
                                "billing": "quote",
                                "contact_name": "Software Agent",
                                "email": "operador@example.com",
                                "station_name": "Evento Demo",
                                "parameters": {
                                    "duration_hours": 2,
                                    "max_listeners": 50,
                                    "bitrate_kbps": 128
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Pago confirmado y servicio creado o recuperado",
                        "headers": {
                            "PAYMENT-RESPONSE": {
                                "schema": {
                                    "type": "string"
                                },
                                "description": "SettlementResponse de x402 v2 codificado en Base64 JSON."
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/OrderResponse"
                                }
                            }
                        }
                    },
                    "402": {
                        "description": "Pago requerido por x402",
                        "headers": {
                            "PAYMENT-REQUIRED": {
                                "schema": {
                                    "type": "string"
                                },
                                "description": "PaymentRequired de x402 v2 codificado en Base64 JSON."
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "409": {
                        "$ref": "#/components/responses/Conflict"
                    },
                    "503": {
                        "$ref": "#/components/responses/NotConfigured"
                    }
                },
                "x-payment-info": {
                    "protocols": [
                        {
                            "x402": {}
                        }
                    ],
                    "price": {
                        "mode": "dynamic",
                        "currency": "USD",
                        "min": "0.27",
                        "max": "16.15"
                    },
                    "network": "eip155:8453"
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "agent-api-key"
            }
        },
        "parameters": {
            "ProductId": {
                "name": "product_id",
                "in": "path",
                "required": true,
                "schema": {
                    "type": "string",
                    "pattern": "^[a-z0-9][a-z0-9-]{1,80}$"
                }
            },
            "OrderId": {
                "name": "order_id",
                "in": "path",
                "required": true,
                "schema": {
                    "type": "string",
                    "pattern": "^ra_[a-zA-Z0-9_-]{8,120}$"
                }
            },
            "ServiceId": {
                "name": "service_id",
                "in": "path",
                "required": true,
                "schema": {
                    "type": "string",
                    "pattern": "^[a-zA-Z0-9_-]{8,120}$"
                }
            },
            "IdempotencyKey": {
                "name": "Idempotency-Key",
                "in": "header",
                "required": true,
                "schema": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255
                },
                "description": "Clave estable para que los reintentos no creen pedidos o pagos duplicados."
            },
            "OptionalIdempotencyKey": {
                "name": "Idempotency-Key",
                "in": "header",
                "required": false,
                "schema": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255
                },
                "description": "Opcional para mantener estable el identificador de la cotización al reintentarlo."
            },
            "PaymentSignature": {
                "name": "PAYMENT-SIGNATURE",
                "in": "header",
                "required": false,
                "schema": {
                    "type": "string"
                },
                "description": "Payload de pago x402 v2 codificado en Base64 JSON."
            }
        },
        "schemas": {
            "Price": {
                "type": "object",
                "properties": {
                    "basis": {
                        "type": "string",
                        "enum": [
                            "subscription",
                            "one_time",
                            "quote"
                        ]
                    },
                    "currency": {
                        "type": "string",
                        "example": "USDC"
                    },
                    "monthly": {
                        "type": "number",
                        "example": 20
                    },
                    "annual": {
                        "type": "number",
                        "example": 200
                    },
                    "amount": {
                        "type": "number",
                        "example": 9.9000000000000003552713678800500929355621337890625
                    },
                    "decimals": {
                        "type": "integer",
                        "example": 6
                    },
                    "base_atomic": {
                        "type": "string",
                        "pattern": "^[0-9]+$"
                    },
                    "per_hour_atomic": {
                        "type": "string",
                        "pattern": "^[0-9]+$"
                    },
                    "per_gb_atomic": {
                        "type": "string",
                        "pattern": "^[0-9]+$"
                    },
                    "packages": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "formula": {
                        "type": "string"
                    },
                    "transfer_unit": {
                        "type": "string"
                    },
                    "transfer_policy": {
                        "type": "string"
                    },
                    "pricing_status": {
                        "type": "string",
                        "enum": [
                            "approved",
                            "pending"
                        ]
                    }
                },
                "additionalProperties": true
            },
            "Product": {
                "type": "object",
                "required": [
                    "id",
                    "name",
                    "type",
                    "billing_type",
                    "status",
                    "pricing_status",
                    "orderable",
                    "pricing",
                    "parameters",
                    "limits",
                    "payment"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "radio-local-plus"
                    },
                    "name": {
                        "type": "string",
                        "example": "Radio Local Plus"
                    },
                    "type": {
                        "type": "string",
                        "example": "radio_streaming_subscription"
                    },
                    "billing_type": {
                        "type": "string",
                        "enum": [
                            "subscription",
                            "quote",
                            "one_time"
                        ]
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "available",
                            "ready",
                            "pending",
                            "planned",
                            "disabled"
                        ]
                    },
                    "pricing_status": {
                        "type": "string",
                        "enum": [
                            "approved",
                            "pending"
                        ]
                    },
                    "visibility": {
                        "type": "object",
                        "required": [
                            "human",
                            "agent"
                        ],
                        "properties": {
                            "human": {
                                "type": "boolean"
                            },
                            "agent": {
                                "type": "boolean"
                            }
                        }
                    },
                    "orderable": {
                        "type": "object",
                        "properties": {
                            "human": {
                                "type": "boolean"
                            },
                            "agent": {
                                "type": "boolean"
                            }
                        }
                    },
                    "description": {
                        "type": "string"
                    },
                    "pricing": {
                        "$ref": "#/components/schemas/Price"
                    },
                    "parameters": {
                        "type": "object",
                        "description": "Parámetros admitidos por un recurso técnico. La presencia no implica que el producto esté todavía orderable.",
                        "additionalProperties": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "limits": {
                        "type": "object",
                        "additionalProperties": true
                    },
                    "fulfillment": {
                        "type": "object",
                        "additionalProperties": true
                    },
                    "payment": {
                        "type": "object",
                        "additionalProperties": true
                    }
                }
            },
            "ProductList": {
                "type": "object",
                "required": [
                    "ok",
                    "products"
                ],
                "properties": {
                    "ok": {
                        "const": true
                    },
                    "catalog_version": {
                        "type": "integer"
                    },
                    "count": {
                        "type": "integer"
                    },
                    "products": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Product"
                        }
                    }
                }
            },
            "Pricing": {
                "type": "object",
                "required": [
                    "ok",
                    "prices"
                ],
                "properties": {
                    "ok": {
                        "const": true
                    },
                    "currency": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "currencies": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "prices": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            },
            "Availability": {
                "type": "object",
                "required": [
                    "ok",
                    "human_checkout",
                    "agent_checkout"
                ],
                "properties": {
                    "ok": {
                        "const": true
                    },
                    "provider": {
                        "type": "string"
                    },
                    "region": {
                        "type": "string"
                    },
                    "human_checkout": {
                        "type": "boolean"
                    },
                    "agent_checkout": {
                        "type": "object",
                        "additionalProperties": true
                    },
                    "products": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    }
                }
            },
            "Health": {
                "type": "object",
                "required": [
                    "ok",
                    "service",
                    "version",
                    "status",
                    "machine_payment"
                ],
                "properties": {
                    "ok": {
                        "const": true
                    },
                    "service": {
                        "type": "string"
                    },
                    "version": {
                        "type": "string"
                    },
                    "status": {
                        "type": "string"
                    },
                    "provider": {
                        "type": "string"
                    },
                    "machine_payment": {
                        "type": "object",
                        "additionalProperties": true
                    },
                    "links": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "string"
                        }
                    }
                }
            },
            "QuoteRequest": {
                "type": "object",
                "required": [
                    "product_id"
                ],
                "properties": {
                    "product_id": {
                        "type": "string",
                        "example": "instant-stream"
                    },
                    "parameters": {
                        "type": "object",
                        "description": "Parámetros del recurso técnico. Los nombres dependen del producto.",
                        "additionalProperties": true
                    }
                },
                "additionalProperties": false
            },
            "QuoteResponse": {
                "type": "object",
                "required": [
                    "ok",
                    "quote"
                ],
                "properties": {
                    "ok": {
                        "const": true
                    },
                    "quote": {
                        "type": "object",
                        "required": [
                            "id",
                            "product",
                            "configuration",
                            "price",
                            "currency",
                            "breakdown",
                            "expires_at_quote"
                        ],
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "product": {
                                "type": "object",
                                "additionalProperties": true
                            },
                            "configuration": {
                                "type": "object",
                                "additionalProperties": true
                            },
                            "price": {
                                "type": "object",
                                "required": [
                                    "amount",
                                    "amount_atomic",
                                    "currency",
                                    "decimals"
                                ],
                                "properties": {
                                    "amount": {
                                        "type": "string",
                                        "pattern": "^[0-9]+(?:\\.[0-9]+)?$"
                                    },
                                    "amount_atomic": {
                                        "type": "string",
                                        "pattern": "^[0-9]+$"
                                    },
                                    "currency": {
                                        "const": "USDC"
                                    },
                                    "decimals": {
                                        "const": 6
                                    }
                                }
                            },
                            "currency": {
                                "const": "USDC"
                            },
                            "breakdown": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "additionalProperties": true
                                }
                            },
                            "formula": {
                                "type": "string"
                            },
                            "transfer_policy": {
                                "type": "string"
                            },
                            "expires_at_quote": {
                                "type": "string",
                                "format": "date-time"
                            },
                            "pricing_status": {
                                "type": "string",
                                "enum": [
                                    "approved",
                                    "pending"
                                ]
                            },
                            "agent_orderable": {
                                "type": "boolean"
                            }
                        }
                    },
                    "idempotency": {
                        "type": "object",
                        "additionalProperties": true
                    }
                }
            },
            "CreateOrderRequest": {
                "type": "object",
                "required": [
                    "product_id",
                    "email",
                    "station_name"
                ],
                "properties": {
                    "product_id": {
                        "type": "string",
                        "example": "radio-local-plus"
                    },
                    "billing": {
                        "type": "string",
                        "enum": [
                            "monthly",
                            "annual",
                            "one_time",
                            "quote"
                        ],
                        "default": "monthly"
                    },
                    "quantity": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 1,
                        "default": 1
                    },
                    "contact_name": {
                        "type": "string",
                        "maxLength": 120
                    },
                    "email": {
                        "type": "string",
                        "format": "email"
                    },
                    "station_name": {
                        "type": "string",
                        "maxLength": 120
                    },
                    "parameters": {
                        "type": "object",
                        "description": "Parámetros del recurso técnico. Los nombres dependen del producto.",
                        "additionalProperties": true
                    },
                    "metadata": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "string",
                            "maxLength": 200
                        }
                    }
                },
                "additionalProperties": false
            },
            "OrderResponse": {
                "type": "object",
                "properties": {
                    "ok": {
                        "const": true
                    },
                    "order": {
                        "type": "object",
                        "additionalProperties": true
                    },
                    "service": {
                        "$ref": "#/components/schemas/Service"
                    },
                    "idempotent_replay": {
                        "type": "boolean"
                    }
                }
            },
            "Service": {
                "type": "object",
                "required": [
                    "service_id",
                    "status",
                    "stream_url",
                    "limits"
                ],
                "properties": {
                    "service_id": {
                        "type": "string"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "pending",
                            "provisioning",
                            "active",
                            "failed",
                            "suspended",
                            "expired"
                        ]
                    },
                    "stream_url": {
                        "type": "string"
                    },
                    "broadcast_url": {
                        "type": "string"
                    },
                    "expires_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "limits": {
                        "type": "object",
                        "additionalProperties": true
                    },
                    "endpoints": {
                        "type": "object",
                        "additionalProperties": true
                    }
                },
                "additionalProperties": false
            },
            "ServiceResponse": {
                "type": "object",
                "properties": {
                    "ok": {
                        "const": true
                    },
                    "service": {
                        "$ref": "#/components/schemas/Service"
                    }
                }
            },
            "UsageResponse": {
                "type": "object",
                "properties": {
                    "ok": {
                        "const": true
                    },
                    "usage": {
                        "type": "object",
                        "additionalProperties": true
                    }
                }
            },
            "UpgradeRequest": {
                "type": "object",
                "required": [
                    "product_id"
                ],
                "properties": {
                    "product_id": {
                        "type": "string"
                    }
                },
                "additionalProperties": false
            },
            "ErrorResponse": {
                "type": "object",
                "required": [
                    "ok",
                    "error"
                ],
                "properties": {
                    "ok": {
                        "const": false
                    },
                    "error": {
                        "type": "object",
                        "required": [
                            "code",
                            "message",
                            "retryable",
                            "request_id"
                        ],
                        "additionalProperties": true
                    }
                }
            }
        },
        "responses": {
            "Unauthorized": {
                "description": "Autenticación requerida o inválida",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        }
                    }
                }
            },
            "NotFound": {
                "description": "Recurso no encontrado",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        }
                    }
                }
            },
            "Conflict": {
                "description": "Conflicto de estado o idempotencia",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        }
                    }
                }
            },
            "NotConfigured": {
                "description": "Funcionalidad aún no configurada para producción",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        }
                    }
                }
            },
            "InvalidRequest": {
                "description": "Petición inválida",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        }
                    }
                }
            },
            "PaymentRequired": {
                "description": "El servidor requiere un pago x402",
                "headers": {
                    "PAYMENT-REQUIRED": {
                        "schema": {
                            "type": "string"
                        }
                    }
                },
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        }
                    }
                }
            }
        }
    }
}