{
  "openapi": "3.1.0",
  "info": {
    "title": "esim-api",
    "version": "1.0.0",
    "description": "Public storefront and partner integration API for esim-labs. Admin routes are internal (Hono RPC) and not included."
  },
  "servers": [
    {
      "url": "https://esim-api.example.com/api/v1",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "config",
      "description": "Market configuration"
    },
    {
      "name": "catalog",
      "description": "Sellable products"
    },
    {
      "name": "orders",
      "description": "Checkout and guest order status"
    },
    {
      "name": "esims",
      "description": "Guest eSIM lifecycle"
    },
    {
      "name": "campaigns",
      "description": "Promotional redemption"
    },
    {
      "name": "partner",
      "description": "Partner API (API key auth)"
    }
  ],
  "paths": {
    "/config": {
      "get": {
        "operationId": "getMarketConfig",
        "tags": [
          "config"
        ],
        "summary": "Market configuration for the resolved market",
        "parameters": [
          {
            "name": "X-Market-Id",
            "in": "header",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Market config",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MarketConfig"
                }
              }
            }
          },
          "503": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/products": {
      "get": {
        "operationId": "listProducts",
        "tags": [
          "catalog"
        ],
        "summary": "List sellable products for the market",
        "responses": {
          "200": {
            "description": "Product list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Product"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/products/{slug}": {
      "get": {
        "operationId": "getProduct",
        "tags": [
          "catalog"
        ],
        "summary": "Get a product by slug",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Product",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/orders": {
      "post": {
        "operationId": "createOrder",
        "tags": [
          "orders"
        ],
        "summary": "Create a checkout order",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateOrder"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Order created"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/orders/{id}": {
      "get": {
        "operationId": "getOrderForGuest",
        "tags": [
          "orders"
        ],
        "summary": "Guest order status",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Guest-Token",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "description": "Guest token from checkout response"
          }
        ],
        "responses": {
          "200": {
            "description": "Order"
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/campaigns/{code}/redeem": {
      "post": {
        "operationId": "redeemCampaign",
        "tags": [
          "campaigns"
        ],
        "summary": "Redeem a campaign code",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  }
                },
                "required": [
                  "email"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Redemption accepted"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/esims/{id}": {
      "get": {
        "operationId": "getEsimForGuest",
        "tags": [
          "esims"
        ],
        "summary": "Guest eSIM detail",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Guest-Token",
            "in": "header",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "eSIM"
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/esims/{id}/usage": {
      "get": {
        "operationId": "getEsimUsage",
        "tags": [
          "esims"
        ],
        "summary": "Guest usage snapshot",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Guest-Token",
            "in": "header",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Usage"
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/esims/{id}/topup": {
      "post": {
        "operationId": "topUpEsim",
        "tags": [
          "esims"
        ],
        "summary": "Request eSIM top-up",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Guest-Token",
            "in": "header",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "productSlug": {
                    "type": "string"
                  }
                },
                "required": [
                  "productSlug"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Top-up queued"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/esims/{id}/refund-request": {
      "post": {
        "operationId": "requestEsimRefund",
        "tags": [
          "esims"
        ],
        "summary": "Request eSIM refund",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Guest-Token",
            "in": "header",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Refund request submitted"
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/partner/orders": {
      "post": {
        "operationId": "createPartnerOrder",
        "tags": [
          "partner"
        ],
        "summary": "Create a partner order",
        "security": [
          {
            "PartnerApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePartnerOrder"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Order created"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/partner/orders/bulk": {
      "post": {
        "operationId": "createPartnerBulk",
        "tags": [
          "partner"
        ],
        "summary": "Bulk partner orders",
        "security": [
          {
            "PartnerApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePartnerBulk"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Bulk job accepted"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/partner/orders/{id}": {
      "get": {
        "operationId": "getPartnerOrder",
        "tags": [
          "partner"
        ],
        "summary": "Partner order status",
        "security": [
          {
            "PartnerApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Order"
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "PartnerApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Partner-Api-Key"
      }
    },
    "schemas": {
      "Product": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "countryCodes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "dataMb": {
            "type": "integer"
          },
          "validityDays": {
            "type": "integer"
          },
          "priceCents": {
            "type": "integer"
          },
          "currency": {
            "type": "string",
            "minLength": 3,
            "maxLength": 3
          },
          "vendorId": {
            "type": "string"
          },
          "vendorProductCode": {
            "type": "string"
          }
        }
      },
      "MarketConfig": {
        "type": "object",
        "properties": {
          "marketId": {
            "type": "string",
            "enum": [
              "kr",
              "jp",
              "global"
            ]
          },
          "uiVariant": {
            "type": "string"
          },
          "defaultLocale": {
            "type": "string"
          },
          "locales": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "currency": {
            "type": "string"
          },
          "apexDomain": {
            "type": "string"
          },
          "flags": {
            "type": "object",
            "additionalProperties": {
              "type": "boolean"
            }
          }
        }
      },
      "CreateOrder": {
        "type": "object",
        "properties": {
          "productSlug": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "successUrl": {
            "type": "string",
            "format": "uri"
          },
          "cancelUrl": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "productSlug",
          "email",
          "successUrl",
          "cancelUrl"
        ]
      },
      "CreatePartnerOrder": {
        "type": "object",
        "properties": {
          "productSlug": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          }
        },
        "required": [
          "productSlug",
          "email"
        ]
      },
      "CreatePartnerBulk": {
        "type": "object",
        "properties": {
          "orders": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/CreatePartnerOrder"
            }
          }
        },
        "required": [
          "orders"
        ]
      }
    }
  }
}