Backoffice API Reference

Comprehensive API documentation for the Toto backoffice platform with all endpoints, data models, and integration details.

📊 Overview

The Toto backoffice API provides comprehensive endpoints for managing users, cases, donations, support tickets, notifications, and audit logs. All endpoints use normalized IDs and ISO 8601 timestamps for consistency.

🔐 Authentication

Authentication Methods

NextAuth.js: Session-based authentication
Firebase Auth: User management and verification
Role-based Access: Admin, guardian, user permissions

Authentication Headers

Authorization: Bearer <session_token>
Content-Type: application/json

👥 User Management

Get Users

GET /api/users?status=active&sort=name&q=search_term

Query Parameters:

status: Filter by user status (active, inactive, pending, waitlist)
sort: Sort by field (name, createdAt)
q: Search term for name or email

Response:

{
  "users": [
    {
      "id": "usr_abc123def456",
      "email": "user@example.com",
      "name": "John Doe",
      "role": "user",
      "status": "active",
      "createdAt": "2024-01-15T10:30:00Z",
      "lastLoginAt": "2024-01-20T14:22:00Z",
      "phone": "+54 11 1234-5678",
      "activityRate": 85,
      "permissions": ["read:cases", "create:donations"]
    }
  ]
}

Get User by ID

GET /api/users/{id}

Response:

{
  "id": "usr_abc123def456",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "user",
  "status": "active",
  "bio": "Animal lover and volunteer",
  "location": "Buenos Aires, Argentina",
  "organization": "Rescue Foundation",
  "contactInfo": {
    "phone": "+54 11 1234-5678",
    "website": "https://example.com",
    "socialLinks": {
      "facebook": "https://facebook.com/johndoe",
      "instagram": "https://instagram.com/johndoe"
    }
  },
  "preferences": {
    "notifications": true,
    "emailUpdates": true,
    "caseTypes": ["rescue", "medical"]
  }
}

Update User

PUT /api/users/{id}

Request Body:

{
  "name": "John Doe Updated",
  "bio": "Updated bio",
  "phone": "+54 11 9876-5432",
  "preferences": {
    "notifications": false,
    "emailUpdates": true
  }
}

Create User

POST /api/users

Request Body:

{
  "email": "newuser@example.com",
  "name": "New User",
  "role": "user",
  "status": "active",
  "phone": "+54 11 1111-2222"
}

🆘 Case Management

Get Cases

GET /api/cases?status=active&priority=urgent&category=rescue

Query Parameters:

status: Filter by status (active, urgent, completed, draft)
priority: Filter by priority (urgent, normal)
category: Filter by category (rescue, surgery, treatment, transit, foster)
guardianId: Filter by guardian ID
sort: Sort by field (createdAt, updatedAt, donationGoal)

Response:

{
  "cases": [
    {
      "id": "cas_xyz789ghi012",
      "name": "Rescue Operation Alpha",
      "description": "Emergency rescue of injured dog",
      "status": "active",
      "priority": "urgent",
      "category": "rescue",
      "guardianId": "usr_guardian123",
      "guardianName": "Jane Guardian",
      "donationGoal": 500000,
      "donationsReceived": 250000,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T14:22:00Z",
      "imageUrl": "https://example.com/case-image.jpg"
    }
  ]
}

Get Case by ID

GET /api/cases/{id}

Response:

{
  "id": "cas_xyz789ghi012",
  "name": "Rescue Operation Alpha",
  "description": "Emergency rescue of injured dog found on the street...",
  "status": "active",
  "priority": "urgent",
  "category": "rescue",
  "guardianId": "usr_guardian123",
  "guardianName": "Jane Guardian",
  "donationGoal": 500000,
  "donationsReceived": 250000,
  "imageUrl": "https://example.com/case-image.jpg",
  "additionalImages": [
    "https://example.com/case-image-2.jpg",
    "https://example.com/case-image-3.jpg"
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T14:22:00Z"
}

Create Case

POST /api/cases

Request Body:

{
  "name": "New Rescue Case",
  "description": "Case description",
  "status": "active",
  "priority": "normal",
  "category": "rescue",
  "guardianId": "usr_guardian123",
  "donationGoal": 100000,
  "imageUrl": "https://example.com/image.jpg"
}

Update Case

PUT /api/cases/{id}

Request Body:

{
  "name": "Updated Case Name",
  "description": "Updated description",
  "status": "completed",
  "donationGoal": 150000
}

💰 Donation Management

Get Donations

GET /api/donations?caseId=cas_xyz789&status=completed&currency=USD

Query Parameters:

caseId: Filter by case ID
guardianId: Filter by guardian ID
userId: Filter by user ID
status: Filter by status (pending, completed, failed, refunded)
currency: Filter by currency (ARS, USD)
sort: Sort by field (createdAt, amount)

Response:

{
  "donations": [
    {
      "id": "don_mno345pqr678",
      "caseId": "cas_xyz789ghi012",
      "guardianId": "usr_guardian123",
      "userId": "usr_donor456",
      "userName": "Donor Name",
      "userEmail": "donor@example.com",
      "amount": 50000,
      "currency": "ARS",
      "originalAmount": 50000,
      "convertedAmount": 50000,
      "paymentProvider": "MoonPay",
      "transactionId": "txn_abc123",
      "partnerTransactionId": "moonpay_xyz789",
      "status": "completed",
      "message": "Hope this helps!",
      "isAnonymous": false,
      "createdAt": "2024-01-15T10:30:00Z",
      "completedAt": "2024-01-15T10:32:00Z"
    }
  ]
}

🎫 Support System

Get Support Tickets

GET /api/support?status=open&priority=urgent&assignedTo=usr_admin123

Query Parameters:

status: Filter by status (open, in_progress, resolved, closed)
priority: Filter by priority (low, medium, high, urgent)
assignedTo: Filter by assigned admin
requesterEmail: Filter by requester email
category: Filter by category
unassigned: Show only unassigned tickets (true/false)
search: Search in title and description

Response:

{
  "tickets": [
    {
      "id": "spt_ticket123abc",
      "ticketNumber": "TKT-2024-001",
      "title": "Payment Issue",
      "description": "Unable to process donation payment",
      "status": "open",
      "priority": "high",
      "category": "billing",
      "assignedTo": "usr_admin123",
      "assignedToName": "Admin User",
      "requesterEmail": "user@example.com",
      "requesterName": "User Name",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "dueDate": "2024-01-16T10:30:00Z",
      "tags": ["payment", "urgent"],
      "attachments": []
    }
  ]
}

Get Support Ticket Stats

GET /api/support/stats

Response:

{
  "urgentOpen": 3,
  "unassignedOpen": 5,
  "totalOpen": 12,
  "statusBreakdown": {
    "open": 8,
    "in_progress": 4,
    "resolved": 15,
    "closed": 10
  }
}

Create Support Ticket

POST /api/support

Request Body:

{
  "title": "New Support Request",
  "description": "Detailed description of the issue",
  "priority": "medium",
  "category": "technical",
  "requesterEmail": "user@example.com",
  "requesterName": "User Name",
  "tags": ["bug", "ui"]
}

Update Support Ticket

PUT /api/support/{id}

Request Body:

{
  "status": "in_progress",
  "assignedTo": "usr_admin123",
  "assignedToName": "Admin User",
  "priority": "high",
  "internalNotes": "Internal notes for admin"
}

🔔 Notification System

Get Notifications

GET /api/notifications?userEmail=user@example.com&limit=50&unreadOnly=true

Query Parameters:

userEmail: Target user email
limit: Number of notifications to return (default: 50)
unreadOnly: Show only unread notifications (true/false)
type: Filter by notification type
priority: Filter by priority

Response:

{
  "notifications": [
    {
      "id": "not_notification123",
      "userId": "usr_user456",
      "userEmail": "user@example.com",
      "type": "case_update",
      "category": "case",
      "priority": "medium",
      "title": "Case Update",
      "message": "Your case has been updated",
      "actionUrl": "/dashboard/cases/cas_xyz789",
      "isRead": false,
      "createdAt": "2024-01-15T10:30:00Z",
      "metadata": {
        "caseId": "cas_xyz789ghi012",
        "updateType": "status_change"
      }
    }
  ]
}

Mark Notification as Read

PATCH /api/notifications/{id}

Request Body:

{
  "isRead": true
}

🔍 Audit Logs

Get Audit Logs

GET /api/audit-logs?category=user&severity=high&userEmail=admin@example.com&page=1&limit=50

Query Parameters:

category: Filter by category (user, case, donation, system, security, support, notification)
severity: Filter by severity (low, medium, high, critical)
userEmail: Filter by user email
action: Filter by action
resource: Filter by resource type
startDate: Filter by start date (ISO 8601)
endDate: Filter by end date (ISO 8601)
page: Page number (default: 1)
limit: Items per page (default: 50)

Response:

{
  "auditLogs": [
    {
      "id": "aud_audit123abc",
      "timestamp": "2024-01-15T10:30:00Z",
      "userId": "usr_admin123",
      "userEmail": "admin@example.com",
      "userRole": "admin",
      "action": "user_role_change",
      "resource": "user_account",
      "resourceId": "usr_user456",
      "details": {
        "before": { "role": "user" },
        "after": { "role": "guardian" },
        "reason": "Promoted for performance",
        "ipAddress": "192.168.1.100"
      },
      "severity": "high",
      "category": "user"
    }
  ],
  "total": 150,
  "page": 1,
  "limit": 50,
  "totalPages": 3
}

Create Audit Log

POST /api/audit-logs

Request Body:

{
  "userId": "usr_admin123",
  "userEmail": "admin@example.com",
  "userRole": "admin",
  "action": "case_status_update",
  "resource": "case",
  "resourceId": "cas_xyz789",
  "details": {
    "before": { "status": "active" },
    "after": { "status": "completed" },
    "reason": "Case successfully resolved"
  },
  "severity": "medium",
  "category": "case"
}

📝 Case Updates

Get Case Updates

GET /api/updates?caseId=cas_xyz789&limit=20&offset=0

Query Parameters:

caseId: Case ID (required)
limit: Number of updates to return (default: 20)
offset: Number of updates to skip (default: 0)

Response:

{
  "updates": [
    {
      "id": "upd_update123abc",
      "caseId": "cas_xyz789ghi012",
      "type": "status_change",
      "status": "completed",
      "previousStatus": "active",
      "notes": "Case successfully completed",
      "updatedBy": "usr_guardian123",
      "updatedByName": "Jane Guardian",
      "createdAt": "2024-01-15T10:30:00Z",
      "metadata": {
        "attachmentUrl": "https://example.com/update-image.jpg",
        "tags": ["milestone", "success"]
      }
    }
  ]
}

Create Case Update

POST /api/updates

Request Body:

{
  "caseId": "cas_xyz789ghi012",
  "type": "note",
  "notes": "Progress update on the case",
  "metadata": {
    "tags": ["progress", "medical"],
    "priority": "medium"
  }
}

📊 Dashboard Statistics

Get Dashboard Stats

GET /api/dashboard/stats

Response:

{
  "summary": {
    "totalUsers": 150,
    "activeUsers": 120,
    "totalCases": 45,
    "activeCases": 12,
    "completedCases": 33,
    "totalDonations": 125000,
    "totalSupportTickets": 25,
    "openSupportTickets": 8
  },
  "trends": {
    "userGrowth": 15.5,
    "caseCompletionRate": 73.3,
    "donationGrowth": 22.1
  },
  "recentActivity": [
    {
      "type": "new_case",
      "description": "New case created: Rescue Operation Beta",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ]
}

🌱 Seeding System

Initialize Staging Database

POST /api/init-staging-final

Response:

{
  "success": true,
  "message": "Final staging database initialized successfully!",
  "summary": {
    "users": 27,
    "supportTickets": 15,
    "cases": 10,
    "donations": 50,
    "follows": 30,
    "notifications": 30,
    "caseUpdates": 36,
    "auditLogs": 200,
    "idFormat": "normalized"
  }
}

📊 Performance Monitoring

Get Performance Metrics

GET /api/performance/monitor?action=metrics&period=24h&type=page_load

Query Parameters:

action: Action type (metrics, report, alerts)
period: Time period (1h, 24h, 7d, 30d)
type: Metric type (page_load, api_response, database_query)

Response:

{
  "success": true,
  "metrics": {
    "averageResponseTime": 250,
    "p95ResponseTime": 500,
    "p99ResponseTime": 1000,
    "errorRate": 0.02,
    "throughput": 150
  },
  "period": "24h",
  "type": "page_load"
}

Record Performance Metric

POST /api/performance/monitor

Request Body:

{
  "type": "page_load",
  "name": "homepage_load",
  "value": 1200,
  "unit": "ms",
  "metadata": {
    "url": "/dashboard",
    "userAgent": "Mozilla/5.0...",
    "userId": "usr_123",
    "sessionId": "sess_456"
  }
}

Get Performance Report

GET /api/performance/monitor?action=report&period=7d

Response:

{
  "success": true,
  "report": {
    "period": "7d",
    "metrics": {
      "averageResponseTime": 300,
      "p95ResponseTime": 600,
      "p99ResponseTime": 1200,
      "errorRate": 0.03,
      "throughput": 200,
      "bundleSize": 800000,
      "imageLoadTime": 400,
      "databaseQueryTime": 150
    },
    "trends": {
      "responseTime": "improving",
      "errorRate": "stable",
      "throughput": "improving"
    },
    "alerts": [],
    "recommendations": [
      "Consider implementing code splitting",
      "Optimize image loading"
    ]
  }
}

🔒 Security Monitoring

Get Security Events

GET /api/security/monitor?type=events

Query Parameters:

type: Data type (events, alerts, metrics)
timeframe: Time frame (24h, 7d, 30d)

Response:

{
  "success": true,
  "events": [
    {
      "id": "sec_event123",
      "timestamp": "2024-01-15T10:30:00Z",
      "type": "failed_login",
      "severity": "medium",
      "description": "Multiple failed login attempts",
      "userId": "usr_123",
      "ipAddress": "192.168.1.100",
      "userAgent": "Mozilla/5.0...",
      "metadata": {
        "attemptCount": 5,
        "timeWindow": "5m"
      }
    }
  ]
}

Get Security Alerts

GET /api/security/monitor?type=alerts

Response:

{
  "success": true,
  "alerts": [
    {
      "id": "sec_alert123",
      "timestamp": "2024-01-15T10:30:00Z",
      "type": "suspicious_activity",
      "severity": "high",
      "description": "Unusual access pattern detected",
      "status": "active",
      "userId": "usr_123",
      "ipAddress": "192.168.1.100"
    }
  ]
}

Get Security Metrics

GET /api/security/monitor?type=metrics&timeframe=24h

Response:

{
  "success": true,
  "metrics": {
    "totalEvents": 150,
    "criticalEvents": 2,
    "highEvents": 8,
    "mediumEvents": 25,
    "lowEvents": 115,
    "topThreats": [
      "brute_force_attack",
      "suspicious_login",
      "rate_limit_exceeded"
    ],
    "blockedIPs": 5,
    "activeAlerts": 3
  }
}

🚀 Blue-Green Deployment

Initialize Deployment

POST /api/deployment/blue-green

Request Body:

{
  "action": "initialize",
  "config": {
    "projectId": "toto-bo",
    "environment": "production",
    "version": "1.0.1",
    "buildId": "build-123456",
    "healthCheckUrl": "https://stg.bo.betoto.pet",
    "commitHash": "abc123def456",
    "branch": "main",
    "author": "developer@example.com",
    "buildTime": 120000,
    "bundleSize": 800000
  }
}

Response:

{
  "success": true,
  "deploymentId": "deploy_123456",
  "message": "Deployment initialized successfully"
}

Deploy to Blue Environment

POST /api/deployment/blue-green

Request Body:

{
  "action": "deploy_blue",
  "deploymentId": "deploy_123456"
}

Run Health Checks

POST /api/deployment/blue-green

Request Body:

{
  "action": "health_check",
  "deploymentId": "deploy_123456"
}

Response:

{
  "success": true,
  "healthCheck": {
    "status": "healthy",
    "responseTime": 250,
    "checks": {
      "api": true,
      "database": true,
      "authentication": true,
      "monitoring": true
    },
    "timestamp": "2024-01-15T10:30:00Z"
  },
  "message": "Health checks completed successfully"
}

Switch Traffic

POST /api/deployment/blue-green

Request Body:

{
  "action": "switch_traffic",
  "deploymentId": "deploy_123456"
}

Rollback Deployment

POST /api/deployment/blue-green

Request Body:

{
  "action": "rollback",
  "deploymentId": "deploy_123456"
}

🏥 Health Checks

General Health Check

GET /api/health

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0.295-staging",
  "environment": "production",
  "checks": {
    "api": true,
    "database": true,
    "authentication": true,
    "monitoring": true
  },
  "uptime": 86400,
  "memory": {
    "rss": 50000000,
    "heapTotal": 20000000,
    "heapUsed": 15000000,
    "external": 5000000
  },
  "responseTime": 45
}

Database Health Check

GET /api/health/database

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "database": {
    "connected": true,
    "responseTime": 25,
    "lastQuery": "2024-01-15T10:29:55Z"
  }
}

