View Source

Documentation

The Credit 5.1 web service main function is to provide the ability to create and update credits. Either EBF or IBF can be created through this web service.

Endpoints

Environment	URL	WSDL
Production	https://distributor.edu-ix.nl/soap/5.1/credit	https://distributor.edu-ix.nl/soap/5.1/credit/wsdl
Acceptance	https://acc-distributor.edu-ix.nl/soap/5.1/credit	https://acc-distributor.edu-ix.nl/soap/5.1/credit/wsdl
Test	https://test-distributor.edu-ix.nl/soap/5.1/credit	https://test-distributor.edu-ix.nl/soap/5.1/credit/wsdl

WSDL

Authorization

The following roles have access to this web service:

Role
Distributor

Operation overview

login
getPersonCredits
uploadPersonCredits
blockCredits
unblockCredits
getSchoolCredits
uploadSchoolCredits
returnCredits

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

login

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
loginHeader	loginHeader	0...n

Request

Empty request

Response

Name	Type	Cardinality
sessionID	string64	1...1

Error codes

Error code	Description
2	Authentication error
4	Authorization error

getPersonCredits

Description

The getPersonCredits can be used to retrieve information about earlier created EBF 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

The distributorCreditID element provides the ability to request up to a maximum of 100 different credits at once.

Name

Type

Cardinality

Description

distributorCreditID

string160

1...100

At least one of these fields must be filled.

distributorPersonID

string256

1…1

eckID

eckID

1…1

userID

string256

1…1

ean

string160

0…1

Source

<urn:getPersonCreditsRequest>
    <!--You have a CHOICE of the next 4 items at this level-->
    <!--1 to 100 repetitions:-->
    <urn:distributorCreditID>?</urn:distributorCreditID>   
    <urn:distributorPersonID>?</urn:distributorPersonID>
    <urn:eckID>?</urn:eckID>
    <urn:userID>?</urn:userID>
    <!--Optional:-->
    <urn:ean>?</urn:ean>
 </urn:getPersonCreditsRequest>

Response

In case of a request by multiple distributorCreditID's the response can be partially built up when records are not found or available.

Specification

The element specification is only provided when the credits has been specified.

Error

The element error is only returned on errors within the specification process. It may contain errors directly from the publisher or transport errors.

Name	Type	Cardinality
personCredit	personCredit	0...n

Error codes

Error code	Description
4	Authorization error
6	Missing required field(s)

getSchoolCredits

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

The distributorCreditID element provides the ability to request up to a maximum of 100 different credits at once.

Name

Type

Cardinality

Description

distributorCreditID

string160

1...100

At least one of these fields must be filled.

organisationID

organisationID

1…1

ean

string160

0…1

Source

<urn:getSchoolCreditsRequest>
    <!--You have a CHOICE of the next 2 items at this level-->
    <!--1 to 100 repetitions:-->
    <urn:distributorCreditID>?</urn:distributorCreditID>
    <urn:organisationID>?</urn:organisationID>
    <!--Optional:-->
    <urn:ean>?</urn:ean>
 </urn:getSchoolCreditsRequest>

Response

In case of a request by multiple distributorCreditID's the response can be partially built up when records are not found or available.

Name	Type	Cardinality
schoolCredit	schoolCredit	0...n

Error codes

Error code	Description
4	Authorization error
6	Missing required field(s)

uploadPersonCredits

Description

With the uploadPersonCredits operation you have the ability to create one or more EBF credits at once.

Idempotent

The idempotent characteristic of this operations ensures calls can be made multiple times without errors. On certain conditions you have the ability to edit fields on existing credits. The following fields can be updated:

Field	Condition
block	Can only be updated before the credit has been specified
eckID	Can only be updated before the credit has been specified and both eckID and userID are empty.
userID	Can only be updated before the credit has been specified and both eckID and userID are empty.

eckID / userID

If eckID or the userID is provided on creation or on update of the credit, the credit will be immediately specified.

Creating credits without existing persons

Unlike earlier versions of the credit webservice it's possible to create credits without an available person record. Previous versions required you to create a person through the profile webservice beforehand.

This scenario is useful when the school, or students of the school, order with the ECK ID. The information about the person is no longer needed for the prematch process and it's therefore possible to omit the creation of a person record.

