Credit 4.3

Endpoints

Zie Technical documentation voor het actuele overzicht.

Authorization

The following roles have access to this web service:

Role
ELO

Change history

Effective as of 08 Jul 2022 : organisationID is available as optional parameter for getPersonCredit and getPersonCreditRaw calls. Change scheduled for release to ACC mid april 2022.

The following items are changed since the previous version /wiki/spaces/EDUIX/pages/4325377:

getPersonCreditRaw operation added
Blocked state is added to state enum (only used by getPersonCreditRaw operation)
responseReferenceId is added to getSchoolCredit response

Operation overview

Operation authentication

All operations, except login, need either the loginHeader or the sessionIDHeader to authenticate. A sessionID can be obtained by performing the login operation beforehand.

Name

Type

Cardinality

Description

loginHeader

sessionIDHeader

loginHeader

sessionIDHeader

1...1

You can use either one of the variables

Source

 <urn:authHeader>
    <!--You have a CHOICE of the next 2 items at this level-->
    <urn:loginHeader>
       <!--Optional:-->
       <urn:username>?</urn:username>
       <!--Optional:-->
       <urn:password>?</urn:password>
    </urn:loginHeader>
    <urn:sessionIDHeader>
       <urn:sessionID>?</urn:sessionID>
    </urn:sessionIDHeader>
 </urn:authHeader>

Operations

Description

The login function provides you with a sessionID after execution. This sessionID can be used to execute consecutive operations with the sessionIDHeader.

Authentication

Name	Type	Cardinality	Description
loginHeader	loginHeader	1...1
Source <urn:loginHeader> <!--Optional:--> <urn:username>?</urn:username> <!--Optional:--> <urn:password>?</urn:password> </urn:loginHeader>

Request

Empty request

Response

Name	Type	Cardinality	Description
sessionID	string64	1...1	Unique identifier of the session

Error codes

Error code	Description
2	Authentication error

getPersonCredit

Description

The getPersonCredits can be used to retrieve information about earlier created EBF credits.
Note: only 1 credit per ean and only credits with a state of “NotYetUsable”, “NotActive” and “Active” are returned. Credits with a state of “Blocked” or “Expired” will not be returned. The state of a credit is defined by the publisher and may in some cases show discrepancies in combination with the “endDate” in the response: e.g. the credit may have a state of “Active”, while the “endDate” lies in the past. in this case the credit is returned by the call, even though it’s not usable.

The call can be used to show the available credits to the user.

Authentication

You have a choice to use either the loginHeader or the sessionIDHeader to authenticate. A sessionID can be obtained by performing the login operation beforehand. See operation authentication.

Request

The userID or eckID is used to retrieve credits of a specific person. Ean, start- & endDate can be used to filter for specific credits.

Name	Type	Cardinality	Description
userID eckID	string256 eckID	1...1 1...1	You must use either one or both of these variables.
startDate	date	0...1	The start date. Licenses which are active on this date are returned: e.g. licenses expired before this date are not returned. Default value is “today” when omitted.
endDate	date	0...1	The end date. Licenses should start before this date. Normally only startDate (today) is used.
ean	string160	0...1	Unique identifier of the product. Only credits with this ean are returned.
organisationID	organisationID	0...1	Unique identifier of an organisation, to fetch only credits for a specific school.
Source <urn:getPersonCreditRequest> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <urn:userID>?</urn:userID> <!--Optional:--> <urn:eckID>?</urn:eckID> <!--Optional:--> <urn:startDate>?</urn:startDate> <!--Optional:--> <urn:endDate>?</urn:endDate> <!--Optional:--> <urn:ean>?</urn:ean> <!--Optional:--> <urn:organisationID>?</urn:organisationID> </urn:getPersonCreditRequest>

Response

The response contains 0 to all credits found for a specific person. In case of an error, a Fault object is returned.

Name

Type

Cardinality

Description

personCreditInformation

0...n

Source

<urn:getPersonCreditResponse>
         <!--Zero or more repetitions:-->
         <urn:personCreditInformation>
            <urn:personCredit>
               <urn:ean>?</urn:ean>
               <urn:startDate>?</urn:startDate>
               <!--Optional:-->
               <urn:endDate>?</urn:endDate>
               <urn:state>?</urn:state>
            </urn:personCredit>
         </urn:personCreditInformation>
</urn:getPersonCreditResponse>

