# Poqet

> Poqet is a calm, free cloud invoicing workspace for freelancers and small businesses, and a high-performance B2B Invoicing REST API & Model Context Protocol (MCP) server for platforms and AI agents.

## Product Overview

Poqet removes the bloated complexity of heavy accounting software, providing independent builders, service businesses, and agencies with an instant invoicing workspace:
- **Instant Vector PDF Generation**: 6 distinct designer themes rendered at high-DPI print precision.
- **Client & Item Directory**: Save frequent clients, billing details, and catalog line items.
- **Payment Tracking**: Track payment statuses (Draft, Unpaid, Partially Paid, Paid, Overdue) with automatic balance due calculation.
- **Multi-Currency Invoicing**: Real-time foreign exchange rate conversion.
- **Cryptographic Document Verification (DV) Codes**: Tamper-proof hash validation proving document authenticity and issue timestamps.
- **Free For Independents**: 100% free web app with zero subscription fees and no credit card required.

## Developer & AI Invoicing API

Poqet provides a developer-first REST API and an official MCP server enabling platforms, marketplaces, and autonomous AI agents to automate end-to-end billing:
- **Authentication**: Bearer API key (`X-Poqet-Key: pq_live_...` or `pq_test_...` for sandbox).
- **Multi-Tenant Sub-Accounts**: Virtual child accounts (`X-Poqet-Account: acc_...`) for multi-vendor marketplaces, clinics, and platforms with isolated numbering, branding, and tax IDs.
- **Idempotency**: Retry safety with `Idempotency-Key` headers retained for 24 hours.
- **Stateless PDF Generation**: Stream vector PDF binaries without database storage overhead.
- **Model Context Protocol**: Official `@poqet/mcp` package for Claude Desktop, Cursor, and Windsurf.

## Key URLs & Documentation

- [Free Invoicing App](https://poqet.app/): Main cloud invoicing workspace.
- [B2B Invoicing API](https://poqet.app/invoicing-api): Developer overview, interactive playground, and architecture guide.
- [Interactive Developer Docs](https://poqet.app/docs): Quickstart guide, SDK snippets, and endpoint reference.
- [Verify Document Authenticity](https://poqet.app/verify): Public verification portal for cryptographically signed DV Codes.
- [About Poqet](https://poqet.app/about): Company mission, team, and design philosophy.
- [Support & Contact](https://poqet.app/support): Help center, account support, and privacy requests.
- [Feedback & Ideas](https://poqet.app/feedback): Product roadmap feedback and community suggestions.
- [Full AI Technical Specification](https://poqet.app/llms-full.txt): Exhaustive technical specification with complete JSON request/response schemas, error codes, and field definitions for AI context ingestion.
- [OpenAPI 3.1 Specification](https://poqet.app/openapi.json): Standard OpenAPI JSON schema.
- [Privacy Policy](https://poqet.app/privacy-policy): Privacy and data governance policies.
- [Terms of Use](https://poqet.app/terms-of-use): Terms and conditions.
- [Cookie Policy](https://poqet.app/cookie-policy): Cookie disclosures and analytics tracking.

## Core API Endpoints

- `POST https://api.poqet.app/api/v1/invoices` - Create and issue an invoice. Computes taxes, discounts, totals, and public share links.
- `POST https://api.poqet.app/api/v1/invoices/generate-pdf` - Stateless on-the-fly PDF generator. Returns raw PDF binary stream without persisting state.
- `GET https://api.poqet.app/api/v1/invoices` - List recent invoices with pagination (`?limit=20&offset=0`).
- `GET https://api.poqet.app/api/v1/invoices/{id}` - Retrieve invoice details, status, breakdown, and banking info.
- `GET https://api.poqet.app/api/v1/invoices/{id}/pdf` - Download vector PDF attachment (`?template=clean-minimal`).
- `POST https://api.poqet.app/api/v1/invoices/{id}/void` - Cancel/void an invoice with audit reason (`?reason=Refunded`).
- `POST https://api.poqet.app/api/v1/sub-accounts` - Provision managed child sub-account for vendor/doctor.
- `GET https://api.poqet.app/api/v1/sub-accounts` - List all active sub-accounts.
- `GET https://api.poqet.app/api/v1/sub-accounts/{id}` - Get sub-account details.
- `PATCH https://api.poqet.app/api/v1/sub-accounts/{id}` - Update sub-account branding or prefix.

## Supported PDF Templates

Pass `templateId` in request body or query parameter:
- `clean-minimal` (Default): Modern Swiss minimalist layout with refined typography and spacious padding.
- `modern`: Contemporary layout featuring colored header band and badge highlights.
- `standard`: Classic corporate layout with balanced columns and corporate hierarchy.
- `grid`: Modular boxed layout with defined borders for itemized bills.
- `spreadsheet`: High-density tabular layout optimized for invoices with 10+ line items.
- `legacy-basic`: Ultra-clean monochrome format for thermal and black-and-white printing.

## Model Context Protocol (MCP) Setup

Add to Claude Desktop (`claude_desktop_config.json`) or Cursor (`.cursor/mcp.json`):
```json
{
  "mcpServers": {
    "poqet": {
      "command": "npx",
      "args": ["-y", "@poqet/mcp"],
      "env": {
        "POQET_API_KEY": "YOUR_POQET_API_KEY"
      }
    }
  }
}
```
Available tools: `poqet_create_invoice`, `poqet_generate_pdf_preview`, `poqet_get_invoice`, `poqet_list_invoices`, `poqet_void_invoice`, `poqet_create_sub_account`, `poqet_list_sub_accounts`, `poqet_get_sub_account`, `poqet_update_sub_account`.