Skip to main content

Reports API

: Reports API - Rate limiting API requests for creating reports

Starting from 17 June 2024, requests for creating reports will be rate limited. This is to ensure that our services remain stable. You can see more details under the “Rate limiting” section in the Reports API documentation.

The Reports API can be used as a tool for analyzing your logistics with Bring. The API lets you generate reports within the categories status, quality and deviation, economy and environment. Supported report formats are XML and Excel.

Authentication

To integrate with the Bring APIs, you will need a Mybring user account with an API key. Information about prerequisites and authentication headers can be found on the general API Getting Started page.

Rate limiting

The Reports application has a rate limiting functionality. When triggered, a response with HTTP status code 429 will immediately be returned for the user if they attempt to create a report. Users can be throttled for creating multiple identical requests in a short amount of time. Additionally, users are also limited to 20 concurrent report requests that can be created at once. After 20 report requests has been created, the user will need to wait for one of them to finish before a new one can be made.

Formats

REST XML/JSON over HTTP.

Fetching reports

The first two steps in the process is only necessary to find customer numbers and report types for the user. You can save these IDs, and perform the generation-step without verifying the IDs. The response may get added information, so implementation should ignore new elements added to the response.

  1. Get the customers IDs
  2. Get the list of report types available for the customer
  3. Initiate report creation and get the report ID. The Report ID is initially used to monitor reports creation progress, later to get the actual report (XML or Excel file).
  4. After initiating report creation, you can check the status, if it’s in-progress, completed or failed. When completed, a URL to the actual report is returned.
  5. Download report

Invoice sources

For specified invoice reports, three different report types can be returned depending on the invoice source:

Parcels

  • PARCEL_DOMESTIC
  • PARCEL_INTERNATIONAL

Cargo international or Supply Base Logistics

  • AMPHORA_BCI
  • SYSPED
  • WINSPED_BCI

Cargo domestic, Sea or Home delivery

  • AMPHORA_DOMESTIC
  • AMPHORA_SEA
  • ALYSTRA

Endpoints

Base URL 
https://www.mybring.com/reports
Usage Method Endpoint
List available customers GET /api/generate
List available reports for a customer GET /api/generate/{customerId}
Generate a report GET /api/generate/{customerId}/{apiDefinitionId}
Check the status of a report GET /api/report/{reportId}/status
Get report GET /api/report/{reportId}

OpenAPI document

https://www.mybring.com/reports/v3/api-docs

List available customers

get 
                  https://www.mybring.com/reports/api/generate

List available customers for the provided API credentials. Also available with specified formats with endpoints:

  • /api/generate.json
  • /api/generate.xml

Request

header parameters

Accept
Description
Format to return response as. Either application/json or application/xml
Type
any
Example
Accept=application/json

Responses

200 Successfully fetched a list of available customers for provided API credentials

Schema

array of objects
id
string
name
string
reports
string <uri>
object
array wrapped
object
id
string
name
string
reports
string <uri>

Response examples

{
  "customers": [
    {
      "id": "PARCELS_NORWAY-00012341234",
      "name": "TEST CUSTOMER",
      "reports": "https://www.mybring.com/reports/api/generate/PARCELS_NORWAY-00012341234/"
    }
  ]
}

List available reports for a customer

get 
                  https://www.mybring.com/reports/api/generate/{customerId}

Each customer has a set of reports available. This endpoint lists all available reports for a given customer. Also available with specified formats with endpoints:

  • /api/generate/{customerId}.json
  • /api/generate/{customerId}.xml

Request

path parameters

customerId
Required
Description
A customer ID from the ’list of available customers’ call.
Type
string

header parameters

Accept
Description
Format to return response as. Either application/json or application/xml
Type
any
Example
Accept=application/json

Responses

200 Successfully got available reports

Schema

array of objects
description
string
id
string
name
string
array of objects
description
string
name
string
type
string
url
string <uri>
object
array wrapped
object
description
string
id
string
name
string
array wrapped
object
description
string
name
string
type
string
url
string <uri>

Response examples

{
  "reports": [
    {
      "description": "Overview of shipments you have sent pre-notification for.",
      "id": "PARCELS-PRE_NOTIFICATION_RECEIVED",
      "name": "Pre-notification provided",
      "parameters": [
        {
          "description": "Startdate of the report. Format: DD.MM.YYYY",
          "name": "fromDate",
          "type": "date"
        },
        {
          "description": "Enddate of the report. Format: DD.MM.YYYY",
          "name": "toDate",
          "type": "date"
        }
      ],
      "url": "https://api.bring.com.com/reports/api/generate/PARCELS_NORWAY-00012341234/PARCELS-PRE_NOTIFICATION_RECEIVED/"
    },
    {
      "description": "Invoiced shipping costs per service.",
      "id": "PARCELS-FREIGHT_STATISTICS_SUMMED",
      "name": "Freight costs, summarized by service",
      "parameters": [
        {
          "description": "INVOICED=Invoiced year, HANDED_IN=Handed in year",
          "name": "reporttype",
          "type": "string"
        },
        {
          "description": "Year for report",
          "name": "year",
          "type": "int"
        }
      ],
      "url": "https://api.bring.com.com/reports/api/generate/PARCELS_NORWAY-00012341234/PARCELS-FREIGHT_STATISTICS_SUMMED/"
    }
  ]
}

