Skip to main content

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#

keyvalue
Content-typeapplication/json
Acceptapplication/json

Upload#

POST /integration-api/v1/dashboard/issues/

Parameters#

Parametertypedefaultnotes
namestring
publication_datestringformat: Y-m-d 2018-07-27.
extensionstringAccept only 'mpga', 'mp3', 'pdf' or 'epub'
file_urlurl, stringEPUB or PDF, up to 256mb
external_idstringnullRecommended, since it's the field you'll need to use for any other operation or when using other APIs like Reading Permissions.
freebooleanfalseOptional

If you need to set taxonomies terms, you need to use the taxonomy slug as the key name and the values in a plain array list. For the available taxonomies slugs check the code example.

Responses#

CodeDescriptio
201Object Created
422Validation error, the reason of the error will be described in the response

Snippet#

// Example in PHP using Laravel's Http
use Illuminate\Support\Facades\Http;
$response = Http::post('https://your-store.com/integration-api/v1/dashboard/issues/?user_token=api-77d0b904-3b46-4e1a-8fde-2596375270b8', [
'publication_date' => '2021-03-17',
'name' => 'The Computing Machine',
'description' => 'The description of the publication...',
'free' => 0,
'extension' => 'pdf',
'file_url' =>
'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf',
// optional, use it if you need to set taxonomies terms and use only the specific taxonomies you want to set
'collection' => ['The classics'],
'author' => ['Grace Hopper', 'Alan Turing'],
'country' => ['Finland'],
'category' => ['Hardware meets software'],
'publisher' => ['publica.la'],
'keyword' => ['API', 'book'],
]);
dd($response->status(), $response->body());

Retrieve#

GET /integration-api/v1/dashboard/issues

Parameters#

optiontypeendpoint
issue_idintegerhttps://your-store.com/integration-api/v1/dashboard/issues/{issue_id}
like_namestring, query parameterhttps://your-store.com/integration-api/v1/dashboard/issues/?like_name=The%20Computing%20Machine

Response#

CodeDescription
200Object returned
404Object not found
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": "&laquo; 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 &raquo;",
"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}

Parameters#

parametertypenotes
namestringrequired
publication_datestringrequired. Format: Y-m-d 2018-07-27.
descriptionnullable, string, max:13000
private_materialnullable, string, max:5000
freenullable, boolean
free_tostringFormat: Y-m-d 2018-07-27
require_loginnullableboolean
external_idnullable, string, uniqueRecommended, since it's the field you'll need to use for any other operation or when using other APIs like Reading Permissions.

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. Ex. If you need to add a new author to the list 'Grace Hopper', 'Alan Turing', you will send:

// to add
'author': ['Grace Hopper', 'Alan Turing', 'New Author'],

If you need remove 'Grace Hopper', you will just send the one that stays:

// to remove
'author': ['Alan Turing'],

Response#

CodeDesctiption
204Object Updated
422Validation error, the reason of the error will be described in the response

Snippet#

// Example in PHP using Laravel's Http
use Illuminate\Support\Facades\Http;
$response = Http::put('https://your-store.com/integration-api/v1/dashboard/issues/{issue_id}?user_token=api-77d0b904-3b46-4e1a-8fde-2596375270b8', [
'publication_date' => '2021-03-17',
'name' => 'The Computing Machine two',
'description' => 'The description of the publication...',
'private_material' => null,
'free' => 0,
'free_to' => '2021-04-11',
'require_login' => 1,
'external_id' => 12345098
]);
dd($response->status(), $response->body());

Delete#

DELETE /integration-api/v1/dashboard/issues/{id}

Parameters#

optiontype
issue_idinteger
external_idinteger

Responses#

CodeDescription
200Object deleted
404Object not found