ForSURE.reports.upload_reports

Base URL for all requests

This endpoint uploads completed reports in Excel or PDF format. The system uses stored client credentials to authenticate and submit reports automatically on behalf of clients to the appropriate PRO portals. Reports are processed and notifications are created for tracking.

Parameters

reports list[UploadFile] - List of file uploads containing reports from one or more sources. Supported formats: Excel (.xlsx) or PDF (.pdf).

fileId list[str] - List of file IDs to keep track of the exact source of each report. Should match the length of the reports list.

Returns

dict

Response containing:

• status_code int - HTTP status code (200 for success, 400 for errors)
• data list - List of results:
  • For success: Contains objects with "reports" (count) and "file_id"
  • For errors: Contains objects with "file_id" and "error" message

Example

curl -X POST "https://api.example.com/saas/finishedreports/" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "reports=@report1.xlsx" \
-F "reports=@report2.pdf" \
-F "fileId=file_001" \
-F "fileId=file_002"

Response Example

{
    "status_code": 200,
    "data": [
        {
            "reports": 2,
            "file_id": "file_id_123"
        }
    ]
}

{
    "status_code": 400,
    "data": [
        {
            "file_id": "file_id",
            "error": "Error Message"
        }
    ]
}

Note

Requires authentication and REPORT_SEND permission. Reports are uploaded to cloud storage and forwarded to the reporting API for processing. Notifications are created for successful uploads. The fileId list should match the reports list in length and order.

This endpoint retrieves available report types from the reporting API and enriches them with information about which clients have credentials configured for automatic report submission. This helps identify which clients can automatically submit reports for each country-PRO combination.

Returns

dict

Response containing:

• data dict - Report types organized by country, report type, and PRO:
  • {country_code} dict - Dictionary keyed by country code
    • {report_type} dict - Dictionary keyed by report type
      • {pro_name} list - List of deadlines or empty dict
• clients dict - Clients with credentials, organized by country, report type, and PRO:
  • {country_code} dict - Dictionary keyed by country code
    • {report_type} dict - Dictionary keyed by report type
      • {pro_name} list[str] - List of client names with credentials

Example

curl -X GET "https://api.example.com/saas/finishedreports/report_types" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

{
    "data": {
        "DE": {
            "WEEE": {
                "Stiftung EAR": {}
            }
        }
    },
    "clients": {
        "DE": {
            "WEEE": {
                "Stiftung EAR": ["Client 1", "Client 2"]
            }
        }
    }
}

{
  "detail": "Failed to get report"
}

Note

Requires authentication and REPORT_SEND permission. Only returns report types for which clients have configured credentials. The clients dictionary shows which clients can automatically submit reports for each country-PRO combination.

This endpoint retrieves available report types organized by client ID, showing which reporting options (country, report type, year, timeframe) are available for each client based on their configured credentials. This helps identify what reports can be created for each client.

Returns

dict

Response containing:

• data dict - Report types organized by client ID:
  • {client_id} str - Client ID as string key
    • {country_code} dict - Dictionary keyed by country code
      • {report_type} dict - Dictionary keyed by report type
        • {year} int - Year as integer key
          • list[str] - List of available timeframes (e.g., ["Q1", "Q2", "Full Year"])
• client_names dict - Mapping of client IDs to client names:
  • {client_id} str - Client ID as string key
  • client_name str - Name of the client

Example

curl -X GET "https://api.example.com/saas/finishedreports/report_types_by_client" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

{
    "data": {
        "1": {
            "DE": {
                "WEEE": {
                    "2024": ["Q1", "Q2", "Q3", "Q4"]
                }
            }
        }
    },
    "client_names": {
        "1": "Client Company Name",
        "2": "Another Client Name"
    }
}

{
  "detail": "Failed to get report types by client"
}

Note

Requires authentication and REPORT_SEND permission. Only includes clients that have credentials configured. The data structure shows all available reporting combinations (country, report type, year, timeframe) for each client based on their credentials and available deadlines from the reporting API.

This endpoint creates and submits zero reports (reports indicating no data for a specific reporting period) to PRO portals. Zero reports are required when a client has no data to report for a given period but still needs to submit a report to maintain compliance.

Parameters

report_data list[_CreateReportData] - List of report data objects, each containing:

• report_id str - Unique identifier for the report (combination of company, year, etc.)
• company str - Company name
• brand str, optional - Brand name (if applicable)
• country str - Country code
• report_type str - Type of report (e.g., "WEEE", "Packaging", "Batteries")
• pro str - PRO name
• year int - Reporting year
• timeframe str - Reporting timeframe (e.g., "Q1", "Q2", "Full Year")

Returns

dict

Response containing:

• status_code int - HTTP status code (200 for success, 400 for errors)
• data list - List of errors if any occurred:
  • For success: Empty list
  • For errors: Contains objects with "report_id" and "error" message

Example

curl -X POST "https://api.example.com/saas/finishedreports/create/zero" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '[
  {
    "report_id": "report_123",
    "company": "ABC Corp",
    "country": "DE",
    "report_type": "WEEE",
    "pro": "Stiftung EAR",
    "year": 2024,
    "timeframe": "Q1"
  }
]'

Response Example

{
    "status_code": 200,
    "data": []
}

{
    "status_code": 400,
    "data": [
        {
            "report_id": "report_123",
            "error": "Error Message"
        }
    ]
}

Note

Requires authentication. Zero reports are submitted to the reporting API which handles the actual submission to PRO portals. If some reports fail, others will still be processed. The report_id should be unique for each report.

This endpoint retrieves client credentials organized by country with dynamic columns for Login, Password, Notes, and ExtraInfo per scheme and wastestream combination. The format is designed for easy editing in Excel and re-upload. Credentials are pivoted so each client has one row with multiple credential columns. Aliases are expanded into separate rows.

Parameters

client str, optional - Filter by client name.

country str, optional - Filter by country code.

scheme str, optional - Filter by PRO (scheme) name.

wastestream str, optional - Filter by report type (wastestream).

collective_account bool, optional - Filter by collective account status (True/False).

interval str, optional - Filter by reporting interval.

Returns

dict

Response containing:

• status_code int - HTTP status code (200)
• data dict - Credentials data:
  • filename str - Suggested filename for Excel export
  • data dict - Credentials organized by country:
    • {country_code} list[dict] - List of client rows, each containing:
      • client str - Client name
      • Login {scheme} {wastestream} str - Login for each scheme/wastestream
      • Password {scheme} {wastestream} str - Password for each scheme/wastestream
      • Notes {scheme} {wastestream} str - Notes for each scheme/wastestream
      • ExtraInfo {scheme} {wastestream} str - Extra info for each scheme/wastestream

Example

curl -X GET "https://api.example.com/saas/finishedreports/clients?country=DE&wastestream=WEEE" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

{
    "status_code": 200,
    "data": {
        "filename": "Clients.xlsx",
        "data": {
            "DE": [
                {
                    "client": "ABC Corporation",
                    "Login Stiftung EAR WEEE": "username@example.com",
                    "Password Stiftung EAR WEEE": "password123",
                    "Notes Stiftung EAR WEEE": "Main credential",
                    "ExtraInfo Stiftung EAR WEEE": "DE123456"
                }
            ]
        }
    }
}

{
  "detail": "Failed to get client credentials"
}

Note

Requires authentication and REPORT_SEND permission. Credentials are pivoted so each client appears once per country with all their credentials as columns. Client aliases are expanded into separate rows. Collective account credentials are resolved to show the actual login/password values.

This endpoint retrieves client credentials in a new format (one row per credential instead of pivoted) for internal use. It supports special handling for organizations that create their own reports (e.g., Fairphone), where credentials are retrieved from selected PROs. Includes client aliases in the response.

Parameters

organization str, optional - Organization name to retrieve credentials for.

client str, optional - Filter by client name.

country str, optional - Filter by country code.

scheme str, optional - Filter by PRO (scheme) name.

wastestream str, optional - Filter by report type (wastestream).

collective_account bool, optional - Filter by collective account status (True/False).

interval str, optional - Filter by reporting interval.

Returns

dict

Response containing:

• status_code int - HTTP status code (200)
• data list[dict] - List of credential objects, each containing:
  • client str - Client name
  • country str - Country code
  • scheme str - PRO name
  • wastestream str - Report type
  • login str - Login username
  • password str - Password
  • notes str, optional - Notes
  • extra_info str, optional - Extra information
  • aliases dict - Dictionary of client aliases (alias name -> list of countries)
  • Additional credential fields

Example

curl -X GET "https://api.example.com/saas/finishedreports/clients/new/internal?organization=/Fairphone&country=DE" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

