{
  "openapi": "3.1.0",
  "info": {
    "title": "Entexia Master API v1",
    "version": "1.0.0",
    "description": "Public REST API za upravljanje SaaS subscriptions, tenants in invoices.\n\nAuthentication: Bearer token (Sanctum). Token ustvari v Master admin: Settings → API Tokens.\n\nRate limit: 120 req/min per token.\n\nBase URL: `https://master.entexia.com/api/v1`",
    "contact": {
      "email": "support@entexia.com",
      "url": "https://entexia.com/contact"
    },
    "license": {
      "name": "Entexia Terms",
      "url": "https://entexia.com/terms"
    }
  },
  "servers": [
    { "url": "https://master.entexia.com/api/v1", "description": "Production" }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Sanctum"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "message": { "type": "string", "example": "Unauthorized" }
        }
      },
      "User": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "example": 1 },
          "name": { "type": "string", "example": "Tomaž Kalan" },
          "email": { "type": "string", "format": "email" },
          "role": { "type": "string", "example": "owner" }
        }
      },
      "Subscription": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "example": 42 },
          "tenant_slug": { "type": "string", "example": "iteca" },
          "tenant_name": { "type": "string", "example": "Iteca d.o.o." },
          "plan_code": { "type": "string", "example": "portal" },
          "plan_name": { "type": "string", "example": "Portal paket" },
          "billing_cycle": { "type": "string", "enum": ["monthly", "annual"] },
          "status": { "type": "string", "enum": ["trial", "active", "past_due", "suspended", "cancelled", "churned", "access_revoked"] },
          "mrr_eur": { "type": "number", "format": "float", "example": 15.0 },
          "trial_ends_at": { "type": "string", "format": "date", "nullable": true },
          "current_period_end": { "type": "string", "format": "date" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "Tenant": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "iteca" },
          "name": { "type": "string", "example": "Iteca d.o.o." },
          "slug": { "type": "string", "example": "iteca" },
          "country": { "type": "string", "example": "SI" },
          "users_count": { "type": "integer", "example": 12 },
          "subscription_status": { "type": "string", "example": "active" },
          "mrr_eur": { "type": "number", "format": "float" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "Invoice": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "example": 1001 },
          "tenant_slug": { "type": "string", "example": "iteca" },
          "erp_invoice_number": { "type": "string", "example": "INV-2026-0042" },
          "type": { "type": "string", "enum": ["invoice", "credit_note"] },
          "period_start": { "type": "string", "format": "date" },
          "period_end": { "type": "string", "format": "date" },
          "total_eur": { "type": "number", "format": "float" },
          "status": { "type": "string", "enum": ["draft", "issued", "paid", "past_due", "cancelled", "refunded", "partially_refunded"] },
          "due_date": { "type": "string", "format": "date", "nullable": true },
          "paid_at": { "type": "string", "format": "date", "nullable": true }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "current_page": { "type": "integer", "example": 1 },
          "per_page": { "type": "integer", "example": 50 },
          "total": { "type": "integer", "example": 234 },
          "last_page": { "type": "integer", "example": 5 }
        }
      }
    }
  },
  "security": [{ "BearerAuth": [] }],
  "tags": [
    { "name": "Auth", "description": "Token user info" },
    { "name": "Subscriptions", "description": "SaaS naročnine" },
    { "name": "Tenants", "description": "Tenanti (kupci)" },
    { "name": "Invoices", "description": "SaaS računi" }
  ],
  "paths": {
    "/me": {
      "get": {
        "tags": ["Auth"],
        "summary": "Current API token user",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "data": { "$ref": "#/components/schemas/User" } }
                }
              }
            }
          },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/subscriptions": {
      "get": {
        "tags": ["Subscriptions"],
        "summary": "List subscriptions",
        "parameters": [
          { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Filter po status" },
          { "name": "page",   "in": "query", "schema": { "type": "integer", "default": 1 } },
          { "name": "per_page","in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } },
                    "meta": { "$ref": "#/components/schemas/Pagination" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/subscriptions/{subscription}": {
      "get": {
        "tags": ["Subscriptions"],
        "summary": "Show single subscription",
        "parameters": [
          { "name": "subscription", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Subscription" } } } } } },
          "404": { "description": "Not found" }
        }
      }
    },
    "/tenants": {
      "get": {
        "tags": ["Tenants"],
        "summary": "List tenants",
        "parameters": [
          { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search by name/slug" },
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
          { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 50 } }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tenant" } },
                    "meta": { "$ref": "#/components/schemas/Pagination" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/tenants/{tenant}": {
      "get": {
        "tags": ["Tenants"],
        "summary": "Show single tenant",
        "parameters": [
          { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tenant slug" }
        ],
        "responses": {
          "200": { "description": "OK" },
          "404": { "description": "Not found" }
        }
      }
    },
    "/invoices": {
      "get": {
        "tags": ["Invoices"],
        "summary": "List SaaS invoices",
        "parameters": [
          { "name": "tenant_slug", "in": "query", "schema": { "type": "string" } },
          { "name": "status", "in": "query", "schema": { "type": "string" } },
          { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } },
                    "meta": { "$ref": "#/components/schemas/Pagination" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/invoices/{invoice}": {
      "get": {
        "tags": ["Invoices"],
        "summary": "Show single invoice",
        "parameters": [
          { "name": "invoice", "in": "path", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "OK" },
          "404": { "description": "Not found" }
        }
      }
    }
  }
}