Reports API

The Reports-API lets merchants access their completed transaction reports programmatically. It’s designed for reconciliation, accounting, analytics, and compliance — without exposing any public storage links.

Two secure APIs are provided:

List Reports : Returns a filtered, paginated list of finished reports (auto or manual), plus a secure download_action.
Download Report : Downloads the binary file using authenticated access.

Why this matters: The dashboard already shows reports, but this API enables automated systems (ERP, BI tools, finance scripts) to fetch and download reports safely.

Setup

Base URL

Use your Ottu domain:

https://<ottu-url>

Endpoints

1) List Reports

GET b/api/v1/reports

2) Download Report

From the response of List Reports API, extract download_action.url for the desired report

make GET request to download_action.url to download the file

If you don’t pass date filters, the List Reports API returns the last 30 days of finished reports, sorted newest first.

Authentication

Supported Methods

For detailed information on authentication procedures, please refer to the Authentication documentation.

Permissions

Permissions apply only when using Basic Auth.

Required permission

report.can_view_report

Rules

If the user has the permission or is a superuser, the List and Download APIs work normally.
If the user does not have the permission, the API responds with:
- 403 Forbidden
- Message like: "No permission assigned"

API Key authentication does not require user permissions, since it is merchant-scoped.

How it works

Reports sources

Reports can be generated in two ways:

Auto reports: daily / weekly / monthly / yearly schedules.
Manual reports: created via dashboard.

Visibility and security rules

A merchant can only see their own reports.
Only finished reports are returned.
No public or raw storage URLs are ever returned.
Every download attempt is audit-logged.

Download workflow (high-level)

Call List Reports to get available reports.
Pick a report from results.
Use its secure download_action.url.
Call that URL with the same authentication headers.
The report file is returned as binary.

API Schema Reference

List Transaction Reports

get

Retrieve a paginated list of completed transaction reports for reconciliation, accounting, analytics, and compliance purposes.

Authentication

API Key (Recommended): Api-Key: your_private_api_key
Basic Auth: User must have report.view_report permission

Example Request

curl -X GET 'https://your-domain.com/api/v1/reports/files/?created_after=2025-11-01&limit=50' \
  -H 'Api-Key: your_private_api_key_here'

Key Features

Only returns finished reports (optimized queries)
Includes encrypted_id for reference (prevents enumeration)
Provides download_action with ready-to-use secure download URL
Ordered by creation date (newest first)
Merchant-isolated (each instance sees only their reports)

Response Fields

encrypted_id: Encrypted report identifier for reference
download_action.url: Pre-signed download URL with embedded token
download_action.method: HTTP method to use (always GET)

Integration Walkthrough

Step 1: Call this endpoint to list available reports

Step 2: From the response, extract download_action.url for the desired report

Step 3: Make a GET request to that URL (same auth headers) to download the file

Authorizations

AuthorizationstringRequired

Query parameters

created_afterstring · dateOptional

Created after (inclusive)

created_beforestring · dateOptional

Created before (inclusive)

intervalstring · enumOptional

Report interval

daily - Daily
weekly - Weekly
monthly - Monthly
yearly - Yearly

Possible values:

limitintegerOptional

Number of results to return per page.

offsetintegerOptional

The initial index from which to return the results.

sourcestring · enumOptional

Report source

auto - Auto
manual - Manual

Possible values:

Header parameters

AuthorizationstringRequired

Private API key to be provided in the format Api-Key <key>.

Default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo

Responses

200Success

application/json

400Error

application/json

401Error

application/json

403Error

application/json

get

/b/api/v1/reports/files/