{
    "status_code": 200,
    "data": [
        {
            "client": "Organization Name",
            "country": "DE",
            "scheme": "Stiftung EAR",
            "wastestream": "WEEE",
            "login": "username@example.com",
            "password": "password123",
            "notes": "Notes for the credential",
            "extra_info": "Extra info for the credential",
            "aliases": {
                "alias": [],
                "alias2": ["DE", "AT"]
            }
        }
    ]
}

{
  "detail": "Failed to get client credentials"
}

Note

This endpoint is for internal use. Returns credentials in a new format with one row per credential (not pivoted). For organizations that create their own reports, credentials come from selected PROs. For others, credentials come from the client credentials database. Data is cleaned to be JSON-compliant (handles inf, -inf, nan values).

This endpoint creates a new credential entry for automatic report submission to a PRO portal. The credential is associated with the current user's organization and can be used for automatic report submission.

Parameters

country str - Country code where these credentials are valid (e.g., "DE", "FR", "NL").

wastestream str - Report type (wastestream) for these credentials (e.g., "WEEE", "Packaging", "Batteries").

scheme str - PRO (scheme) name for these credentials (e.g., "Stiftung EAR", "Stichting Open").

login str - Username/login for the PRO portal.

password str - Password for the PRO portal.

notes str - Optional notes about the credential.

extra_info str - Optional additional information (e.g., registration number).

Returns

dict

Response containing:

• success bool - True if credential was created successfully
• detail str, optional - Error message if credential already exists

Example

curl -X POST "https://api.example.com/saas/finishedreports/clientsadd" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "country=DE" \
-F "wastestream=WEEE" \
-F "scheme=Stiftung EAR" \
-F "login=username@example.com" \
-F "password=securepassword123" \
-F "notes=Main credential" \
-F "extra_info=DE123456"

Response Example

{
    "success": true
}

{
    "success": false,
    "detail": "Log in already exists, please update that instead"
}

{
  "detail": "Failed to add PRO"
}

Note

Requires authentication and REPORT_SEND permission. The credential is created for the current user's organization. If a credential already exists for the same client, country, scheme, and wastestream combination, the request will fail with a message indicating the credential should be updated instead.

This endpoint retrieves all reports for the current user's organization with advanced filtering options. Reports can be filtered by company, country, report type, timeframe, year, and PRO. The endpoint enriches reports with submission eligibility, relevance indicators, and includes related files (submissions, audit trails, excluded data).

Parameters

company str, optional - Filter reports by company name.

country str, optional - Filter reports by country code.

report_type str, optional - Filter reports by report type (e.g., "WEEE", "Packaging", "Batteries").

timeframe str, optional - Filter reports by timeframe (e.g., "Q1", "Q2", "Full Year").

year int, optional - Filter reports by year.

pro str, optional - Filter reports by PRO name.

only_user_reports bool, default False - If True, only returns reports uploaded by the current user.

with_submission bool, default True - If True, includes submission validation; if False, returns reports without validation.

Returns

dict

Response containing:

• data list[dict] - List of report objects, each containing:
  • id int - Report ID
  • filename str - Report filename
  • company str - Company name
  • country str - Country code
  • report_type str - Report type
  • pro str - PRO name
  • year int - Reporting year
  • timeframe str - Reporting timeframe
  • status str - Report status (e.g., "wait_confirmation", "waiting", "done")
  • can_submit bool - Whether report can be submitted
  • new bool - Whether report was updated in the last day
  • my_reports bool - Whether report was uploaded by current user
  • relevant_for_me bool - Whether report is relevant to current user
  • receipt bool - Whether this is a receipt/submission
  • can_delete bool - Whether report can be deleted
  • Additional report metadata
• last_updated float - Unix timestamp of the most recent report update

Example

curl -X GET "https://api.example.com/saas/finishedreports/reportsDone?country=DE&report_type=WEEE&year=2024" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

{
    "data": [
        {
            "id": 456,
            "filename": "report_2024_Q1.xlsx",
            "company": "ABC Corp",
            "country": "DE",
            "report_type": "WEEE",
            "pro": "Stiftung EAR",
            "year": 2024,
            "timeframe": "Q1",
            "status": "wait_confirmation",
            "can_submit": true,
            "new": false,
            "my_reports": true,
            "relevant_for_me": true,
            "receipt": false,
            "can_delete": true
        }
    ],
    "last_updated": 1713175800.0
}

{
  "detail": "Failed to display reports done"
}

Note

