63 lines
3.1 KiB
Markdown
63 lines
3.1 KiB
Markdown
# API + MCP Layer
|
|
|
|
## Environment
|
|
Add to `.env.local`:
|
|
|
|
```bash
|
|
NEXT_PUBLIC_POCKETBASE_URL=http://127.0.0.1:8090
|
|
PB_ADMIN_EMAIL=your_admin_email
|
|
PB_ADMIN_PASSWORD=your_admin_password
|
|
AGENT_API_KEY=replace_with_secure_token
|
|
ORDER_ITEMS_COLLECTION=order_items
|
|
```
|
|
|
|
## REST Endpoints
|
|
- `GET /api/v1/health`
|
|
- `GET /api/v1/orders?page=1&perPage=50&status=new`
|
|
- `POST /api/v1/orders/from-quote`
|
|
- `GET /api/v1/collection-pool?page=1&perPage=50&status=queued`
|
|
- `PATCH /api/v1/order-items/{id}/status`
|
|
- `GET /api/v1/quotes/next-number` — atomic `Q-YYYY-MM-NNN` counter via the `quote_counters` collection. Used by the quote form and the inbound email pipeline.
|
|
|
|
Auth for agent routes:
|
|
- Header: `Authorization: Bearer <AGENT_API_KEY>`
|
|
|
|
`POST /orders/from-quote` body:
|
|
```json
|
|
{ "quote_id": "QUOTE_RECORD_ID" }
|
|
```
|
|
|
|
`PATCH /order-items/{id}/status` body supports:
|
|
```json
|
|
{
|
|
"item_status": "processed",
|
|
"drv_status": "assigned",
|
|
"notes": "Assigned to route 2"
|
|
}
|
|
```
|
|
|
|
## MCP Endpoint
|
|
- `POST /api/mcp`
|
|
|
|
Supported methods:
|
|
- `tools/list`
|
|
- `tools/call`
|
|
|
|
Available tools:
|
|
- `orders.list`
|
|
- `orders.create_from_quote`
|
|
- `collection_pool.list`
|
|
- `order_items.update_status`
|
|
- `quotes.create_from_email` — create a new quote (with customer/company/items) from a parsed email payload. Idempotent on `message_id`. **Attachments are no longer uploaded inline in this call** — the legacy `attachments` field in the payload is accepted but ignored. After the create call returns the new quote id, call `attachments.upload_for_quote` once per file. This split exists because embedding base64 attachments in the create POST would blow past the Next.js 1 MB request body limit on a 5 MB PDF.
|
|
- `attachments.upload_for_quote` — upload a single attachment (PDF, image, Word, Excel, CSV, plain text, or any binary up to 25 MB) to an existing quote. One call per file. Errors are surfaced per-attachment so a single bad file does not roll back the quote.
|
|
- `quotes.append_reply` — append a structured reply to an existing quote. Matches by `In-Reply-To` header first, then `Q-YYYY-MM-NNN` in the subject.
|
|
- `quotes.find_by_message_id` — look up a quote by the inbound email's RFC 5322 `Message-ID` header.
|
|
|
|
The `quotes.*` tools are the inbound side of the [Quote Email Monitor](quotes-email-monitor.md) n8n workflow. They are the only path new quotes and replies should be created through. The `orders.*` and `order_items.*` tools are likewise the only path for the orders side.
|
|
|
|
## Notes
|
|
- `ORDER_ITEMS_COLLECTION` controls where order-item writes/updates go.
|
|
- Set `ORDER_ITEMS_COLLECTION=order_items` once new collection is created/imported.
|
|
- Status endpoint accepts `driver_status` input and normalizes to `drv_status`.
|
|
- `quotes.create_from_email` **must** receive a `message_id` for idempotency — duplicate sends of the same email return the existing record with `deduped: true`.
|
|
- `quotes.append_reply` returns `matched_by: 'in_reply_to' | 'subject' | 'none'`. The `'none'` case is the workflow's signal to move the email to `INBOX.Quotes-Unmatched` and not create a reply row.
|