diff --git a/docs/src/chapter-02/template-samples.md b/docs/src/chapter-02/template-samples.md new file mode 100644 index 000000000..d3ea10ef8 --- /dev/null +++ b/docs/src/chapter-02/template-samples.md @@ -0,0 +1,700 @@ +# Template Samples & Conversations + +> **Ready-to-use bots for common business needs** +> +> *See real conversations and learn how each template works* + +--- + +## How to Use Templates + +1. Go to **Sources** app +2. Click **+ New Bot** +3. Select **From Template** +4. Choose the template you want +5. Click **Create** + +Your bot is ready to use immediately! + +--- + +## Customer Support (CRM Template) + +**Best for:** Handling customer inquiries, tracking issues, managing contacts + +### Sample Conversation + +``` +User: I need help with my order + +Bot: I'd be happy to help with your order! + What's your order number? + +User: ORD-12345 + +Bot: Found it! Order #ORD-12345 + + πŸ“¦ Status: Shipped + πŸ“… Shipped: May 14, 2025 + 🚚 Carrier: FedEx + πŸ“ Tracking: 7891234567890 + + Expected delivery: May 17, 2025 + + Is there something specific about this order? + +User: I want to return it + +Bot: I can help you start a return for Order #ORD-12345. + + πŸ“‹ Return Policy: + β€’ Returns accepted within 30 days + β€’ Item must be unused + β€’ Original packaging required + + Would you like me to create a return request? + +User: Yes + +Bot: βœ… Return Request Created! + + Return #: RET-5678 + + Next steps: + 1. Print the return label (sent to your email) + 2. Pack the item securely + 3. Drop off at any FedEx location + + Refund will process within 5-7 business days + after we receive the item. + + Anything else I can help with? +``` + +### What It Can Do + +- Look up orders by number or customer email +- Check shipping status +- Create return requests +- Log customer interactions +- Track support tickets + +--- + +## FAQ Bot (AI Search Template) + +**Best for:** Answering common questions from your documents + +### Sample Conversation + +``` +User: What's your refund policy? + +Bot: Based on our policies: + + **Refund Policy** + + β€’ Full refund within 30 days of purchase + β€’ Items must be unused and in original packaging + β€’ Refunds processed to original payment method + β€’ Processing time: 5-7 business days + + For items over 30 days old, store credit is available. + + πŸ“„ Source: Company Policies Handbook, Page 12 + +User: How do I contact support? + +Bot: You can reach our support team through: + + πŸ“§ Email: support@company.com + πŸ“ž Phone: 1-800-555-0123 (Mon-Fri, 9am-5pm) + πŸ’¬ Chat: You're using it right now! + + Average response time: + β€’ Chat: Immediate + β€’ Email: Within 24 hours + β€’ Phone: Under 5 minutes wait + + πŸ“„ Source: Contact Information Page + +User: Do you ship internationally? + +Bot: Yes! We ship to over 50 countries. + + **International Shipping:** + β€’ Standard: 10-15 business days ($15) + β€’ Express: 5-7 business days ($35) + + **Note:** Import duties and taxes may apply + depending on your country. + + Countries we ship to include: Canada, UK, + Australia, Germany, France, Japan, and more. + + πŸ“„ Source: Shipping FAQ Document +``` + +### Setup Tips + +1. Upload your FAQ documents to the knowledge base +2. Include policy documents, product guides, help articles +3. The bot automatically learns from your files + +--- + +## Appointment Booking (Calendar Template) + +**Best for:** Scheduling meetings, consultations, appointments + +### Sample Conversation + +``` +User: I want to book an appointment + +Bot: I'll help you schedule an appointment! + + What type of appointment do you need? + + 1. πŸ“‹ Consultation (30 min) + 2. πŸ”§ Service Visit (1 hour) + 3. πŸ“ž Phone Call (15 min) + +User: Consultation + +Bot: Great! A 30-minute consultation. + + Here are available times this week: + + πŸ“… Tuesday, May 20 + β€’ 10:00 AM + β€’ 2:00 PM + β€’ 4:00 PM + + πŸ“… Wednesday, May 21 + β€’ 9:00 AM + β€’ 11:00 AM + β€’ 3:00 PM + + Which works best for you? + +User: Tuesday at 2pm + +Bot: Perfect! Let me confirm your details. + + What's your name? + +User: John Smith + +Bot: And your email address? + +User: john@email.com + +Bot: βœ… Appointment Confirmed! + + πŸ“‹ Consultation + πŸ‘€ John Smith + πŸ“… Tuesday, May 20, 2025 + πŸ• 2:00 PM (30 minutes) + + A confirmation email has been sent to + john@email.com with calendar invite. + + Need to reschedule? Just ask! +``` + +### What It Can Do + +- Show available time slots +- Book appointments +- Send confirmation emails +- Send reminders before appointments +- Allow rescheduling and cancellation + +--- + +## HR Assistant (Employee Template) + +**Best for:** Employee self-service, HR questions, leave requests + +### Sample Conversation + +``` +User: How many vacation days do I have? + +Bot: Let me check your balance, John. + + πŸ“Š Your Time Off Balance: + + Vacation Days + β”œβ”€β”€ Available: 12 days + β”œβ”€β”€ Used: 3 days + └── Pending: 0 days + + Sick Days + β”œβ”€β”€ Available: 8 days + └── Used: 2 days + + Your vacation resets on January 1, 2026. + + Would you like to request time off? + +User: Yes, I need next Friday off + +Bot: I'll create a time off request for you. + + πŸ“… Requesting: Friday, May 23, 2025 + πŸ“‹ Type: Vacation (1 day) + + Reason for time off? (optional) + +User: Personal appointment + +Bot: βœ… Time Off Request Submitted! + + πŸ“‹ Request #PTO-2025-0142 + πŸ“… Date: May 23, 2025 (1 day) + πŸ“ Reason: Personal appointment + πŸ‘€ Approver: Sarah Johnson (your manager) + + You'll receive an email when it's approved. + + Current status: ⏳ Pending Approval + +User: What holidays do we have this year? + +Bot: πŸ“… Company Holidays 2025: + + βœ“ New Year's Day - Jan 1 (past) + βœ“ Memorial Day - May 26 + βœ“ Independence Day - July 4 + βœ“ Labor Day - Sep 1 + βœ“ Thanksgiving - Nov 27-28 + βœ“ Christmas - Dec 25-26 + + Total: 8 paid holidays + + Note: If a holiday falls on a weekend, + it's observed on the nearest weekday. +``` + +### What It Can Do + +- Check PTO balances +- Submit time off requests +- Look up company holidays +- Answer HR policy questions +- Find employee directory info + +--- + +## Sales Lead Capture + +**Best for:** Qualifying leads, collecting contact info, scheduling demos + +### Sample Conversation + +``` +User: I'm interested in your product + +Bot: Great! I'd love to learn more about what you're + looking for. + + What's your name? + +User: Maria Garcia + +Bot: Nice to meet you, Maria! + + What company are you with? + +User: Acme Corp + +Bot: Acme Corp - got it! + + What's your role there? + +User: Marketing Director + +Bot: Perfect! And what's the best email to reach you? + +User: maria@acmecorp.com + +Bot: Thanks Maria! One last question: + + What's your biggest challenge right now? + + 1. πŸ“ˆ Growing leads + 2. ⏱️ Saving time on manual tasks + 3. πŸ“Š Better reporting + 4. πŸ”— Integrating tools + 5. Other + +User: Saving time + +Bot: That's exactly what we help with! + + βœ… I've saved your information: + + πŸ‘€ Maria Garcia + 🏒 Acme Corp (Marketing Director) + πŸ“§ maria@acmecorp.com + 🎯 Interest: Time savings + + Would you like to: + + 1. πŸ“… Schedule a demo (15 min) + 2. πŸ“„ Get a product overview PDF + 3. πŸ’¬ Ask questions now + +User: Schedule a demo + +Bot: I can schedule you with our team! + + Available demo times: + + πŸ“… Tomorrow (May 16) + β€’ 10:00 AM + β€’ 3:00 PM + + πŸ“… Monday (May 19) + β€’ 11:00 AM + β€’ 2:00 PM + + Which works for you? + +User: Tomorrow at 3pm + +Bot: βœ… Demo Scheduled! + + πŸ“… Friday, May 16 at 3:00 PM + πŸ‘€ With: Alex from our Sales team + πŸ“§ Calendar invite sent to maria@acmecorp.com + + Alex will show you how companies like Acme + save 10+ hours per week with our platform. + + See you tomorrow, Maria! +``` + +### What It Can Do + +- Qualify leads with questions +- Capture contact information +- Score leads automatically +- Schedule demo calls +- Send follow-up emails + +--- + +## IT Helpdesk + +**Best for:** IT support tickets, troubleshooting, password resets + +### Sample Conversation + +``` +User: I can't access my email + +Bot: I'll help you troubleshoot your email access. + + What error are you seeing? + + 1. πŸ” Password incorrect + 2. πŸ“§ Can't connect to server + 3. πŸ”„ Email not syncing + 4. ❓ Something else + +User: Password incorrect + +Bot: Let's fix your password issue. + + Have you tried resetting your password in the + last 24 hours? + +User: No + +Bot: I can send a password reset link to your + backup email address. + + For security, please confirm your employee ID: + +User: EMP-4521 + +Bot: βœ… Verified! + + I've sent a password reset link to your backup + email (j***@gmail.com). + + πŸ“§ Check your email and click the reset link + ⏱️ Link expires in 15 minutes + + After resetting: + 1. Use the new password for email + 2. Update password on your phone too + 3. It may take 5 minutes to sync + + Still having issues after resetting? + +User: It worked, thanks! + +Bot: Glad it's working! πŸŽ‰ + + Quick security tips: + β€’ Use a strong, unique password + β€’ Enable two-factor authentication + β€’ Never share your password + + Anything else I can help with? + +User: No that's all + +Bot: βœ… Ticket #IT-2025-0891 closed as resolved. + + Have a great day! Remember, I'm here 24/7 + if you need IT help. +``` + +### What It Can Do + +- Create support tickets +- Reset passwords +- Troubleshoot common issues +- Check system status +- Escalate to human agents + +--- + +## Compliance & Privacy (LGPD/GDPR) + +**Best for:** Handling data privacy requests + +### Sample Conversation + +``` +User: I want to see what data you have about me + +Bot: I can help you with a Data Access Request. + + Under privacy regulations (LGPD, GDPR, CCPA), + you have the right to receive a copy of your + personal data. + + To process your request, I need to verify your + identity. What's your email address? + +User: john.doe@email.com + +Bot: I've sent a verification code to john.doe@email.com + + Please enter the 6-digit code: + +User: 847291 + +Bot: βœ… Identity verified! + + What would you like to do? + + 1. πŸ“₯ Get a copy of my data + 2. ✏️ Correct my information + 3. πŸ—‘οΈ Delete my data + 4. ❓ Ask about data usage + +User: Get a copy of my data + +Bot: βœ… Data Access Request Submitted + + πŸ“‹ Request #DSR-2025-0142 + πŸ“§ john.doe@email.com + πŸ“… Submitted: May 15, 2025 + ⏱️ Due: May 30, 2025 (15 days) + + We will compile all your personal data and + send it to your email in a secure format. + + You'll receive: + β€’ Profile information + β€’ Communication history + β€’ Preferences and settings + β€’ Activity logs + + Is there anything specific you're looking for? + +User: No, that's all + +Bot: Your request is being processed. + + You'll receive an email within 15 days with + a secure link to download your data. + + Questions? Reply to the confirmation email + or come back here anytime. +``` + +--- + +## Broadcast & Announcements + +**Best for:** Sending company-wide messages, news updates + +### Sample Conversation (Admin) + +``` +Admin: Send an announcement + +Bot: I'll help you create an announcement. + + What's the title? + +Admin: Office Closure Tomorrow + +Bot: Got it! Now the message content: + +Admin: Due to the holiday, our office will be closed + tomorrow May 16. We'll reopen Monday at 9am. + +Bot: Who should receive this? + + 1. πŸ‘₯ All employees + 2. 🏒 Specific department + 3. πŸ“ Specific location + 4. πŸ“‹ Custom list + +Admin: All employees + +Bot: How should I send it? + + β˜‘οΈ Email + β˜‘οΈ Chat notification + ☐ SMS + + (Select all that apply) + +Admin: Email and chat + +Bot: πŸ“’ Announcement Preview: + + ━━━━━━━━━━━━━━━━━━━━━━━━━━━ + OFFICE CLOSURE TOMORROW + ━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + Due to the holiday, our office will be + closed tomorrow May 16. We'll reopen + Monday at 9am. + + ━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + Recipients: 247 employees + Channels: Email, Chat + + Send now or schedule? + +Admin: Send now + +Bot: βœ… Announcement Sent! + + πŸ“§ 247 emails delivered + πŸ’¬ 247 chat notifications sent + + Delivery report saved. View in Analytics. +``` + +--- + +## Talk to Data (Analytics) + +**Best for:** Asking questions about your business data in plain English + +### Sample Conversation + +``` +User: How many sales did we make last month? + +Bot: πŸ“Š Sales Summary - April 2025 + + Total Sales: 1,247 + Revenue: $156,340 + Average Order: $125.35 + + Compared to March: + β€’ Sales: β–² 12% (+134) + β€’ Revenue: β–² 8% (+$11,520) + +User: Which product sold the most? + +Bot: πŸ† Top 5 Products - April 2025 + + 1. Widget Pro - 342 units ($42,750) + 2. Basic Package - 289 units ($28,900) + 3. Premium Bundle - 201 units ($40,200) + 4. Starter Kit - 187 units ($18,700) + 5. Add-on Pack - 156 units ($15,600) + + Widget Pro has been #1 for 3 months in a row! + +User: Show me sales by region + +Bot: πŸ—ΊοΈ Sales by Region - April 2025 + + North America β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–‘β–‘ $68,500 (44%) + Europe β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘β–‘β–‘ $42,300 (27%) + Asia Pacific β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ $31,200 (20%) + Latin America β–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘ $14,340 (9%) + + Fastest growing: Asia Pacific (β–² 23%) + +User: Who are our top customers? + +Bot: πŸ‘₯ Top 5 Customers - April 2025 + + 1. Acme Corp $12,450 (8 orders) + 2. TechStart Inc $9,800 (12 orders) + 3. Global Services $8,200 (5 orders) + 4. Smith & Co $7,650 (6 orders) + 5. DataFlow Ltd $6,900 (4 orders) + + Want me to show purchase history for any of these? +``` + +### What It Can Do + +- Answer business questions in plain English +- Show sales, revenue, customer data +- Compare time periods +- Create simple reports +- Export data to spreadsheets + +--- + +## Quick Template Selection Guide + +| I need to... | Use this template | +|--------------|-------------------| +| Answer customer questions | AI Search (FAQ) | +| Handle support tickets | CRM / IT Helpdesk | +| Book appointments | Calendar | +| Capture sales leads | CRM (Sales) | +| Help employees with HR | HR Assistant | +| Send announcements | Broadcast | +| Query business data | Talk to Data | +| Handle privacy requests | Compliance | + +--- + +## Need Something Custom? + +If these templates don't fit your needs: + +1. **Start with the closest template** - Modify it +2. **Use the Default template** - Build from scratch +3. **Combine templates** - Use features from multiple templates +4. **Ask for help** - Our community can guide you + +--- + +## See Also + +- [Templates Reference](./templates.md) - Full template list +- [How To: Create Your First Bot](../chapter-04-gbui/how-to/create-first-bot.md) +- [Sources App](../chapter-04-gbui/apps/sources.md) - Managing templates +- [Write Your First Dialog](../chapter-04-gbui/how-to/write-first-dialog.md) \ No newline at end of file diff --git a/docs/src/chapter-04-gbui/apps/compliance-api.md b/docs/src/chapter-04-gbui/apps/compliance-api.md new file mode 100644 index 000000000..604796b5d --- /dev/null +++ b/docs/src/chapter-04-gbui/apps/compliance-api.md @@ -0,0 +1,691 @@ +# Compliance API Reference + +> **Programmatic access to privacy and compliance features** + +--- + +## Overview + +The Compliance API allows you to programmatically manage data subject requests, consent records, and compliance scanning. Use this API to integrate privacy features into your applications or automate compliance workflows. + +**Base URL:** `https://your-server.com/api/compliance` + +--- + +## Authentication + +All API requests require authentication using a Bearer token: + +``` +Authorization: Bearer your-api-key +``` + +Get your API key from **Settings** β†’ **API Keys** β†’ **Create New Key** with `compliance` scope. + +--- + +## Endpoints + +### Data Subject Requests (DSR) + +#### List All Requests + +``` +GET /api/compliance/dsr +``` + +**Query Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `status` | string | Filter by status: `pending`, `processing`, `completed`, `rejected` | +| `type` | string | Filter by type: `access`, `deletion`, `rectification`, `portability`, `objection` | +| `from` | date | Start date (YYYY-MM-DD) | +| `to` | date | End date (YYYY-MM-DD) | +| `limit` | number | Results per page (default: 20, max: 100) | +| `offset` | number | Pagination offset | + +**Example Request:** + +``` +GET /api/compliance/dsr?status=pending&limit=10 +``` + +**Example Response:** + +``` +{ + "total": 7, + "limit": 10, + "offset": 0, + "requests": [ + { + "id": "DSR-2025-0142", + "type": "access", + "status": "pending", + "userId": "usr_abc123", + "email": "john.doe@email.com", + "submittedAt": "2025-05-13T10:30:00Z", + "dueDate": "2025-05-28T10:30:00Z", + "assignee": null + }, + { + "id": "DSR-2025-0141", + "type": "deletion", + "status": "processing", + "userId": "usr_def456", + "email": "sarah@company.com", + "submittedAt": "2025-05-10T14:15:00Z", + "dueDate": "2025-05-25T14:15:00Z", + "assignee": "admin@company.com" + } + ] +} +``` + +--- + +#### Get Single Request + +``` +GET /api/compliance/dsr/{id} +``` + +**Example Response:** + +``` +{ + "id": "DSR-2025-0142", + "type": "access", + "status": "pending", + "userId": "usr_abc123", + "email": "john.doe@email.com", + "name": "John Doe", + "submittedAt": "2025-05-13T10:30:00Z", + "dueDate": "2025-05-28T10:30:00Z", + "assignee": null, + "message": "I would like a copy of all my data", + "verifiedAt": "2025-05-13T10:35:00Z", + "dataFound": { + "profile": true, + "conversations": true, + "consents": true, + "activityLogs": true + }, + "history": [ + { + "action": "created", + "timestamp": "2025-05-13T10:30:00Z", + "actor": "system" + }, + { + "action": "verified", + "timestamp": "2025-05-13T10:35:00Z", + "actor": "system" + } + ] +} +``` + +--- + +#### Create Request + +``` +POST /api/compliance/dsr +``` + +**Request Body:** + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | Yes | `access`, `deletion`, `rectification`, `portability`, `objection` | +| `email` | string | Yes | User's email address | +| `userId` | string | No | User ID if known | +| `message` | string | No | User's message/reason | +| `skipVerification` | boolean | No | Skip email verification (default: false) | + +**Example Request:** + +``` +POST /api/compliance/dsr +Content-Type: application/json + +{ + "type": "access", + "email": "john.doe@email.com", + "message": "Please provide all my personal data" +} +``` + +**Example Response:** + +``` +{ + "id": "DSR-2025-0143", + "type": "access", + "status": "pending_verification", + "email": "john.doe@email.com", + "submittedAt": "2025-05-15T14:00:00Z", + "dueDate": "2025-05-30T14:00:00Z", + "verificationSent": true +} +``` + +--- + +#### Update Request Status + +``` +PATCH /api/compliance/dsr/{id} +``` + +**Request Body:** + +| Field | Type | Description | +|-------|------|-------------| +| `status` | string | `processing`, `completed`, `rejected` | +| `assignee` | string | Email of person handling request | +| `notes` | string | Internal notes | +| `rejectionReason` | string | Required if status is `rejected` | + +**Example Request:** + +``` +PATCH /api/compliance/dsr/DSR-2025-0142 +Content-Type: application/json + +{ + "status": "processing", + "assignee": "admin@company.com" +} +``` + +--- + +#### Complete Request (with data package) + +``` +POST /api/compliance/dsr/{id}/complete +``` + +**Request Body:** + +| Field | Type | Description | +|-------|------|-------------| +| `notifyUser` | boolean | Send completion email (default: true) | +| `dataPackageUrl` | string | URL to downloadable data (for access/portability) | +| `expiresAt` | datetime | When download link expires | + +**Example Request:** + +``` +POST /api/compliance/dsr/DSR-2025-0142/complete +Content-Type: application/json + +{ + "notifyUser": true, + "dataPackageUrl": "https://secure.company.com/data/abc123.zip", + "expiresAt": "2025-06-15T00:00:00Z" +} +``` + +--- + +### Consent Management + +#### Get User Consent + +``` +GET /api/compliance/consent/{userId} +``` + +**Example Response:** + +``` +{ + "userId": "usr_abc123", + "email": "john.doe@email.com", + "consents": [ + { + "type": "terms_of_service", + "status": "given", + "version": "2.3", + "timestamp": "2025-01-15T10:32:00Z", + "method": "web_form", + "ip": "192.168.1.100" + }, + { + "type": "marketing", + "status": "given", + "timestamp": "2025-01-15T10:32:00Z", + "method": "web_form" + }, + { + "type": "analytics", + "status": "withdrawn", + "timestamp": "2025-03-22T15:15:00Z", + "method": "preference_center" + } + ] +} +``` + +--- + +#### Record Consent + +``` +POST /api/compliance/consent +``` + +**Request Body:** + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `userId` | string | Yes | User identifier | +| `email` | string | Yes | User's email | +| `type` | string | Yes | Consent type (e.g., `marketing`, `analytics`) | +| `status` | string | Yes | `given` or `withdrawn` | +| `method` | string | No | How consent was collected | +| `ip` | string | No | User's IP address | +| `userAgent` | string | No | User's browser | + +**Example Request:** + +``` +POST /api/compliance/consent +Content-Type: application/json + +{ + "userId": "usr_abc123", + "email": "john.doe@email.com", + "type": "marketing", + "status": "given", + "method": "chatbot", + "ip": "192.168.1.100" +} +``` + +**Example Response:** + +``` +{ + "success": true, + "consentId": "con_xyz789", + "userId": "usr_abc123", + "type": "marketing", + "status": "given", + "timestamp": "2025-05-15T14:30:00Z" +} +``` + +--- + +#### Withdraw Consent + +``` +DELETE /api/compliance/consent/{userId}/{type} +``` + +**Example Request:** + +``` +DELETE /api/compliance/consent/usr_abc123/marketing +``` + +**Example Response:** + +``` +{ + "success": true, + "userId": "usr_abc123", + "type": "marketing", + "status": "withdrawn", + "timestamp": "2025-05-15T14:35:00Z" +} +``` + +--- + +#### List Consent Types + +``` +GET /api/compliance/consent-types +``` + +**Example Response:** + +``` +{ + "consentTypes": [ + { + "id": "terms_of_service", + "name": "Terms of Service", + "required": true, + "description": "Agreement to terms and conditions", + "currentVersion": "2.3" + }, + { + "id": "marketing", + "name": "Marketing Communications", + "required": false, + "description": "Receive promotional emails and offers" + }, + { + "id": "analytics", + "name": "Analytics & Improvement", + "required": false, + "description": "Help us improve by analyzing usage patterns" + } + ] +} +``` + +--- + +### Compliance Scanning + +#### Start a Scan + +``` +POST /api/compliance/scan +``` + +**Request Body:** + +| Field | Type | Description | +|-------|------|-------------| +| `type` | string | `quick`, `full`, or `custom` | +| `targets` | array | For custom: `["bots", "kb", "users", "logs"]` | +| `botId` | string | Scan specific bot only | + +**Example Request:** + +``` +POST /api/compliance/scan +Content-Type: application/json + +{ + "type": "full", + "targets": ["bots", "kb", "users", "logs"] +} +``` + +**Example Response:** + +``` +{ + "scanId": "scan_20250515_001", + "status": "running", + "type": "full", + "startedAt": "2025-05-15T14:45:00Z", + "estimatedDuration": "30 minutes" +} +``` + +--- + +#### Get Scan Status + +``` +GET /api/compliance/scan/{scanId} +``` + +**Example Response (In Progress):** + +``` +{ + "scanId": "scan_20250515_001", + "status": "running", + "progress": 45, + "currentStep": "Scanning conversation logs", + "startedAt": "2025-05-15T14:45:00Z" +} +``` + +**Example Response (Complete):** + +``` +{ + "scanId": "scan_20250515_001", + "status": "completed", + "progress": 100, + "startedAt": "2025-05-15T14:45:00Z", + "completedAt": "2025-05-15T15:12:00Z", + "summary": { + "totalChecks": 148, + "passed": 145, + "warnings": 2, + "critical": 1 + }, + "issues": [ + { + "severity": "critical", + "type": "unencrypted_pii", + "description": "Unencrypted PII found in conversation logs", + "location": "support-bot/logs/2025-05-10", + "affectedRecords": 23, + "recommendation": "Enable automatic PII redaction" + }, + { + "severity": "warning", + "type": "consent_expiring", + "description": "Consent records older than 2 years", + "affectedUsers": 12, + "recommendation": "Send consent renewal requests" + } + ] +} +``` + +--- + +#### Get Latest Scan Results + +``` +GET /api/compliance/scan/latest +``` + +Returns the most recent completed scan results. + +--- + +### Reports + +#### Generate Compliance Report + +``` +POST /api/compliance/report +``` + +**Request Body:** + +| Field | Type | Description | +|-------|------|-------------| +| `type` | string | `summary`, `detailed`, `audit` | +| `period` | string | `last_30_days`, `last_90_days`, `year`, `custom` | +| `from` | date | Start date for custom period | +| `to` | date | End date for custom period | +| `format` | string | `json`, `pdf`, `csv` | + +**Example Request:** + +``` +POST /api/compliance/report +Content-Type: application/json + +{ + "type": "summary", + "period": "last_30_days", + "format": "json" +} +``` + +**Example Response:** + +``` +{ + "reportId": "rpt_20250515_001", + "generatedAt": "2025-05-15T15:00:00Z", + "period": { + "from": "2025-04-15", + "to": "2025-05-15" + }, + "summary": { + "overallScore": 92, + "dsrRequests": { + "received": 15, + "completed": 12, + "pending": 3, + "averageResponseDays": 8.5 + }, + "consentRate": 94.2, + "dataBreaches": 0, + "scansPerformed": 4, + "issuesFound": 7, + "issuesResolved": 5 + } +} +``` + +--- + +#### Download Report + +``` +GET /api/compliance/report/{reportId}/download +``` + +Returns the report file in the requested format. + +--- + +### Data Deletion + +#### Delete User Data + +``` +DELETE /api/compliance/user/{userId}/data +``` + +**Query Parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `scope` | string | `all`, `conversations`, `profile`, `analytics` | +| `confirm` | boolean | Must be `true` to execute | + +**Example Request:** + +``` +DELETE /api/compliance/user/usr_abc123/data?scope=all&confirm=true +``` + +**Example Response:** + +``` +{ + "success": true, + "userId": "usr_abc123", + "deletedAt": "2025-05-15T15:30:00Z", + "scope": "all", + "itemsDeleted": { + "profile": 1, + "conversations": 45, + "consents": 3, + "activityLogs": 234 + }, + "retainedForLegal": { + "auditLogs": 15 + } +} +``` + +--- + +## Error Responses + +All errors follow this format: + +``` +{ + "error": { + "code": "ERROR_CODE", + "message": "Human readable message", + "details": {} + } +} +``` + +**Common Error Codes:** + +| Code | HTTP Status | Description | +|------|-------------|-------------| +| `UNAUTHORIZED` | 401 | Invalid or missing API key | +| `FORBIDDEN` | 403 | API key lacks required scope | +| `NOT_FOUND` | 404 | Resource not found | +| `VALIDATION_ERROR` | 400 | Invalid request parameters | +| `RATE_LIMITED` | 429 | Too many requests | +| `INTERNAL_ERROR` | 500 | Server error | + +--- + +## Rate Limits + +| Endpoint | Limit | +|----------|-------| +| All endpoints | 100 requests/minute | +| Scan endpoints | 5 requests/hour | +| Report generation | 10 requests/hour | + +Rate limit headers are included in responses: + +``` +X-RateLimit-Limit: 100 +X-RateLimit-Remaining: 95 +X-RateLimit-Reset: 1621234567 +``` + +--- + +## Webhooks + +Configure webhooks to receive real-time notifications. + +**Available Events:** + +| Event | Description | +|-------|-------------| +| `dsr.created` | New DSR submitted | +| `dsr.completed` | DSR marked complete | +| `dsr.due_soon` | DSR due within 3 days | +| `consent.changed` | User consent updated | +| `scan.completed` | Compliance scan finished | +| `issue.critical` | Critical issue detected | + +**Webhook Payload Example:** + +``` +POST https://your-server.com/webhook +Content-Type: application/json +X-Signature: sha256=... + +{ + "event": "dsr.created", + "timestamp": "2025-05-15T14:00:00Z", + "data": { + "id": "DSR-2025-0143", + "type": "access", + "email": "user@example.com" + } +} +``` + +--- + +## See Also + +- [Compliance App](./compliance.md) - User interface guide +- [How To: Configure Compliance](../how-to/configure-compliance.md) +- [BASIC Compliance Keywords](../../chapter-06-gbdialog/keywords-reference.md) \ No newline at end of file