{
  "name": "shopPRO API",
  "version": "1.0.0",
  "entrypoint": "/api.php",
  "authentication": {
    "type": "header",
    "header": "X-Api-Key",
    "required": true,
    "description": "API key stored in pp_settings.param=api_key"
  },
  "response_format": {
    "success": {
      "status": "ok",
      "data": {}
    },
    "error": {
      "status": "error",
      "code": "BAD_REQUEST",
      "message": "Human-readable error message"
    },
    "error_codes": [
      { "code": "UNAUTHORIZED", "http": 401 },
      { "code": "BAD_REQUEST", "http": 400 },
      { "code": "NOT_FOUND", "http": 404 },
      { "code": "METHOD_NOT_ALLOWED", "http": 405 },
      { "code": "INTERNAL_ERROR", "http": 500 }
    ]
  },
  "endpoints": [
    {
      "group": "orders",
      "action": "list",
      "method": "GET",
      "url_template": "/api.php?endpoint=orders&action=list",
      "query_params": [
        { "name": "status", "type": "string", "required": false },
        { "name": "paid", "type": "string", "required": false },
        { "name": "date_from", "type": "string", "required": false, "format": "YYYY-MM-DD" },
        { "name": "date_to", "type": "string", "required": false, "format": "YYYY-MM-DD" },
        { "name": "updated_since", "type": "string", "required": false, "format": "YYYY-MM-DD HH:MM:SS" },
        { "name": "number", "type": "string", "required": false },
        { "name": "client", "type": "string", "required": false },
        { "name": "page", "type": "integer", "required": false, "default": 1, "min": 1 },
        { "name": "per_page", "type": "integer", "required": false, "default": 50, "min": 1, "max": 100 }
      ]
    },
    {
      "group": "orders",
      "action": "get",
      "method": "GET",
      "url_template": "/api.php?endpoint=orders&action=get&id={order_id}",
      "query_params": [
        { "name": "id", "type": "integer", "required": true, "min": 1 }
      ]
    },
    {
      "group": "orders",
      "action": "change_status",
      "method": "PUT",
      "url_template": "/api.php?endpoint=orders&action=change_status&id={order_id}",
      "query_params": [
        { "name": "id", "type": "integer", "required": true, "min": 1 }
      ],
      "json_body": {
        "required_fields": ["status_id"],
        "fields": {
          "status_id": { "type": "integer" },
          "send_email": { "type": "boolean", "required": false }
        }
      }
    },
    {
      "group": "orders",
      "action": "set_paid",
      "method": "PUT",
      "url_template": "/api.php?endpoint=orders&action=set_paid&id={order_id}",
      "query_params": [
        { "name": "id", "type": "integer", "required": true, "min": 1 }
      ],
      "json_body": {
        "required_fields": [],
        "fields": {
          "send_email": { "type": "boolean", "required": false }
        }
      }
    },
    {
      "group": "orders",
      "action": "set_unpaid",
      "method": "PUT",
      "url_template": "/api.php?endpoint=orders&action=set_unpaid&id={order_id}",
      "query_params": [
        { "name": "id", "type": "integer", "required": true, "min": 1 }
      ]
    },
    {
      "group": "products",
      "action": "list",
      "method": "GET",
      "url_template": "/api.php?endpoint=products&action=list",
      "query_params": [
        { "name": "search", "type": "string", "required": false },
        { "name": "status", "type": "string", "required": false },
        { "name": "promoted", "type": "string", "required": false },
        { "name": "attribute_{id}", "type": "integer", "required": false, "description": "e.g. attribute_5=12" },
        { "name": "sort", "type": "string", "required": false, "default": "id", "allowed": ["id", "name", "price_brutto", "status", "promoted", "quantity"] },
        { "name": "sort_dir", "type": "string", "required": false, "default": "DESC", "allowed": ["ASC", "DESC"] },
        { "name": "page", "type": "integer", "required": false, "default": 1, "min": 1 },
        { "name": "per_page", "type": "integer", "required": false, "default": 50, "min": 1, "max": 100 }
      ]
    },
    {
      "group": "products",
      "action": "get",
      "method": "GET",
      "url_template": "/api.php?endpoint=products&action=get&id={product_id}",
      "query_params": [
        { "name": "id", "type": "integer", "required": true, "min": 1 }
      ]
    },
    {
      "group": "products",
      "action": "create",
      "method": "POST",
      "url_template": "/api.php?endpoint=products&action=create",
      "json_body": {
        "required_fields": ["languages", "price_brutto"],
        "rules": [
          "languages must be an object with at least one language entry containing name",
          "price_brutto must be numeric and >= 0"
        ]
      }
    },
    {
      "group": "products",
      "action": "update",
      "method": "PUT",
      "url_template": "/api.php?endpoint=products&action=update&id={product_id}",
      "query_params": [
        { "name": "id", "type": "integer", "required": true, "min": 1 }
      ],
      "json_body": {
        "required_fields": [],
        "rules": ["partial update; only changed fields are needed"]
      }
    },
    {
      "group": "products",
      "action": "variants",
      "method": "GET",
      "url_template": "/api.php?endpoint=products&action=variants&id={product_id}",
      "query_params": [
        { "name": "id", "type": "integer", "required": true, "min": 1 }
      ]
    },
    {
      "group": "products",
      "action": "create_variant",
      "method": "POST",
      "url_template": "/api.php?endpoint=products&action=create_variant&id={product_id}",
      "query_params": [
        { "name": "id", "type": "integer", "required": true, "min": 1 }
      ],
      "json_body": {
        "required_fields": ["attributes"],
        "fields": {
          "attributes": { "type": "object", "description": "Map attribute_id -> value_id" }
        }
      }
    },
    {
      "group": "products",
      "action": "update_variant",
      "method": "PUT",
      "url_template": "/api.php?endpoint=products&action=update_variant&id={variant_id}",
      "query_params": [
        { "name": "id", "type": "integer", "required": true, "min": 1 }
      ],
      "json_body": {
        "required_fields": [],
        "rules": ["partial update of variant fields"]
      }
    },
    {
      "group": "products",
      "action": "delete_variant",
      "method": "DELETE",
      "url_template": "/api.php?endpoint=products&action=delete_variant&id={variant_id}",
      "query_params": [
        { "name": "id", "type": "integer", "required": true, "min": 1 }
      ]
    },
    {
      "group": "products",
      "action": "upload_image",
      "method": "POST",
      "url_template": "/api.php?endpoint=products&action=upload_image",
      "json_body": {
        "required_fields": ["id", "file_name", "content_base64"],
        "fields": {
          "id": { "type": "integer", "description": "product id" },
          "file_name": { "type": "string" },
          "content_base64": { "type": "string", "description": "base64 payload" },
          "alt": { "type": "string", "required": false },
          "o": { "type": "integer", "required": false, "description": "image position" }
        }
      }
    },
    {
      "group": "dictionaries",
      "action": "statuses",
      "method": "GET",
      "url_template": "/api.php?endpoint=dictionaries&action=statuses"
    },
    {
      "group": "dictionaries",
      "action": "transports",
      "method": "GET",
      "url_template": "/api.php?endpoint=dictionaries&action=transports"
    },
    {
      "group": "dictionaries",
      "action": "payment_methods",
      "method": "GET",
      "url_template": "/api.php?endpoint=dictionaries&action=payment_methods"
    },
    {
      "group": "dictionaries",
      "action": "attributes",
      "method": "GET",
      "url_template": "/api.php?endpoint=dictionaries&action=attributes"
    },
    {
      "group": "dictionaries",
      "action": "ensure_attribute",
      "method": "POST",
      "url_template": "/api.php?endpoint=dictionaries&action=ensure_attribute",
      "json_body": {
        "required_fields": ["name"],
        "fields": {
          "name": { "type": "string" },
          "type": { "type": "integer", "required": false, "default": 0 },
          "lang": { "type": "string", "required": false, "default": "pl" }
        }
      }
    },
    {
      "group": "dictionaries",
      "action": "ensure_attribute_value",
      "method": "POST",
      "url_template": "/api.php?endpoint=dictionaries&action=ensure_attribute_value",
      "json_body": {
        "required_fields": ["attribute_id", "name"],
        "fields": {
          "attribute_id": { "type": "integer" },
          "name": { "type": "string" },
          "lang": { "type": "string", "required": false, "default": "pl" }
        }
      }
    },
    {
      "group": "dictionaries",
      "action": "ensure_producer",
      "method": "POST",
      "url_template": "/api.php?endpoint=dictionaries&action=ensure_producer",
      "json_body": {
        "required_fields": ["name"],
        "fields": {
          "name": { "type": "string" }
        }
      }
    },
    {
      "group": "categories",
      "action": "list",
      "method": "GET",
      "url_template": "/api.php?endpoint=categories&action=list"
    }
  ],
  "examples": {
    "curl_list_products": "curl -X GET \"https://twoja-domena.pl/api.php?endpoint=products&action=list&page=1&per_page=20\" -H \"X-Api-Key: TWOJ_KLUCZ\"",
    "curl_get_order": "curl -X GET \"https://twoja-domena.pl/api.php?endpoint=orders&action=get&id=42\" -H \"X-Api-Key: TWOJ_KLUCZ\"",
    "curl_create_product": "curl -X POST \"https://twoja-domena.pl/api.php?endpoint=products&action=create\" -H \"X-Api-Key: TWOJ_KLUCZ\" -H \"Content-Type: application/json\" -d \"{\\\"price_brutto\\\":99.99,\\\"languages\\\":{\\\"pl\\\":{\\\"name\\\":\\\"Nowy produkt\\\"}}}\""
  },
  "source_of_truth": [
    "autoload/api/ApiRouter.php",
    "autoload/api/Controllers/OrdersApiController.php",
    "autoload/api/Controllers/ProductsApiController.php",
    "autoload/api/Controllers/DictionariesApiController.php",
    "autoload/api/Controllers/CategoriesApiController.php"
  ]
}