The specification proces within Edu-iX requires at least one identifier on which it can specify to publishers. This identifier can either be obtained by the prematch proces (executed by the ELO) or provided through this operation. Although it doesn't enforce specifying the ECK ID or userID, at least one of both fields must be provided to ensure the working of the specification proces.

Adding person details later

Once a credit is created it's still possible to add personal details. For more details on how to update a person record take a look at the profile 5.x instructions.

EAN

The EAN indicated in the request does not have to exist in Edu-iX to be valid. Credits indicated with a non existing EAN won't be specified until the related product is created. Adding products is done automatically between Edu-iX and publishers.

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

Name

Type

Cardinality

personCredit

uploadPersonCredit

1...100

Source

<urn:uploadPersonCreditsRequest>
    <!--1 to 100 repetitions:-->
    <urn:personCredit>
       <urn:distributorCreditID>?</urn:distributorCreditID>
       <urn:distributorPersonID>?</urn:distributorPersonID>
       <urn:organisationID>?</urn:organisationID>
       <urn:ean>?</urn:ean>
       <urn:startDate>?</urn:startDate>
       <!--Optional:-->
       <urn:block>?</urn:block>
       <!--Optional:-->
       <urn:eckID>?</urn:eckID>
       <!--Optional:-->
       <urn:userID>?</urn:userID>
    </urn:personCredit>
 </urn:uploadPersonCreditsRequest>

Response

Empty response

Error codes

In case of errors on a single credit or on multiple credits, the response contains a FaultPerCredit complex-type for each occurred error. Credits without error are processed and stored in Edu-iX.

Error code	Description
4	Authorization error
6	Missing required field(s)
8	Record cannot be changed
9	Process validation error

uploadSchoolCredits

Description

With the uploadSchoolCredits operation you have the ability to create one or more IBF credits at once.

Idempotent

The idempotent characteristic of this operations ensures calls can be made multiple times without errors.

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

Name

Type

Cardinality

schoolCredit

uploadSchoolCredit

1...100

Source

<urn:uploadSchoolCreditsRequest>
    <!--1 to 100 repetitions:-->
    <urn:schoolCredit>
       <urn:distributorCreditID>?</urn:distributorCreditID>
       <urn:organisationID>?</urn:organisationID>
       <urn:ean>?</urn:ean>
       <urn:startDate>?</urn:startDate>
       <urn:amount>?</urn:amount>
    </urn:schoolCredit>
 </urn:uploadSchoolCreditsRequest>

Response

Empty response

Error codes

In case of errors on a single credit or on multiple credits, the response contains a FaultPerCredit complex-type for each occurred error. Credits without error are processed and stored in Edu-iX.

Error code	Description
4	Authorization error
6	Missing required field(s)
8	Record cannot be changed
9	Process validation error

returnCredits

Description

A returnCredit cancels the indicated credit for further use by the end 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

Name

Type

Cardinality

returnCredit

1...100

Source

<urn:returnCreditsRequest>
    <!--1 to 100 repetitions:-->
    <urn:returnCredit>
       <urn:distributorCreditID>?</urn:distributorCreditID>
       <urn:amount>?</urn:amount>
       <urn:distributorReturnCreditID>?</urn:distributorReturnCreditID>
    </urn:returnCredit>
 </urn:returnCreditsRequest>

Response

Empty response

Error codes

In case of errors on a single credit or on multiple credits, the response contains a FaultPerCredit complex-type for each occurred error. Credits without error are processed and stored in Edu-iX.

Error code	Description
4	Authorization error
6	Missing required field(s)
8	Record cannot be changed
9	Process validation error

blockCredits

Description

A blockCredit blocks the indicated credit (which must have been specified) for further use by the end user.

Idempotent

The idempotent characteristic of this operations ensures calls can be made multiple times without errors.

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

Name

Type

Cardinality

blockCredit

1...100

Source

<urn:blockCreditsRequest>
    <!--1 to 100 repetitions:-->
    <urn:blockCredit>
       <urn:distributorCreditID>?</urn:distributorCreditID>
       <urn:specificationRequestID>?</urn:specificationRequestID>
    </urn:blockCredit>
 </urn:blockCreditsRequest>

Response

Empty response

Error codes