Authentication Health Check

GET /api/health/auth

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "authentication": {
    "configured": true,
    "providers": ["google"],
    "sessionValid": true
  }
}

Monitoring Health Check

GET /api/health/monitoring

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "monitoring": {
    "enabled": true,
    "metricsCollection": true,
    "alerting": true,
    "lastMetric": "2024-01-15T10:29:45Z"
  }
}

POST /api/gdpr/request

Request Body:

{
  "requestType": "access",
  "metadata": {
    "reason": "Data access request",
    "priority": "normal",
    "contactMethod": "email"
  }
}

Response:

{
  "success": true,
  "requestId": "gdpr_req_123456",
  "message": "GDPR request created successfully"
}

Data Access Request

POST /api/gdpr/access

Request Body:

{
  "dataTypes": ["personal_info", "activity_logs", "donations"],
  "format": "json",
  "deliveryMethod": "email"
}

Data Rectification Request

POST /api/gdpr/rectification

Request Body:

{
  "field": "email",
  "currentValue": "old@example.com",
  "newValue": "new@example.com",
  "reason": "Email address change"
}

Data Erasure Request

POST /api/gdpr/erasure

Request Body:

{
  "dataTypes": ["personal_info", "activity_logs"],
  "reason": "Account deletion request",
  "confirmDeletion": true
}