GET /b/api/v1/reports/files/ HTTP/1.1
Host: saphira.ottu.dev
Authorization: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo
Accept: */*

{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "encrypted_id": "text",
      "report_name": "text",
      "interval": "text",
      "source": "text",
      "file_format": "text",
      "records_amount": 1,
      "status": "in_progress",
      "generated_at": "2025-12-12T20:26:01.298Z",
      "created_at": "2025-12-12T20:26:01.298Z",
      "download_action": "text"
    }
  ]
}

Download Transaction Report File

get

Download a report file using the secure token from the list endpoint.

How It Works

Call /api/v1/reports/files/ to list reports
Each report includes a download_action object with a pre-built URL
Use that URL directly - the token is already embedded in the path

Authentication

API Key (Recommended): Api-Key: your_private_api_key
Basic Auth: User must have report.view_report permission

Example Flow

# Step 1: List reports
curl -X GET 'https://your-domain.com/api/v1/reports/files/' \
  -H 'Api-Key: your_private_api_key_here'

# Response includes:
# {
#   "encrypted_id": "abc123...",
#   "download_action": {
#     "method": "GET",
#     "url": "https://your-domain.com/api/v1/reports/files/<token>/download/"
#   }
# }

# Step 2: Download using the URL from download_action
curl -X GET 'https://your-domain.com/api/v1/reports/files/<token>/download/' \
  -H 'Api-Key: your_private_api_key_here' \
  -o report.csv

Security Features

Token-based: Download tokens are UUIDs cached in Redis
Time-limited: Tokens expire (configurable TTL, default from settings)
User-bound: Token is tied to the user who requested the list
Rate Limiting: Downloads are rate-limited per user
Ownership Verification: Server verifies user owns the report

File Delivery

S3 Storage: Redirects (302) to a pre-signed S3 URL
Local Storage: Returns file with X-Sendfile header for Apache

File Formats

CSV: text/csv - UTF-8 encoded, comma-delimited
XLSX: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Authorizations

AuthorizationstringRequired

Path parameters

tokenstringRequired

Secure download token (UUID) from the download_action.url field in the list response. Tokens are time-limited and bound to the authenticated user.

Header parameters

AuthorizationstringRequired

Private API key to be provided in the format Api-Key <key>.

Default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo

Responses

200

Report file (CSV or XLSX). For S3: redirects to pre-signed URL.

application/json

Responsestring · binary

302

Redirect to pre-signed S3 URL (when S3 storage is enabled)

400

Invalid token (unknown alias or malformed token)

401Error

application/json

403

User is not authorized to download this file

404

Report or file not found

410

Download link has expired or is invalid

get

/b/api/v1/reports/files/{token}/download/

GET /b/api/v1/reports/files/{token}/download/ HTTP/1.1
Host: saphira.ottu.dev
Authorization: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo
Accept: */*

binary

Guide

1) List Reports

Purpose: Retrieve a paginated list of completed reports.

Request

GET b/api/v1/reports/files/

Query parameters

Name

Type

Required

Notes

created_after

date

Lower bound (inclusive)

created_before

date

Upper bound (inclusive)

interval

enum

daily, weekly, monthly, yearly

source

enum

auto or manual

limit

int

Default 50, max 200

offset

int

Pagination mode (cursor recommended if enabled)

Response

download_action.url – pre-signed download URL with embedded token.
download_action.method – always GET.

2) Download Report

Purpose Download the report file as binary.

Request

GET b/api/v1/reports/files/a75cd20e-d5b7-4019-972e-c0fe45c1bb96/download/

:report_id is file download token

Response

Returns the file directly (CSV, XLSX, etc.) as binary.
No JSON body unless there’s an error.

Best Practices

Use API Key for automation
- More stable and permission-free for system integrations.
Always filter by date
- Avoid pulling large histories unintentionally.
- Example: fetch only last month’s reports.
Respect pagination
- Use limit and cursor/offset until next is null.

Handle empty results

A valid response can be:

{"count":0, "next":null, "previous":null, "results":[]}

Log your own download tracking
- Even though Ottu logs downloads, your system should store:
  - report id
  - download time
  - success state
Retry safely
- On 429 rate_limited, backoff before retrying.

FAQ

1️Can I download reports without listing them first?

You technically can if you already stored the encrypted_id. But listing first is the safest way to discover available reports.

2️Why don’t I see reports that are still generating?

The List Reports API returns finished reports only to keep results correct and fast.

3️What happens if I don’t pass date filters?

The API returns reports from the last 30 days, newest first.

No. Download URLs are secure, tokenized, and require authentication. They are not permanent or public.

5️What errors should I expect?

HTTP

code

message

When

400

invalid_parameters

Bad filters

created_before < created_after

401

unauthorized

Invalid/missing auth

Header missing or wrong

403

forbidden

Insufficient permissions

Basic user lacks report permission

404

not_found

Report not found

Wrong or inaccessible ID

429

rate_limited

Too many requests

Quota exceeded

6️ I’m using Basic Auth but still getting 403 — why?

Your user is missing report.can_view_report. Ask your admin to enable report API access.

7️ Are downloads logged even if they fail?

Yes. Every attempt is logged with outcome status for audit compliance.

PreviousInvoice API NextMessage Notifications

Last updated 1 day ago

Base URL

Endpoints

1) List Reports

2) Download Report

Required permission

Rules

Reports sources

Visibility and security rules

Download workflow (high-level)

List Transaction Reports

Authentication

Example Request

Key Features

Response Fields

Integration Walkthrough

Download Transaction Report File

How It Works

Authentication

Example Flow

Security Features

File Delivery

File Formats

1) List Reports

2) Download Report

1️Can I download reports without listing them first?

2️Why don’t I see reports that are still generating?

3️What happens if I don’t pass date filters?

4️Can I share download links publicly?

5️What errors should I expect?

6️ I’m using Basic Auth but still getting 403 — why?

7️ Are downloads logged even if they fail?