{
  "components": {
    "parameters": {
      "StoreId": {
        "in": "path",
        "name": "storeId",
        "required": true,
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 50
        }
      },
      "CategoryId": {
        "in": "path",
        "name": "categoryId",
        "required": true,
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 50
        }
      },
      "ProductId": {
        "in": "path",
        "name": "productId",
        "required": true,
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 50
        }
      },
      "CouponId": {
        "in": "path",
        "name": "couponId",
        "required": true,
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 50
        }
      },
      "Code": {
        "in": "path",
        "name": "code",
        "required": true,
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 32
        }
      },
      "PaymentId": {
        "in": "path",
        "name": "paymentId",
        "required": true,
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 50
        }
      },
      "AffiliateId": {
        "in": "path",
        "name": "affiliateId",
        "required": true,
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 50
        }
      },
      "Domain": {
        "in": "path",
        "name": "domain",
        "required": true,
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        }
      },
      "UUID": {
        "in": "path",
        "name": "uuid",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "schemas": {
      "Domain": {
        "properties": {
          "type": {
            "enum": [
              "CUSTOM",
              "DEFAULT"
            ],
            "type": "string"
          },
          "value": {
            "maxLength": 75,
            "minLength": 8,
            "type": "string",
            "pattern": "^(?:[a-z0-9-]+\\.)*[a-z0-9-]+(\\.[a-z]{2,})?$"
          }
        },
        "required": [
          "type",
          "value"
        ],
        "type": "object"
      },
      "Error": {
        "properties": {
          "code": {
            "example": "STORE_NOT_FOUND",
            "type": "string"
          }
        },
        "required": [
          "code"
        ],
        "type": "object"
      },
      "Pagination": {
        "properties": {
          "hasMore": {
            "type": "boolean"
          },
          "limit": {
            "type": "integer"
          },
          "nextCursor": {
            "nullable": true,
            "type": "string"
          },
          "page": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "totalPages": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "Store": {
        "properties": {
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "description": {
            "nullable": true,
            "type": "string"
          },
          "domain": {
            "nullable": true,
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "image": {
            "nullable": true,
            "type": "string"
          },
          "metadata": {
            "nullable": true,
            "type": "object"
          },
          "name": {
            "type": "string"
          },
          "position": {
            "type": "integer"
          },
          "template": {
            "enum": [
              "PERSONALIZADO",
              "N/A"
            ],
            "type": "string"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "position",
          "template",
          "createdAt",
          "updatedAt"
        ],
        "type": "object"
      },
      "StoreInput": {
        "properties": {
          "description": {
            "maxLength": 256,
            "minLength": 12,
            "type": "string",
            "nullable": true
          },
          "domain": {
            "$ref": "#/components/schemas/Domain",
            "nullable": true
          },
          "image": {
            "maxLength": 512,
            "minLength": 12,
            "type": "string",
            "nullable": true
          },
          "metadata": {
            "type": "object",
            "nullable": true
          },
          "name": {
            "maxLength": 32,
            "minLength": 4,
            "type": "string"
          },
          "template": {
            "enum": [
              "PERSONALIZADO",
              "N/A"
            ],
            "type": "string"
          }
        },
        "required": [
          "template"
        ],
        "type": "object"
      },
      "StoreUpdate": {
        "properties": {
          "description": {
            "maxLength": 256,
            "minLength": 12,
            "type": "string"
          },
          "domain": {
            "$ref": "#/components/schemas/Domain"
          },
          "image": {
            "maxLength": 512,
            "minLength": 12,
            "type": "string"
          },
          "metadata": {
            "type": "object"
          },
          "name": {
            "maxLength": 32,
            "minLength": 4,
            "type": "string"
          },
          "position": {
            "minimum": 1,
            "type": "integer"
          },
          "template": {
            "enum": [
              "PERSONALIZADO",
              "N/A"
            ],
            "type": "string"
          }
        },
        "type": "object",
        "minProperties": 1
      },
      "Affiliate": {
        "description": "Store affiliate (referral code, commission, and stats).",
        "properties": {
          "code": {
            "type": "string"
          },
          "commissionRules": {
            "items": {
              "properties": {
                "commission": {
                  "type": "number"
                },
                "position": {
                  "type": "integer"
                },
                "targetId": {
                  "type": "string"
                },
                "type": {
                  "enum": [
                    "DEFAULT",
                    "PRODUCT",
                    "CATEGORY",
                    "COUPON"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "type",
                "commission",
                "position"
              ],
              "type": "object"
            },
            "nullable": true,
            "type": "array"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "email": {
            "format": "email",
            "nullable": true,
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "image": {
            "nullable": true,
            "type": "string"
          },
          "metadata": {
            "nullable": true,
            "type": "object"
          },
          "name": {
            "type": "string"
          },
          "pausedAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "status": {
            "enum": [
              "ativo",
              "inativo"
            ],
            "type": "string"
          },
          "storeId": {
            "format": "uuid",
            "type": "string"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          },
          "statistics": {
            "description": "Included when statistics=true.",
            "type": "object",
            "properties": {
              "clicks": {
                "type": "integer"
              },
              "revenue": {
                "type": "number"
              },
              "sales": {
                "type": "integer"
              }
            }
          },
          "metrics": {
            "description": "Included when statistics=true.",
            "type": "object",
            "properties": {
              "commissions": {
                "type": "object",
                "properties": {
                  "totalCount": {
                    "type": "integer"
                  },
                  "totalValue": {
                    "type": "number"
                  },
                  "graph": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "date": {
                          "type": "string"
                        },
                        "total": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "date",
                        "total"
                      ]
                    }
                  }
                },
                "required": [
                  "totalCount",
                  "totalValue",
                  "graph"
                ]
              },
              "affiliateRevenue": {
                "type": "object",
                "properties": {
                  "totalCount": {
                    "type": "integer"
                  },
                  "totalValue": {
                    "type": "number"
                  },
                  "graph": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "date": {
                          "type": "string"
                        },
                        "total": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "date",
                        "total"
                      ]
                    }
                  }
                },
                "required": [
                  "totalCount",
                  "totalValue",
                  "graph"
                ]
              }
            },
            "required": [
              "commissions",
              "affiliateRevenue"
            ]
          }
        },
        "required": [
          "id",
          "name",
          "code",
          "status",
          "storeId",
          "createdAt",
          "updatedAt"
        ],
        "type": "object"
      },
      "Category": {
        "description": "Store product category.",
        "properties": {
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "description": {
            "nullable": true,
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "image": {
            "nullable": true,
            "type": "string"
          },
          "metadata": {
            "nullable": true,
            "type": "object"
          },
          "name": {
            "type": "string"
          },
          "position": {
            "type": "integer"
          },
          "storeId": {
            "format": "uuid",
            "type": "string"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "position",
          "storeId",
          "createdAt",
          "updatedAt"
        ],
        "type": "object"
      },
      "Product": {
        "description": "Store product.",
        "properties": {
          "categories": {
            "items": {
              "properties": {
                "id": {
                  "format": "uuid",
                  "type": "string"
                },
                "name": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "delivery": {
            "enum": [
              "DIGITAL",
              "PHYSICAL"
            ],
            "type": "string"
          },
          "description": {
            "nullable": true,
            "type": "string"
          },
          "disabled": {
            "type": "boolean"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "image": {
            "nullable": true,
            "type": "string"
          },
          "metadata": {
            "nullable": true,
            "type": "object"
          },
          "name": {
            "type": "string"
          },
          "position": {
            "type": "integer"
          },
          "price": {
            "type": "number"
          },
          "sold": {
            "type": "integer"
          },
          "stock": {
            "type": "integer"
          },
          "storeId": {
            "format": "uuid",
            "type": "string"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "position",
          "price",
          "delivery",
          "stock",
          "sold",
          "storeId",
          "disabled",
          "createdAt",
          "updatedAt",
          "categories"
        ],
        "type": "object"
      },
      "Coupon": {
        "description": "Store discount coupon.",
        "properties": {
          "categories": {
            "items": {
              "properties": {
                "id": {
                  "format": "uuid",
                  "type": "string"
                },
                "name": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "code": {
            "type": "string"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "discount": {
            "type": "integer"
          },
          "expiredAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "position": {
            "type": "integer"
          },
          "products": {
            "items": {
              "properties": {
                "id": {
                  "format": "uuid",
                  "type": "string"
                },
                "name": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "rules": {
            "items": {
              "properties": {
                "type": {
                  "enum": [
                    "SINGLE_USE_PER_CUSTOMER",
                    "MIN_ORDER_AMOUNT",
                    "AFFILIATE_ONLY",
                    "MIN_ITEMS_QUANTITY",
                    "PAYMENT_METHOD"
                  ],
                  "type": "string"
                },
                "value": {}
              },
              "required": [
                "type"
              ],
              "type": "object"
            },
            "nullable": false,
            "type": "array"
          },
          "storeId": {
            "format": "uuid",
            "type": "string"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          },
          "useLimit": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "code",
          "discount",
          "position",
          "useLimit",
          "storeId",
          "createdAt",
          "updatedAt",
          "products",
          "categories",
          "rules",
          "expiredAt"
        ],
        "type": "object"
      },
      "Payment": {
        "description": "Store payment/charge.",
        "properties": {
          "affiliateCode": {
            "nullable": true,
            "type": "string"
          },
          "affiliateCommission": {
            "nullable": true,
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "email": {
                "type": "string",
                "nullable": true
              },
              "value": {
                "type": "number"
              }
            },
            "required": [
              "code",
              "name",
              "value"
            ]
          },
          "coupon": {
            "type": "boolean"
          },
          "cpf": {
            "nullable": true,
            "type": "string"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "email": {
            "format": "email",
            "type": "string"
          },
          "gateway": {
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "metadata": {
            "nullable": true,
            "type": "object"
          },
          "name": {
            "type": "string"
          },
          "price": {
            "type": "number"
          },
          "products": {
            "items": {
              "properties": {
                "description": {
                  "nullable": true,
                  "type": "string"
                },
                "id": {
                  "format": "uuid",
                  "type": "string"
                },
                "image": {
                  "nullable": true,
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "price": {
                  "type": "number"
                }
              },
              "required": [
                "id",
                "name",
                "price"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "shipment": {
            "enum": [
              "PENDING",
              "PREPARING",
              "SHIPPED",
              "DELIVERED",
              "RETURNED",
              "CANCELLED"
            ],
            "type": "string"
          },
          "status": {
            "enum": [
              "PENDING",
              "APPROVED",
              "REJECTED",
              "CANCELLED",
              "REFUNDED",
              "CHARGED_BACK",
              "EXPIRED"
            ],
            "type": "string"
          },
          "storeId": {
            "format": "uuid",
            "type": "string"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          },
          "uuid": {
            "format": "uuid",
            "type": "string"
          }
        },
        "required": [
          "id",
          "uuid",
          "status",
          "name",
          "email",
          "price",
          "coupon",
          "gateway",
          "shipment",
          "storeId",
          "createdAt",
          "updatedAt",
          "products"
        ],
        "type": "object"
      },
      "Page": {
        "description": "Store web page (HTML served on domain).",
        "properties": {
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "html": {
            "type": "string"
          },
          "store": {
            "properties": {
              "id": {
                "format": "uuid",
                "type": "string"
              },
              "ownerId": {
                "format": "uuid",
                "type": "string"
              }
            },
            "required": [
              "ownerId",
              "id"
            ],
            "type": "object"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "html",
          "createdAt",
          "updatedAt",
          "store"
        ],
        "type": "object"
      },
      "Webhook": {
        "description": "Store webhook (events and delivery URL).",
        "properties": {
          "events": {
            "items": {
              "enum": [
                "store.created",
                "store.updated",
                "store.deleted",
                "store.reordered",
                "product.created",
                "product.updated",
                "product.deleted",
                "product.reordered",
                "category.created",
                "category.updated",
                "category.deleted",
                "category.reordered",
                "coupon.created",
                "coupon.updated",
                "coupon.deleted",
                "coupon.reordered",
                "page.upserted",
                "page.deleted",
                "affiliate.created",
                "affiliate.updated",
                "affiliate.deleted",
                "payment.created",
                "payment.updated",
                "payment.deleted",
                "payment.status.changed"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "url": {
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "url",
          "events"
        ],
        "type": "object"
      },
      "StoreDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Store"
          },
          {
            "type": "object",
            "properties": {
              "categories": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Category"
                }
              },
              "products": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Product"
                }
              },
              "coupons": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Coupon"
                }
              },
              "payment": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Payment"
                }
              }
            },
            "required": [
              "categories",
              "products",
              "coupons",
              "payment"
            ]
          }
        ]
      }
    },
    "securitySchemes": {
      "ApiKey": {
        "in": "header",
        "name": "Authorization",
        "type": "apiKey",
        "x-default": "YOUR_API_KEY_HERE"
      }
    }
  },
  "info": {
    "title": "caBRAPI",
    "version": "1.0.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/pages/{domain}": {
      "get": {
        "operationId": "getPage",
        "parameters": [
          {
            "$ref": "#/components/parameters/Domain"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Page"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Retrieve web page."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Unauthorized (missing store owner or unavailable database)."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "502": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Upstream gateway or storage error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [],
        "summary": "Retrieve web page",
        "tags": [
          "Store Page"
        ]
      },
      "put": {
        "operationId": "upsertPage",
        "parameters": [
          {
            "$ref": "#/components/parameters/Domain"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "PAGE_UPSERTED",
                      "type": "string"
                    }
                  },
                  "required": [
                    "code"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Upsert web page."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "502": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Upstream gateway or storage error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Upsert web page",
        "tags": [
          "Store Page"
        ],
        "requestBody": {
          "required": true,
          "description": "Page HTML (upsert by domain).",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "html"
                ],
                "properties": {
                  "html": {
                    "type": "string",
                    "minLength": 60,
                    "maxLength": 1000000
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deletePage",
        "parameters": [
          {
            "$ref": "#/components/parameters/Domain"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "PAGE_DELETED",
                      "type": "string"
                    }
                  },
                  "required": [
                    "code"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Delete web page."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Delete web page",
        "tags": [
          "Store Page"
        ]
      }
    },
    "/stores": {
      "get": {
        "operationId": "listStores",
        "parameters": [
          {
            "in": "query",
            "name": "page",
            "schema": {
              "default": 1,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 20,
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Opaque cursor from previous page (do not combine with page).",
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "SUCCESS",
                      "type": "string"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "stores": {
                      "items": {
                        "$ref": "#/components/schemas/Store"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "code",
                    "stores",
                    "pagination"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Owner stores list ordered by position."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_PAGINATION, INVALID_PAGINATION_LIMIT, INVALID_PAGINATION_PAGE, INVALID_PAGINATION_CURSOR"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "API_KEY_NOT_PROVIDED, INVALID_API_KEY, UNAUTHENTICATED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "USER_DISABLED, NO_ACTIVE_SUBSCRIPTION"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "List stores",
        "tags": [
          "Stores"
        ],
        "x-mint": {
          "mcp": {
            "enabled": true
          }
        }
      },
      "post": {
        "operationId": "createStore",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StoreInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "STORE_CREATED",
                      "type": "string"
                    },
                    "store": {
                      "$ref": "#/components/schemas/Store"
                    }
                  },
                  "required": [
                    "code",
                    "store"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Store created."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_DATA, INVALID_DATA_NAME_MIN, INVALID_DATA_NAME_MAX, INVALID_DATA_DESCRIPTION_MIN, INVALID_DATA_DESCRIPTION_MAX, INVALID_DATA_IMAGE, INVALID_DATA_TEMPLATE, INVALID_DATA_DOMAIN, DOMAIN_REQUIRED, DOMAIN_ALREADY_EXISTS, NAME_ALREADY_EXISTS"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "API_KEY_NOT_PROVIDED, INVALID_API_KEY, UNAUTHENTICATED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "USER_DISABLED, NO_ACTIVE_SUBSCRIPTION, STORE_LIMIT_REACHED"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Create store",
        "tags": [
          "Stores"
        ]
      }
    },
    "/stores/reorder": {
      "put": {
        "operationId": "reorderStores",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "storeIds": {
                    "items": {
                      "format": "uuid",
                      "type": "string"
                    },
                    "minItems": 1,
                    "type": "array",
                    "uniqueItems": true
                  }
                },
                "required": [
                  "storeIds"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "STORES_REORDERED",
                      "type": "string"
                    }
                  },
                  "required": [
                    "code"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Positions updated in provided order."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_DATA, STORE_LIST_INVALID"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "API_KEY_NOT_PROVIDED, INVALID_API_KEY, UNAUTHENTICATED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "USER_DISABLED, NO_ACTIVE_SUBSCRIPTION"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Reorder stores",
        "tags": [
          "Stores"
        ]
      }
    },
    "/stores/{storeId}": {
      "delete": {
        "operationId": "deleteStore",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "STORE_DELETED",
                      "type": "string"
                    }
                  },
                  "required": [
                    "code"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Store deleted (soft delete)."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_DATA"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "API_KEY_NOT_PROVIDED, INVALID_API_KEY, UNAUTHENTICATED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "USER_DISABLED, NO_ACTIVE_SUBSCRIPTION"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "STORE_NOT_FOUND"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Delete store",
        "tags": [
          "Stores"
        ]
      },
      "get": {
        "operationId": "getStore",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "SUCCESS",
                      "type": "string"
                    },
                    "store": {
                      "$ref": "#/components/schemas/StoreDetail"
                    }
                  },
                  "required": [
                    "code",
                    "store"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Store with related entities."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_DATA"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "API_KEY_NOT_PROVIDED, INVALID_API_KEY, UNAUTHENTICATED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "USER_DISABLED, NO_ACTIVE_SUBSCRIPTION"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "STORE_NOT_FOUND"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Get store by ID",
        "tags": [
          "Stores"
        ],
        "x-mint": {
          "mcp": {
            "enabled": true
          }
        }
      },
      "parameters": [
        {
          "in": "path",
          "name": "storeId",
          "required": true,
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 50
          }
        }
      ],
      "put": {
        "operationId": "updateStore",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StoreUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "STORE_UPDATED",
                      "type": "string"
                    },
                    "store": {
                      "$ref": "#/components/schemas/Store"
                    }
                  },
                  "required": [
                    "code",
                    "store"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Store updated."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "INVALID_DATA, INVALID_DATA_POSITION, INVALID_DATA_NAME_MIN, INVALID_DATA_NAME_MAX, INVALID_DATA_DESCRIPTION_MIN, INVALID_DATA_DESCRIPTION_MAX, INVALID_DATA_IMAGE, INVALID_DATA_TEMPLATE, INVALID_DATA_DOMAIN, DOMAIN_REQUIRED, DOMAIN_ALREADY_EXISTS, NAME_ALREADY_EXISTS"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "API_KEY_NOT_PROVIDED, INVALID_API_KEY, UNAUTHENTICATED"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "USER_DISABLED, NO_ACTIVE_SUBSCRIPTION"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "STORE_NOT_FOUND"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Update store",
        "tags": [
          "Stores"
        ]
      }
    },
    "/stores/{storeId}/affiliates": {
      "get": {
        "operationId": "listAffiliates",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "in": "query",
            "name": "id",
            "schema": {
              "maxLength": 50,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "name",
            "schema": {
              "maxLength": 56,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "email",
            "schema": {
              "format": "email",
              "maxLength": 120,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "code",
            "schema": {
              "maxLength": 50,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "ativo",
                "inativo"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "from",
            "schema": {
              "type": "string"
            },
            "description": "Start date filter (RFC3339 or YYYY-MM-DD)."
          },
          {
            "in": "query",
            "name": "to",
            "schema": {
              "type": "string"
            },
            "description": "End date filter (RFC3339 or YYYY-MM-DD)."
          },
          {
            "in": "query",
            "name": "page",
            "schema": {
              "default": 1,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 20,
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Opaque cursor from previous page (do not combine with page).",
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "statistics",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "AFFILIATES_FETCHED",
                      "type": "string"
                    },
                    "affiliates": {
                      "items": {
                        "$ref": "#/components/schemas/Affiliate"
                      },
                      "type": "array"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "required": [
                    "code",
                    "affiliates",
                    "pagination"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "List affiliates."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "List affiliates",
        "tags": [
          "Affiliates"
        ]
      },
      "post": {
        "operationId": "createAffiliate",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          }
        ],
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "AFFILIATE_CREATED",
                      "type": "string"
                    },
                    "affiliate": {
                      "$ref": "#/components/schemas/Affiliate"
                    }
                  },
                  "required": [
                    "code",
                    "affiliate"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Create affiliate."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource already exists."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Create affiliate",
        "tags": [
          "Affiliates"
        ],
        "requestBody": {
          "required": true,
          "description": "Affiliate details (name, email, code, commissionRules).",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "email",
                  "code"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 56
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 120
                  },
                  "code": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 50,
                    "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
                  },
                  "image": {
                    "type": "string",
                    "maxLength": 512,
                    "nullable": true
                  },
                  "metadata": {
                    "type": "object",
                    "maxProperties": 64,
                    "nullable": true
                  },
                  "commissionRules": {
                    "type": "array",
                    "nullable": true,
                    "items": {
                      "type": "object",
                      "required": [
                        "type",
                        "commission",
                        "position"
                      ],
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "DEFAULT",
                            "PRODUCT",
                            "CATEGORY",
                            "COUPON"
                          ]
                        },
                        "targetId": {
                          "type": "string"
                        },
                        "commission": {
                          "type": "number",
                          "minimum": 1,
                          "maximum": 100
                        },
                        "position": {
                          "type": "integer",
                          "minimum": 0
                        }
                      }
                    },
                    "minItems": 1
                  }
                }
              }
            }
          }
        }
      }
    },
    "/stores/{storeId}/affiliates/{affiliateId}": {
      "put": {
        "operationId": "updateAffiliate",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "$ref": "#/components/parameters/AffiliateId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "AFFILIATE_UPDATED",
                      "type": "string"
                    },
                    "affiliate": {
                      "$ref": "#/components/schemas/Affiliate"
                    }
                  },
                  "required": [
                    "code",
                    "affiliate"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Update affiliate."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource already exists."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Update affiliate",
        "tags": [
          "Affiliates"
        ],
        "requestBody": {
          "required": true,
          "description": "Affiliate fields to update.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 56
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 120
                  },
                  "code": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 50,
                    "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
                  },
                  "image": {
                    "type": "string",
                    "maxLength": 512,
                    "nullable": true
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "ativo",
                      "inativo"
                    ]
                  },
                  "metadata": {
                    "type": "object",
                    "maxProperties": 64,
                    "nullable": true
                  },
                  "commissionRules": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "type",
                        "commission",
                        "position"
                      ],
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "DEFAULT",
                            "PRODUCT",
                            "CATEGORY",
                            "COUPON"
                          ]
                        },
                        "targetId": {
                          "type": "string"
                        },
                        "commission": {
                          "type": "number",
                          "minimum": 1,
                          "maximum": 100
                        },
                        "position": {
                          "type": "integer",
                          "minimum": 0
                        }
                      }
                    }
                  }
                },
                "minProperties": 1
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteAffiliate",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "$ref": "#/components/parameters/AffiliateId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "AFFILIATE_DELETED",
                      "type": "string"
                    }
                  },
                  "required": [
                    "code"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Delete affiliate."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Delete affiliate",
        "tags": [
          "Affiliates"
        ]
      }
    },
    "/stores/{storeId}/categories": {
      "get": {
        "operationId": "listCategories",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "in": "query",
            "name": "page",
            "schema": {
              "default": 1,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 20,
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "description": "Opaque cursor from previous page (do not combine with page).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "CATEGORIES_FETCHED",
                      "type": "string"
                    },
                    "categories": {
                      "items": {
                        "$ref": "#/components/schemas/Category"
                      },
                      "type": "array"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "required": [
                    "code",
                    "categories",
                    "pagination"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "List categories."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Unauthorized (missing store owner or unavailable database)."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [],
        "summary": "List categories",
        "tags": [
          "Categories"
        ]
      },
      "post": {
        "operationId": "createCategory",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          }
        ],
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "CATEGORY_CREATED",
                      "type": "string"
                    },
                    "category": {
                      "$ref": "#/components/schemas/Category"
                    }
                  },
                  "required": [
                    "code",
                    "category"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Create category."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Create category",
        "tags": [
          "Categories"
        ],
        "requestBody": {
          "required": true,
          "description": "Category details (name, description, image, metadata).",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 4,
                    "maxLength": 32
                  },
                  "description": {
                    "type": "string",
                    "minLength": 12,
                    "maxLength": 256,
                    "nullable": true
                  },
                  "image": {
                    "type": "string",
                    "minLength": 12,
                    "maxLength": 512,
                    "nullable": true
                  },
                  "metadata": {
                    "type": "object",
                    "nullable": true
                  }
                }
              }
            }
          }
        }
      }
    },
    "/stores/{storeId}/categories/reorder": {
      "put": {
        "operationId": "reorderCategories",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "CATEGORIES_REORDERED",
                      "type": "string"
                    }
                  },
                  "required": [
                    "code"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Positions updated in provided order."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Reorder categories",
        "tags": [
          "Categories"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "categoryIds": {
                    "items": {
                      "format": "uuid",
                      "type": "string"
                    },
                    "minItems": 1,
                    "type": "array",
                    "uniqueItems": true
                  }
                },
                "required": [
                  "categoryIds"
                ],
                "type": "object"
              }
            }
          },
          "description": "Ordered category IDs.",
          "required": true
        }
      }
    },
    "/stores/{storeId}/categories/{categoryId}": {
      "get": {
        "operationId": "getCategory",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "$ref": "#/components/parameters/CategoryId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "CATEGORY_FETCHED",
                      "type": "string"
                    },
                    "category": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/Category"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "coupons": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string",
                                    "format": "uuid"
                                  },
                                  "code": {
                                    "type": "string"
                                  },
                                  "discount": {
                                    "type": "integer"
                                  },
                                  "useLimit": {
                                    "type": "integer"
                                  },
                                  "expiredAt": {
                                    "type": "string",
                                    "format": "date-time",
                                    "nullable": true
                                  },
                                  "createdAt": {
                                    "type": "string",
                                    "format": "date-time"
                                  },
                                  "updatedAt": {
                                    "type": "string",
                                    "format": "date-time"
                                  }
                                },
                                "required": [
                                  "id",
                                  "code",
                                  "discount",
                                  "useLimit",
                                  "expiredAt",
                                  "createdAt",
                                  "updatedAt"
                                ]
                              }
                            },
                            "products": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string",
                                    "format": "uuid"
                                  },
                                  "name": {
                                    "type": "string"
                                  },
                                  "description": {
                                    "type": "string",
                                    "nullable": true
                                  },
                                  "image": {
                                    "type": "string",
                                    "nullable": true
                                  },
                                  "price": {
                                    "type": "number"
                                  },
                                  "stock": {
                                    "type": "integer"
                                  },
                                  "sold": {
                                    "type": "integer"
                                  },
                                  "delivery": {
                                    "type": "string",
                                    "enum": [
                                      "DIGITAL",
                                      "PHYSICAL"
                                    ]
                                  },
                                  "metadata": {
                                    "type": "object",
                                    "nullable": true
                                  },
                                  "createdAt": {
                                    "type": "string",
                                    "format": "date-time"
                                  },
                                  "updatedAt": {
                                    "type": "string",
                                    "format": "date-time"
                                  }
                                },
                                "required": [
                                  "id",
                                  "name",
                                  "price",
                                  "stock",
                                  "sold",
                                  "delivery",
                                  "createdAt",
                                  "updatedAt"
                                ]
                              }
                            }
                          },
                          "required": [
                            "coupons",
                            "products"
                          ]
                        }
                      ]
                    }
                  },
                  "required": [
                    "code",
                    "category"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Get category by ID."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Unauthorized (missing store owner or unavailable database)."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [],
        "summary": "Get category by ID",
        "tags": [
          "Categories"
        ]
      },
      "put": {
        "operationId": "updateCategory",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "$ref": "#/components/parameters/CategoryId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "CATEGORY_UPDATED",
                      "type": "string"
                    },
                    "category": {
                      "$ref": "#/components/schemas/Category"
                    }
                  },
                  "required": [
                    "code",
                    "category"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Update category."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Update category",
        "tags": [
          "Categories"
        ],
        "requestBody": {
          "required": true,
          "description": "Category fields to update.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 4,
                    "maxLength": 32
                  },
                  "description": {
                    "type": "string",
                    "minLength": 12,
                    "maxLength": 256
                  },
                  "image": {
                    "type": "string",
                    "minLength": 12,
                    "maxLength": 512
                  },
                  "metadata": {
                    "type": "object"
                  },
                  "position": {
                    "type": "integer",
                    "minimum": 1
                  }
                },
                "minProperties": 1
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteCategory",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "$ref": "#/components/parameters/CategoryId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "CATEGORY_DELETED",
                      "type": "string"
                    }
                  },
                  "required": [
                    "code"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Delete category."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Delete category",
        "tags": [
          "Categories"
        ]
      }
    },
    "/stores/{storeId}/categories/{categoryId}/products": {
      "get": {
        "operationId": "listCategoryProducts",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "$ref": "#/components/parameters/CategoryId"
          },
          {
            "in": "query",
            "name": "page",
            "schema": {
              "default": 1,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 20,
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "description": "Opaque cursor from previous page (do not combine with page).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "PRODUCTS_BY_CATEGORY_FETCHED",
                      "type": "string"
                    },
                    "products": {
                      "items": {
                        "$ref": "#/components/schemas/Product"
                      },
                      "type": "array"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "required": [
                    "code",
                    "products",
                    "pagination"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "List products by category."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Unauthorized (missing store owner or unavailable database)."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [],
        "summary": "List products by category",
        "tags": [
          "Categories"
        ]
      }
    },
    "/stores/{storeId}/clicks": {
      "post": {
        "operationId": "trackAffiliateClick",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "ref": {
                    "description": "Affiliate referral code.",
                    "example": "my-affiliate",
                    "type": "string",
                    "maxLength": 50,
                    "minLength": 1
                  }
                },
                "required": [
                  "ref"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "CLICK_TRACKED",
                      "type": "string",
                      "enum": [
                        "CLICK_TRACKED",
                        "CLICK_IGNORED"
                      ]
                    }
                  },
                  "required": [
                    "code"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Click tracked or ignored successfully."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Unauthorized (missing store owner or unavailable database)."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Store not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [],
        "summary": "Track affiliate click"
      }
    },
    "/stores/{storeId}/coupons": {
      "get": {
        "operationId": "listCoupons",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "in": "query",
            "name": "page",
            "schema": {
              "default": 1,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 20,
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "description": "Opaque cursor from previous page (do not combine with page).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "COUPONS_FETCHED",
                      "type": "string"
                    },
                    "coupons": {
                      "items": {
                        "$ref": "#/components/schemas/Coupon"
                      },
                      "type": "array"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "required": [
                    "code",
                    "coupons",
                    "pagination"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "List coupons."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "List coupons",
        "tags": [
          "Coupons"
        ]
      },
      "post": {
        "operationId": "createCoupon",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          }
        ],
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "COUPON_CREATED",
                      "type": "string"
                    },
                    "coupon": {
                      "$ref": "#/components/schemas/Coupon"
                    }
                  },
                  "required": [
                    "code",
                    "coupon"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Create coupon."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource already exists."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Create coupon",
        "tags": [
          "Coupons"
        ],
        "requestBody": {
          "required": true,
          "description": "Coupon details (code, discount, expiration).",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "code",
                  "discount"
                ],
                "properties": {
                  "code": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 32
                  },
                  "discount": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100
                  },
                  "useLimit": {
                    "type": "integer",
                    "minimum": -1,
                    "maximum": 9999,
                    "nullable": true
                  },
                  "rules": {
                    "type": "array",
                    "nullable": true,
                    "maxItems": 32,
                    "items": {
                      "type": "object",
                      "required": [
                        "type"
                      ],
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "SINGLE_USE_PER_CUSTOMER",
                            "MIN_ORDER_AMOUNT",
                            "AFFILIATE_ONLY",
                            "MIN_ITEMS_QUANTITY",
                            "PAYMENT_METHOD"
                          ]
                        },
                        "value": {}
                      }
                    }
                  },
                  "expiredAt": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  },
                  "productIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 50
                    }
                  },
                  "categoryIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 50
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/stores/{storeId}/coupons/reorder": {
      "put": {
        "operationId": "reorderCoupons",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "COUPONS_REORDERED",
                      "type": "string"
                    }
                  },
                  "required": [
                    "code"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Positions updated in provided order."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Reorder coupons",
        "tags": [
          "Coupons"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "couponIds": {
                    "items": {
                      "format": "uuid",
                      "type": "string"
                    },
                    "minItems": 1,
                    "type": "array",
                    "uniqueItems": true
                  }
                },
                "required": [
                  "couponIds"
                ],
                "type": "object"
              }
            }
          },
          "description": "Ordered coupon IDs.",
          "required": true
        }
      }
    },
    "/stores/{storeId}/coupons/uuid/{couponId}": {
      "get": {
        "operationId": "getCouponById",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "$ref": "#/components/parameters/CouponId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "SUCCESS",
                      "type": "string"
                    },
                    "coupon": {
                      "$ref": "#/components/schemas/Coupon"
                    }
                  },
                  "required": [
                    "code",
                    "coupon"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Get coupon by ID."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Get coupon by ID",
        "tags": [
          "Coupons"
        ]
      }
    },
    "/stores/{storeId}/coupons/{code}": {
      "get": {
        "operationId": "getCouponByCode",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "$ref": "#/components/parameters/Code"
          },
          {
            "description": "Optional buyer email to validate single-use-per-customer coupons.",
            "in": "query",
            "name": "email",
            "schema": {
              "type": "string",
              "format": "email"
            }
          },
          {
            "description": "Optional buyer CPF to validate single-use-per-customer coupons.",
            "in": "query",
            "name": "cpf",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "SUCCESS",
                      "type": "string"
                    },
                    "coupon": {
                      "$ref": "#/components/schemas/Coupon"
                    }
                  },
                  "required": [
                    "code",
                    "coupon"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Get coupon by code."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Unauthorized (missing store owner or unavailable database)."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [],
        "summary": "Get coupon by code",
        "tags": [
          "Coupons"
        ]
      }
    },
    "/stores/{storeId}/coupons/{couponId}": {
      "put": {
        "operationId": "updateCoupon",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "$ref": "#/components/parameters/CouponId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "COUPON_UPDATED",
                      "type": "string"
                    },
                    "coupon": {
                      "$ref": "#/components/schemas/Coupon"
                    }
                  },
                  "required": [
                    "code",
                    "coupon"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Update coupon."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource already exists."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Update coupon",
        "tags": [
          "Coupons"
        ],
        "requestBody": {
          "required": true,
          "description": "Coupon fields to update.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 32
                  },
                  "discount": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100
                  },
                  "position": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "useLimit": {
                    "type": "integer",
                    "minimum": -1,
                    "maximum": 9999,
                    "nullable": true
                  },
                  "rules": {
                    "type": "array",
                    "nullable": true,
                    "maxItems": 32,
                    "items": {
                      "type": "object",
                      "required": [
                        "type"
                      ],
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "SINGLE_USE_PER_CUSTOMER",
                            "MIN_ORDER_AMOUNT",
                            "AFFILIATE_ONLY",
                            "MIN_ITEMS_QUANTITY",
                            "PAYMENT_METHOD"
                          ]
                        },
                        "value": {}
                      }
                    }
                  },
                  "expiredAt": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true
                  },
                  "productIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 50
                    },
                    "nullable": true
                  },
                  "categoryIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 50
                    },
                    "nullable": true
                  }
                },
                "minProperties": 1
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteCoupon",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "$ref": "#/components/parameters/CouponId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "COUPON_DELETED",
                      "type": "string"
                    }
                  },
                  "required": [
                    "code"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Delete coupon."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Delete coupon",
        "tags": [
          "Coupons"
        ]
      }
    },
    "/stores/{storeId}/fees": {
      "get": {
        "operationId": "getStoreFees",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "fees": {
                      "type": "object"
                    },
                    "gateways": {
                      "items": {
                        "properties": {
                          "fees": {
                            "type": "object"
                          },
                          "installmentFees": {
                            "items": {
                              "type": "object"
                            },
                            "type": "array"
                          },
                          "maxInstallments": {
                            "type": "number"
                          },
                          "methods": {
                            "items": {
                              "type": "string"
                            },
                            "type": "array"
                          },
                          "type": {
                            "enum": [
                              "MERCADOPAGO",
                              "ASAAS",
                              "EFI_BANK",
                              "STRIPE"
                            ],
                            "type": "string"
                          },
                          "publicKey": {
                            "type": "string"
                          },
                          "payeeCode": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "type",
                          "methods"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "gateways",
                    "fees"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Active gateways and store fees."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "NO_ACTIVE_SUBSCRIPTION"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "STORE_NOT_FOUND"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [],
        "summary": "Get store fees",
        "tags": [
          "Stores"
        ]
      }
    },
    "/stores/{storeId}/payments": {
      "get": {
        "operationId": "listPayments",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "in": "query",
            "name": "page",
            "schema": {
              "default": 1,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 20,
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "description": "Opaque cursor from previous page (do not combine with page).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "PAYMENTS_RETRIEVED",
                      "type": "string"
                    },
                    "payments": {
                      "items": {
                        "$ref": "#/components/schemas/Payment"
                      },
                      "type": "array"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "required": [
                    "code",
                    "payments",
                    "pagination"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "List payments."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "List payments",
        "tags": [
          "Payments"
        ]
      },
      "post": {
        "operationId": "createPayment",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "description": "Optional idempotency key to prevent duplicate charges.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "type": "object"
                    },
                    "status": {
                      "example": true,
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Idempotent replay of an already-created payment."
          },
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "type": "object"
                    },
                    "status": {
                      "example": true,
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Payment created."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Unauthorized (missing store owner or unavailable database)."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "502": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Upstream gateway or storage error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [],
        "summary": "Create payment",
        "tags": [
          "Payments"
        ],
        "requestBody": {
          "required": true,
          "description": "Charge details (items, customer, gateway).",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "email",
                  "gateway",
                  "items"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 50
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "minLength": 12,
                    "maxLength": 100
                  },
                  "cpf": {
                    "type": "string",
                    "maxLength": 24,
                    "nullable": true
                  },
                  "gateway": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 50
                  },
                  "coupon": {
                    "type": "string",
                    "maxLength": 32,
                    "nullable": true
                  },
                  "idempotencyKey": {
                    "type": "string",
                    "maxLength": 255,
                    "nullable": true
                  },
                  "metadata": {
                    "type": "object",
                    "nullable": true
                  },
                  "items": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "object",
                      "required": [
                        "productId",
                        "quantity"
                      ],
                      "properties": {
                        "productId": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 50
                        },
                        "quantity": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 50
                        },
                        "billingCycleMonths": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 60,
                          "nullable": true
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/stores/{storeId}/payments/filter": {
      "get": {
        "operationId": "filterPayments",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "in": "query",
            "name": "page",
            "schema": {
              "default": 1,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 20,
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Opaque cursor from previous page (do not combine with page; only valid when sortBy=createdAt).",
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "id",
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "uuid",
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "name",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "email",
            "schema": {
              "format": "email",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "cpf",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "PENDING",
                "APPROVED",
                "REJECTED",
                "CANCELLED",
                "REFUNDED",
                "CHARGED_BACK",
                "EXPIRED"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "price",
            "schema": {
              "type": "number"
            }
          },
          {
            "in": "query",
            "name": "minPrice",
            "schema": {
              "type": "number"
            }
          },
          {
            "in": "query",
            "name": "maxPrice",
            "schema": {
              "type": "number"
            }
          },
          {
            "in": "query",
            "name": "coupon",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "gateway",
            "schema": {
              "enum": [
                "MERCADOPAGO",
                "EFI_BANK",
                "ASAAS",
                "STRIPE"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "shipment",
            "schema": {
              "enum": [
                "PENDING",
                "PREPARING",
                "SHIPPED",
                "DELIVERED",
                "RETURNED",
                "CANCELLED"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "createdAtFrom",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "createdAtTo",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "updatedAtFrom",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "updatedAtTo",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "productId",
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "metadataKey",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "metadataValue",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "sortBy",
            "schema": {
              "default": "createdAt",
              "enum": [
                "createdAt",
                "updatedAt",
                "price",
                "name",
                "email"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "sortOrder",
            "schema": {
              "default": "desc",
              "enum": [
                "asc",
                "desc"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "PAYMENTS_FILTERED",
                      "type": "string"
                    },
                    "payments": {
                      "items": {
                        "$ref": "#/components/schemas/Payment"
                      },
                      "type": "array"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "required": [
                    "code",
                    "payments",
                    "pagination"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Filter payments."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Filter too broad (metadata scan limit exceeded)."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Filter payments",
        "tags": [
          "Payments"
        ]
      }
    },
    "/stores/{storeId}/payments/status/{uuid}": {
      "get": {
        "operationId": "getPaymentStatus",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "$ref": "#/components/parameters/UUID"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "PAYMENT_STATUS",
                      "type": "string"
                    },
                    "payment": {
                      "properties": {
                        "status": {
                          "enum": [
                            "PENDING",
                            "APPROVED",
                            "REJECTED",
                            "CANCELLED",
                            "REFUNDED",
                            "CHARGED_BACK",
                            "EXPIRED"
                          ],
                          "example": "APPROVED",
                          "type": "string"
                        },
                        "uuid": {
                          "example": "550e8400-e29b-41d4-a716-446655440000",
                          "type": "string"
                        }
                      },
                      "required": [
                        "uuid",
                        "status"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "code",
                    "payment"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Payment status retrieved successfully."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request (invalid UUID or invalid storeId)."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Unauthorized (missing store owner or unavailable database)."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (NO_ACTIVE_SUBSCRIPTION)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Payment or store not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [],
        "summary": "Get payment status",
        "tags": [
          "Payments"
        ]
      }
    },
    "/stores/{storeId}/payments/{paymentId}": {
      "get": {
        "operationId": "getPayment",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "$ref": "#/components/parameters/PaymentId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "PAYMENT_FETCHED",
                      "type": "string"
                    },
                    "payment": {
                      "$ref": "#/components/schemas/Payment"
                    }
                  },
                  "required": [
                    "code",
                    "payment"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Get payment by ID."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Get payment by ID",
        "tags": [
          "Payments"
        ]
      },
      "put": {
        "operationId": "updatePayment",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "$ref": "#/components/parameters/PaymentId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "PAYMENT_UPDATED",
                      "type": "string"
                    },
                    "payment": {
                      "$ref": "#/components/schemas/Payment"
                    }
                  },
                  "required": [
                    "code",
                    "payment"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Update payment."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Update payment",
        "tags": [
          "Payments"
        ],
        "requestBody": {
          "required": false,
          "description": "Payment fields to update.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "shipment": {
                    "type": "string",
                    "enum": [
                      "PENDING",
                      "PREPARING",
                      "SHIPPED",
                      "DELIVERED",
                      "RETURNED",
                      "CANCELLED"
                    ]
                  },
                  "metadata": {
                    "type": "object",
                    "maxProperties": 999
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deletePayment",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "$ref": "#/components/parameters/PaymentId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "PAYMENT_DELETED",
                      "type": "string"
                    }
                  },
                  "required": [
                    "code"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Delete payment."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Delete payment",
        "tags": [
          "Payments"
        ]
      }
    },
    "/stores/{storeId}/products": {
      "get": {
        "operationId": "listProducts",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "in": "query",
            "name": "page",
            "schema": {
              "default": 1,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 20,
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "description": "Opaque cursor from previous page (do not combine with page).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "PRODUCTS_FETCHED",
                      "type": "string"
                    },
                    "products": {
                      "items": {
                        "$ref": "#/components/schemas/Product"
                      },
                      "type": "array"
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "required": [
                    "code",
                    "products",
                    "pagination"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "List products."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Unauthorized (missing store owner or unavailable database)."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [],
        "summary": "List products",
        "tags": [
          "Products"
        ]
      },
      "post": {
        "operationId": "createProduct",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "SUCCESS",
                      "type": "string"
                    },
                    "product": {
                      "$ref": "#/components/schemas/Product"
                    }
                  },
                  "required": [
                    "code",
                    "product"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Create product."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Create product",
        "tags": [
          "Products"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "description": "Fields documented on the reference page.",
                "type": "object"
              }
            }
          },
          "description": "Product details (name, price, stock, categories).",
          "required": true
        }
      }
    },
    "/stores/{storeId}/products/reorder": {
      "put": {
        "operationId": "reorderProducts",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "PRODUCTS_REORDERED",
                      "type": "string"
                    }
                  },
                  "required": [
                    "code"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Positions updated in provided order."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Reorder products",
        "tags": [
          "Products"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "productIds": {
                    "items": {
                      "format": "uuid",
                      "type": "string"
                    },
                    "minItems": 1,
                    "type": "array",
                    "uniqueItems": true
                  }
                },
                "required": [
                  "productIds"
                ],
                "type": "object"
              }
            }
          },
          "description": "Ordered product IDs.",
          "required": true
        }
      }
    },
    "/stores/{storeId}/products/{productId}": {
      "get": {
        "operationId": "getProduct",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "$ref": "#/components/parameters/ProductId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "PRODUCT_FETCHED",
                      "type": "string"
                    },
                    "product": {
                      "$ref": "#/components/schemas/Product"
                    }
                  },
                  "required": [
                    "code",
                    "product"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Get product by ID."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Unauthorized (missing store owner or unavailable database)."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [],
        "summary": "Get product by ID",
        "tags": [
          "Products"
        ]
      },
      "put": {
        "operationId": "updateProduct",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "$ref": "#/components/parameters/ProductId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "SUCCESS",
                      "type": "string"
                    },
                    "product": {
                      "$ref": "#/components/schemas/Product"
                    }
                  },
                  "required": [
                    "code",
                    "product"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Update product."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Update product",
        "tags": [
          "Products"
        ],
        "requestBody": {
          "required": true,
          "description": "Product fields to update.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 32
                  },
                  "image": {
                    "type": "string",
                    "maxLength": 512,
                    "nullable": true
                  },
                  "description": {
                    "type": "string",
                    "minLength": 12,
                    "maxLength": 256
                  },
                  "categoryIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 50
                    }
                  },
                  "delivery": {
                    "type": "string",
                    "enum": [
                      "DIGITAL",
                      "PHYSICAL"
                    ]
                  },
                  "price": {
                    "type": "number",
                    "minimum": 0.5,
                    "maximum": 9999
                  },
                  "stock": {
                    "type": "integer",
                    "minimum": -1,
                    "maximum": 9999
                  },
                  "position": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "metadata": {
                    "type": "object"
                  },
                  "disabled": {
                    "type": "boolean"
                  }
                },
                "minProperties": 1
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteProduct",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "$ref": "#/components/parameters/ProductId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "SUCCESS",
                      "type": "string"
                    }
                  },
                  "required": [
                    "code"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Delete product."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Delete product",
        "tags": [
          "Products"
        ]
      }
    },
    "/stores/{storeId}/webhooks": {
      "get": {
        "operationId": "listWebhooks",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "max": {
                      "example": 3,
                      "type": "integer"
                    },
                    "webhooks": {
                      "items": {
                        "$ref": "#/components/schemas/Webhook"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "webhooks",
                    "max"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "List store webhooks."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "List store webhooks",
        "tags": [
          "Webhooks"
        ]
      },
      "post": {
        "operationId": "createWebhook",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "WEBHOOK_ADDED",
                      "type": "string"
                    },
                    "events": {
                      "items": {
                        "enum": [
                          "store.created",
                          "store.updated",
                          "store.deleted",
                          "store.reordered",
                          "product.created",
                          "product.updated",
                          "product.deleted",
                          "product.reordered",
                          "category.created",
                          "category.updated",
                          "category.deleted",
                          "category.reordered",
                          "coupon.created",
                          "coupon.updated",
                          "coupon.deleted",
                          "coupon.reordered",
                          "page.upserted",
                          "page.deleted",
                          "affiliate.created",
                          "affiliate.updated",
                          "affiliate.deleted",
                          "payment.created",
                          "payment.updated",
                          "payment.deleted",
                          "payment.status.changed"
                        ],
                        "type": "string"
                      },
                      "type": "array"
                    },
                    "webhook": {
                      "format": "uri",
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "webhook",
                    "events"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Webhook added."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "example": "WEBHOOK_LIMIT_REACHED",
                      "type": "string"
                    },
                    "max": {
                      "example": 2,
                      "type": "integer"
                    }
                  },
                  "required": [
                    "code"
                  ]
                }
              }
            },
            "description": "Invalid request (e.g. INVALID_URL, INVALID_DATA, OWNER_API_KEY_MISSING, WEBHOOK_INVALID, WEBHOOK_ALREADY_EXISTS, WEBHOOK_LIMIT_REACHED)."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Add webhook to store",
        "tags": [
          "Webhooks"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "events": {
                    "items": {
                      "enum": [
                        "store.created",
                        "store.updated",
                        "store.deleted",
                        "store.reordered",
                        "product.created",
                        "product.updated",
                        "product.deleted",
                        "product.reordered",
                        "category.created",
                        "category.updated",
                        "category.deleted",
                        "category.reordered",
                        "coupon.created",
                        "coupon.updated",
                        "coupon.deleted",
                        "coupon.reordered",
                        "page.upserted",
                        "page.deleted",
                        "affiliate.created",
                        "affiliate.updated",
                        "affiliate.deleted",
                        "payment.created",
                        "payment.updated",
                        "payment.deleted",
                        "payment.status.changed"
                      ],
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "url": {
                    "format": "uri",
                    "maxLength": 200,
                    "minLength": 9,
                    "type": "string"
                  }
                },
                "required": [
                  "url"
                ],
                "type": "object"
              }
            }
          },
          "description": "Webhook URL and optional event subscriptions.",
          "required": true
        }
      },
      "delete": {
        "operationId": "deleteWebhook",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          },
          {
            "name": "url",
            "in": "query",
            "required": false,
            "description": "Exact webhook URL to be removed (can be passed via query param or JSON body `{\"url\": \"...\"}`).",
            "schema": {
              "type": "string",
              "format": "uri"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "WEBHOOK_REMOVED",
                      "type": "string"
                    }
                  },
                  "required": [
                    "code"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Remove webhook from store."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Remove webhook from store",
        "tags": [
          "Webhooks"
        ],
        "requestBody": {
          "required": false,
          "description": "Alternative to the `url` query parameter: JSON body `{\"url\": \"...\"}`.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri"
                  }
                },
                "required": [
                  "url"
                ]
              }
            }
          }
        }
      },
      "put": {
        "operationId": "updateWebhook",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "events": {
                    "items": {
                      "enum": [
                        "store.created",
                        "store.updated",
                        "store.deleted",
                        "store.reordered",
                        "product.created",
                        "product.updated",
                        "product.deleted",
                        "product.reordered",
                        "category.created",
                        "category.updated",
                        "category.deleted",
                        "category.reordered",
                        "coupon.created",
                        "coupon.updated",
                        "coupon.deleted",
                        "coupon.reordered",
                        "page.upserted",
                        "page.deleted",
                        "affiliate.created",
                        "affiliate.updated",
                        "affiliate.deleted",
                        "payment.created",
                        "payment.updated",
                        "payment.deleted",
                        "payment.status.changed"
                      ],
                      "type": "string"
                    },
                    "minItems": 1,
                    "type": "array"
                  },
                  "url": {
                    "format": "uri",
                    "maxLength": 200,
                    "minLength": 9,
                    "type": "string"
                  }
                },
                "required": [
                  "url",
                  "events"
                ],
                "type": "object"
              }
            }
          },
          "description": "Webhook URL and updated event subscriptions.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "WEBHOOK_UPDATED",
                      "type": "string"
                    },
                    "events": {
                      "items": {
                        "enum": [
                          "store.created",
                          "store.updated",
                          "store.deleted",
                          "store.reordered",
                          "product.created",
                          "product.updated",
                          "product.deleted",
                          "product.reordered",
                          "category.created",
                          "category.updated",
                          "category.deleted",
                          "category.reordered",
                          "coupon.created",
                          "coupon.updated",
                          "coupon.deleted",
                          "coupon.reordered",
                          "page.upserted",
                          "page.deleted",
                          "affiliate.created",
                          "affiliate.updated",
                          "affiliate.deleted",
                          "payment.created",
                          "payment.updated",
                          "payment.deleted",
                          "payment.status.changed"
                        ],
                        "type": "string"
                      },
                      "type": "array"
                    },
                    "webhook": {
                      "format": "uri",
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "webhook",
                    "events"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Webhook updated."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Update webhook events",
        "tags": [
          "Webhooks"
        ]
      },
      "patch": {
        "operationId": "patchWebhook",
        "parameters": [
          {
            "$ref": "#/components/parameters/StoreId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "events": {
                    "items": {
                      "enum": [
                        "store.created",
                        "store.updated",
                        "store.deleted",
                        "store.reordered",
                        "product.created",
                        "product.updated",
                        "product.deleted",
                        "product.reordered",
                        "category.created",
                        "category.updated",
                        "category.deleted",
                        "category.reordered",
                        "coupon.created",
                        "coupon.updated",
                        "coupon.deleted",
                        "coupon.reordered",
                        "page.upserted",
                        "page.deleted",
                        "affiliate.created",
                        "affiliate.updated",
                        "affiliate.deleted",
                        "payment.created",
                        "payment.updated",
                        "payment.deleted",
                        "payment.status.changed"
                      ],
                      "type": "string"
                    },
                    "minItems": 1,
                    "type": "array"
                  },
                  "url": {
                    "format": "uri",
                    "maxLength": 200,
                    "minLength": 9,
                    "type": "string"
                  }
                },
                "required": [
                  "url",
                  "events"
                ],
                "type": "object"
              }
            }
          },
          "description": "Webhook URL and updated event subscriptions.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "code": {
                      "example": "WEBHOOK_UPDATED",
                      "type": "string"
                    },
                    "events": {
                      "items": {
                        "enum": [
                          "store.created",
                          "store.updated",
                          "store.deleted",
                          "store.reordered",
                          "product.created",
                          "product.updated",
                          "product.deleted",
                          "product.reordered",
                          "category.created",
                          "category.updated",
                          "category.deleted",
                          "category.reordered",
                          "coupon.created",
                          "coupon.updated",
                          "coupon.deleted",
                          "coupon.reordered",
                          "page.upserted",
                          "page.deleted",
                          "affiliate.created",
                          "affiliate.updated",
                          "affiliate.deleted",
                          "payment.created",
                          "payment.updated",
                          "payment.deleted",
                          "payment.status.changed"
                        ],
                        "type": "string"
                      },
                      "type": "array"
                    },
                    "webhook": {
                      "format": "uri",
                      "type": "string"
                    }
                  },
                  "required": [
                    "code",
                    "webhook",
                    "events"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Webhook updated."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Invalid request."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Missing or invalid API key."
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Forbidden (inactive plan or insufficient permissions)."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Resource not found."
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Rate limit exceeded."
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Internal server error."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "Service unavailable."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Update webhook events",
        "tags": [
          "Webhooks"
        ]
      }
    }
  },
  "servers": [
    {
      "url": "https://api.cabrapi.com.br/v1"
    }
  ]
}