Data Portability Request

POST /api/gdpr/portability

Request Body:

{
  "dataTypes": ["personal_info", "donations", "cases"],
  "format": "json",
  "deliveryMethod": "download"
}

POST /api/gdpr/consent

Request Body:

{
  "consentType": "marketing",
  "granted": false,
  "timestamp": "2024-01-15T10:30:00Z"
}

🔐 Error Handling

Error Response Format

{
  "error": "Error message",
  "details": "Additional error details",
  "code": "ERROR_CODE",
  "timestamp": "2024-01-15T10:30:00Z"
}

Common Error Codes

400 - Bad Request (invalid parameters)
401 - Unauthorized (authentication required)
403 - Forbidden (insufficient permissions)
404 - Not Found (resource not found)
409 - Conflict (resource already exists)
500 - Internal Server Error (server error)

Validation Errors

{
  "error": "Validation failed",
  "details": {
    "email": "Invalid email format",
    "phone": "Phone number is required"
  },
  "code": "VALIDATION_ERROR"
}

📈 Rate Limiting

Rate Limits

General API: 100 requests per minute per user
Seeding API: 10 requests per hour per user
Audit Logs: 50 requests per minute per user

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642248000

🔄 Pagination

Pagination Parameters

page: Page number (starts from 1)
limit: Items per page (max 100)
offset: Number of items to skip

Pagination Response

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": false
  }
}

🚀 Webhooks

Webhook Events

user.created - New user created
case.updated - Case status changed
donation.completed - Donation processed
support_ticket.assigned - Support ticket assigned
notification.sent - Notification sent

Webhook Payload

{
  "event": "case.updated",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "cas_xyz789ghi012",
    "status": "completed",
    "previousStatus": "active"
  }
}

👤 Admin Management

Create User in Main App

POST /api/admin/create-user

Description: Create user account in main toto-app (toto-f9d2f project)

Auth: Admin only

Request Body:

{
  "email": "newuser@example.com",
  "name": "New User",
  "role": "user"
}

Response:

{
  "success": true,
  "userId": "usr_abc123def456",
  "user": {
    "id": "usr_abc123def456",
    "email": "newuser@example.com",
    "name": "New User",
    "role": "user",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Create Backoffice User

POST /api/admin/create-user-bo

Description: Create backoffice collaborator account

Auth: Admin only

Request Body:

{
  "email": "admin@example.com",
  "name": "Admin User",
  "department": "Operations",
  "role": "admin"
}

Response:

{
  "success": true,
  "userId": "usr_collaborator123",
  "message": "Backoffice user created successfully"
}

🤖 AI System Integration

All AI endpoints proxy requests to toto-ai-hub Base URL: TOTO_AI_HUB_URL environment variable Auth: Admin only for all AI endpoints

Get AI Agents

GET /api/ai/agents

Description: List all available AI agents

Response:

{
  "agents": [
    {
      "name": "TwitterAgent",
      "description": "Monitors guardian Twitter accounts",
      "version": "1.0.0",
      "capabilities": ["tweet_fetching", "content_analysis", "case_update_creation"],
      "isEnabled": true
    },
    {
      "name": "CaseAgent",
      "description": "Handles case-related inquiries",
      "version": "1.0.0",
      "capabilities": ["case_analysis", "donation_info", "conversational_ai"],
      "isEnabled": true
    }
  ]
}

Get AI Insights

GET /api/ai/insights

Description: Get AI analytics and insights

Response:

{
  "insights": {
    "totalInteractions": 1247,
    "averageConfidence": 0.89,
    "successRate": 0.94,
    "trends": {
      "interactionsPerDay": 178,
      "improvementRate": 15.5
    }
  }
}

Query AI Knowledge Base

GET /api/ai/knowledge?query=search_term&limit=10

Description: Search AI knowledge base

Query Parameters:

query: Search query string
limit: Number of results (default: 10)

Response:

{
  "results": [
    {
      "id": "kb_article123",
      "content": "Knowledge base article content",
      "relevance": 0.95,
      "source": "documentation",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 25
}

Reset AI Knowledge Base

POST /api/ai/knowledge/reset

Description: Reset AI knowledge base (DANGEROUS - use with caution)

Request Body:

{
  "confirm": true
}

Response:

{
  "success": true,
  "message": "Knowledge base reset complete"
}

Test AI Functionality

POST /api/ai/test

Description: Test AI agent functionality

Request Body:

{
  "prompt": "Test question or prompt",
  "agentType": "CaseAgent",
  "context": {
    "caseId": "cas_xyz789"
  }
}

Response:

{
  "success": true,
  "response": "AI generated response",
  "confidence": 0.92,
  "agentUsed": "CaseAgent",
  "processingTime": 1200
}

Train AI Agent

POST /api/ai/train/{agentId}

Description: Train specific AI agent with custom data

Path Parameters:

agentId: Agent identifier (e.g., "TwitterAgent", "CaseAgent")

Request Body:

{
  "trainingData": [
    {
      "input": "Sample input text",
      "expectedOutput": "Expected response",
      "category": "case_inquiry"
    }
  ],
  "epochs": 10,
  "learningRate": 0.001
}

Response:

{
  "success": true,
  "trainingResults": {
    "agentId": "CaseAgent",
    "recordsTrained": 50,
    "accuracy": 0.94,
    "timeElapsed": 5000
  }
}

🔒 Authentication Extensions

Check User Role

POST /api/auth/check-role

Description: Verify if user has specific role

Request Body:

{
  "userId": "usr_abc123",
  "requiredRole": "admin"
}

Response:

{
  "hasRole": true,
  "userRole": "admin",
  "permissions": ["canManageCases", "canManageUsers"]
}

Setup Multi-Factor Authentication

POST /api/auth/setup-mfa

Description: Initialize MFA for user account

Request Body:

{
  "userId": "usr_abc123"
}

Response:

{
  "success": true,
  "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "secret": "JBSWY3DPEHPK3PXP",
  "backupCodes": [
    "12345678",
    "87654321"
  ]
}

Verify MFA Token

POST /api/auth/verify-mfa

Description: Verify 6-digit TOTP code

Request Body:

{
  "userId": "usr_abc123",
  "token": "123456"
}

Response:

{
  "success": true,
  "message": "MFA verification successful",
  "validUntil": "2024-01-15T10:35:00Z"
}

📊 Extended Monitoring & Analytics

Client Performance Metrics

POST /api/monitoring/app-performance

Description: Receive client-side performance metrics from toto-app

Request Body:

{
  "metrics": [
    {
      "name": "page_load_time",
      "value": 1200,
      "timestamp": 1705312200000,
      "metadata": {
        "url": "/dashboard",
        "userAgent": "Mozilla/5.0..."
      }
    }
  ]
}

Response:

{
  "success": true,
  "count": 5,
  "message": "Performance metrics received successfully"
}

Client Log Aggregation

POST /api/monitoring/app-logs

Description: Aggregate client-side logs

Request Body:

{
  "logs": [
    {
      "level": "error",
      "message": "Failed to load resource",
      "timestamp": 1705312200000,
      "context": {
        "component": "DonationForm",
        "error": "Network timeout"
      }
    }
  ]
}

User Activity Tracking

POST /api/monitoring/app-user-activity

Description: Track client-side user activity

Request Body:

{
  "activities": [
    {
      "action": "button_click",
      "component": "DonateButton",
      "timestamp": 1705312200000,
      "metadata": {
        "caseId": "cas_xyz789",
        "amount": 50000
      }
    }
  ]
}

Client Health Status

GET /api/monitoring/app-health

Description: Get client application health status

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "checks": {
    "api": true,
    "database": true,
    "auth": true
  },
  "clientMetrics": {
    "activeUsers": 125,
    "avgResponseTime": 250,
    "errorRate": 0.02
  }
}

Alert Management

GET /api/monitoring/alerts?severity=critical&status=active
POST /api/monitoring/alerts

Description: Manage monitoring alerts

GET Response:

{
  "alerts": [
    {
      "id": "alert_abc123",
      "severity": "critical",
      "status": "active",
      "message": "High error rate detected",
      "createdAt": "2024-01-15T10:30:00Z",
      "metadata": {
        "errorRate": 0.15,
        "threshold": 0.05
      }
    }
  ]
}

POST Request Body:

{
  "severity": "high",
  "message": "Database response time degraded",
  "metadata": {
    "avgResponseTime": 500,
    "threshold": 200
  }
}

Alert Rules Configuration

GET /api/monitoring/alert-rules

Description: Get monitoring alert rule configuration

Response:

{
  "rules": [
    {
      "id": "rule_error_rate",
      "condition": "error_rate > 0.05",
      "severity": "critical",
      "enabled": true,
      "notificationChannels": ["email", "slack"]
    }
  ]
}

Unified Monitoring Stats

GET /api/monitoring/unified-stats

Description: Get aggregated monitoring statistics

Response:

{
  "performance": {
    "avgResponseTime": 250,
    "p95ResponseTime": 500,
    "p99ResponseTime": 1000
  },
  "errors": {
    "count": 15,
    "rate": 0.02,
    "topErrors": ["NetworkError", "ValidationError"]
  },
  "system": {
    "cpu": 45.5,
    "memory": 60.2,
    "uptime": 86400
  },
  "users": {
    "active": 125,
    "peak": 180,
    "avgSessionDuration": 1200
  }
}

Real-Time Monitoring Streams (SSE)

Description: Server-Sent Events (SSE) endpoints for real-time monitoring updates

GET /api/monitoring/alerts/updates
GET /api/monitoring/errors/updates
GET /api/monitoring/logs/updates
GET /api/monitoring/performance/updates
GET /api/monitoring/system/updates

Connection: text/event-stream

Event Format:

data: {"type": "metric", "payload": {...}}

Example Event:

{
  "type": "performance_metric",
  "timestamp": "2024-01-15T10:30:00Z",
  "payload": {
    "metric": "response_time",
    "value": 250,
    "threshold": 500,
    "status": "normal"
  }
}

💼 Investor Management

List Investors

GET /api/investors?status=lead&type=demo&search=company&limit=50&offset=0

Description: Get list of investors and stakeholders

Query Parameters:

status: Filter by status (lead, engaged, converted)
type: Filter by type (demo, deck)
source: Filter by acquisition source
search: Search in email, company, notes
limit: Results per page (default: 50)
offset: Pagination offset (default: 0)

Response:

{
  "investors": [
    {
      "id": "usr_investor123",
      "email": "investor@example.com",
      "name": "John Investor",
      "role": "investor",
      "investorMetadata": {
        "type": "demo",
        "status": "lead",
        "source": "website",
        "company": "Tech Ventures Inc",
        "jobRole": "Managing Partner",
        "location": "San Francisco, CA",
        "notes": "Interested in Q2 investment round"
      },
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 25,
  "limit": 50,
  "offset": 0
}

Create Investor

POST /api/investors

Description: Add new investor to tracking system

Request Body:

{
  "email": "newi

nvestor@example.com",
  "type": "demo",
  "name": "Jane Investor",
  "company": "Growth Capital Partners",
  "role": "Partner",
  "location": "New York, NY",
  "source": "referral",
  "notes": "Referred by existing investor"
}

Response (201):

{
  "success": true,
  "id": "usr_investor456",
  "investor": {
    "id": "usr_investor456",
    "email": "newinvestor@example.com",
    "role": "investor",
    "investorMetadata": {
      "type": "demo",
      "status": "lead",
      "source": "referral",
      "company": "Growth Capital Partners"
    }
  }
}

📈 System Analytics

Get Analytics

GET /api/analytics?timeRange=30d

Description: Get system-wide analytics and metrics

Query Parameters:

timeRange: Time range for analytics (24h, 7d, 30d, 90d)

Response:

{
  "timeRange": "30d",
  "metrics": {
    "totalUsers": 150,
    "activeUsers": 120,
    "newUsers": 25,
    "totalCases": 45,
    "activeCases": 12,
    "completedCases": 33,
    "totalDonations": 125000,
    "donationCount": 250,
    "avgDonation": 500
  },
  "trends": {
    "userGrowth": 15.5,
    "caseCompletionRate": 73.3,
    "donationGrowth": 22.1,
    "engagementRate": 68.5
  },
  "charts": {
    "userGrowthOverTime": [...],
    "donationsOverTime": [...],
    "caseStatusDistribution": [...]
  }
}

🐦 Twitter Bot Configuration Management

Note: Twitter Bot endpoints manage configuration for Twitter monitoring. Actual Twitter scraping is performed by toto-ai-hub TwitterAgent (see AI Hub API Reference).

Get Twitter Bot Stats

GET /api/twitter-bot/stats

Description: Get Twitter monitoring statistics

Response:

{
  "success": true,
  "totalTweets": 1247,
  "newTweetsToday": 25,
  "activeGuardians": 5
}

Get Twitter Bot Config

GET /api/twitter-bot/config

Description: Get Twitter bot configuration

Response:

{
  "id": "main",
  "isEnabled": false,
  "fetchInterval": 15,
  "maxTweetsPerFetch": 10,
  "lastRun": "2024-01-15T10:00:00Z",
  "nextRun": "2024-01-15T10:15:00Z",
  "apiUsage": {
    "requestsUsed": 1500,
    "requestsLimit": 10000,
    "resetDate": "2024-02-15T00:00:00Z"
  }
}

Update Twitter Bot Config

PUT /api/twitter-bot/config

Request Body:

{
  "isEnabled": true,
  "fetchInterval": 30,
  "maxTweetsPerFetch": 20
}

Get Monitored Guardians

GET /api/twitter-bot/guardians

Response:

{
  "success": true,
  "guardians": [
    {
      "id": "guardian_1",
      "name": "Maria Fernandez",
      "twitterHandle": "maria_rescue",
      "twitterUserId": "123456789",
      "isActive": true,
      "lastTweetFetch": "2024-01-15T10:00:00Z"
    }
  ]
}

Add Guardian to Monitoring

POST /api/twitter-bot/guardians

Request Body:

{
  "twitterHandle": "new_guardian",
  "name": "New Guardian Name"
}

Manually Trigger Monitoring

POST /api/twitter-bot/run-now

Description: Manually trigger Twitter monitoring cycle (currently stub implementation)

Response:

{
  "success": true,
  "message": "Tweet fetching initiated for 5 guardian(s)",
  "guardiansProcessed": 5,
  "timeRange": "24 hours"
}

GET /api/social-media/posts?guardianId=usr_abc123&platform=twitter&status=pending&limit=50&offset=0&search=search_term

Query Parameters:

guardianId: Filter by guardian ID
platform: Filter by platform (twitter, instagram)
status: Filter by status (pending, approved, dismissed, rejected)
isUrgent: Filter by urgency (true, false)
limit: Number of posts to return (default: 50, max: 100)
offset: Pagination offset
search: Search in post content

Response:

{
  "success": true,
  "posts": [
    {
      "id": "post_abc123",
      "postId": "twitter_post_123",
      "platform": "twitter",
      "guardianId": "usr_abc123",
      "guardianName": "Maria Fernandez",
      "postContent": "Rescued a beautiful dog today...",
      "postUrl": "https://twitter.com/...",
      "status": "pending",
      "isUrgent": false,
      "analysisResult": {
        "confidence": 0.85,
        "extractedInfo": {}
      },
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 150,
    "hasMore": true,
    "nextOffset": 50
  }
}

POST /api/social-media/posts

Request Body:

{
  "postId": "twitter_post_123",
  "platform": "twitter",
  "guardianId": "usr_abc123",
  "postContent": "Rescued a beautiful dog today...",
  "postUrl": "https://twitter.com/...",
  "analysisResult": {
    "confidence": 0.85,
    "extractedInfo": {}
  }
}

GET /api/social-media/posts/{id}

PUT /api/social-media/posts/{id}

Request Body:

{
  "status": "approved",
  "reviewedAt": "2024-01-15T11:00:00Z"
}

DELETE /api/social-media/posts/{id}

POST /api/social-media/posts/{id}/approve

POST /api/social-media/posts/{id}/complete

POST /api/social-media/posts/{id}/dismiss

POST /api/social-media/posts/{id}/match-case

Request Body:

{
  "caseId": "cas_xyz789"
}

GET /api/social-media/analytics?timeRange=all

Query Parameters:

timeRange: Time range filter (today, week, month, all)

Response:

{
  "success": true,
  "analytics": {
    "totalPosts": 150,
    "pendingCount": 25,
    "approvedCount": 100,
    "dismissedCount": 20,
    "rejectedCount": 5,
    "casesCreated": 15,
    "updatesCreated": 30,
    "approvalRate": 0.8,
    "avgConfidence": 0.85,
    "platformBreakdown": {
      "twitter": 100,
      "instagram": 50
    },
    "statusBreakdown": {
      "pending": 25,
      "approved": 100,
      "dismissed": 20,
      "rejected": 5
    },
    "timeRange": "all"
  }
}

GET /api/social-media/monitor

GET /api/social-media/jobs/{id}

👥 Guardian Management

Get Guardians

GET /api/guardians?q=search_term&status=active&limit=20&cursor=2024-01-15T10:30:00Z

Query Parameters:

q or search: Search term for name or email
status: Filter by status
limit: Number of results (default: 20, max: 100)
cursor: Pagination cursor (ISO 8601 timestamp)

Response:

{
  "success": true,
  "guardians": [
    {
      "id": "usr_abc123",
      "name": "Maria Fernandez",
      "email": "maria@example.com",
      "role": "guardian",
      "status": "active",
      "phone": "+54 11 1234-5678",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "hasMore": true,
    "nextCursor": "2024-01-15T10:30:00Z"
  }
}

Create Guardian

POST /api/guardians

Request Body:

{
  "name": "New Guardian",
  "email": "guardian@example.com",
  "phone": "+54 11 1234-5678"
}

Get Guardian by ID

GET /api/guardians/{id}

Update Guardian

PUT /api/guardians/{id}

Delete Guardian

DELETE /api/guardians/{id}

Get Guardian Cases

GET /api/guardians/{id}/cases

Get Guardian Insights

GET /api/guardians/{id}/insights

Link KB Entry to Guardian Insights

POST /api/guardians/{id}/insights/link-kb

Request Body:

{
  "kbEntryId": "kb_abc123",
  "insightId": "insight_xyz789"
}

Update Guardian from Insights

POST /api/guardians/{id}/update-from-insights

💰 Cost Monitoring

Get Cost Monitoring Data

GET /api/cost-monitoring?period=7d

Query Parameters:

period: Time period (7d, 30d, 90d, all)

Response:

{
  "success": true,
  "data": {
    "summary": {
      "totalCost": 150.50,
      "totalCalls": 1000,
      "averageCostPerCall": 0.15,
      "costSavings": 25.00,
      "mostUsedModel": "gemini-1.5-pro",
      "period": "7d",
      "lastUpdated": "2024-01-15T10:30:00Z"
    },
    "breakdown": [
      {
        "modelName": "gemini-1.5-pro",
        "cost": 100.00,
        "percentage": 66.67
      }
    ],
    "usage": [
      {
        "modelName": "gemini-1.5-pro",
        "totalCalls": 800,
        "totalInputTokens": 1000000,
        "totalOutputTokens": 500000,
        "totalCost": 100.00,
        "averageLatency": 1.5,
        "successRate": 0.98,
        "failureCount": 16
      }
    ],
    "analytics": {
      "totalCalls": 1000,
      "totalCost": 150.50,
      "averageCostPerCall": 0.15,
      "mostUsedModel": "gemini-1.5-pro",
      "costSavingsEstimate": 25.00
    }
  }
}

Get Comprehensive Cost Monitoring

GET /api/cost-monitoring/comprehensive?period=30d

Get Cost Monitoring Snapshot

GET /api/cost-monitoring/snapshot

Get Cost Monitoring Trends

GET /api/cost-monitoring/trends?period=90d

📤 File Upload

Upload File

POST /api/upload

Request Body: Multipart form data

file: File to upload
folder: Optional folder path
fileName: Optional custom file name

Response:

{
  "success": true,
  "url": "https://storage.googleapis.com/...",
  "path": "uploads/filename.jpg"
}

🔍 Knowledge Base & Insights

Extract Insights from KB

POST /api/kb/extract-insights

Request Body:

{
  "text": "Text to extract insights from",
  "context": "Additional context"
}

📝 Case Generation

POST /api/cases/generate-from-post

Request Body:

{
  "postId": "post_abc123",
  "guardianId": "usr_abc123"
}

Response:

{
  "success": true,
  "caseId": "cas_xyz789",
  "message": "Case generated successfully"
}

🐛 Debug Endpoints

Check Firebase Status

GET /api/debug/firebase-status

Get Firebase Apps

GET /api/debug/firebase-apps

Check Database Connection

GET /api/check-db-connection

Clean Production Data

POST /api/clean-production

⚠️ Warning: This endpoint is for development/testing only.

🔧 Utility Endpoints

Get Version Information

GET /api/version

Description: Get deployment version and environment information

Response:

{
  "success": true,
  "data": {
    "version": "1.0.295",
    "environment": "production",
    "commitHash": "abc123def456",
    "buildTime": "2024-01-15T08:00:00Z",
    "deployTime": "2024-01-15T10:30:00Z",
    "nodeEnv": "production",
    "versionFormat": "npm-compatible"
  }
}

Verify Donation Transaction

POST /api/donations/verify

Description: Verify donation transaction with payment provider

Request Body:

{
  "donationId": "don_mno345pqr678",
  "transactionId": "txn_abc123"
}

Response:

{
  "verified": true,
  "status": "completed",
  "amount": 50000,
  "currency": "ARS",
  "provider": "MoonPay"
}

Send Email Invitation

POST /api/invitation/email

Description: Send email invitation to new users

Request Body:

{
  "email": "newuser@example.com",
  "name": "New User",
  "role": "guardian",
  "customMessage": "Welcome to Toto platform"
}

Response:

{
  "success": true,
  "message": "Invitation sent successfully",
  "invitationId": "inv_abc123"
}

📊 Endpoint Summary

Total Endpoints: 120+

Category	Endpoints	Status
User Management	4	✅ Documented
Case Management	4	✅ Documented
Donation Management	3	✅ Documented
Support System	4	✅ Documented
Notification System	2	✅ Documented
Audit Logs	2	✅ Documented
Case Updates	2	✅ Documented
Dashboard Statistics	1	✅ Documented
Performance Monitoring	3	✅ Documented
Security Monitoring	3	✅ Documented
Blue-Green Deployment	5	✅ Documented
Health Checks	4	✅ Documented
GDPR Compliance	6	✅ Documented
Admin Management	2	✅ Documented
AI System Integration	6	✅ Documented
Authentication Extensions	3	✅ Documented
Extended Monitoring	11	✅ Documented
Investor Management	2	✅ Documented
System Analytics	1	✅ Documented
Twitter Bot Config	6	✅ Documented
Social Media Management	10	✅ NEW
Guardian Management	8	✅ NEW
Cost Monitoring	4	✅ NEW
File Upload	1	✅ NEW
Knowledge Base & Insights	1	✅ NEW
Case Generation	1	✅ NEW
Debug Endpoints	4	✅ NEW
Utility Endpoints	3	✅ Documented

Last Updated: January 2025

This API reference covers 120+ endpoints for the Toto backoffice platform. For data model details, see Data Models.

📊 Overview​

🔐 Authentication​

Authentication Methods​

Authentication Headers​

👥 User Management​

Get Users​

Get User by ID​

Update User​

Create User​

🆘 Case Management​

Get Cases​

Get Case by ID​

Create Case​

Update Case​

💰 Donation Management​

Get Donations​

🎫 Support System​

Get Support Tickets​

Get Support Ticket Stats​

Create Support Ticket​

Update Support Ticket​

🔔 Notification System​

Get Notifications​

Mark Notification as Read​

🔍 Audit Logs​

Get Audit Logs​

Create Audit Log​

📝 Case Updates​

Get Case Updates​

Create Case Update​

📊 Dashboard Statistics​

Get Dashboard Stats​

🌱 Seeding System​

Initialize Staging Database​

📊 Performance Monitoring​

Get Performance Metrics​

Record Performance Metric​

Get Performance Report​

🔒 Security Monitoring​

Get Security Events​

Get Security Alerts​

Get Security Metrics​

🚀 Blue-Green Deployment​

Initialize Deployment​

Deploy to Blue Environment​

Run Health Checks​

Switch Traffic​

Rollback Deployment​

🏥 Health Checks​

General Health Check​

Database Health Check​

Authentication Health Check​

Monitoring Health Check​

🔐 GDPR Compliance​

Create GDPR Request​

Data Access Request​

Data Rectification Request​

Data Erasure Request​

Data Portability Request​

Consent Management​

🔐 Error Handling​

Error Response Format​

Common Error Codes​

Validation Errors​

📈 Rate Limiting​

Rate Limits​

Rate Limit Headers​

🔄 Pagination​

Pagination Parameters​

Pagination Response​

🚀 Webhooks​

Webhook Events​

Webhook Payload​

👤 Admin Management​

Create User in Main App​

Create Backoffice User​

🤖 AI System Integration​

Get AI Agents​

Get AI Insights​

Query AI Knowledge Base​

📊 Overview

🔐 Authentication

Authentication Methods

Authentication Headers

👥 User Management

Get Users

Get User by ID

Update User

Create User

🆘 Case Management

Get Cases

Get Case by ID

Create Case

Update Case

💰 Donation Management

Get Donations

🎫 Support System

Get Support Tickets

Get Support Ticket Stats

Create Support Ticket

Update Support Ticket

🔔 Notification System

Get Notifications

Mark Notification as Read

🔍 Audit Logs

Get Audit Logs

Create Audit Log

📝 Case Updates

Get Case Updates

Create Case Update

📊 Dashboard Statistics

Get Dashboard Stats

🌱 Seeding System

Initialize Staging Database

📊 Performance Monitoring

Get Performance Metrics

Record Performance Metric

Get Performance Report

🔒 Security Monitoring

Get Security Events

Get Security Alerts

Get Security Metrics

🚀 Blue-Green Deployment

Initialize Deployment

Deploy to Blue Environment

Run Health Checks

Switch Traffic

Rollback Deployment

🏥 Health Checks

General Health Check

Database Health Check

Authentication Health Check

Monitoring Health Check

🔐 GDPR Compliance

Create GDPR Request

Data Access Request

Data Rectification Request

Data Erasure Request

Data Portability Request

Consent Management

🔐 Error Handling

Error Response Format

Common Error Codes

Validation Errors

📈 Rate Limiting

Rate Limits

Rate Limit Headers

🔄 Pagination

Pagination Parameters

Pagination Response

🚀 Webhooks

Webhook Events

Webhook Payload

👤 Admin Management

Create User in Main App

Create Backoffice User

🤖 AI System Integration

Get AI Agents

Get AI Insights

Query AI Knowledge Base