ForSURE.reports.report_submission

baseURL = '/reports/submission'

Base URL for all requests

GET /reports/submission/submission_configuration
async def get_submission_configuration()

Get data_format and send_email (submission_type) for a given country, report_type, and pro. Returns the configuration if found, None otherwise.

This endpoint retrieves submission configuration from the reporting API, which specifies the data format and submission type (email vs. portal) required for submitting reports to a specific PRO.

Parameters

  • country str - Country code (e.g., "DE", "FR", "NL")
  • report_type str - Type of report (e.g., "WEEE", "Packaging", "Batteries")
  • pro str - PRO identifier (e.g., "Stiftung EAR", "Eco-Emballages")

Returns

dict or None

Response containing:

  • data_format dict - Schema describing the required data structure. The keys are the field names that must be present in each data record, and the values are descriptions of what each field represents.
  • submission_type str - Submission method ("email" or "portal") Returns None if configuration not found.

Example

curl -X GET "https://api.example.com/saas/reports/submission/submission_configuration?country=DE&report_type=WEEE&pro=Stiftung%20EAR" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

Successful response If the request was successful you should receive the status code 200 and a response body like this:

{
    "data_format": {
        "category": "Category code",
        "description": "Description",
        "weight": "Total Weight in kg",
        "report_type": "Report Type"
    },
    "submission_type": "portal"
}

Data Transformation Example:

Based on the data_format response above, you need to submit your data as a list of dictionaries where each dictionary contains the keys specified in data_format. For example:

[
    {
        "category": "1",
        "description": "Large Household Appliances",
        "weight": "1250.5",
        "report_type": "WEEE"
    },
    {
        "category": "2",
        "description": "Small Household Appliances",
        "weight": "850.3",
        "report_type": "WEEE"
    }
]

Battery Report Example GRS DE:

[
    {
        "GRS Article Number": 1023304352,
        "Total Amount (pcs)": 492.0,
        "Total Battery Weight (kg)": 49.2,
        "GRS Article Number Explanation": "Lithium, Primary, 1 - 50 g"
    },
    {
        "GRS Article Number": 1023314453,
        "Total Amount (pcs)": 888.0,
        "Total Battery Weight (kg)": 27.2,
        "GRS Article Number Explanation": "Lithium-Ion/Lithium-Polymer, Secondary, 1 - 50 g"
    },
    {
        "GRS Article Number": 1024304151,
        "Total Amount (pcs)": 336.0,
        "Total Battery Weight (kg)": 25.2,
        "GRS Article Number Explanation": "Alkaline-Manganese/Nickel-Zinc, Primary, 51 - 150 g"
    },
    {
        "GRS Article Number": 1024304352,
        "Total Amount (pcs)": 402.0,
        "Total Battery Weight (kg)": 24.12,
        "GRS Article Number Explanation": "Lithium, Primary, 51 - 150 g"
    }
]

Packaging Report Example NPA SE:

[
    {
        "category": "3210",
        "weight": "248.0",
        "description": "Paper packaging (Compatible with material recycling)"
    },
    {
        "category": "4210",
        "weight": "45.0",
        "description": "Plastic packaging (Compatible with material recycling)"
    },
    {
        "category": "5220",
        "weight": "8.4",
        "description": "Steel packaging (Compatible with material recycling)"
    }
]

WEEE Report Example with Weights and Questions:

{
    "WB": [
        {
            "category": "1",
            "weight_b2c": "0.578",
            "weight_b2b": "0.000"
        },
        {
            "category": "2",
            "weight_b2c": "1.987",
            "weight_b2b": "0.000"
        },
        {
            "category": "3",
            "weight_b2c": "4.973",
            "weight_b2b": "0.000"
        },
        {
            "category": "7",
            "weight_b2c": "1.145",
            "weight_b2b": "0.000"
        }
    ],
    "Questions": [
        {
            "topic": "Weights Identification",
            "question": "100% of products weighed",
            "response": "True"
        },
        {
            "topic": "Weights Identification",
            "question": "Supplier weights used",
            "response": "True"
        },
        {
            "topic": "Weights Identification",
            "question": "Sample weighing",
            "response": "True"
        },
        {
            "topic": "Weights Identification",
            "question": "Weights obtained through grouping products",
            "response": "False"
        },
        {
            "topic": "Weights Identification",
            "question": "Other",
            "response": "False"
        },
        {
            "topic": "Quantification",
            "question": "Purchasing data",
            "response": "True"
        },
        {
            "topic": "Quantification",
            "question": "Sales data",
            "response": "False"
        },
        {
            "topic": "Quantification",
            "question": "Other",
            "response": "ERROR"
        },
        {
            "topic": "WEEE Collections",
            "question": "Have you had any collections of obligated WEEE in the previous quarter that were not arranged through Beyondly?",
            "response": "False"
        }
    ]
}

