openapi: 3.1.0 info: title: Reporting version: 2.0.0 description: >- The Reporting API allows you to generate and download a CSV report containing data related to your Sendcloud account for tracking and analysis purposes. contact: name: Sendcloud API Support url: https://www.sendcloud.dev email: contact@sendcloud.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://panel.sendcloud.sc/api/v2 description: Sendcloud Production tags: - name: Reporting description: Generate data exports and reports. paths: /reporting/parcels: post: tags: - Reporting summary: Create a parcels report x-mint: href: /api/v2/reporting/create-a-parcels-report content: >- The parcels included in the report will depend on the `filters` provided, and the columns will be determined by the `fields` parameter. Use this endpoint to create the report and obtain the report `id`, which you will use to obtain the actual CSV download via the [Retrieve a parcels report](/api/v2/reporting/retrieve-a-parcels-report) endpoint. description: >- Generate a CSV report containing information about outgoing or incoming parcels. operationId: sc-public-v2-reporting_analytics-post-parcels_report security: - HTTPBasicAuth: [] - OAuth2ClientCreds: [] parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/ParcelsReportRequest' required: true responses: '202': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ParcelsReport' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPError' examples: ValidationError: summary: Validation Error value: detail: - loc: - body - fields msg: >- value is not a valid enumeration member; permitted: 'parcel_id', 'direction', 'carrier_code', 'carrier_name', 'from_company_name', 'contract_id', 'contract_type', 'origin_city', 'origin_postal_code', 'origin_country_code', 'origin_country_name', 'destination_city', 'destination_postal_code', 'destination_country_code', 'destination_country_name', 'order_number', 'tracking_number', 'created_at', 'updated_at', 'announced_at', 'shipped_at', 'first_delivery_at', 'arrived_at', 'shipping_method', 'shipping_method_name', 'price', 'global_status_slug', 'carrier_status', 'integration_id', 'integration_type', 'weight' type: type_error.enum ctx: enum_values: - parcel_id - direction - carrier_code - carrier_name - from_company_name - contract_id - contract_type - origin_city - origin_postal_code - origin_country_code - origin_country_name - destination_city - destination_postal_code - destination_country_code - destination_country_name - order_number - tracking_number - created_at - updated_at - announced_at - shipped_at - first_delivery_at - arrived_at - shipping_method - shipping_method_name - price - global_status_slug - carrier_status - integration_id - integration_type - weight /reporting/parcels/{report_id}: get: tags: - Reporting summary: Retrieve a parcels report x-mint: href: /api/v2/reporting/retrieve-a-parcels-report content: >- The report `id` is the one you obtained via the [Create a parcels report](/api/v2/reporting/create-a-parcels-report) endpoint. Depending on the size of the report, it may not be immediately available for download. The status of the report is indicated in the response body under the `status_message` field. The report will expire after a certain amount of time, after which you will have to generate it again. The time of expiry is indicated in the response body under the `expires_at` field. description: Generate a URL to download a parcels report in CSV format. operationId: sc-public-v2-reporting_analytics-get-parcels_report security: - HTTPBasicAuth: [] - OAuth2ClientCreds: [] parameters: - required: true schema: title: Report Id type: string format: uuid name: report_id in: path description: Report id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ParcelsReport' '422': $ref: '#/components/responses/422' parameters: - schema: type: integer name: report_id in: path required: true description: The report unique identifier components: schemas: HTTPError: title: HTTP Error Object type: object properties: detail: title: Detail type: array items: $ref: '#/components/schemas/Error' ParcelDirections: type: string title: Parcel Directions enum: - incoming - outgoing description: The direction of the parcel example: outgoing ParcelsReport: title: Parcels Report Object type: object description: |- Report information This model contains information about the creation of a report and the status of processing such report. properties: id: type: string title: Id description: The unique identifier for the report. format: uuid example: 419f3be0-2f49-434b-bee4-d8cff9cf7d01 user_id: type: integer title: User Id description: Id of the user that created the report. minimum: 1 example: 1 status: allOf: - $ref: '#/components/schemas/ReportStatus' description: Current status of the report. example: ready status_message: title: Status Message type: string description: Description of the status of the report. example: The report is ready filters: $ref: '#/components/schemas/ParcelsReportFilter' fields: type: array items: $ref: '#/components/schemas/ParcelsReportFields' url: title: Url maxLength: 65536 minLength: 1 type: string description: URL to download the report. format: uri example: >- https://reporting-service.s3.eu-central-1.amazonaws.com/reports/report-type/2021-08-09/afc46bb9-95d3-4880-80f7-660da3e68b5c.csv expires_at: type: string title: Expires At description: When the report will expire. format: date-time example: '2022-07-14T08:38:10.226217Z' updated_at: type: string title: Updated At description: When was the report last updated. format: date-time example: '2022-07-14T08:23:10.226265Z' created_at: type: string title: Created At description: When was the report created. format: date-time example: '2022-07-14T08:23:10.226265Z' required: - filters - fields ParcelsReportFields: title: Parcel Report Fields enum: - parcel_id - direction - carrier_code - carrier_name - from_company_name - contract_id - contract_type - origin_city - origin_postal_code - origin_country_code - origin_country_name - destination_city - destination_postal_code - destination_country_code - destination_country_name - order_number - tracking_number - created_at - updated_at - announced_at - shipped_at - first_delivery_at - arrived_at - shipping_method - shipping_method_name - price - global_status_slug - carrier_status - integration_id - integration_type - weight type: string description: The parcel fields to include for the report ParcelsReportFilter: title: Parcels Report Filters Object type: object properties: direction: allOf: - $ref: '#/components/schemas/ParcelDirections' description: >- Includes only the parcels that are sent (`outgoing`) or returned (`incoming`). integration_id: type: integer title: Integration Id description: >- Includes only the parcels created by the shop integration with the provided id. minimum: 1 updated_after: title: Updated After type: string description: > Includes only the parcels which have been updated in our system after your given time. You can use the value of ISO 8601 DateTime string like this: - 2018-02-26T11:01:47.505309+00:00 - 2018-02-26T11:01:47 - 2018-02-26 Note: the default timezone is UTC format: date-time updated_before: title: Updated Before type: string description: > Includes only the parcels which have been updated in our system before your given time. You can use the value of ISO 8601 DateTime string like this: - 2018-02-26T11:01:47.505309+00:00 - 2018-02-26T11:01:47 - 2018-02-26 Note: the default timezone is UTC format: date-time announced_after: title: Announced After type: string description: > Includes only the parcels which have been announced in our system after your given time. You can use the value of ISO 8601 DateTime string like this: - 2018-02-26T11:01:47.505309+00:00 - 2018-02-26T11:01:47 - 2018-02-26 Note: the default timezone is UTC format: date-time announced_before: title: Announced Before type: string description: > Includes only the parcels which have been announced in our system before your given time. You can use the value of ISO 8601 DateTime string like this: - 2018-02-26T11:01:47.505309+00:00 - 2018-02-26T11:01:47 - 2018-02-26 Note: the default timezone is UTC format: date-time description: A parcels report filter ParcelsReportRequest: title: Parcels Report Request Object required: - fields - filters type: object properties: fields: type: array items: $ref: '#/components/schemas/ParcelsReportFields' filters: $ref: '#/components/schemas/ParcelsReportFilter' description: A parcel report request ReportStatus: title: Report Status enum: - queued - generating - ready - failed - expired type: string description: The report status Error: title: Error type: object properties: loc: type: array description: The location that the error occured items: type: string example: path msg: type: string example: value is not a valid uuid description: A description of the error type: type: string example: type_error.uuid ctx: type: object description: Provides a list of possible fields to be used properties: enum_values: type: array items: $ref: '#/components/schemas/ParcelsReportFields' required: - loc - msg - type securitySchemes: HTTPBasicAuth: type: http description: >- Basic Authentication using API key and secrets is currently the main authentication mechanism. scheme: basic OAuth2ClientCreds: type: oauth2 description: >- OAuth2 is a standardized protocol for authorization that allows users to share their private resources stored on one site with another site without having to provide their credentials. OAuth2 Client Credentials Grant workflow. This workflow is typically used for server-to-server interactions that require authorization to access specific resources. flows: clientCredentials: tokenUrl: https://account.sendcloud.com/oauth2/token/ scopes: api: Default OAuth scope required to access Sendcloud API. responses: '422': description: Example response content: application/json: schema: $ref: '#/components/schemas/Error'