Generate a report

get 
                  https://www.mybring.com/reports/api/generate/{customerId}/{apiDefinitionId}

To generate a report do a GET to the supplied URL, and include the parameters described in the previous response. You need not invoke the two first steps for every report generation if customer id and report type are known.
This is asynchronous request. So the GET-call will return 202, telling the caller the that the request for a report is put on the queue. The URL to query to get the status for the request if provided as an HTTP header and also in the response.
Also available with specified formats with endpoints:

  • /api/generate/{customerId}/{apiDefinitionId}.json
  • /api/generate/{customerId}/{apiDefinitionId}.xml

Request

path parameters

customerId
Required
Description
A customer ID from the ’list of available customers’ call.
Type
string
apiDefinitionId
Required
Description
A report type ID from the ’list of available reports’ call.
Type
string

query parameters

queryParams
Required
Description
The different report types have different params. The params are documented in the list of available reports, for example fromDate and toDate.
Type
object

header parameters

Accept-Language
Description
A comma-separated list of language codes.
Type
any
Examples
English
Accept-Language=en
Norwegian
Accept-Language=no
Accept
Description
Format to return response as. Either application/json or application/xml
Type
any
Example
Accept=application/json

Responses

202 The URL to query to get the status for the request.

Schema

statusUrl
string <uri>
object
statusUrl
string <uri>

Response examples

{
  "statusUrl": "https://www.mybring.com/reports/api/report/db285042-6e8d-4563-94ca-eb1100706a73/status/"
}

Check the status of a report

get 
                  https://www.mybring.com/reports/api/report/{reportId}/status

Since the generation of reports may take several minutes, we supply a status address to check the status of the report generation. The status page will display NOT_DONE, until the report is ready to be downloaded. When the report is ready, URLs to download the report will be in the response
Also available with specified formats with endpoints:

  • /api/report/{reportId}/status.json
  • /api/report/{reportId}/status.xml

Request

path parameters

reportId
Required
Description
A report ID from a ‘generate a report’ call.
Type
string

header parameters

Accept
Description
Format to return response as. Either application/json or application/xml
Type
any
Example
Accept=application/json
Accept-Language
Description
A comma-separated list of language codes.
Type
any
Examples
English
Accept-Language=en
Norwegian
Accept-Language=no

Responses

200 Status of requested report, including URL to get the report if it is DONE. Response type based on Accept Header

Schema

status
string
xlsUrl
string
xmlUrl
string
object
status
string
xlsUrl
string
xmlUrl
string
404 Report not found

Schema

status
string
xlsUrl
string
xmlUrl
string
object
status
string
xlsUrl
string
xmlUrl
string

Response examples

{
  "status": "DONE",
  "xlsUrl": "https://www.mybring.com/reports/api/report/4cb1f149-19b9-4403-a871-17e1d142214f.xlsx",
  "xmlUrl": "https://www.mybring.com/reports/api/report/4cb1f149-19b9-4403-a871-17e1d142214f.xml"
}

Get report

get 
                  https://www.mybring.com/reports/api/report/{reportId}

Returns the generated report, file type determined by Accept Header.
Also available with specified formats with endpoints:

  • /api/report/{reportId}.json
  • /api/report/{reportId}.xml

Request

path parameters

reportId
Required
Description
A report ID from a ‘generate a report’ call.
Type
string

header parameters

Accept
Description
Format to return response as. Either application/json or application/xml
Type
any
Example
Accept=application/json
Accept-Language
Description
A comma-separated list of language codes.
Type
any
Examples
English
Accept-Language=en
Norwegian
Accept-Language=no

query parameters

compress
Description
Get the XML report as a compressed ZIP archive.
Type
boolean

Responses

200 The report as XML or Excel file
404 Report with specified id not found

Schema

StreamingResponseBody
object
StreamingResponseBody
object

Response examples

<Report xmlns="urn:bring.no/mybring/Report">
  <MetaData>
    <ReportName>Delivered to recipient</ReportName>
    <FinishedAt type="iso8601">2015-10-19T15:17:07.077+02:00</FinishedAt>
    <CustomerId>00012341234</CustomerId>
    <CustomerName>TEST CUSTOMER</CustomerName>
    <Interval>
      <Start type="iso8601">2015-01-01T00:00:00.000+01:00</Start>
      <End type="iso8601">2015-10-19T23:59:59.000+02:00</End>
    </Interval>
    <NumberOfRows>0</NumberOfRows>
  </MetaData>
  <Lines>
  </Lines>
</Report>
comments powered by Disqus