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.
...
| Panel | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
For information about authentication see Authentication Service |
...
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"
}
], ...
} |
| 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 https://bokbasen.jira.com/wiki/spaces/api/pages/2994962433/Authentication+Service+upcoming
version: 1.0.0
servers:
- url: 'https://api.bokbasen.io/reporting'
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: [ ] |