DEVELOPER’S MANUAL FOR SPAINBOX RESTFUL API

1.OBTAINING THE TOKEN #

To access the different resources of the Spainbox API, it is necessary to obtain a token that will accompany each of the requests that are made. To obtain the token, a request must be made to the resource:  
URL API
https://api.shipeu.com/security/login_check

    That receives the following parameters:
  • _username: Provided by Spainbox
  • _password: Provided by Spainbox
  If the answer was satisfactory, it will return a status code of 200 and the token that should be used for requests in the API.  

Notice: The token is valid for 30 days. After 30 days it is due to re-generate the token otherwise requests to the API will be denied. Example of request using cURL:          
Yes No Suggest edit
Last updated on 7 julio 2022

2.USING THE TOKEN #

All requests made to the API must be accompanied by the token; for this, the token must be attached in the authorization header of the HTTP request, prefixed by the word Bearer and one space, like this:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ……

Notice: The bold characters represent the token

Yes No Suggest edit
Last updated on 19 junio 2020

3.RESOURCES #

3.1.SENDING ORDERS #

The resource to create new orders is: https://api.shipeu.com/v1/order-shipments/new-order

Requests to this resource must have the token in the Authorization header and must be sent with the POST method.

The fields allowed in the request are the following:

FieldDescriptionMax lengthNullable?
orderIdId of the order 128 no
statusStatus of the order. Valid values
= [completed, cancelled, failed,
on-hold, pending, processing,
refunded, shipped]
10no
firstNameFirst name of the client128no
lastNameLast name of the client128yes
companyName of the company if the
payer is a company
128yes
countryThe 2-letter code of the country
where the order will be sent to.
E.g. (ES, FR, DE)
2no
stateThe state where the where the
order will be sent to.
64no
cityThe city where the where the
order will be sent to.
64no
addressOneThe main direction of the client.
Can be used as street name.
255no
addressTwoThe secondary direction of the
client. Can be used as street
number.
255yes
postCodePostcode of the client25no
billingEmailThe billing email of the client255yes
billingPhoneThe billing phone of the client20yes
shippingMethodShipping method of the order100no
paymentMethodPayment method of the order100no
orderTotalTotal price of the order.
Only numbers allowed
yes
codCost of cash on delivery.
Only numbers allowed
yes
linesLines (products) of the order.
Could be one line or an array of
lines. See line specification.
no
shippingCostCost of the shipping without
taxes.
Only numbers allowed
yes
nipNifNIP/NIF128yes

Note: When a new order is created, it must have the status“completed”. Shipeu will take the orderswith “completed” status and will change it to “shipped” when the order has been shipped and the tracking info has been set. Later in this manual, will be explained how to obtain those trackings numbers from the orders through the API.

Note 2: The courier for the dispatch of the orders will be set with the one agreed with Spainbox.

ALLOWED VALUES FOR LINES:

FieldDescriptionMax lengthNullable?
skuThe sku of the product that is
going to be sent in the order
255no
quantityThe quantity of products that
are going to be sent in the order.
Only integers allowed.
no
totalTotal price128no
taxRatePercent of taxes to apply to the
price of the line (only numbers)
yes
linePriceProduct line price (price per
product, not the total of the
products in the line)
yes

RESPONSES

FieldDescription
statusStatus of the response. Possible values: [201, 400, 500]
errorError message in case an error has occurred
dataReturns the previously registered data in case of success (status=200) or returns a list of errors in case an error or errors has occurred (status=400)