In case of errors on a single credit or on multiple credits, the response contains a FaultPerCredit complex-type for each occurred error. Credits without error are processed and stored in Edu-iX.

Error code	Description
4	Authorization error
6	Missing required field(s)
9	Process validation error
9	Credit not specified yet

unblockCredits

Description

An unblockCredit unblocks the indicated credit (which was blocked before) so it can be used again by the end user.

Idempotent

The idempotent characteristic of this operations ensures calls can be made multiple times without errors.

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

Name

Type

Cardinality

unblockCredit

blockCredit

1...100

Source

 <urn:blockCreditsRequest>
    <!--1 to 100 repetitions:-->
    <urn:unblockCredit>
       <urn:distributorCreditID>?</urn:distributorCreditID>
       <urn:specificationRequestID>?</urn:specificationRequestID>
    </urn:unblockCredit>
 </urn:blockCreditsRequest>

Response

Empty response

Error codes

In case of errors on a single credit or on multiple credits, the response contains a FaultPerCredit complex-type for each occurred error. Credits without error are processed and stored in Edu-iX.

Error code	Description
4	Authorization error
6	Missing required field(s)
8	Record cannot be unblocked because it is not blocked
9	Process validation error

Errors

General errors

General errors may occur within every operation.

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	Login sessionID is 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) One or more fields are missing within the request. In case of a choice-element at least one value must be given.
7	Record not found A given value was not found.
8	Record cannot be changed Some functions are idempotent and therefor values cannot be altered within a second request.
9	Process validation error The given request does not meet the process constraints

Complex Types

personCredit

Name

Type

Cardinality

Description

distributorCreditID

string160

1...1

Unique identifier of the credit indicated by the distributor.

parentDistributorCreditID

string160

0...1

In case of a returnCredit this identifies the parent credit.

distributorPersonID

string256

1...1

Unique identifier of the person to which this credit is connected.

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.

personProductState

1...1

The state in which the product is active.

eckID

0...1

Unique identification of the end user by the ECK standard.

userID

string256

0...1

Unique identification of the end user. This value is also known as the prematch value.

specification

0...1

In case the credit is specified detailed information about the specification can be found here.

error

0...1

Detailed information about occurred errors while specifying credits can be found within the error object.

Source

<xs:complexType name="personCredit">
 <xs:sequence>
    <xs:element name="distributorCreditID" type="types:string160" minOccurs="1" maxOccurs="1"/>
    <xs:element name="parentDistributorCreditID" type="types:string160" minOccurs="0" maxOccurs="1"/>
    <xs:element name="distributorPersonID" type="types:string256" minOccurs="1" maxOccurs="1"/>
    <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="personProductState" type="types:personProductState" minOccurs="1" maxOccurs="1"/>
    <xs:element name="eckID" type="types:eckID" minOccurs="0" maxOccurs="1"/>
    <xs:element name="userID" type="types:string256" minOccurs="0" maxOccurs="1"/>
    <xs:element name="specification" type="types:specification" minOccurs="0" maxOccurs="1"/>
    <xs:element name="error" type="types:error" minOccurs="0" maxOccurs="1"/>
 </xs:sequence>
</xs:complexType>

schoolCredit

Name

Type

Cardinality

Description

distributorCreditID

string160

1...1

Unique identifier of the credit indicated by the distributor.

parentDistributorCreditID

string160

0...1

In case of a returnCredit this identifies the parent credit.

organisationID

1...1

Unique identifier of the school to which this credit will be 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.

amount

1...1

The amount of credits.

returnedAmount

amount

0...1

The amount of credits canceled. In case of multiple returnCredits on the same distributorCreditID a sum of the total return amount is shown.

specification

0...1

In case the credit is specified detailed information about the specification can be found here.

error

0...1

Detailed information about occurred errors while inserting or updating credits can be found within the error object.

Source

<xs:complexType name="schoolCredit">
 <xs:sequence>
    <xs:element name="distributorCreditID" type="types:string160" minOccurs="1" maxOccurs="1"/>
    <xs:element name="parentDistributorCreditID" type="types:string160" minOccurs="0" maxOccurs="1"/>
    <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="amount" type="types:amount" minOccurs="1" maxOccurs="1"/>
    <xs:element name="returnedAmount" type="types:amount" minOccurs="0" maxOccurs="1"/>
    <xs:element name="specification" type="types:specification" minOccurs="0" maxOccurs="1"/>
    <xs:element name="error" type="types:error" minOccurs="0" maxOccurs="1"/>
 </xs:sequence>