Error codes

Error code	Description
6	Missing required field(s)

getPersonCreditRaw

Description

The getPersonCreditsRaw can be used to retrieve unfiltered EBF credits data.
Note: because all data is returned, it cannot be used to show directly to the user: e.g. it can contain multiple credits with the same ean, expired or blocked credits, etc.

Authorization

The following roles have access to this operation:

Role
ELO

Authentication

You have a choice to use either the loginHeader or the sessionIDHeader to authenticate. A sessionID can be obtained by performing the login operation beforehand. See operation authentication.

Request

The userID or eckID is used to retrieve credits of a specific person. Ean, start- & endDate can be used to filter for specific credits.

Name	Type	Cardinality	Description
userID eckID	string256 eckID	1...1 1...1	You can use either one of these variables
startDate	date	0...1	The start date. Licenses which are active on this date are returned: e.g. licenses expired before this date are not returned. Default value is “today” when omitted.
endDate	date	0...1	The end date. Licenses should start before this date. Normally only startDate (today) is used.
ean	string160	0...1	Unique identifier of the product. The credit gives right of use for the indicated ean.
organisationID	organisationID	0...1	Unique identifier of an organisation, to fetch only credits for a specific school.
Source <urn:getPersonCreditRawRequest> <!--You have a CHOICE of the next 2 items at this level--> <!--Optional:--> <urn:userID>?</urn:userID> <!--Optional:--> <urn:eckID>?</urn:eckID> <!--Optional:--> <urn:startDate>?</urn:startDate> <!--Optional:--> <urn:endDate>?</urn:endDate> <!--Optional:--> <urn:ean>?</urn:ean> <!--Optional:--> <urn:organisationID>?</urn:organisationID> </urn:getPersonCreditRawRequest>

Response

The response contains 0 to all credits found for a specific person. In case of an error, a Fault object is returned.

Name

Type

Cardinality

Description

personCreditInformation

0...n

Source

<urn:getPersonCreditRawResponse>
     <!--Zero or more repetitions:-->
     <urn:personCreditInformation>
             <urn:personCredit>
             <urn:ean>?</urn:ean>
             <urn:startDate>?</urn:startDate>
             <!--Optional:-->
             <urn:endDate>?</urn:endDate>
             <urn:state>?</urn:state>
         </urn:personCredit>
     </urn:personCreditInformation>
</urn:getPersonCreditRawResponse>

Error codes

Error code	Description
6	Missing required field(s)

getSchoolCredit

Description

The getSchoolCredits can be used to retrieve information about earlier created IBF credits.

Authentication

You have a choice to use either the loginHeader or the sessionIDHeader to authenticate. A sessionID can be obtained by performing the login operation beforehand. See operation authentication.

Request

Credits of a specifc school are retrieved based on the organisationID. Ean, start- & endDate can be used to filter for specific credits.

Name	Type	Cardinality	Description
organisationID	organisationID	1...1	Unique identifier of the organisation
startDate	date	0...1	The start date. Licenses which are active on this date are returned: e.g. licenses expired before this date are not returned. Default value is “today” when omitted.
endDate	date	0...1	The end date. Licenses should start before this date. Normally only startDate (today) is used.
ean	string160	0...1	Unique identifier of the product. The credit gives right of use for the indicated ean.
Source <urn:getSchoolCreditRequest> <urn:organisationID>?</urn:organisationID> <!--Optional:--> <urn:ean>?</urn:ean> <!--Optional:--> <urn:startDate>?</urn:startDate> <!--Optional:--> <urn:endDate>?</urn:endDate> </urn:getSchoolCreditRequest>

Response

The response contains 0 to all credits found for a specific school. In case of an error, a Fault object is returned.

Name

Type

Cardinality

Description

schoolCreditInformation

0...n

Source

  <urn:getSchoolCreditResponse>
         <!--Zero or more repetitions:-->
         <urn:schoolCreditInformation>
            <urn:schoolCredit>
               <urn:organisationID>?</urn:organisationID>
               <urn:ean>?</urn:ean>
               <urn:startDate>?</urn:startDate>
               <!--Optional:-->
               <urn:endDate>?</urn:endDate>
            </urn:schoolCredit>
            <!--Optional:-->
            <urn:amountActive>?</urn:amountActive>
            <!--Optional:-->
            <urn:amountNotActive>?</urn:amountNotActive>
         </urn:schoolCreditInformation>
  </urn:getSchoolCreditResponse>