EXAMPLE OF SUCCESS REQUEST

  • Json Request for one order and one line:
{
"orderId": "7885-45622-12336",
"firstName": "Jhon",
"secondName": "Doe",
"addressOne": "Av fake",
"addressTwo": "123",
"country": "ES",
"status": "completed",
"state": "Madrid",
"city": "Madrid",
"postCode": "28033",
"shippingMethod": "24h delivery",
"shippingCost": "4.09",
"nipNif": "1234",
"lines": [
{
"sku": "vitanoria",
"quantity": 4,
"total": 20
},
{
"sku": "viswiss",
"quantity": 2,
"total": 25.5
}
]
  • Success response:
{
"code": 201,
"data": {
"orderId": "7885-45622-12336",
"firstName": "Jhon",
"secondName": "Doe",
"addressOne": "Av fake",
"addressTwo": "123",
"country": "ES",
"status": "completed",
"state": "Madrid",
"city": "Madrid",
"postCode": "28033",
"shippingMethod": "24h delivery",
"shippingCost": "4.09",
"nipNif": "1234",
"lines": [
{
"sku": "vitanoria",
"quantity": 4,
"total": 20
},
{
"sku": "viswiss",
"quantity": 2,
"total": 25.5
}
]
}
}
  • Error response:
{
"code": 400,
"error": "Order validation failed. Please check the errors.",
"data": {
"orderId": [
"This value is already used."
],
"firstName": [
"This value should not be blank."
],
"country": [
"This value should not be blank."
]
}
}
Yes No Suggest edit
Last updated on 7 julio 2022

3.2.GETTING TRACKINGS #

The resource to get the tracking of the orders in a range of dates is:

https://api.shipeu.com/v1/order-shipments/get-tracking

Requests to this resource must have the token in the Authorization header and must be sent with the GET method. The fields allowed in the request are the following:

FieldDescriptionFormatNullable?
registeredDateStartStart of the range of dates
considering the date of
registration of the order
YYYY-MM-DDTHH:MMno
registeredDateEndEnd of the range of dates
considering the date of
registration of the order
YYYY-MM-DDTHH:MMno

EXAMPLE OF REQUEST

Get all the orders from July first of 2018 at 00:00 to July second of 2018 at 23:50

https://api.shipeu.com/v1/order-shipments/get-tracking?registeredDateStart=2018-07-01T00:00&registeredDateEnd=2018-07-02T23:50
  • Success response:
{
"code": 200,
"data": [
{
"orderId": "12653",
"registeredDate": "2018-07-02T08:21:10+00:00"
},
{
"orderId": "12652",
 "tracking": "PQ54A71100012590106230N",
"registeredDate": "2018-07-02T08:21:23+00:00",
"shippedDate": "2018-07-02T09:04:11+00:00"
},
{
"orderId": "12645",
"tracking": "PQ54A71100012600141020T",
"registeredDate": "2018-07-02T08:21:35+00:00",
"shippedDate": "2018-07-02T09:04:11+00:00"
}
]
}
  • Error response:
{
"code": 400,
"error": "Start date cannot be greater than end date"
}
Yes No Suggest edit
Last updated on 7 julio 2022

3.3.GETTING ORDERS LIST #

You can get a list of orders registered in a range of dates and a status. The resource is: https://api.shipeu.com/v1/order-shipments/get-orders

Requests to this resource must have the token in the Authorization header and must be sent with the GET method.

The fields allowed in the request are the following:

FieldDescriptionFormatNullable?
registeredDateStartStart of the range of dates
considering the date of
registration of the order
YYYY-MM-DDTHH:MMno
registeredDateEndStart of the range of dates
considering the date of
registration of the order
YYYY-MM-DDTHH:MMno
statusStatus of the order. The
values can be:
completed -> The order has
been registered in Shipeu.
shipped -> The order has been
shipped
no

EXAMPLE OF REQUEST

Get all the orders shipped from July first of 2018 to July second of 2018

https://api.shipeu.com/v1/order-shipments/get-orders?registeredDateStart=2018-07-01&registeredDateEnd=2018-07-02&status=shipped
  • Success response:
{
"code": 200,
"error": null,
"data": [
{
"order_id": "12652",
"status": "shipped",
"first_name": "maria",
"last_name": "manzano dominguez",
"country": "ES",
"state": "BA",
"city": "los santos de maimona",
"address_one": "hernando de soto 12",
"address_two": "",
"post_code": "06230",
"billing_email": "[email protected]",
"billing_phone": "655789323",
"shipping_method": "Gratis por Carta ordinaria (10-15 dias)",
"payment_method": "redsys",
"registered_date": "2018-07-02T08:21",
"shipped_date": "2018-07-02T09:04",
"tracking": "PQ0001998457771N",
"lines": [
{
"sku": "1xSKUTEST",
"product_name": "Test product 1",
"quantity": 1,

"total_price": 15.69
},
{
"sku": "1xSKUTEST2",
"product_name": "Test product 2",
"quantity": 5,
"total_price": 23.03
}
]
},
{
"order_id": "12645",
"status": "shipped",
"first_name": "Susana",
"last_name": "Vergara Marquez",
"country": "ES",
"state": "SE",

"city": "Sevilla",
"address_one": "Avenida Del Deporte n 1, Bloque 2,",
"address_two": "4 C",
"post_code": "41020",
"billing_email": "[email protected]",
"billing_phone": "664165132",
"shipping_method": "Envío gratuito con entrega 48/72h.",
"payment_method": "redsys",
"registered_date": "2018-07-02T08:21",
"shipped_date": "2018-07-02T09:04",
"tracking": "PQ991884777571T",
"lines": [
{
"sku": "1xSKUTEST3",
"product_name": "Test product 3",
"quantity": 1,
"total_price": 9.99
}
]
}
]
}
  • Error response:
{
"code": 400,
"error": "Start date cannot be greater tan end date",
"data": null
}

Yes No Suggest edit
Last updated on 7 julio 2022

3.4.GET PRODUCTS STOCK #

You can get a list of products with his current stock

The resource is: https://api.shipeu.com/v1/order-shipments/get-stock

Requests to this resource must have the token in the Authorization header and must be sent with the GET method.

https://api.shipeu.com/v1/order-shipments/get-stock
  • Success response:
{
"code": 200,
"error": null,
"data": [
{
"sku": "1xSKUTEST",
"name": "Test product",
"stock": 12
},
{
"sku": "1xSKUTEST2",
"name": "Test product 2",
"stock": 76
},
{
"sku": "1xSKUTEST3",
"name": "Test product 3",
"stock": 29
}
]
}
Yes No Suggest edit
Last updated on 7 julio 2022

3.5.CANCEL ORDERS #

You can cancel an order that has not been sent or already cancelled.

The resource is: https://api.shipeu.com/v1/order-shipments/cancel-order?order-id={orderid}

Requests to this resource must have the token in the Authorization header and must be sent with the PATCH method.

The param “orderid» is the id given to the order.

Note: The order must be in status different from shipped or cancelled in order to be cancelled, otherwise it will return a 400 bad request.

Example request:

https://api.shipeu.com/v1/order-shipments/cancel-order?order-id=test_order_789

  • Success response:
{
"code": 200,
"error": null,
"data":
{
"orderId": "test_order_789",
"status": "cancelled"
}
}
  • Error response:
{
"code": 400,
"error": "The order was already shipped",
}
Yes No Suggest edit
Last updated on 7 julio 2022

3.6.SCHEDULE ORDER PICKUP #

You can schedule the pick up of an order.

The resource is:

Production
https://api.shipeu.com/v1/order-shipments/order-return-by-customer

Requests to this resource must have the token in the Authorization header and must be sent with the GET method.

The fields allowed in the request are the following:

FieldDescriptionFormatLengthNullable?
order-idId of the orderMax 128no
collected-dateIndicate the date you want
generate collection
DD-MM-YYYY 10no
from-hourIndicates the time from which
wants to generate the collection
00:00 – 23: 595no
to-hourIndicates the last hour at which
you want to generate the collection.
Must be at least one hour after form-hour
00:00 – 23: 595no

RESPONSE

FieldDescription
statusStatus of the response.
Possible values: [200, 400, 500]
errorError message in case an error has occurred
dataReturns the data of the scheduled collection.

tracking -> generated tracking code
delivery_number -> Associated shipping number
pick_up_date -> Pick date
from_hour -> from what time is the pickup
to_hour -> until what time can you pick up
address -> Collection address obtained from the order

EXAMPLE OF REQUEST

Schedule an order pickup for June 30, 2020, between 8 a.m. to 6 p.m.

https://api.shipeu.com/v1/order-shipments/order-return-by-customer?order-id=FS/ES/2020/4/00988-R&collected-date=30-06-2020&from-hour=08:00&to-hour=18:00
  • Success response:
{
"code":200,
"error":"",
"data":{
"tracking":"6300000000239379",
"delivery_number":"69158989",
"pick_up_date":"30062020",
"from_hour":"09:00",
"to_hour":"17:30",
"address":"C\/ Guifr\u00e9 el pel\u00f3s 42","city":"Matar\u00f3"
}
}
  • Error response:
{
"code": 400,
"error": "The end time must be at least one hour higher than the start time."
}
Yes No Suggest edit
Last updated on 7 julio 2022
Suggest Edit