132 lines
3.8 KiB
Markdown
132 lines
3.8 KiB
Markdown
# QR Master Internal RevOps Export API
|
|
|
|
This endpoint exposes read-only QR Master admin/product data for trusted automations such as Hermes cron jobs.
|
|
|
|
## Endpoint
|
|
|
|
```http
|
|
GET /api/internal/revops-export
|
|
Authorization: Bearer <INTERNAL_API_SECRET>
|
|
```
|
|
|
|
The endpoint accepts `INTERNAL_API_SECRET` first, with `CRON_SECRET` as a fallback for compatibility.
|
|
|
|
## Purpose
|
|
|
|
QR Master only exports structured data. It does **not** perform AI analysis, web research, email drafting, or lead outreach.
|
|
|
|
Hermes is responsible for:
|
|
|
|
- calling this API on a schedule,
|
|
- researching public websites/domains with its tools,
|
|
- deciding which leads are worth manual outreach,
|
|
- drafting personalized emails,
|
|
- sending Timo an internal briefing,
|
|
- never auto-sending messages to QR Master users.
|
|
|
|
## Query Parameters
|
|
|
|
| Parameter | Example | Notes |
|
|
|---|---|---|
|
|
| `range` | `24h`, `7d`, `30d`, `all` | Defaults to `24h`. |
|
|
| `from` | `2026-06-30T00:00:00Z` | Optional explicit start. Overrides `range`. |
|
|
| `to` | `2026-07-01T00:00:00Z` | Optional explicit end. Defaults to now if `from` is set. |
|
|
| `limit` | `100` | User/lead limit. Defaults to 100, max 500. |
|
|
| `allUsers` | `true` | Exports all users up to `limit`; otherwise exports users active/relevant in range. |
|
|
|
|
## Example Calls
|
|
|
|
Daily Hermes lead research context:
|
|
|
|
```bash
|
|
curl -H "Authorization: Bearer $INTERNAL_API_SECRET" \
|
|
"https://www.qrmaster.net/api/internal/revops-export?range=24h&limit=100"
|
|
```
|
|
|
|
Weekly progress context:
|
|
|
|
```bash
|
|
curl -H "Authorization: Bearer $INTERNAL_API_SECRET" \
|
|
"https://www.qrmaster.net/api/internal/revops-export?range=7d&limit=200"
|
|
```
|
|
|
|
Local development:
|
|
|
|
```bash
|
|
curl -H "Authorization: Bearer $INTERNAL_API_SECRET" \
|
|
"http://localhost:3050/api/internal/revops-export?range=24h"
|
|
```
|
|
|
|
## Response Shape
|
|
|
|
Top-level fields:
|
|
|
|
```json
|
|
{
|
|
"ok": true,
|
|
"generatedAt": "2026-07-01T18:00:00.000Z",
|
|
"endpoint": "/api/internal/revops-export",
|
|
"range": {
|
|
"preset": "24h",
|
|
"from": "2026-06-30T18:00:00.000Z",
|
|
"to": "2026-07-01T18:00:00.000Z"
|
|
},
|
|
"overview": {},
|
|
"breakdowns": {},
|
|
"users": [],
|
|
"leads": [],
|
|
"newsletterSubscriptions": []
|
|
}
|
|
```
|
|
|
|
Each exported user includes:
|
|
|
|
- identity: `id`, `name`, `email`, `emailDomain`, `createdAt`, `updatedAt`
|
|
- plan/subscription flags
|
|
- attribution fields
|
|
- onboarding fields
|
|
- lifecycle scores and timestamps
|
|
- aggregate stats
|
|
- QR codes, content, public path, and scan summaries
|
|
- integrations
|
|
- recent lifecycle logs
|
|
|
|
## Safety Rules for Hermes Jobs
|
|
|
|
Hermes should treat this API as internal source data and follow these rules:
|
|
|
|
1. Do not send outreach emails directly to leads.
|
|
2. Send only an internal briefing/draft pack to Timo.
|
|
3. Use public web research only when it improves personalization.
|
|
4. Do not tell leads they were researched.
|
|
5. Avoid creepy language; frame personalization around their QR Master activity and likely workflow.
|
|
6. Never expose API secrets or raw sensitive internals in the briefing.
|
|
7. Prefer business-use signals: QR content type, destination, scans, onboarding use case, domain, company website, landing path.
|
|
|
|
## Suggested Hermes Cron Jobs
|
|
|
|
### Daily QR Master Lead Research
|
|
|
|
Schedule: daily, evening.
|
|
|
|
Prompt should:
|
|
|
|
1. call `/api/internal/revops-export?range=24h`,
|
|
2. identify promising leads,
|
|
3. research public company/domain signals,
|
|
4. draft personalized outreach emails from Timo,
|
|
5. send Timo an internal email briefing,
|
|
6. never send emails to leads.
|
|
|
|
### Weekly QR Master Progress Review
|
|
|
|
Schedule: Sunday evening.
|
|
|
|
Prompt should:
|
|
|
|
1. call `/api/internal/revops-export?range=7d`,
|
|
2. summarize users, QR creation, scans, activations, paid/upgrades,
|
|
3. identify bottlenecks,
|
|
4. suggest next-week goals,
|
|
5. email Timo the review.
|