Error codes

Error code	Description
6	Missing required field(s)

getSummedSchoolCredit

Description

The getSummedSchoolCredits can be used to retrieve the total amount and the amount used for each school credit of a specific organisation.

Authentication

You have a choice to use either the loginHeader or the sessionIDHeader to authenticate. A sessionID can be obtained by performing the login operation beforehand. See operation authentication.

Request

Credits of a specifc school are retrieved based on the organisationID. Ean, start- & endDate can be used to filter for specific credits.

Name	Type	Cardinality	Description
organisationID	organisationID	1...1	Unique identifier of the organisation
startDate	date	0...1	The start date. Licenses which are active on this date are returned: e.g. licenses expired before this date are not returned. Default value is “today” when omitted.
endDate	date	0...1	The end date. Licenses should start before this date. Normally only startDate (today) is used.
ean	string160	0...1	Unique identifier of the product. The credit gives right of use for the indicated ean.
Source <urn:getSummedSchoolCreditRequest> <urn:organisationID>?</urn:organisationID> <!--Optional:--> <urn:ean>?</urn:ean> <!--Optional:--> <urn:startDate>?</urn:startDate> <!--Optional:--> <urn:endDate>?</urn:endDate> </urn:getSummedSchoolCreditRequest>

Response

The response contains 0 to all summed credits found for a specific school. In case of an error, a Fault object is returned.

Name

Type

Cardinality

Description

summedSchoolCredit

0...n

Source

   <urn:getSummedSchoolCreditResponse>
         <!--Zero or more repetitions:-->
         <urn:summedSchoolCredit>
            <urn:ean>?</urn:ean>
            <urn:amount>?</urn:amount>
            <!--Optional:-->
            <urn:used>?</urn:used>
         </urn:summedSchoolCredit>
   </urn:getSummedSchoolCreditResponse>

Error codes

Error code	Description
6	Missing required field(s)

Errors

General errors

Error code	Description
0	Unkown error
1	General error This occurs in for example: database errors or internal server errors.
2	Authentication error For instance when invalid credentials are provided.
3	Session expired The given sessionID is no longer active and has expired. Acquire a new sessionID to proceed.
4	Authorization error You do not have permission to use this operation.
5	Bad request Parsing error, for instance when invalid xml has been provided.

Specific errors

Specific errors are bound to the given input or request and depend on the operation you execute.

Error code	Description
6	Missing required field(s) or other validation error One or more fields do not meet the XSD constraints.

Complex types

loginHeader

Name

Type

Cardinality

Description

username

string100

0...1

An identification used by a person to login.

password

string64

0...1

A secret word or phrase used for authentication.

Source

 <xs:complexType name="loginHeader">
 	<xs:sequence>
    	<xs:element name="username" type="types:string100" minOccurs="0" maxOccurs="1"/>
    	<xs:element name="password" type="types:string64" minOccurs="0" maxOccurs="1"/>
 	</xs:sequence>
</xs:complexType>

sessionIDHeader

Name	Type	Cardinality	Description
sessionID	string64	1...1	Unique token which can be acquired by executing the login operation.
Source <xs:sequence> <xs:element name="sessionID" type="types:string64" minOccurs="1" maxOccurs="1"/> </xs:sequence>

personCredit

Name	Type	Cardinality	Description
ean	string160	1...1	Unique identifier of the product. The credit gives right of use for the indicated ean.
startDate	date	1...1	The start date. Until the start date the credit cannot be used.
endDate	date	0...1	The end date. Until the end date the credit can be used.
state	state	1...1	The current state of the credit.
Source <xs:complexType name="personCredit"> <xs:sequence> <xs:element name="ean" type="types:string160" minOccurs="1" maxOccurs="1"/> <xs:element name="startDate" type="types:date" minOccurs="1" maxOccurs="1"/> <xs:element name="endDate" type="types:date" minOccurs="0" maxOccurs="1"/> <xs:element name="state" type="types:state" minOccurs="1" maxOccurs="1"/> </xs:sequence> </xs:complexType>

personCreditInformation

Name	Type	Cardinality	Description
personCredit	personCredit	1...1	Specific person credit details.
Source <xs:complexType name="personCreditInformation"> <xs:sequence> <xs:element name="personCredit" type="types:personCredit" minOccurs="1" maxOccurs="1"/> </xs:sequence> </xs:complexType>