This list would then be passed as the extracted_data field (as a JSON string) when creating a report via the /create endpoint.

Error response If the request failed you might receive status code 400, 401, 403, or 500 with a response body like this:

{
  "detail": "Failed to get submission configuration"
}

GET /reports/submission/countries
async def get_countries()

Get a list of all available countries for report submission.

This endpoint retrieves the list of countries that are available for report submission. Countries are extracted from the report types configuration.

Returns

list[str]

List of country codes (e.g., ["DE", "FR", "NL", "IT"])

Example

curl -X GET "https://api.example.com/saas/reports/submission/countries" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

Successful response If the request was successful you should receive the status code 200 and a response body like this:

["DE", "FR", "NL", "IT", "ES", "BE"]

Error response If the request failed you might receive status code 400, 401, 403, or 500 with a response body like this:

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

GET /reports/submission/report_types
async def get_report_types()

Get available report types organized by country and PRO.

This endpoint retrieves all available report types from the reporting API. If a country is specified, only report types for that country are returned.

Parameters

  • country str, optional - Country code to filter report types (e.g., "DE"). If not provided, returns report types for all countries.

Returns

dict

Response containing report types organized by country and PRO:

  • {country_code} dict - Dictionary keyed by country code
    • {report_type} dict - Dictionary keyed by report type
      • {pro_name} dict - Dictionary keyed by PRO name

Example

curl -X GET "https://api.example.com/saas/reports/submission/report_types?country=DE" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

Successful response If the request was successful you should receive the status code 200 and a response body like this:

{
    "DE": {
        "WEEE": {
            "Stiftung EAR": {}
        },
        "Packaging": {
            "LUCID": {}
        }
    }
}

Error response If the request failed you might receive status code 400, 401, 403, or 500 with a response body like this:

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

GET /reports/submission/pros
async def get_pros()

Get a list of available PROs (Producer Responsibility Organizations).

This endpoint retrieves all available PROs from the reporting API. Results can be filtered by country and/or report type.

Parameters

  • country str, optional - Country code to filter PROs (e.g., "DE")
  • report_type str, optional - Report type to filter PROs (e.g., "WEEE")

Returns

list[str]

List of PRO names (e.g., ["Stiftung EAR", "LUCID", "Eco-Emballages"])

Example

curl -X GET "https://api.example.com/saas/reports/submission/pros?country=DE&report_type=WEEE" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

Successful response If the request was successful you should receive the status code 200 and a response body like this:

["Stiftung EAR", "LUCID"]

Error response If the request failed you might receive status code 400, 401, 403, or 500 with a response body like this:

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

POST /reports/submission/create/zero
async def create_report_zero()

Create and submit zero reports to PRO portals.

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:

  • 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 '[
  {
    "company": "ABC Corp",
    "country": "DE",
    "report_type": "WEEE",
    "pro": "Stiftung EAR",
    "year": 2024,
    "timeframe": "Q1"
  }
]'

Response Example

Successful response If the request was successful you should receive the status code 200 and a response body like this:

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

Error response If the request failed you might receive status code 400 with a response body like this:

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

Note

If some reports fail, others will still be processed.

POST /reports/submission/create
async def create_report_with_extracted_data()

Create a report with extracted data.

This endpoint creates a report in the reporting API with pre-extracted data. Unlike zero reports, this endpoint accepts extracted_data which contains the actual report data in JSON format. The report is created and a report_id is returned for tracking and further operations.

Parameters

report_data _CreateReportData - Report data object containing:

  • 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")
  • extracted_data str, optional - JSON string containing the extracted report data

Returns

dict

Response containing:

  • report_id int - ID of the created report (for use in subsequent requests)
  • status str - Current status of the report
  • filename str - Generated filename for the report

Example

curl -X POST "https://api.example.com/saas/reports/submission/create" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "company": "ABC Corp",
  "country": "DE",
  "report_type": "WEEE",
  "pro": "Stiftung EAR",
  "year": 2024,
  "timeframe": "Q1",
  "extracted_data": "[{"category": "Large Household Appliances", "weight": 100.5}]"
}'

