Skip to main content

Orders API

This documentation describes the snabble API endpoints related to the access of orders. These endpoints are available on the api subdomain. See General API access for general information about api access.

Endpoints

Model

Order

PathTypeDescription
idstringThe id of the Order
projectstringThe id of the Project
datedateThe date on which the order was contracted
createdAtdateThe date on which the order was processed
finalizedAtdateThe date on which the order was finalized (i.e. the time the order was paid)
clientIDstringThe app ID
customer.loyaltyCardstringThe loyalty card number used
shopIDstringID of the in which the order was contracted
shop.namestringName of the Shop (see Shops API)
shop.externalIDstringAn identifier for the provided by external sources (see Shops API)
shop.streetstringStreet and number of the Shop (see Shops API)
shop.zipstringZip of the Shop (see Shops API)
shop.statestringState in which the Shop is situated (see Shops API)
shop.countrystringCountry in which the Shop is situated (see Shops API)
shop.citystringCity in which the Shop is situated (see Shops API)
shop.phonestringPhone number of the Shop (see Shops API)
shop.emailstringEmail address of the Shop (see Shops API)
paymentMethodstringThe payment method used
paymentInformationObjectPayment dependent additional information
paymentResult ObjectPayment gateway result object (Payment Result
paymentStatusstringThe final Status of the associated payment process
lineItemsLineItem[]Line items of the order. For details see Checkout API: Line Item
currencystringCurrency of the project
price.priceintThe total brutto price of the order
price.netPriceintThe total netto price of the order
price.taxmap[string]intMapping of tax rates on the portion of the price
price.taxNetmap[string]intMapping of tax rates sums all net prices of products with this rate up
price.taxPremap[string]intMapping of tax rates sums all pre tax prices of products with this rate up
sessionstringThe session ID
fiscalReferenceFiscalReferenceOptional Fiscal Reference
RelationDescription
receiptThe Receipt generated for the order

Example:

{
"id": "99e13f9f-0412-4686-907a-331003b2a703",
"project": "test-project-faa116",
"clientID": "app-id-12345",
"date": "2018-06-05T12:25:06.821Z",
"createdAt": "2018-06-05T12:25:07.519Z",
"shopID": "128",
"shop": {
"externalID": test",
"street": "Street 1",
"zip": "12345",
"state": "State",
"country": "Country",
"city": "City",
"phone": "+49123456",
"email": "test@test.de",
"name": "Integration Test"
},
customer: {
"loyaltyCard": "12354567"
},
"paymentMethod": "cash",
"paymentState": "successful",
"lineItems": [
{
"sku": "20001",
"name": "Pommes,
"amount": 2,
"price": 107,
"taxRate": "7",
"totalPrice": 214
}
],
"price": {
"price": 214,
"netPrice": 200,
"tax": {
"7": 14
},
"taxNet": {
"7": 200
},
"taxPre": {
"7": 214
}
},
"session": "asdaf24u-0124-77a4-77a8-ada100011112",
"currency": "EUR",
"links": {
"self": {
"href": "/test-project-faa116/orders/99e13f9f-0412-4686-907a-331003b2a703"
},
"receipt": {
"href": "/project/receipts/id"
}
}
}

Closing

PathTypeDescription
projectstringProject identifier
shopIDstringIdentifier of the shop
sequenceNumberintSequence number of the closing
createdAtdateDate of creation. Formated in the RFC3339 format (ie. 2018-05-02T00:00:00-02:00)
currencystringCurrency code of the closings currency
lastOrderSequenceNumberintSequence number of the last order included in the closing
shop.namestringName of the Shop (see Shops API)
shop.externalIDstringAn identifier for the provided by external sources (see Shops API)
shop.streetstringStreet and number of the Shop (see Shops API)
shop.zipstringZip of the Shop (see Shops API)
shop.statestringState in which the Shop is situated (see Shops API)
shop.countrystringCountry in which the Shop is situated (see Shops API)
shop.citystringCity in which the Shop is situated (see Shops API)
shop.phonestringPhone number of the Shop (see Shops API)
shop.emailstringEmail address of the Shop (see Shops API)
taxSharesTaxShare[]List of Tax Share
shareByPaymentMethodShareByPaymentMethod[]List of Share by Payment Method
totalintThe total sum of the closing
taxNumberstringTax number
vatIDstringValue added tax identifier
companyNamestringName of the company
companyAddress.citystringCompany official address city
companyAddress.countrystringCompany official address country
companyAddress.streetstringCompany official address street
companyAddress.zipstringCompany official address zipcode
ordersOrder[]List of Order included in this closing
logsClosingLog[]List of Closing Log written for this closing
{
"project" : "project",
"shopID" : "aShop",
"sequenceNumber" : 1234,

"createdAt" : "2019-11-12T12:13:15Z",
"currency" : "EUR",
"lastOrderSequenceNumber" : 1234,

"shop" : {
"city" : "City",
"country" : "Country",
"countryCode" : "DEU",
"email" : "Email",
"externalID" : "ExternalID",
"name" : "Name",
"phone" : "Phone",
"state" : "State",
"street" : "Street",
"zip" : "Zip"
},

"taxShares" : [ ... ],
"shareByPaymentMethod" : [ ... ],
"totalPrice" : 119,

"taxNumber" : "TaxNumber",
"vatID" : "TaxID",

"companyName" : "CompanyName",
"companyAddress" : {
"city" : "City",
"country" : "Country",
"street" : "Street",
"zip" : "Zip"
},

"orders": [ ... ],

"logs": [ ... ],

"fiscalReference": { ... },

"links": {
"self": {
"href": "/project/closings/shops/aShop/sequenceNumbers/1234"
}
}
}

Tax Share

Represents a share of the total which was taxed with the given rate.

PathTypeDescription
ratestringDecimal represantation of the tax rate
netintNetto portion
taxintTax share
totalintTotal share
{
"rate" : "19",
"net" : 100,
"tax" : 19,
"total" : 119
}

Share by Payment Method

Represents a share of the total which was paid with the named method.

PathTypeDescription
paymentMethodstringIdentifier of the Payment Method
amountintAmount paid with the Payment Method
{
"amount" : 119,
"paymentMethod" : "sepa"
}

Closing Logs

PathTypeDescription
idintIdentifier of the log
formatstringFromat of the log file
statestringState of the log (Values: not_present = The log is currently not created, ongoing = The log gets currently created, present = The log was sucessfully created, failed = The creation of the log is failed.)

The file link of the object points to actual log content.

{
"format" : "dfka_taxonomie_2_0",
"id" : 10,
"state" : "not_present",
"links": {
"file": {
"href": "/project/closings/logs/10"
}
}
}

Closing List

PathTypeDescription
closingsClosings[]List of Closing
{
"closings": [ ... ],
"links": {
"self": {
"href": "/project/closings"
}
}
}

Create Closing Schedule

PathTypeDescription
idintIdentifier
projectstringProject
shopstringIdentifier of the shop for which the closing should be created
modestringMode of the created Closing Schedule. Supported are: includeUntilExecution, includeUntilScheduled
hourintHour (0-24) at which the closing should be created
minuteintMinute (0-60) at which the closing should be created
daysstring[]Name of the days used (Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday)
locationstringIANA Timezone Database name of the location used
{
"id": 12,
"project": "project",
"shop": "1",
"mode": "includeUntilExecution",
"hour": 10,
"minute": 30,
"days": [
"Monday",
"Tuesday"
],
"location": "Europe/Berlin",
"links": {
"self": {
"href": "/project/closings/schedules/id/12"
}
}
}

Create Closing Schedule List

PathTypeDescription
schedulesCreateClosingSchedule[]Schedules returned
{
"schedules": [ ... ],
"links": {
"self": {
"href": "/project/closings/schedules"
}
}
}

Fiscal Reference

The Fiscal Reference provides the metadata and logs that were obtained by required fiscal processes. The provided information and carried out steps heavily depend on the country where the transaction was executed an the modus of operation.

In germany the process is regulated by the Kassensicherungsverordnung (KassenSichV) and hence the values are provided by a Technische Sicherheitseinrichtung (TSE).

PathTypeDescription
securityDeviceModule.serialNumberstringSerial number of the security device
securityDeviceModule.signatureAlgorithmstringSignature Algorithm used by the device
securityDeviceModule.logTimeFormatstringTime Format of the security device
securityDeviceModule.certificatestringCertificate presented by the security device
logs[].timestampstringRFC3339 encoded point in time on which the log was created
logs[].counterintCounter value of the signature
logs[].processTypestringThe process type send to the security device
logs[].processDatastringThe data send to security device
logs[].errorstringMessage describing errors during the signature process

Get orders

GET /{project}/orders

Get the list of orders of the project.

Orders can be queried either by date or by shop.

Required permissions : ordersRead for the project

Request

Parameters :

NameDescription
dateDate for which the orders should be returned. Formated in the RFC3339 format (ie. 2018-05-02T00:00:00-02:00)
shopIDID of the shop
shop.externalIDExternal ID of the shop as provided through the Shops API

Success Response 200 OK

Content-Type : application/json

Data : List of Orders

Get order

GET /{project}/orders/{id}

Get a order.

Success Response 200 OK

Content-Type : application/json

Data : Order

Get closings

GET /{project}/closings

Get the list of closings of the project.

Required permissions : ordersRead for the project

Request

Parameters :

NameDefaultDescription
page0Number of the page to be fetched
perPage1000Number of items per page

Success Response 200 OK

Content-Type : application/json

Data : A Closing List

Get closing

GET /{project}/closings/shops/{shopID}/sequenceNumbers/{seqNum}

Get a single closing.

Required permissions : ordersRead for the project

Success Response 200 OK

Content-Type : application/json

Data : A Closing

Get closing log file

GET /{project}/closings/logs/{id}

Get a single log file for a closing.

Required permissions : closingRead for the project

Success Response 200 OK or a http redirect

Warning : The service might send a redirect to the correct ressource!

Create schedule

POST /{project}/closings/schedules

Create a new schedule.

Required permissions : closingSchedulesWrite for the project

Request

Data : Create Closing Schedule

Success Response 201 Created

Header : Location contains a link to the created resource

Get schedules

GET /{project}/closings/schedules

Get the list of schedules of the project.

Required permissions : createClosingSchedulesRead for the project

Success Response 200 OK

Content-Type : application/json

Data : A Create Closing Schedule List

Get schedule

GET /{project}/closings/schedules/id/{id}

Get a single schedule.

Required permissions : createClosingSchedulesRead for the project

Success Response 200 OK

Content-Type : application/json

Data : A Create Closing Schedule

Update schedule

PUT /{project}/closings/schedules/id/{id}

Update the schedule.

Required permissions : createClosingSchedulesWrite for the project

Request

Data : Create Closing Schedule

Success Response 200 OK

Delete schedule

DELETE /{project}/closings/schedules/id/{id}

Delete a schedule.

Required permissions : createClosingSchedulesWrite for the project

Success Response 200 OK