Content
Base URL
All following endpoints operates over the URL of your store: https://your-store.com/
example: https://alephdigital.publica.la/
| Endpoints |
|---|
| upload |
| retrieve |
| update |
| delete |
Headers
{
"Content-Type": "application/json",
"Accept": "application/json",
"X-User-Token": api_token,
}
info
Make sure you generated the api_token on your store. More info HERE
Upload
POST /integration-api/v1/dashboard/issues
Example: https://your-store.com/integration-api/v1/dashboard/issues
Body Parameters
| Parameter | Type | Description |
|---|---|---|
| publication_date | string | Required. Format: YYYY-MM-DD 2018-07-27. |
| name | string | Required |
| description | string | |
| extension | string | |
| file_url | string, url | Required. Up to 256mb. The file must be hosted in a public repository (*). |
| external_id | string | Required |
| free | boolean | |
| bisac | list of objects | Bisac Code used as genre for of the title. You may find all available values at BISG Website |
| collection | list of strings | |
| author | list of strings | |
| country | list of strings | |
| category | list of strings | |
| publisher | list of strings | |
| keyword | list of strings | |
| prices | object | Supported values: USD,ARS,EUR,MXN,COP,PEN,CLP,AUD,UYU,BOB,PYG,BRL,INR,GTQ,HNL. |
{
"publication_date": "2020-06-01",
"name": "The Computing Machine",
"description": "The description of the publication...",
"free": 0,
"bisac": [{ "code": "ANT018000" }],
"extension": "pdf",
"file_url": "",
"collection": ["The classics"],
"author": ["Grace Hopper"],
"country": ["Finland"],
"category": ["Hardware meets software"],
"publisher": ["publica.la"],
"keyword": ["API", "book"],
"prices": {
"USD": 2.00,
"ARS": 0.02,
"EUR": 2.35,
"MXN": 0.10,
"COP": 0.00,
"PEN": 0.51,
"CLP": 0.00,
"AUD": 1.47,
"UYU": 0.05,
"BOB": 0.29,
"PYG": 0.00,
"BRL": 0.38,
"INR": 0.03,
"GTQ": 0.26,
"HNL": 0.08,
},
}
Responses
| Code | Description |
|---|---|
| 201 | Object Created |
| 422 | Validation error, the reason of the error will be described in the response body |
| 401 | Unauthenticated |
(*) You can host your files in Google Drive and use the URL where it is hosted. You must convert that URL to be a direct link to download the file, for that you can use this Google tool to get the URL that you can then use in the file_url. Once the file is uploaded, remember to change the permissions or delete it from your Google Drive for safety.
Retrieve
GET /integration-api/v1/dashboard/issues
In this case we will obtain all the existing publications in the store.
tip
Using query parameter you can filter by converting or deferred, name, external_id and id
Example 1: https://your-store.com/integration-api/v1/dashboard/issues/?query=converting
Example 2: https://your-store.com/integration-api/v1/dashboard/issues/?query=deferred
Example 3: https://your-store.com/integration-api/v1/dashboard/issues/?query=name
Example 4: https://your-store.com/integration-api/v1/dashboard/issues/?query=468166
Response
| Code | Description |
|---|---|
| 200 | Object returned |
| 404 | Object not found |
| 401 | Unauthenticated |
Response Example
Example
{
"CODE": "success",
"data": {
"paginator": {
"current_page": 1,
"data": [
{
"id": 468166,
"external_id": "9781496822482",
"version": 1,
"marketplace": 1,
"license": {
"ppu": false,
"retail": true
},
"discount": 50,
"file_type": "epub",
"lang": "en",
"user_id": 47635,
"medusa_automation_id": null,
"name": "Conversations with Donald Hall",
"slug": "conversations-with-donald-hall",
"conversion_status": "done",
"conversion_settings": {
"PdfSplitInPages": {
"pagesPerGroup": null,
"concurrentWorkerRequests": null
}
},
"conversion_details": null,
"published_at": {
"timestamp": 1616122800,
"date": "2021-03-19 00:00:00",
"timezone": "America/Argentina/Buenos_Aires"
},
"bucket_domain": "storage.publica.la",
"cover_image_path": "https://your-store.com/publicala/issues/2021/03/ZotqenpMS797S5wS/41a3c9c7-5f9f-4db5-bb6c-714865d2fdbd_cover.jpg",
"number_of_pages": null,
"notifies_users": null,
"notification_text": null,
"notified_users_at": null,
"medusa_automation_status": null,
"created_at": "2021-03-06 06:00:51",
"ti_id": 531184,
"ti_tenant_id": 627,
"ti_issue_id": 468166,
"ti_license": "retail",
"ti_withdrawn": 0,
"ti_free": 0,
"ti_free_to": null,
"ti_require_login": null,
"ti_preview": 0,
"ti_require_login_for_preview": 0,
"ti_private_material": null,
"ti_published_at": "2021-03-19 03:00:00",
"ti_created_at": "2021-03-24 13:46:37",
"ti_updated_at": "2021-03-24 16:10:15",
"ti_deleted_at": null,
"cover": "https://your-store.com/publicala/issues/2021/03/ZotqenpMS797S5wS/41a3c9c7-5f9f-4db5-bb6c-714865d2fdbd_cover.jpg",
"url": "https://your-store.com/reader/conversations-with-donald-hall",
"share_url": "https://your-store.com/library/publication/conversations-with-donald-hall",
"public_file_url": "https://your-store.com/api/v1/dashboard/issues/468166/temp-public-url",
"current_session_limit": 0,
"can_be_removed_from_inventory": true,
"notes_count": 0,
"description": "<i>Conversations with Donald Hall</i> offers a unique glimp...",
"description_with_html": "<i>Conversations with Donald Hall</i> offers a unique glimp...",
"is_owned_by_current_tenant": true,
"free": false,
"free_to": null,
"prices": {
"USD": 25
},
"preview": true,
"private_material": null,
"publication_date": {
"timestamp": 1616122800,
"date": "2021-03-19 00:00:00",
"timezone": "America/Argentina/Buenos_Aires"
},
"require_login": null,
"require_login_for_preview": 0,
"conversion_status_progress": null,
"published_at_utc": "2021-03-19 03:00:00",
"price_morph": [
{
"tenant_id": 1,
"id": 461064,
"priceable_type": "issue",
"priceable_id": 468166,
"type": "single",
"country_code": null,
"currency_id": "USD",
"amount_in_cents": 2500,
"created_at": "2021-03-06 06:00:52",
"updated_at": "2021-03-06 06:00:52",
"deleted_at": null
}
],
"sessions": null,
"issue_description": {
"issue_id": 468166,
"description": "<i>Conversations with Donald Hall</i> offers a unique glimp..."
}
},
{
...
},
],
"first_page_url": "https://your-store.com/integration-api/v1/dashboard/issues?page=1",
"from": 1,
"last_page": 6,
"last_page_url": "https://your-store.com/integration-api/v1/dashboard/issues?page=6",
"links": [
{
"url": null,
"label": "« Previous",
"active": false
},
{
"url": "https://your-store.com/integration-api/v1/dashboard/issues?page=1",
"label": 1,
"active": true
},
{
"url": "https://your-store.com/integration-api/v1/dashboard/issues?page=2",
"label": 2,
"active": false
},
{
"url": "https://your-store.com/integration-api/v1/dashboard/issues?page=3",
"label": 3,
"active": false
},
{
"url": "https://your-store.com/integration-api/v1/dashboard/issues?page=4",
"label": 4,
"active": false
},
{
"url": "https://your-store.com/integration-api/v1/dashboard/issues?page=5",
"label": 5,
"active": false
},
{
"url": "https://your-store.com/integration-api/v1/dashboard/issues?page=6",
"label": 6,
"active": false
},
{
"url": "https://your-store.com/integration-api/v1/dashboard/issues?page=2",
"label": "Next »",
"active": false
}
],
"next_page_url": "https://your-store.com/integration-api/v1/dashboard/issues?page=2",
"path": "https://your-store.com/integration-api/v1/dashboard/issues",
"per_page": 15,
"prev_page_url": null,
"to": 15,
"total": 82
},
"reached_issues_limit": false,
"reached_free_issues_limit": false
}
}
Update
PUT /integration-api/v1/dashboard/issues/{issue_id}
Example : https://your-store.com/integration-api/v1/dashboard/issues/468166
info
The issue_id can be obtained with the GET method
Parameters
| Parameter | Type | Description |
|---|---|---|
| publication_date | string | Required. Format: Y-m-d 2018-07-27. |
| name | string | Required |
| description | string | |
| external_id | string | Required |
| free | boolean | |
| bisac | list of objects | BISAC CODE used as genre for the title. You may find all available values at BISG Website |
| collection | list of strings | |
| author | list of strings | |
| country | list of strings | |
| category | list of strings | |
| publisher | list of strings | |
| keyword | list of strings | |
| prices | object | Supported values: USD,ARS,EUR,MXN,COP,PEN,CLP,AUD,UYU,BOB,PYG,BRL,INR,GTQ,HNL. |
::: tip When updating a publication, make sure to send all the desired final taxonomies and terms. If a publication already has a term in a specific taxonomy and you just want to add a second one, you still need to send both. :::
{
"publication_date": "2020-06-01",
"name": "The Computing Machine",
"description": "The description of the publication...",
"free": 0,
"bisac": [{ "code": "ANT018000" }],
"collection": ["The classics"],
"author": ["Grace Hopper", "Alan Turing"],
"country": ["Finland"],
"category": ["Hardware meets software"],
"publisher": ["publica.la"],
"keyword": ["API", "book"],
"prices": {
"USD": 2.00,
"ARS": 0.02,
"EUR": 2.35,
"MXN": 0.10,
"COP": 0.00,
"PEN": 0.51,
"CLP": 0.00,
"AUD": 1.47,
"UYU": 0.05,
"BOB": 0.29,
"PYG": 0.00,
"BRL": 0.38,
"INR": 0.03,
"GTQ": 0.26,
"HNL": 0.08,
},
}
warning
The file and file type cannot be updated. If this action is necessary, you can replace the file with another file of the same type from the store publication panel.
Response
| Code | Description |
|---|---|
| 204 | Object Updated |
| 422 | Validation error, the reason of the error will be described in the response body |
| 401 | Unauthenticated |
Delete
DELETE /integration-api/v1/dashboard/issues/{issue_id}
DELETE /integration-api/v1/dashboard/issues/{external_id}
Example 1: https://your-store.com/integration-api/v1/dashboard/issues/468166
Example 2: https://your-store.com/integration-api/v1/dashboard/issues/9781496822482
Responses
| Code | Description |
|---|---|
| 200 | Success |
| 404 | Object not found |
| 401 | Unauthenticated |