/account

This page describes different customer’s account related actions, like login and logout.

Implements basic account management.

/account/login

Login action. Required for identifying the user and client. See Authentication.

Request

POST nameValueRequired?
usernamenyaYes
passwordpasswordYes
api_keykeyYes
secretsecretYes
languagefinnishNo
valid_for1369124412No
cardstrueNo
addressestrueNo

Explanations

username is case insensitive.

If cards is true, this action will also Solinor card data, as they would be returned by action /customer/cards inside attribute cards. If cards have not been requested, the value will be missing from the response altogether.

If addresses is true, this action will also return addresses, as they would be returned by action /customer/address/get inside attribute addresses. If addresses have not been requested, the value will be missing from the response altogether.

Language

There is possibility of setting language which will be used in messages sent from server to the client. This mainly means error messages and other custom data; data related to restaurants, like products and ingredients of restaurants, are not translatable, and will be in Finnish regardless of a language selection.

Because of this technical problem, doing completely localized program for other languages than Finnish is not possible. Translating the UI and having error messages might be enough for people to understand how to order something. After all, names like ”Opera” for a pizza might tell people enough of its contents.

If you want to have additional language for the API, please contact us.

Language will be determined by session id. If session id is not passed in request, errors will be in English. There are two exceptions to this rule: login and register actions, that have separate language attribute instead.
Supported languages
LabelDescription
finnishFinnish
englishEnglish

ISO-639-1 codes for the language can also be used, for example fi.

valid_for

This field can be used to determine session length. Default is two weeks. Allowed values are between 1 second to 365 days. By default session gets deleted after 2 weeks.

The unixtime passed is the time when session will expire. It should be for local timezone.

Response

Response is following object, or in case of error an Error string.

{
  "forename":"John",
  "surname":"Doe",
  "phone_number":"0505640847",
  "email":"john@example.com",
  "session_id":"0800fc577294c34e0b28ad2839435945",
  "user_id":"774",
  "newsletter":false
}

newsletter

Even if the newsletter flag is true, it does not mean that you have privilege to send newsletters to this customer. See newsletter section in /account/register for more information.

Expectable errors

Label Additional data Description
USERNAME_NOT_SUPPLIEDNoneUsername or password not in request. Either failure in client’s validation (customer has not inserted username or password) or client sent invalid data.
INVALID_USERNAMENoneEither username or password was invalid. Or in other words, customer was not able to log in.
USER_ALREADY_EXISTS_IN_DATABASEusernameIf username already exists, this error is returned.
INVALID_VALID_FORNoneThe valid_for passed is not proper unixtime.
VALID_FOR_OUTSIDE_RANGEvalid_forvalid_for is less than current time or more than 365 days in future.

/account/logout

Logs an user out from the service.

Note that calling logout after customer has done its actions is not necessarily needed.

For cases where customer wants to change to another account, or is using for example her friend’s device where she does not want to leave her information behind to make an account. A logout button, in other words.

Request

POST nameValueRequired?
session_idsecret_valueYes

Session id must be given, see Session management.

>

Response

ResponseJSON
Success:"true"
Failure:"false"

If user for example is not logged in, returns "false". Returns "true" if the user was found and login session has been terminated.

/account/check_login

This can be used to check if user is still logged in.

Request

POST nameValueRequired?
session_idsecret_valueYes
customer_datatrueNo
addressestrueNo
cardstrueNo

If customer_data is true, in case of successful session hash of customer is returned instead of true. In case of expired or invalid session, false is returned. See /account/login above for data that will be returned. This applies to addresses and cards parameters too.

Response

ResponseJSON
Success:"true" or hash of account information, see /account/login for structure.
Failure:"false"

/account/reset_password

If customer has forgot her password, this action can be used to reset it.

Request

POST nameValueRequired?
usernamenyaYes
api_keykeyYes
secretsecretYes
languagefinnishNo

Response

ResponseJSON
Success:"true"
Failure:"false"

true means that password reset email has been successfully sent. false means that there was no corresponding email or some other failure happened. Please understand that we can’t tell the exact reason of the failure in order to avoid spamming through this action.

In case of success, an email instructing the customer to reset the password has been sent. It’s up to client to decide how to phrase this information to customer to know the situation :)

/account/register

An action to register new account for an user.

Request

POST nameValueMinimum lengthMaximum lengthRequired?
username"nya"250Yes
password"password"4512Yes
forename"Test"2100Yes
surname"User"2100Yes
email"test@user.sml"2200Yes
phone_number"0123456789"230Yes
language"finnish"--No
newslettertrue--No

Details

  • username is case insensitive
  • password should be plaintext password. Password’s minimum length is 4 characters. It is adviced that clients uses higher security related passwords
  • email address is not needed but suggested. Full order receipts are only sent to email, text message receipts are not equally full featured.
  • language See language section

All values goes through certain validators that validates if they are valid form; for address and similar basically only [:alnum:] are accepted. For some cases, like forename and surname, some extra characters like ä and è are accepted. If you know some extra character our service does not accept, please contact us to get it allowed.