Response Example

Successful response If the request was successful you should receive the status code 200 and a response body like this:

{
    "report_id": 456,
    "status": "wait_confirmation",
    "filename": "report_ABC_Corp_DE_WEEE_2024_Q1.xlsx"
}

Error response If the request failed you might receive status code 400, 401, 403, or 500 with a response body like this:

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

Note

Requires REPORT_SEND permission. The extracted_data should be a JSON string containing an array of objects representing the report rows. The report_id returned can be used for subsequent operations like getting report details, updates, or deleting the report.

DELETE /reports/submission/report/{report_id}
async def delete_report()

Delete a report by ID.

This endpoint deletes a report from the reporting API. Reports that have already been submitted may not be deletable.

Parameters

  • report_id int - ID of the report to delete

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 DELETE "https://api.example.com/saas/reports/submission/report/456" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

Successful response If the request was successful you should receive the status code 200 and a response body like this:

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

Error response If the request failed you might receive status code 400 with a response body like this:

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

Note

Requires REPORT_DELETE permission. Reports that have been submitted to PRO portals are not deletable.

GET /reports/submission/report/{report_id}
async def get_report_details()

Get detailed information about a specific report.

This endpoint retrieves comprehensive details about a report including its status, submission information, and metadata.

Parameters

  • report_id int - ID of the report to retrieve

Returns

dict

Response containing report details including:

  • id int - Report ID
  • status str - Current status
  • organization str - Organization name
  • country str - Country code
  • report_type str - Report type
  • pro str - PRO name
  • year int - Reporting year
  • timeframe str - Reporting timeframe
  • Additional metadata fields

Example

curl -X GET "https://api.example.com/saas/reports/submission/report/456" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

Successful response If the request was successful you should receive the status code 200 and a response body like this:

{
    "id": 456,
    "status": "wait_confirmation",
    "organization": "/org-abc",
    "country": "DE",
    "report_type": "WEEE",
    "pro": "Stiftung EAR",
    "year": 2024,
    "timeframe": "Q1",
    "filename": "report_ABC_Corp_DE_WEEE_2024_Q1.xlsx",
    "created_at": "2024-01-15T10:30:00Z"
}

Error response If the request failed you might receive status code 400, 401, 403, 404, or 500 with a response body like this:

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

Note

Requires REPORT_VIEW permission.

GET /reports/submission/report/{report_id}/updates
async def get_report_updates()

Get status updates and history for a specific report.

This endpoint retrieves the update history and status changes for a report, including submission attempts, confirmations, and any errors.

Parameters

  • report_id int - ID of the report to retrieve updates for

Returns

list[dict]

List of update records, each containing:

  • timestamp str - When the update occurred
  • status str - Status at that time
  • message str - Update message or description
  • submission_id int, optional - ID of submission if applicable

Example

curl -X GET "https://api.example.com/saas/reports/submission/report/456/updates" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

Successful response If the request was successful you should receive the status code 200 and a response body like this:

[
    {
        "timestamp": "2024-01-15T10:30:00Z",
        "status": "wait_confirmation",
        "message": "Report created successfully"
    },
    {
        "timestamp": "2024-01-16T14:20:00Z",
        "status": "submitted",
        "message": "Report submitted to PRO portal",
        "submission_id": 789
    }
]

Error response If the request failed you might receive status code 400, 401, 403, 404, or 500 with a response body like this:

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

Note

Requires REPORT_VIEW permission. Returns an empty list if no updates are available for the report.

GET /reports/submission/report/{report_id}/extracted
async def get_details_extracted()

Retrieve extracted data from a report in JSON format.

This endpoint returns the raw extracted data from a report before any processing or transformation. This is useful for debugging or viewing the original data structure as it was extracted from the uploaded file.

Parameters

  • report_id int - ID of the report to retrieve extracted data for.

Returns

JSONResponse

Response containing the extracted data as a JSON array of objects. Structure depends on the report format but typically contains rows with column values.

Example

curl -X GET "https://api.example.com/saas/reports/submission/report/456/extracted" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

Successful response If the request was successful you should receive the status code 200 and a response body like this:

[
    {
        "Type": "WEEE",
        "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": "5.1"
    }
]

Error response If the request failed you might receive status code 400, 401, 403, 404, or 500 with a response body like this:

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

Note

Requires REPORT_VIEW permission. Returns the raw extracted data as it was parsed from the uploaded file or posted to this API.