scoro（scoro 搜索）

Scoro Integration

Full Scoro API v2 integration for OpenClaw. Provides task management, time tracking, hours calculation, utilization reports, team dashboards, and billable status corrections.

Setup

1. Get your Scoro API key from Settings → External connections → API in your Scoro account.
2. Set your company URL (e.g. https://yourcompany.scoro.com/api/v2).
3. Add both to your OpenClaw config:

{
  "env": {
    "vars": {
      "SCORO_API_KEY": "ScoroAPI_your_key_here",
      "SCORO_COMPANY_URL": "https://yourcompany.scoro.com/api/v2"
    }
  }
}

1. Add "scoro" to your agent's skills list in openclaw.json.

Standard Prompts

Users can trigger these capabilities with natural language:

Task Management

• fetch my scoro tasks / show my tasks for this week
• fetch tasks for <user email or name>
• show overdue tasks

Hours & Time Entries

• show my hours this week / how many hours have I logged?
• calculate my billable hours / show billable vs non-billable hours
• send me a report of my billable and non-billable hours
• show time entries for <user> from <date> to <date>

Team & Manager Reports

• show team status / team pulse
• generate team hours report

Utilization Reporting

• generate weekly utilization report
• show billable ratio for <user>

Billable Corrections

• find incorrect billable entries
• fix billable status for entries <IDs>
• adjust all logs on task X to be billable

Environment Variables

• SCORO_COMPANY_URL — full base URL (e.g. https://yourcompany.scoro.com/api/v2)
• SCORO_API_KEY — company API key (starts with ScoroAPI_)

Both must be set in openclaw.json under env.vars. They are available as shell environment variables. Do NOT use .env files.

API Basics

All Scoro API v2 requests are POST. Every request body must include apiKey and company_account_id.

The company_account_id is the subdomain from your Scoro URL. For https://yourcompany.scoro.com, it is yourcompany.

Example Request (curl)

curl -X POST "$SCORO_COMPANY_URL/timeEntries/list" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "'"$SCORO_API_KEY"'",
    "company_account_id": "yourcompany",
    "filter": {
      "time_entry_date": {
        "from": "2026-03-10",
        "to": "2026-03-16"
      },
      "user_ids": [123]
    },
    "per_page": 100,
    "page": 1,
    "detailed_response": true
  }'

Example Request (PowerShell / Windows)

$body = @{
    apiKey = $env:SCORO_API_KEY
    company_account_id = 'yourcompany'
    filter = @{
        time_entry_date = @{ from = '2026-03-10'; to = '2026-03-16' }
        user_ids = @(123)
    }
    per_page = 100
    page = 1
    detailed_response = $true
} | ConvertTo-Json -Depth 10

$response = Invoke-RestMethod -Method Post `
    -Uri "$env:SCORO_COMPANY_URL/timeEntries/list" `
    -ContentType 'application/json' -Body $body

Key Endpoints

All endpoints: POST $SCORO_COMPANY_URL/{module}/{action}

Filtering

Tasks

{
  "filter": {
    "responsible_person_ids": [123],
    "deadline": { "from": "2026-03-16", "to": "2026-03-22" },
    "status": "in_progress"
  }
}

• responsible_person_ids — array of assigned user IDs
• deadline — {"from": "YYYY-MM-DD", "to": "YYYY-MM-DD"}
• modified_date — {"from": "YYYY-MM-DD", "to": "YYYY-MM-DD"}

Time Entries

CRITICAL: The date filter field is time_entry_date with from/to keys. NOT start_date/end_date.

{
  "filter": {
    "time_entry_date": { "from": "2026-03-10", "to": "2026-03-16" },
    "user_ids": [123]
  }
}

• user_ids — array of user IDs (not a single value)

Users

No specific filter needed. Returns all active users.

Response Fields

Task Fields

• event_id — unique task ID
• event_name — task name/title
• datetime_due — deadline (ISO datetime)
• is_completed — 0 or 1
• activity_type — project/category name
• responsible_person_id — assigned user ID
• description — task description

Time Entry Fields

• time_entry_id — unique ID
• user_id — the user who logged it
• duration — format "HH:MM:SS" (e.g. "01:30:00" = 1.5h)
• title — task/event name
• billable_time_type — "billable", "non_billable", or "custom"
• time_entry_date — "YYYY-MM-DD"
• event_id — the task/event this entry is for
• is_billable — 0 or 1

User Fields

• id — unique user ID
• full_name — display name
• email — email address
• position — job title

Duration Parsing

Format is "HH:MM:SS". Convert to decimal hours: hours + minutes/60 + seconds/3600.

Pagination — CRITICAL

Scoro caps page size at 25 items regardless of per_page setting.

You MUST paginate through ALL pages for any list operation:

page = 1
all_results = []
loop:
  response = POST .../endpoint { per_page: 100, page: page }
  if length(response.data) == 0: break
  all_results += response.data
  page += 1
  sleep 1 second (rate limit)

Important: Do NOT use data.length < per_page as a stop condition — the API returns a max of 25 items per page even if you request 100. Stop when a page returns 0 results.

Calculating Hours

1. Determine date range (default: this week Monday to today)
2. Fetch all time entries for the date range and user(s), paginating all pages
3. Calculate:

   total_hours = sum(duration)
   billable_hours = sum(duration where billable_time_type == "billable")
   non_billable_hours = sum(duration where billable_time_type == "non_billable")
   billable_ratio = (billable_hours / total_hours) * 100

1. Present with 2 decimal places

Team Reports

Teams are organized by direct manager (reporting lines).

Workflow for Team Status

1. Resolve user IDs for all team members (by email, from users/list, all pages)
2. Fetch today's time entries for all team members at once
3. Per member: total hours, billable split, latest task name
4. Calculate team totals and billable ratio

Billable Status Correction

Detection

1. Retrieve time entries for the period
2. Retrieve task billing type for each task
3. Flag mismatches: task is billable but time entry is non_billable

Correction

POST /timeEntries/modify/<ENTRY_ID>
{
  "apiKey": "...",
  "company_account_id": "yourcompany",
  "request": {
    "billable_time_type": "billable"
  }
}

Always confirm with the user before modifying entries.

Rate Limits

• 2-second rate limit window
• Add 1-second delay between paginated API calls
• On 429 errors, wait and retry

Response Format

{
  "status": "OK",
  "statusCode": 200,
  "messages": null,
  "data": []
}

All Available Modules

tasks, timeEntries, users, projects, contacts, invoices, quotes, orders, bills, expenses, products, calendarEvents, bookings, purchaseOrders, tags, customModules, vatCodes, financeAccounts

Each module supports: list, view, modify, delete.

Use modify and delete only with explicit user permission.

Notes

• All requests are POST (even "list" and "view")
• Always include apiKey and company_account_id in the JSON body
• Use detailed_response: true for full field data in list requests
• Duration format: "HH:MM:SS" → convert to decimal hours for reporting
• The lang parameter is optional (defaults to site language)
• On Windows, prefer PowerShell Invoke-RestMethod over curl