username can take virtually any character. Clients are adviced not to restrict character set of username to only ASCII unless that proves to be problematic for client.

Customer’s addresses

It’s generally good idea to ask customer’s address in registration form and then save the address; see below for workflow.

If you want to allow customer to give address within register action, you can do it for example in following way:

  1. Show registration form and wait user to input data and press ok button
  2. Save all data from registration form to memory
  3. Try to do a register action
    1. If successful, do a login action to get a session id.
    2. Do a /customer/address/set call to save customer’s address using the session id received from login.
      1. If there was some errors with address validation, user should be shown generic address entry field (maybe same thing she is using to modify addresses) with the data she entered and the error what was wrong.
    1. If unsuccessful, return to form, restore data from memory and ask customer to fix her information by showing the error received
    2. (Continues from step 1.)

Newsletter possibility

Possible values for newsletter are true and false. If newsletter is omissed, false is assumed.

It is possible to give customers a possibility to subscribe to Pizzaonline newsletter. This newsletter, while not exactly PO specific, may contain mostly PO specific information or something similar, and may not be relevant to your client’s needs. You won’t be able to send newsletters to people which has opted in to newsletter using this switch.

In case you want to do your own newsletter for users of your client, you need to have something specific to your client where you ask your users whether they want to join to your list. These will then be subscribed to your list, and we won’t be able to access your list.

You can contact us if you have any questions, suggestions, or otherwise, about this matter, we’ll gladly help you.

Response

ResponseJSON
Success:"success"
Failure:error array

Expectable errors

See error conventions section for explanation how error system works.

Label Additional data Description
INVALID_USERNAMENoneUsername was most likely too short, or not given.
TOO_SHORT_PASSWORDNonePassword has certain minimum length (5 characters). User’s password was too short.
INVALID_FORENAMENoneThis may be returned even when the name should’ve been accepted. In that case it’s some uncommon UTF-8 letter. Please tell us if you spot any of not accepted but legal characters.
INVALID_SURNAMENoneThis may be returned even when the name should’ve been accepted. In that case it’s some uncommon UTF-8 letter. Please tell us if you spot any of not accepted but legal characters.
INVALID_EMAILNoneEmails must consist of a@b at minimum.
INVALID_PHONENonePhone numbers valid in Finland are accepted. The filter is quite loose so numbers that fits to same amounts of numbers will pass too. Phone number must not contain spaces.
USERNAME_EXISTSNoneCustomer’s chosen username already exists.
INVALID_NEWSLETTERNoneGiven newsletter value is not true or false.

/account/modify

An action to modify user’s personal information.

Request

POST nameValueMinimum lengthMaximum lengthRequired?
session_id"nya"250Yes
password"password"4512No
forename"Test"2100No
surname"User"2100No
email"test@user.sml"2200No
phone_number"0123456789"230No
newslettertrue--No

Details

Data follows same rules as /account/register, with following exceptions. If a value is not given, it won’t be changed.

session_id

This is required, as it identifies user to the service.

username

To reduce misuse, username can’t be changed.

newsletter

See newsletter section in /account/register about newsletter flag.

Response

ResponseJSON
Success:"success"
Failure:error array

Expectable errors

See error conventions section for explanation how error system works.

Label Additional data Description
TOO_SHORT_PASSWORDNonePassword has certain minimum length (5 characters). User’s password was too short.
INVALID_FORENAMENoneThis may be returned even when the name should’ve been accepted. In that case it’s some uncommon UTF-8 letter. Please tell us if you spot any of not accepted but legal characters.
INVALID_SURNAMENoneThis may be returned even when the name should’ve been accepted. In that case it’s some uncommon UTF-8 letter. Please tell us if you spot any of not accepted but legal characters.
INVALID_EMAILNoneEmails must consist of a@b at minimum.
INVALID_PHONENonePhone numbers valid in Finland are accepted. The filter is quite loose so numbers that fits to same amounts of numbers will pass too. Phone number must not contain spaces.
INVALID_NEWSLETTERNoneNeeds to be either true or false.
INVALID_PREFERRED_ADDRESSNoneNeeds to be either true or false.

/account/verify

A customer may require verification before she can make an order. This action can be used to verify a customer.

In some cases, when creating an order, the API may return USER_NEEDS_VERIFICATION as an error. This means that customer must be verified before the order can be submitted. We send a message automatically to customer’s phone number which contains the code that can be used for the verification, which can then submitted to the server using this call.

Request

POST nameValueRequired?
session_idsecret_valueYes
codebarYes
languagefinnishNo

For language, see language section.

Response

ResponseJSON
Success:"success"
Failure:error array
Label Additional data Description
VALIDATION_ATTEMPTS_EXCEEDEDNoneWe don’t allow infinite amount of tries for user validation. You can show this message to customers.
INVALID_SESSIONNoneIf the session is not valid.
VERIFICATION_FAILEDNoneIf verification of the code did not succeed.