# Poqet Invoicing API Specification for AI Agents & LLMs

> Poqet is a developer-first B2B Invoicing and automated PDF generation API.
> Platforms, e-commerce stores, marketplaces, and autonomous AI agents use Poqet to automate invoice creation, PDF generation, tax calculations, visual template customization, and customer email delivery.

## Key URLs
- **Production API**: https://api.poqet.app
- **Interactive Documentation**: https://poqet.app/docs
- **Full API Specification**: https://poqet.app/llms-full.txt
- **OpenAPI 3.1 JSON**: https://poqet.app/openapi.json
- **Hosted Invoice Views**: https://poqet.app/invoice/share/{shareToken}

---

## 3 Seamless Integration Methods

1. **Direct REST API**: Make standard HTTPS requests using `X-Poqet-Key: pq_live_...` or `pq_test_...`.
2. **AI-Agent Coder (`llms.txt`)**: Feed this URL (`https://poqet.app/llms.txt`) to Cursor, Claude Code, Windsurf, or ChatGPT to generate custom integration code.
3. **Model Context Protocol (MCP Server `@poqet/mcp`)**: Add Poqet MCP server to Claude Desktop or Cursor for zero-code tool invocation.

---

## Authentication & Headers

- **API Key**: `X-Poqet-Key: pq_live_...` (or `X-Poqet-Key: pq_test_...` for test sandbox)
- **Multi-Tenant / Sub-Account Header**: `X-Poqet-Account: acc_...` (or `dr_smith_99`)
  - Dynamically scopes invoice sequences (`DRS-001`), clinic branding, logo, tax ID, and address to that specific doctor/vendor.

---

## Core Endpoints Summary

### Invoices API
- `POST /api/v1/invoices` - Create and issue an invoice. Computes totals, taxes, balance due, and amount in words. Optionally emails the customer.
- `POST /api/v1/invoices/generate-pdf` - Stateless on-the-fly PDF binary generator. Returns PDF bytes without saving records.
- `GET /api/v1/invoices` - List recent invoices with pagination (`?limit=20&offset=0`).
- `GET /api/v1/invoices/{id}` - Retrieve invoice details, status, breakdown, and banking info.
- `GET /api/v1/invoices/{id}/pdf` - Download vector PDF attachment (`?template=modern`).
- `POST /api/v1/invoices/{id}/void` - Cancel/void an invoice with cancellation reason (`?reason=Refunded`).

### Sub-Accounts API (Marketplaces & Clinics)
- `POST /api/v1/sub-accounts` - Provision managed child account (doctor, clinic, merchant).
- `GET /api/v1/sub-accounts` - List all active sub-accounts.
- `GET /api/v1/sub-accounts/{id}` - Get sub-account details.
- `PATCH /api/v1/sub-accounts/{id}` - Update sub-account branding or prefix.

---

## Supported Visual PDF Templates
Pass `templateId` in request payload or query parameter:
- `clean-minimal` (Default): Clean, modern Swiss minimalist layout.
- `modern`: Sleek layout with colored header accent band and badge styling.
- `standard`: Classic professional business invoice layout with balanced typography.
- `grid`: Structured modular grid layout with defined bordered sections.
- `spreadsheet`: Compact data-dense tabular spreadsheet design for high-line-item orders.
- `legacy-basic`: Ultra-clean black-and-white print-friendly format.

---

## Model Context Protocol (MCP) Server
Add to `claude_desktop_config.json` or `.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "poqet": {
      "command": "npx",
      "args": ["-y", "@poqet/mcp"],
      "env": {
        "POQET_API_KEY": "YOUR_POQET_API_KEY"
      }
    }
  }
}
```
Exposed tools: `poqet_create_invoice`, `poqet_generate_pdf_preview`, `poqet_get_invoice`, `poqet_list_invoices`, `poqet_void_invoice`, `poqet_create_sub_account`.