Requires authentication and REPORT_VIEW permission. Reports are enriched with submission eligibility based on upcoming deadlines. The response includes the main report plus related files (submissions, audit trails, excluded data) as separate entries. Reports are marked as "relevant_for_me" if they were uploaded by the user or match the user's PRO responsibilities.

This endpoint retrieves a report overview from the reporting API. The overview provides a high-level summary of reports for the organization, with optional filtering by user reports or relevant reports based on PRO responsibilities.

Parameters

only_user_reports bool, default False - If True, only returns reports uploaded by the current user.

only_relevant_reports bool, default False - If True, only returns reports relevant to the current user based on their PRO responsibilities (countries they're responsible for) or reports they uploaded.

Returns

dict

Response from the reporting API containing report overview data. Structure depends on the reporting API response format.

Example

curl -X GET "https://api.example.com/saas/finishedreports/reports/reportOverview?only_relevant_reports=true" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

{
  "detail": "Failed to display reports done"
}

Note

Requires authentication and REPORT_VIEW permission. This endpoint forwards the request to the reporting API with organization and filtering parameters. The response format matches the reporting API's reportOverview endpoint.

This endpoint retrieves reports that have been updated or changed since a specified timestamp. This is useful for incremental updates to avoid re-fetching all reports, improving performance for large datasets.

Parameters

previous_time float - Unix timestamp of the last update check. Only reports modified after this time will be returned.

Returns

dict

Response containing:

• data list[dict] - List of updated report objects with the same structure as GET /reportsDone, but only includes reports modified after previous_time
• last_updated float - Unix timestamp of the most recent report update (can be used as previous_time for the next request)

Example

curl -X GET "https://api.example.com/saas/finishedreports/reportsDone/updates?previous_time=1713175800.0" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

{
    "data": [
        {
            "filename": "report_2024_Q1.xlsx",
            "status": "wait_confirmation",
            "updated_at": "2024-04-15T10:30:00Z",
            "last_checked": "2024-04-15T10:30:00Z"
        }
    ],
    "last_updated": 1713175800.0
}

{
  "detail": "Failed to update reports history"
}

Note

Requires authentication and REPORT_VIEW permission. Use this endpoint for efficient incremental updates. The last_updated value from the response can be used as previous_time for the next request. Only reports with last_checked timestamp greater than previous_time are returned.

This endpoint retrieves the detailed content of various file types associated with reports. The response format depends on the file type and the display parameter. Supports reports, submissions, audit trails, and excluded data files.

Parameters

filepath str, optional - Name/path of the file to retrieve (required for submission filetype).

report_id int, optional - ID of the report, submission, audit trail, or excluded data entry (required for most filetypes).

filetype str - Type of file, one of:

• "report" - Main report file
• "submission" - Submission file (PDF or screenshot)
• "audit_trail" - Audit trail file
• "excluded_data" - Excluded data file

display bool, default False - If True, returns data as JSON for display in UI; if False, returns file for download.

Returns

JSONResponse or StreamingResponse

Response format depends on display parameter:

If display=True:

• JSONResponse with dictionary containing sheet names as keys and list of row dictionaries as values (for XLSX/CSV) or raw data (for other formats)

If display=False:

• StreamingResponse with file content and appropriate Content-Type header
• For XLSX: Excel file with multiple sheets
• For CSV: CSV file
• For PDF/images: Binary file with appropriate media type
• For other formats: JSON file

Example

# Get report data for display
curl -X POST "https://api.example.com/saas/finishedreports/getdetails" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "report_id=456" \
-F "filetype=report" \
-F "filepath=report.xlsx" \
-F "display=true"

# Download report file
curl -X POST "https://api.example.com/saas/finishedreports/getdetails" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "report_id=456" \
-F "filetype=report" \
-F "filepath=report.xlsx" \
-F "display=false" \
--output report.xlsx

Response Example

{
    "Sheet1": [
        {
            "Type": "DE",
            "Amount Total": 5115,
            "Weight Total (kg)": 26.589,
            "Amount B2B": 3443,
            "Weight B2B (kg)": 17.944,
            "Amount B2C": 1672,
            "Weight B2C (kg)": 8.645,
            "Category": "Paper/Cardboard"
        }
    ]
}

{
  "detail": "Failed to get file content"
}

Note

Requires authentication and REPORT_VIEW permission. The endpoint routes to different reporting API endpoints based on filetype. For XLSX files, all sheets are processed and returned. For CSV files, only the first sheet is used. Unnamed columns are automatically renamed to "Column A", "Column B", etc.

This endpoint allows bulk downloading of multiple reports, submissions, audit trails, or excluded data files. All selected files are packaged into a single ZIP archive for convenient download.

Parameters

reportSelection list[dict[str, Any]] - List of report selection dictionaries, each containing identifiers for the reports to download. The structure depends on the file type but typically includes:

• report_id or submission_id or audit_trail_id or excluded_data_id int
• filepath or filename str - Name of the file
• filetype str - Type of file (report, submission, audit_trail, excluded_data)
• Additional identifiers as needed

Returns

Response

ZIP file download with:

• Content-Type: application/zip
• Content-Disposition: attachment; filename="reports.zip"
• Binary ZIP archive containing all selected files

Example

curl -X POST "https://api.example.com/saas/finishedreports/multiple-reports" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '[
  {
    "report_id": 456,
    "filepath": "report1.xlsx",
    "filetype": "report"
  },
  {
    "submission_id": 789,
    "filepath": "submission1.pdf",
    "filetype": "submission"
  }
]' \
--output reports.zip