schoolCredit

Name	Type	Cardinality	Description
organisationID	organisationID	1...1	Unique identifier of the school to which this credit is connected.
ean	string160	1...1	Unique identifier of the product. The credit gives right of use for the indicated ean.
startDate	date	1...1	The start date. Until the start date the credit cannot be used.
endDate	date	0...1	The end date. Until the end date the credit can be used.
Source <xs:complexType name="schoolCredit"> <xs:sequence> <xs:element name="organisationID" type="types:organisationID" minOccurs="1" maxOccurs="1"/> <xs:element name="ean" type="types:string160" minOccurs="1" maxOccurs="1"/> <xs:element name="startDate" type="types:date" minOccurs="1" maxOccurs="1"/> <xs:element name="endDate" type="types:date" minOccurs="0" maxOccurs="1"/> </xs:sequence> </xs:complexType>

schoolCreditInformation

Name	Type	Cardinality	Description
schoolCredit	schoolCredit	1...1	Specific school credit details.
amountActive	integer	0...1	Amount of credits that have been activated by the end-user.
amountNotActive	integer	0...1	Amount of credits that have not been activated by the end-user.
responseReferenceId	string160	0...1	The identifier returned when specified (so specification and license can be mapped).
Source <xs:complexType name="schoolCreditInformation"> <xs:sequence> <xs:element name="schoolCredit" type="types:schoolCredit" minOccurs="1" maxOccurs="1"/> <xs:element name="amountActive" type="types:integer" minOccurs="0" maxOccurs="1"/> <xs:element name="amountNotActive" type="types:integer" minOccurs="0" maxOccurs="1"/> <xs:element name="responseReferenceId" type="types:string160" minOccurs="0" maxOccurs="1"/> </xs:sequence> </xs:complexType>

summedSchoolCredit

Name	Type	Cardinality	Description
ean	string160	1...1	Unique identifier of the product. The credit gives right of use for the indicated ean.
amount	amount	1...1	Total of credits.
used	amount	0...1	Total of credits used.
Source <xs:complexType name="summedSchoolCredit"> <xs:sequence> <xs:element name="ean" type="types:string160" minOccurs="1" maxOccurs="1"/> <xs:element name="amount" type="types:amount" minOccurs="1" maxOccurs="1"/> <xs:element name="used" type="types:amount" minOccurs="0" maxOccurs="1"/> </xs:sequence> </xs:complexType>

Fault

Name

Type

Cardinality

Description

code

integer

1...1

Code to identify the fault type.

message

string

1...1

Specific message which describes the fault.

Source

<xs:element name="Fault">
	<xs:complexType>
	  	<xs:sequence>
			<xs:element name="code" type="types:integer" minOccurs="1" maxOccurs="1"/>
			<xs:element name="message" type="types:string" minOccurs="1" maxOccurs="1"/>
		</xs:sequence>
	</xs:complexType>
</xs:element>

Simple types

Name	Type	Possible values / format	Description
string64	String	Max length: 64 characters	String limited by a number of maximum allowed characters.
string100	String	Max length: 100 characters	String limited by a number of maximum allowed characters.
string256	String	Max length: 256 characters	String limited by a number of maximum allowed characters.
organisationID	String	Min length: 1, Max length: 160	Unique identifier of a school, e.g. “digiDeliveryId”
amount	Integer	Min length: 1	Amount is a positive number.
state	Enum	Possible values: NotYetUsable NotActive Active Expired Blocked	State of a license. Values “Expired” and “Blocked” are only available at getPersonCreditRaw operation.
eckID	String	Min length: 128, Max length: 256	Unique identification of the end user by the ECK standard.

Appendix

Terms

Term	Description
EBF	External book fund
IBF	Internal book fund
ECK	Educatieve contentketen. More information on: https://www.eck-id.nl/
ECK ID	Unique identifier of a person according to the ECK standard
ELO	Elektronische leeromgeving (electronic learning environment)
Specification	Specification is the proces of sending credits from Edu-iX to the publisher. Each specification contains information about the end user and the credit itself. After the specification is completed the credit is available for user by the end user.
Prematch	Prematch is the process of connecting the unique identifier of the end user, available in the ELO, to order data (personal details and credit information) in Edu-iX.