{
  "openapi": "3.1.0",
  "info": {
    "title": "POS Software API",
    "version": "v1",
    "description": "POS Software APIs help stores manage billing, item catalogs, inventory movement, registers, payments, taxes, and daily sales reporting.",
    "contact": {
      "name": "Azeosoft Web Technologies",
      "url": "https://azeosoft.com"
    }
  },
  "servers": [
    {
      "url": "https://api-pos.azeosoft.com/v1",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Authentication",
      "description": "Authenticate and verify access for POS Software integrations."
    },
    {
      "name": "Products",
      "description": "Create, read, update, and list products in POS Software."
    },
    {
      "name": "Sales Orders",
      "description": "Manage sales orders workflows in POS Software."
    },
    {
      "name": "Reports",
      "description": "Export POS Software analytics and operational summaries."
    }
  ],
  "paths": {
    "/auth/token": {
      "post": {
        "operationId": "pos-token",
        "summary": "Create access token",
        "description": "Creates a short-lived access token for POS Software API requests.",
        "tags": [
          "Authentication"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Access token returned",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "access_token": "az_live_token",
                    "token_type": "Bearer",
                    "expires_in": 3600
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "description": "Client credentials issued from the product admin panel.",
          "required": true,
          "content": {
            "application/json": {
              "example": {
                "client_id": "pos_client",
                "client_secret": "********"
              }
            }
          }
        }
      }
    },
    "/auth/profile": {
      "get": {
        "operationId": "pos-profile",
        "summary": "Get integration profile",
        "description": "Returns organization and permission details for the authenticated POS Software integration.",
        "tags": [
          "Authentication"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Integration profile returned",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "organizationId": "org_001",
                    "product": "POS Software",
                    "scopes": [
                      "read",
                      "write"
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/products": {
      "get": {
        "operationId": "pos-list-records",
        "summary": "List products",
        "description": "Returns a paginated list of products for the organization.",
        "tags": [
          "Products"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum records to return.",
            "schema": {
              "type": "integer"
            },
            "example": "50"
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Pagination cursor from the previous response.",
            "schema": {
              "type": "string"
            },
            "example": "next_abc123"
          }
        ],
        "responses": {
          "200": {
            "description": "Products list returned",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "items": [
                      {
                        "id": "product_id_001",
                        "name": "Cotton Shirt",
                        "sku": "CS-001",
                        "price": 1299,
                        "stock": 48,
                        "tax_rate": 18
                      }
                    ],
                    "nextCursor": null
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "post": {
        "operationId": "pos-create-record",
        "summary": "Create products",
        "description": "Creates a new products record.",
        "tags": [
          "Products"
        ],
        "parameters": [],
        "responses": {
          "201": {
            "description": "Products created",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "id": "product_id_001",
                    "name": "Cotton Shirt",
                    "sku": "CS-001",
                    "price": 1299,
                    "stock": 48,
                    "tax_rate": 18,
                    "created_at": "2026-07-26T09:00:00Z"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "description": "Products fields.",
          "required": true,
          "content": {
            "application/json": {
              "example": {
                "name": "Cotton Shirt",
                "sku": "CS-001",
                "price": 1299,
                "stock": 48,
                "tax_rate": 18
              }
            }
          }
        }
      }
    },
    "/products/{product_id}": {
      "get": {
        "operationId": "pos-get-record",
        "summary": "Get products details",
        "description": "Returns details for a specific products record.",
        "tags": [
          "Products"
        ],
        "parameters": [
          {
            "name": "product_id",
            "in": "path",
            "required": true,
            "description": "Products ID.",
            "schema": {
              "type": "string"
            },
            "example": "product_id_001"
          }
        ],
        "responses": {
          "200": {
            "description": "Products details returned",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "id": "product_id_001",
                    "name": "Cotton Shirt",
                    "sku": "CS-001",
                    "price": 1299,
                    "stock": 48,
                    "tax_rate": 18
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "patch": {
        "operationId": "pos-update-record",
        "summary": "Update products",
        "description": "Updates selected fields on a products record.",
        "tags": [
          "Products"
        ],
        "parameters": [
          {
            "name": "product_id",
            "in": "path",
            "required": true,
            "description": "Products ID.",
            "schema": {
              "type": "string"
            },
            "example": "product_id_001"
          }
        ],
        "responses": {
          "200": {
            "description": "Products updated",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "id": "product_id_001",
                    "status": "active",
                    "updated_at": "2026-07-26T10:00:00Z"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "description": "Partial Products fields.",
          "required": true,
          "content": {
            "application/json": {
              "example": {
                "status": "active"
              }
            }
          }
        }
      }
    },
    "/sales-orders": {
      "get": {
        "operationId": "pos-workflow-list",
        "summary": "List sales orders",
        "description": "Returns workflow records used by POS Software.",
        "tags": [
          "Sales Orders"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Sales Orders returned",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "items": [
                      {
                        "id": "flow_001",
                        "name": "Sales Orders",
                        "status": "active"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/sales-orders/actions": {
      "post": {
        "operationId": "pos-workflow-action",
        "summary": "Create sales orders action",
        "description": "Creates an operational action inside the sales orders workflow.",
        "tags": [
          "Sales Orders"
        ],
        "parameters": [],
        "responses": {
          "201": {
            "description": "Workflow action created",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "actionId": "act_001",
                    "status": "queued"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "description": "Workflow action payload.",
          "required": true,
          "content": {
            "application/json": {
              "example": {
                "target_id": "product_id_001",
                "action": "assign",
                "owner_id": "user_001",
                "note": "Assigned from API"
              }
            }
          }
        }
      }
    },
    "/reports/daily-sales": {
      "get": {
        "operationId": "pos-summary-report",
        "summary": "Daily sales report",
        "description": "Returns the daily sales report for a selected date range.",
        "tags": [
          "Reports"
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": true,
            "description": "Start date in YYYY-MM-DD format.",
            "schema": {
              "type": "string"
            },
            "example": "2026-07-01"
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "description": "End date in YYYY-MM-DD format.",
            "schema": {
              "type": "string"
            },
            "example": "2026-07-26"
          }
        ],
        "responses": {
          "200": {
            "description": "Report returned",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "from": "2026-07-01",
                    "to": "2026-07-26",
                    "totals": {
                      "records": 128,
                      "open": 18,
                      "closed": 110
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/reports/daily-sales/export": {
      "post": {
        "operationId": "pos-export-report",
        "summary": "Export report",
        "description": "Creates a downloadable POS Software report export.",
        "tags": [
          "Reports"
        ],
        "parameters": [],
        "responses": {
          "202": {
            "description": "Export queued",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "exportId": "exp_001",
                    "status": "processing"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "description": "Export options.",
          "required": true,
          "content": {
            "application/json": {
              "example": {
                "format": "csv",
                "from": "2026-07-01",
                "to": "2026-07-26"
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      },
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      }
    }
  }
}