{
  "openapi": "3.1.0",
  "info": {
    "title": "Poqet Invoicing & PDF Automation API",
    "version": "1.1.0",
    "description": "Developer-first B2B API for automated invoice generation, multi-tenant virtual sub-accounts, instant PDF rendering, and customer email delivery."
  },
  "servers": [
    {
      "url": "https://api.poqet.app",
      "description": "Production Server"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Poqet-Key",
        "description": "Master API Key starting with pq_live_ or pq_test_"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Alternative Bearer token authentication"
      }
    },
    "parameters": {
      "TenantAccountHeader": {
        "name": "X-Poqet-Account",
        "in": "header",
        "required": false,
        "description": "Sub-Account identifier (e.g. acc_... or custom ID like dr_smith_99) for multi-tenant isolation",
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "BusinessProfile": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "businessName": { "type": "string" },
          "address": { "type": "string" },
          "taxNumber": { "type": "string" },
          "logoUrl": { "type": "string" },
          "email": { "type": "string" },
          "phone": { "type": "string" },
          "website": { "type": "string" },
          "invoicePrefix": { "type": "string" },
          "invoicePadding": { "type": "integer" },
          "initialInvoiceNumber": { "type": "integer" }
        }
      },
      "CustomerDetails": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "email": { "type": "string" },
          "phone": { "type": "string" },
          "address": { "type": "string" },
          "gstin": { "type": "string" }
        }
      },
      "InvoiceItem": {
        "type": "object",
        "required": ["name", "unitPrice"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "quantity": { "type": "number", "default": 1.0 },
          "unitPrice": { "type": "number" },
          "discount": { "type": "number", "default": 0.0 },
          "tax": { "type": "number", "default": 0.0 },
          "lineTotal": { "type": "number" },
          "hsnSacCode": { "type": "string" }
        }
      },
      "BankPaymentDetails": {
        "type": "object",
        "properties": {
          "accountHolderName": { "type": "string" },
          "accountNumber": { "type": "string" },
          "ifscCode": { "type": "string" },
          "bankName": { "type": "string" },
          "branchName": { "type": "string" },
          "upiId": { "type": "string" },
          "upiLinkedNumber": { "type": "string" },
          "iban": { "type": "string" },
          "swiftBic": { "type": "string" },
          "routingNumber": { "type": "string" },
          "accountType": { "type": "string" },
          "qrCodeDataUrl": { "type": "string" },
          "paymentLink": { "type": "string" },
          "instructions": { "type": "string" }
        }
      },
      "InvoiceApiResponse": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "invoiceNumber": { "type": "string" },
          "status": { "type": "string", "enum": ["PAID", "PENDING", "DRAFT", "VOID"] },
          "date": { "type": "string" },
          "dueDate": { "type": "string" },
          "currency": { "type": "string" },
          "subtotal": { "type": "number" },
          "discount": { "type": "number" },
          "tax": { "type": "number" },
          "deliveryCharge": { "type": "number" },
          "packagingCharge": { "type": "number" },
          "amount": { "type": "number" },
          "paidAmount": { "type": "number" },
          "balanceDue": { "type": "number" },
          "amountInWords": { "type": "string" },
          "notes": { "type": "string" },
          "terms": { "type": "string" },
          "templateId": { "type": "string" },
          "business": { "$ref": "#/components/schemas/BusinessProfile" },
          "customer": { "$ref": "#/components/schemas/CustomerDetails" },
          "items": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/InvoiceItem" }
          },
          "paymentDetails": { "$ref": "#/components/schemas/BankPaymentDetails" },
          "hostedUrl": { "type": "string" },
          "pdfUrl": { "type": "string" },
          "emailed": { "type": "boolean" },
          "mode": { "type": "string", "enum": ["LIVE", "TEST"] },
          "createdAt": { "type": "string" }
        }
      },
      "SubAccountResponse": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "businessName": { "type": "string" },
          "email": { "type": "string" },
          "phone": { "type": "string" },
          "taxNumber": { "type": "string" },
          "businessAddress": { "type": "string" },
          "businessLogoUrl": { "type": "string" },
          "currency": { "type": "string" },
          "invoiceNumberPrefix": { "type": "string" },
          "invoiceNumberPadding": { "type": "integer" },
          "nextInvoiceNumber": { "type": "integer" },
          "defaultTemplateId": { "type": "string" },
          "active": { "type": "boolean" },
          "createdAt": { "type": "string" }
        }
      }
    }
  },
  "security": [
    { "ApiKeyAuth": [] },
    { "BearerAuth": [] }
  ],
  "paths": {
    "/api/v1/sub-accounts": {
      "post": {
        "summary": "Provision Sub-Account",
        "description": "Creates a virtual sub-account for an individual doctor, merchant, or vendor under the platform.",
        "responses": {
          "201": {
            "description": "Sub-account provisioned successfully",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SubAccountResponse" }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List Sub-Accounts",
        "description": "Returns all active sub-accounts provisioned under this platform API key.",
        "responses": {
          "200": {
            "description": "List of sub-accounts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/SubAccountResponse" }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/sub-accounts/{id}": {
      "get": {
        "summary": "Get Sub-Account Details",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Sub-account details",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SubAccountResponse" }
              }
            }
          },
          "404": { "description": "Sub-account not found" }
        }
      },
      "patch": {
        "summary": "Update Sub-Account",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Sub-account updated successfully",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SubAccountResponse" }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Deactivate Sub-Account",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "204": { "description": "Sub-account deactivated successfully" }
        }
      }
    },
    "/api/v1/invoices": {
      "get": {
        "summary": "List Invoices",
        "description": "Returns a list or paginated page of invoices created under this account or sub-account.",
        "parameters": [
          { "$ref": "#/components/parameters/TenantAccountHeader" },
          { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } },
          { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": {
            "description": "List of invoices retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/InvoiceApiResponse" }
                }
              }
            }
          },
          "401": { "description": "Invalid or missing API key" }
        }
      },
      "post": {
        "summary": "Create Invoice",
        "description": "Creates and stores an invoice, assigns an official sequence number, renders PDF, and optionally emails the buyer. Supports automatic JIT sub-account upsert if business payload is provided with X-Poqet-Account.",
        "parameters": [
          { "$ref": "#/components/parameters/TenantAccountHeader" }
        ],
        "responses": {
          "201": {
            "description": "Invoice created successfully",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/InvoiceApiResponse" }
              }
            }
          },
          "400": { "description": "Invalid input payload" },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    },
    "/api/v1/invoices/generate-pdf": {
      "post": {
        "summary": "Instant PDF Stream",
        "description": "Generates a PDF on-the-fly and streams the binary bytes without database persistence.",
        "parameters": [
          { "$ref": "#/components/parameters/TenantAccountHeader" }
        ],
        "responses": {
          "200": {
            "description": "Binary PDF stream (application/pdf)"
          }
        }
      }
    },
    "/api/v1/invoices/{id}": {
      "get": {
        "summary": "Get Invoice",
        "parameters": [
          { "$ref": "#/components/parameters/TenantAccountHeader" },
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Invoice found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/InvoiceApiResponse" }
              }
            }
          },
          "404": { "description": "Invoice not found" }
        }
      }
    },
    "/api/v1/invoices/{id}/pdf": {
      "get": {
        "summary": "Download Invoice PDF",
        "parameters": [
          { "$ref": "#/components/parameters/TenantAccountHeader" },
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "template", "in": "query", "required": false, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "PDF file attachment"
          }
        }
      }
    },
    "/api/v1/invoices/{id}/void": {
      "post": {
        "summary": "Void Invoice",
        "parameters": [
          { "$ref": "#/components/parameters/TenantAccountHeader" },
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "reason", "in": "query", "required": false, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Invoice voided successfully" },
          "404": { "description": "Invoice not found" }
        }
      }
    }
  }
}