</xs:complexType>

uploadPersonCredit

Name

Type

Cardinality

Description

distributorCreditID

string160

1...1

Unique identifier of the credit indicated by the distributor.

distributorPersonID

string256

1...1

Unique identifier of the person to which this credit is connected.

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.

block

boolean

0...1

Indicating if the credit should be blocked for specification.

eckID

0...1

Unique identification of the end user by the ECK standard.

userID

string256

0...1

Unique identification of the end user. This value is also known as the prematch value. The given value must be according the syntax: ID@REALM

Source

<xs:complexType name="uploadPersonCredit">
 <xs:sequence>
    <xs:element name="distributorCreditID" type="types:string160" minOccurs="1" maxOccurs="1"/>
    <xs:element name="distributorPersonID" type="types:string256" minOccurs="1" maxOccurs="1"/>
    <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="block" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
    <xs:element name="eckID" type="types:eckID" minOccurs="0" maxOccurs="1"/>
    <xs:element name="userID" type="types:string256" minOccurs="0" maxOccurs="1"/>
 </xs:sequence>
</xs:complexType>

uploadSchoolCredit

Name

Type

Cardinality

Description

distributorCreditID

string160

1...1

Unique identifier of the credit indicated by the distributor.

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.

amount

1...1

The amount of credits.

Source

<xs:complexType name="uploadSchoolCredit">
 <xs:sequence>
    <xs:element name="distributorCreditID" type="types:string160" minOccurs="1" maxOccurs="1"/>
    <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="amount" type="types:amount" minOccurs="1" maxOccurs="1"/>
 </xs:sequence>
</xs:complexType>

returnCredit

Name

Type

Cardinality

Description

distributorCreditID

string160

1...1

Unique identifier of the credit you want to return.

amount

1...1

The amount of credits which should be returned.

distributorReturnCreditID

string160

1...1

Unique identifier of the returnCredit.

Source

<xs:complexType name="returnCredit">
 <xs:sequence>
    <xs:element name="distributorCreditID" type="types:string160" minOccurs="1" maxOccurs="1"/>
    <xs:element name="amount" type="types:amount" minOccurs="1" maxOccurs="1"/>
    <xs:element name="distributorReturnCreditID" type="types:string160" minOccurs="1" maxOccurs="1"/>
 </xs:sequence>
</xs:complexType>

blockCredit

Name

Type

Cardinality

Description

distributorCreditID

string160

1...1

Unique identifier of the credit you want to block.

specificationRequestID

string160

0...1

Identifier used by the specify engine. Default the same value as distributorCreditID (so leave empty) but can be different in case of prematch changes after specification, which results in a double specification. The specific specification requestID from the notification service must be supplied then.

Source

<xs:complexType name="blockCredit">
 <xs:sequence>
    <xs:element name="distributorCreditID" type="types:string160" minOccurs="1" maxOccurs="1"/>
    <xs:element name="specificationRequestID" type="types:string160" minOccurs="0" maxOccurs="1"/>
 </xs:sequence>
</xs:complexType>

loginHeader

Name

Type

Cardinality

Description

username

string100

0...1

The username.

password

string64

0...1

The password.

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:complexType name="sessionIDHeader">
 <xs:sequence>
    <xs:element name="sessionID" type="types:string64" minOccurs="1" maxOccurs="1"/>
 </xs:sequence>
</xs:complexType>

specification

Name	Type	Cardinality	Description
specificationResponseID	string256	1...1	Unique identifier of the specification provided by the publisher. The given value is according the ECK standard.
timeStamp	date	1...1	The date and time of the specification.

error

Name	Type	Cardinality	Description
errorKind	errorKind	1...1
errorCode	integer	1...1	In case of external errors the given value will be an ECK standard error.

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.
string160	String	Max length: 160 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.
amount	Integer	Minimal value must be at least 1
organisationID	String	Min length: 1, Max length: 160	Unique identifier of a school.
eckID	String	Min length: 128, Max length: 256	Unique identification of the end user by the ECK standard.
personProductState	Enum	Possible values: Active Blocked Returned

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.