Response Example

{
  "detail": "Failed to download multiple reports"
}

Note

Requires authentication and REPORT_VIEW permission. The endpoint forwards the request to the reporting API which packages all selected files into a ZIP archive. The ZIP file structure matches the file organization in the reporting system.

This endpoint deletes reports and related files. If report_id is provided, the deletion is handled by the reporting API. If not provided, the file is deleted from local storage. Reports that have already been submitted may not be deletable.

Parameters

file_name str - Name/path of the file to delete.

filetype str - Type of file being deleted (used for validation and routing).

report_id int, optional - ID of the report to delete. If provided, deletes from the reporting API. If not provided, deletes from local storage.

Returns

dict

Response containing:

• status_code int - HTTP status code (200 for success, 400 for errors)
• message str - Success or error message
• hide bool - Whether the file should be hidden from UI (True for local deletions, False for API deletions)

Example

curl -X POST "https://api.example.com/saas/finishedreports/delete-report" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "file_name=report.xlsx" \
-F "filetype=report" \
-F "report_id=456"

Response Example

{
    "status_code": 200,
    "message": "Report deleted successfully.",
    "hide": true
}

{
    "status_code": 400,
    "message": "Failed to delete report, might be already submitted.",
    "hide": false
}

{
  "detail": "FileNotFoundError"
}

Note

Requires authentication and REPORT_DELETE permission. If report_id is provided, deletion is handled by the reporting API which may prevent deletion of submitted reports. If report_id is not provided, the file is deleted from local storage and associated .pkl files are also removed.

This endpoint creates a correction report for an existing report. Correction reports are used when errors are discovered in a previously submitted report and need to be corrected.

Parameters

report_id int - The ID of the report to create a correction report for.

Returns

dict

Response containing:

• status_code int - HTTP status code (200 for success)
• message str - Success message

Example

curl -X POST "https://api.example.com/saas/finishedreports/correction-report" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "report_id=456"

Response Example

{
    "status_code": 200,
    "message": "Correction report created successfully."
}

{
  "detail": "Failed to create correction report"
}

Note

Requires authentication and REPORT_SEND permission. This endpoint is a placeholder for future correction report functionality. The actual implementation may be added in the future.

This endpoint updates the categories and metadata for a report. The update request is forwarded to the reporting API which handles the actual update operation.

Parameters

report_id str - ID of the report to update.

company_name str - Name of the company.

client_id str - ID of the client.

country str - Country code (e.g., "DE", "FR", "NL").

report_type str - Type of report (e.g., "WEEE", "Batteries", "Packaging").

year str - Year of the report (e.g., "2024").

timeframe str - Timeframe of the report (e.g., "Q1", "Q2", "Full Year").

Returns

dict

Response containing:

• status_code int - HTTP status code (200 for success, 400 for errors)
• message str - Success or error message

Example

curl -X POST "https://api.example.com/saas/finishedreports/update-categories" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "report_id=456" \
-F "company_name=ABC Corp" \
-F "client_id=123" \
-F "country=DE" \
-F "report_type=WEEE" \
-F "year=2024" \
-F "timeframe=Q1"

Response Example

{
    "status_code": 200,
    "message": "Report categories updated successfully."
}

{
    "status_code": 400,
    "message": "Error message"
}

{
  "detail": "Failed to update report categories"
}

Note

Requires authentication and REPORT_SEND permission. The update request is forwarded to the reporting API which validates and applies the changes. All parameters are required.