API v1.0 : Loans - www.pretnumerique.ca

List of loans

This service allows you to retrieve a complete list of your loans.

You can refine a search by specifying certain parameters. You will then get a partial list of results matching the specified criteria.

Depending on the number of loans on the list, it may be made out of multiple lists that will need to be retrieved in several requests. For more information, refer to the "Pagination" section on the "General Concepts" page in this guide.

get https://www.pretnumerique.ca/v1/loans.[xml | json]

Settings

Name	Required	Description
member_id	No	Patron identifier.
start_at	No	Start date of the loan list. Must be in extended ISO 8601 format. If no value is provided, the list starts with the first loan.
end_at	No	End date of the loan list. Must be in extended ISO 8601 format. If no value is provided, the list ends with the latest loan.

Successful response

{
   "loans":[
      {
         "id":"522f30dba5f317bf49000004",
         "created_at":"2014-01-01T12:00:00Z",
         "downloads":[
           "2014-01-01T13:00:00Z"
         ],
         "expires_at":"2014-01-21T12:00:00Z",
         "hold_expires_at":null,
         "shippings":[
            "2014-01-01T12:05:00Z"
         ],
         "member_id":"jsmith",
         "resource_id":"ENQC1234",
         "key":"9987654321234",
         "key_type":"isbn"
      }
    ]
}

<loan>
  <id>522f30dba5f317bf49000004</id>
  <created_at>2014-01-01T12:00:00Z</created_at>
  <downloads>
    <download>2014-01-01T13:00:00Z</download>
  </downloads/>
  <expires_at>2014-01-21T12:00:00Z</expires_at>
  <hold_expires_at/>
  <shippings>
    <shipping>2014-01-01T12:05:00Z</shipping>
  </shippings>
  <member_id>jsmith</member_id>
  <resource_id>ENQC1234</resource_id>
  <key>9987654321234</key>
  <key_type>isbn</key_type>
</loan>

idLoan identifier

created_atLoan creation date (ISO 8601)

downloadsDate on which the borrowed book was downloaded (ISO 8601)

expires_atLoan expiration date (ISO 8601)

hold_expires_atEmpty element (XML) or null (JSON)

shippingsDate on which the loan request confirmation email was sent (ISO 8601)

member_idPatron identifier

resource_idResource identifier

keyMedia identifier

key_typeIdentifier type (key), e.g. ISBN, EAN, custom.

Loan creation

This Web service allows you to create a loan for a patron and returns a download URL. It is also possible to send the patron an email containing the download link.

Please note that this version of the service requires a unique patron ID (member_id).

post https://www.pretnumerique.ca/v1/media/[medium_id]/loans.[xml | json]

Settings

Name	Required	Description
medium_id	Yes	Media unique ID
member_id	Yes	Patron identifier.
expires_at	No	Loan expiration date. The date should be encoded in the ISO 8601 Extended format. If no date is provided, the loan will end on the end date set by default by the organization.
notify	No	If `notify` is set to 1, an email with the download link will be sent to the borrower.
email	No	Borrower's email. This parameter is required if `notify` is set to 1.
return_url	No	URL that will be called with the POST method if the loan is returned early.

Successful response

Code	Description
201	Loan successfully created.
200	This loan already exists. Its end date remains the same as when it was created.

{
  "url": "https://www.pretnumerique.ca/loans/123",
  "expires_at": "2011-01-30T13:00:00"
}

<loan>
  <url>https://www.pretnumerique.ca/loans/123</url>
  <expires_at>2011-01-30T13:00:00</expires_at>
</loan>

urlLoan download link.

expires_atLoan expiration date.

Unsuccessful response

Code	Description
400	A required parameter is missing from the query or the syntax is incorrect.
403	The loan limit was reached by a patron.
404	The resource and/or its media does not exist.

{
  "errors": ["invalid_email","missing_member_id"]
}

<loan>
  <errors>
    <error>invalid_email</error>
    <error>missing_member_id</error>
  </errors>
</loan>

Code : 400

invalid_emailThe email address is invalid.

email_already_existsThe email address is already in use

missing_member_idThe patron identifier is missing.

Code : 403

loans_limit_reachedYou have reached the loan limit authorized by your library.

member_downloaded_daily_limit_reachedThis patron has reached the maximum number of loans per day.

member_downloaded_monthly_limit_reachedThis patron has reached the maximum number of loans per month.

no_loan_availableAll resources are currently on loan.

Code : 404

medium_not_foundThe media cannot be found.

Loan retrieval

The loan retrieval service allows patrons to retrieve the ACSM file required to download the loan.

The loan retrieval service can only be used after the loan was created using the loan creation service. When a loan is created, the Web service returns the appropriate retrieval URL.

get https://www.pretnumerique.ca/v1/loans/[loan_id]

Settings

Name	Required	Description
loan_id	Yes	Loan identifier.

Successful response

Code	Description
200	ACS4 file downloaded successfully

Details

URLLink.acsmFile allowing the patron to access the loan.

Unsuccessful response

Code	Description
403	The requested loan has expired.
404	The requested loan does not exist.

{
  "errors": ["loan_not_found"]
}

Code : 404

loan_not_foundLoan not found.

Code : 403

loan_expiredThe loan has expired.

loan_hold_expiredThis loan's availability period has expired.

member_downloaded_limit_reachedThis patron has reached the maximum number of loans.

member_downloaded_daily_limit_reachedThis patron has reached the maximum number of loans per day.

member_downloaded_monthly_limit_reachedThis patron has reached the maximum number of loans per month.