# Poqet Invoicing API: Comprehensive AI & LLM Technical Specification

> Complete reference manual for AI coding assistants, autonomous agents, and developer integrations.
> Authoritative documentation for Poqet REST API and Model Context Protocol (MCP) Server.

## 1. System Overview
Poqet is an all-in-one invoicing platform combining a calm, free cloud workspace for freelancers and small businesses with a developer-first B2B Invoicing REST API & Model Context Protocol (MCP) Server for automated platform and AI agent billing.
- Production App URL: https://poqet.app
- Base API Endpoint: https://api.poqet.app
- Document Verification Portal: https://poqet.app/verify
- Hosted Documents Base: https://poqet.app/invoice/share/{shareToken}
- Interactive Documentation: https://poqet.app/docs
- API Overview: https://poqet.app/invoicing-api
- OpenAPI 3.1 Spec: https://poqet.app/openapi.json
- Model Context Protocol (MCP) Package: `@poqet/mcp` on NPM

---

## 2. Authentication & Tenancy Model

### Master API Key
All requests require secret API key authentication via header:
- Header: `X-Poqet-Key: pq_live_` followed by 48 lowercase hexadecimal characters (production mode)
- Header: `X-Poqet-Key: pq_test_` followed by 48 lowercase hexadecimal characters (sandbox test mode)
- Alternative: `Authorization: Bearer pq_live_...`
- Invoice retries: `Idempotency-Key: order_1001` (URL-safe, up to 128 characters, retained for 24 hours and bound to the exact request body).
- Test keys use isolated invoice storage and numbering. Test PDFs are watermarked; email, public share links, and live sub-account management are disabled.

### Multi-Tenant Virtual Sub-Accounts (`X-Poqet-Account`)
Marketplace platforms (e.g. Doctor Plus, clinic management portals, multi-vendor marketplaces) can isolate branding, doctor profiles, tax numbers, and invoice sequences per professional:
- Header: `X-Poqet-Account: dr_sarah_smith` (or `acc_8f9a1b2c3d4e5f60`)
- Features:
  - Dedicated sequential numbering series (e.g. `DRS-001`, `DRS-002`).
  - Isolated clinic address, logo, and GSTIN/VAT tax number.
  - Zero-Touch Just-In-Time (JIT) provisioning: Passing a new sub-account ID with `business` profile metadata in `POST /api/v1/invoices` automatically creates the sub-account on first invoice creation.

---

## 3. Visual PDF Templates & Themes
Poqet includes built-in visual themes for PDF generation and hosted invoice rendering. Pass `templateId` in request bodies or query parameters:
1. `clean-minimal` (Default): Modern Swiss minimalist design with refined typography and spacious padding.
2. `modern`: Contemporary layout featuring colored header bands and badge highlights.
3. `standard`: Classic corporate layout with balanced columns and corporate hierarchy.
4. `grid`: Modular boxed layout with defined borders for itemized bills.
5. `spreadsheet`: High-density tabular layout optimized for invoices with 10+ line items.
6. `legacy-basic`: Ultra-clean monochrome format for thermal printers and standard black-and-white printing.

---

## 4. Complete Invoicing API Reference

### 4.1 Create Invoice
- **Endpoint**: `POST /api/v1/invoices`
- **Description**: Persists an official invoice in the database, allocates sequence counter, renders the vector PDF, creates public share token, and optionally sends an automated email.

#### Full Request JSON Schema
```json
{
  "customer": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "+1 555-0199",
    "address": "123 Main St, New York, NY 10001",
    "gstin": "29ABCDE1234F1Z5"
  },
  "business": {
    "name": "Dr. Sarah Smith",
    "businessName": "Smith Heart & Vascular Clinic",
    "email": "dr.smith@clinic.example",
    "phone": "+1 555-0144",
    "address": "Suite 400, 100 Medical Plaza, NY 10001",
    "taxNumber": "29ABCDE1234F1Z5",
    "logoUrl": "data:image/png;base64,iVBORw0KGgo...",
    "invoicePrefix": "DRS-",
    "invoicePadding": 3,
    "initialInvoiceNumber": 1
  },
  "items": [
    {
      "name": "Specialist Consultation",
      "description": "Comprehensive cardiac evaluation and ECG review",
      "quantity": 1,
      "unitPrice": 250.00,
      "discount": 10.0,
      "tax": 18.0,
      "hsnSacCode": "998311"
    }
  ],
  "paymentDetails": {
    "accountHolderName": "Smith Heart Clinic LLC",
    "accountNumber": "9876543210",
    "ifscCode": "HDFC0001234",
    "bankName": "HDFC Bank",
    "branchName": "Fifth Avenue",
    "upiId": "smithclinic@okhdfcbank",
    "upiLinkedNumber": "9876543210",
    "iban": "US12345678901234567890",
    "swiftBic": "HDFCINBB",
    "paymentLink": "https://pay.stripe.com/invoice/inv_123"
  },
  "date": "2026-08-31",
  "dueDate": "2026-09-15",
  "currency": "USD",
  "templateId": "clean-minimal",
  "status": "PAID",
  "notes": "Thank you for choosing our clinic.",
  "terms": "Payment due within 15 days of issue.",
  "discount": 0.0,
  "tax": 0.0,
  "deliveryCharge": 0.0,
  "packagingCharge": 0.0,
  "paymentMethod": "STRIPE",
  "transactionReference": "pi_3N9xYz123456",
  "autoEmail": true
}
```

