Please note the following:
Single point of reporting. Bokbasen will distribute reports to all relevant product owners (publisher) to be used for invoicing the subscription service and calculation of royalty to authors, etc.
The report should only include reads above the threshold (i.e 10%), as agreed upon with the publisher.
All data within a reporting period must be delivered simultaneously.
If a product changes product owner within a reporting period, the product must be reported twice (one time on each owner)
Frequency as agreed upon with the publisher, but should not include partial months, making a month the shortest reporting period possible.
| Info |
|---|
New Authentication & URLs introduced Q2 2024 |
...
URL
...
https://api.bokbasen.io/reporting/loan/tibi/v1
...
Method
...
POST
...
Request headers
...
Authorization
...
Required
...
The token acquired from the Authentication Service
Audience: https://api.bokbasen.io/reporting/
...
JSON attributes
(for each item in items)
...
isbn
...
Required
...
ISBN of the book you are reporting numbers for, mandatory
...
periodFrom
...
Required
...
Start of the reporting period on the format yyyy-MM
...
periodTo
...
Required
...
End of the reporting period on the format yyyy-MM
...
productOwnerId
...
Required
...
Numeric ID of the publisher who owned the rights to the book during the reporting period
...
productOwnerName
...
Optional
...
Name of the publisher who owned the rights to the book during the reporting period
...
cost.totalCost
...
Required
...
The total cost that will be billed for this ISBN
...
cost.paidCost
...
Optional
...
Can be sent in addition to cost.totalCost if you separate between trial and subscription
...
cost.trialCost
...
consumption.total
...
Required
...
The total amount of books read
...
consumption.paid
...
Optional
...
Can be sent in addition to consumption.total if you separate between trial and subscription
...
consumption.trial
...
price.ppu
...
Optional
...
The price per book read (price per unit)
...
price.paidPpu
...
Optional
...
Can be sent in addition to price.ppu if you separate between trial and subscription
...
price.trialPpu
...
currency
...
Optional
...
The currency of the cost/ppu-fields
...
market
...
Optional
...
The market you are reporting for
...
Response headers
...
Response body
...
Empty on success
...
Returns
...
204
...
No success
...
40x
...
On errors
...
413
| Status | ||||
|---|---|---|---|---|
|
...
If payload is too big (6MB limit)
Example (curl)
| Code Block |
|---|
curl -v -X POST \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" \
--data-binary "@sales_data.json" \
https://api.bokbasen.io/reporting/streaming/v1 |
Example content of sales_data.json
| Code Block | ||
|---|---|---|
| ||
{
items: [
{
"isbn": "9782123456789",
"period": "2021-05",
"productOwnerId": "9999",
"productOwnerName": "Example name",
"cost": {
"totalCost": "600",
"paidCost": "450",
"trialCost": "150"
},
"consumption": {
"total": "30",
"paid": "15",
"trial": "15"
},
"price": {
"ppu": "20",
"paidPpu": "30",
"trialPpu": "10"
},
"currency": "NOK",
"market": "NO"
}
], ...
} |
| Panel | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
For information about authentication see Authentication Service |
| Info |
|---|
The payload max size is 10MB. If you have reports larger than this level the report must be spilt up. |
| Confluence open api | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
openapi: 3.0.3 info: title: Reporting API Specification description: Reporting API Specification. All operations requires Bearer token from login-process. For more information, please visit version: 1.0.0 servers: - url: 'https://api.bokbasen.jira.com/wiki/spaces/api/pages/2994962433/Authentication+Service+upcomingio/reporting' version: 1.0.0 description: servers:Production - url: 'https://api.stage.bokbasen.io/reporting' description: Stage paths: /loan/tibi/v1: post: summary: POST TIBI loan report operationId: postTibiLoanReport requestBody: content: application/json: schema: $ref: '#/components/schemas/TibiLoanReport' required: true responses: 201: description: Successfully registered streaming report content: application/json: schema: $ref: '#/components/schemas/LoanReportResponse' 400: $ref: '#/components/responses/BadRequest' 413: description: Payload is to large. 10 MB limit. components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT schemas: LoanReportResponse: type: object required: - id properties: id: type: string format: uuid description: The report ID. TibiLoanReport: type: object required: - reportInfo - items properties: reportInfo: type: object required: - period properties: id: type: string format: uuid description: Report id in UUID format. Can be used to update a reports content. Must exist if used. example: "feeada9c-af12-4733-86fe-4b60fa70b669" period: type: string format: year-month description: The period the report is for in the YYYY-mm format example: 2024-05 items: type: array x-field-extra-annotation: "@lombok.Builder.Default" items: $ref: '#/components/schemas/TibiItem' TibiItem: type: object required: - ean - count - libraryUnit - adaptedVersion properties: ean: type: string example: "9782123456789" description: EAN of the original book you are reporting numbers for count: type: integer example: "55" description: The number of loans of the ean in the given period libraryUnit: type: string description: The library where the loan happened example: "NLB" adaptedVersion: $ref: '#/components/schemas/TibiAdaptedVersionInfo' TibiAdaptedVersionInfo: type: object required: - format - availableDate - audioContent - textContent - brailleContent - speechSynthesis properties: reference: type: string description: Internal reference to product. Eg. booknumber. example: "686512" format: type: string description: The format of the edition example: "DAISY2.0" availableDate: type: string format: date description: The date the adapted version was ready for loan example: "2024-09-01" ean: type: string description: The ean of the adapted book version if any example: "9876543212345" audioContent: type: boolean description: True if the adapted version contains audio content example: true textContent: type: boolean description: True if the adapted version contains text content example: true brailleContent: type: boolean description: True if the adapted version contains braille content example: true speechSynthesis: type: boolean description: True if the adapted version contains speech synthesis example: true ProblemDetail: title: An RFC 9457 problem object type: object properties: type: type: string format: uri-reference title: type: string status: type: integer description: HTTP status code minimum: 100 maximum: 599 detail: type: string description: A human-readable explanation specific to this occurrence of the problem. responses: BadRequest: description: Bad Request content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' security: - bearerAuth: [ ] |