#### Response JSON Schema (201 Created)
```json
{
  "id": "7b8f9e0a-1c2d-4e5f-9a8b-0c1d2e3f4a5b",
  "invoiceNumber": "DRS-001",
  "status": "PAID",
  "date": "2026-08-31",
  "dueDate": "2026-09-15",
  "currency": "USD",
  "subtotal": 250.00,
  "discount": 25.00,
  "tax": 40.50,
  "deliveryCharge": 0.0,
  "packagingCharge": 0.0,
  "amount": 265.50,
  "paidAmount": 265.50,
  "balanceDue": 0.0,
  "amountInWords": "USD Two Hundred Sixty Five Dollars and Fifty Cents Only",
  "notes": "Thank you for choosing our clinic.",
  "terms": "Payment due within 15 days of issue.",
  "templateId": "clean-minimal",
  "business": {
    "name": "Dr. Sarah Smith",
    "businessName": "Smith Heart & Vascular Clinic",
    "address": "Suite 400, 100 Medical Plaza, NY 10001",
    "taxNumber": "29ABCDE1234F1Z5",
    "email": "dr.smith@clinic.example",
    "phone": "+1 555-0144"
  },
  "customer": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "+1 555-0199",
    "address": "123 Main St, New York, NY 10001"
  },
  "items": [
    {
      "id": "item_0",
      "name": "Specialist Consultation",
      "description": "Comprehensive cardiac evaluation and ECG review",
      "quantity": 1.0,
      "unitPrice": 250.00,
      "discount": 10.0,
      "tax": 18.0,
      "lineTotal": 265.50,
      "hsnSacCode": "998311"
    }
  ],
  "paymentDetails": {
    "accountHolderName": "Smith Heart Clinic LLC",
    "accountNumber": "9876543210",
    "ifscCode": "HDFC0001234",
    "bankName": "HDFC Bank",
    "branchName": "Fifth Avenue",
    "upiId": "smithclinic@okhdfcbank",
    "qrCodeDataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  },
  "hostedUrl": "https://poqet.app/invoice/share/tok_7b8f9e0a",
  "pdfUrl": "https://api.poqet.app/api/v1/invoices/7b8f9e0a-1c2d-4e5f-9a8b-0c1d2e3f4a5b/pdf",
  "emailed": true,
  "mode": "LIVE",
  "createdAt": "2026-08-31T12:00:00Z"
}
```

---

### 4.2 Instant On-The-Fly PDF Generation (Stateless)
- **Endpoint**: `POST /api/v1/invoices/generate-pdf`
- **Query Parameters**: `?template=modern` (optional)
- **Headers**: `X-Poqet-Key: pq_live_...`, `Content-Type: application/json`
- **Description**: Accepts invoice JSON payload and directly returns binary vector PDF stream with `Content-Type: application/pdf` without database persistence.

---

### 4.3 List Invoices
- **Endpoint**: `GET /api/v1/invoices`
- **Query Parameters**: `?limit=20&cursor=<nextCursor>` (preferred), or `?limit=20&offset=0` for compatibility
- **Headers**: `X-Poqet-Key: pq_live_...`, optional `X-Poqet-Account: acc_...`
- **Returns**: Paginated object `{ items, limit, offset?, total, hasMore, nextCursor? }`. Pass `nextCursor` back as `cursor`; defaults to limit 50 and maximum limit is 200.

---

### 4.4 Retrieve Single Invoice
- **Endpoint**: `GET /api/v1/invoices/{id}`
- **Headers**: `X-Poqet-Key: pq_live_...`, optional `X-Poqet-Account: acc_...`

---

### 4.5 Download Invoice PDF
- **Endpoint**: `GET /api/v1/invoices/{id}/pdf`
- **Query Parameters**: `?template=clean-minimal` (optional)
- **Headers**: `X-Poqet-Key: pq_live_...`, optional `X-Poqet-Account: acc_...`
- **Returns**: Binary PDF with `Content-Disposition: attachment; filename="invoice_{invoiceNumber}.pdf"`.

---

### 4.6 Void / Cancel Invoice
- **Endpoint**: `POST /api/v1/invoices/{id}/void`
- **Query Parameters**: `?reason=Customer%20Refund`
- **Headers**: `X-Poqet-Key: pq_live_...`, optional `X-Poqet-Account: acc_...`

---

## 5. Model Context Protocol (MCP) Server Specification

### Package Installation & Execution
```bash
npx -y @poqet/mcp
```

### Configuration Snippet (`claude_desktop_config.json` / `.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "poqet": {
      "command": "npx",
      "args": ["-y", "@poqet/mcp"],
      "env": {
        "POQET_API_KEY": "pq_live_your_key_here"
      }
    }
  }
}
```

### Exposed MCP Tools
1. `poqet_create_invoice(customer, items, currency, status, autoEmail, templateId, notes, terms, business, paymentDetails, subAccountId, idempotencyKey)`
2. `poqet_generate_pdf_preview(customer, items, currency, templateId, subAccountId)` (returns a temporary local PDF path)
3. `poqet_get_invoice(id, subAccountId)`
4. `poqet_list_invoices(limit, cursor, offset, subAccountId)`
5. `poqet_void_invoice(id, reason, subAccountId)`
6. `poqet_create_sub_account(name, businessName, email, taxNumber, invoiceNumberPrefix)`
7. `poqet_list_sub_accounts()`
8. `poqet_get_sub_account(id)`
9. `poqet_update_sub_account(id, businessName, taxNumber)`

---

## 6. HTTP Status & Error Codes
- `200 OK`: Request succeeded.
- `201 Created`: Invoice or sub-account created.
- `400 Bad Request`: Payload validation failed.
- `401 Unauthorized`: Invalid or missing `X-Poqet-Key`.
- `404 Not Found`: Target invoice ID or sub-account does not exist.
- `403 Forbidden`: API key scope or environment does not permit the operation.
- `429 Too Many Requests`: Rate limit threshold reached (300 requests/minute per authenticated account; PDF/render operations use a lower 30/minute bucket).
- `500 Internal Server Error`: Backend error.