1. Introduction

Storecove offers a number of different products, both for senders of invoices as well as for those who wish to receive invoices in a digital format that can be processed directly by an accountancy package.

1.1. Receiving invoices

If you offer an accountancy package and want to (white-label) embed Storecove’s supplier connections solution, then this document, particularly sections API Access and Embedded Supplier Connections, is for you. The embedded solution allows you to have your Customers create connections to their suppliers inside your accounting package.

1.2. Sending invoices

For companies wishing to send invoices to their Customers through various networks/channels, including the PEPPOL network, we offer a flexible solution that can send invoices directly to accountancy packages as digital invoices that can be automatically processed by the receiving accountancy package.

There are two ways of pushing your invoices into the Storecove platform for delivery:

  • Invoice Email Ingestion

  • Invoice API Ingestion

Whichever way you choose, we have a web interface where you can view how we processed your invoice and correct any errors. We also offer this functionality through an API, available for you to integrate into your Customer Service system. And there are webhooks available that you can subscribe to, to actively let you know what actions where taken to deliver an invoice.

Also, whichever way you choose, we offer a widget that you can embed in your website, in which your Customers can configure how to send your invoice directly into their accountancy package as a booking proposal.

1.2.1. Invoice Ingestion via Email

The easiest way of having Storecove deliver your invoices, is to send them to Storecove via email. You simply send your invoice to an address @peppol.storecove.com and we will ensure it gets delivered into your Customers' accountancy package. This is discussed in section Email Ingestion.

1.2.2. Invoice Ingestion via the API

For high-volume, the most scalable way of having Storecove deliver your invoices, is to process them through the Storecove API. This is discussed in sections API Access and API Ingestion.

1.2.3. Destination Configuration

Both API as well as Email ingestion support Destination Configuration through the Storecove Widget. This is discussed in section Destination Configuration.

2. API Access

2.1. Keys

To use the Storecove API, the first thing you will need to do is to create an account. There are different plans available on the Storecove website, so make sure you create the right kind of account. For instance, if you want to submit invoices for sending, make sure you create a sender account. You will need to create two accounts, one for development and one for production. Note that at this moment it is not possible to create accounts for the (white-label) embedded solution. To use this, please contact Storecove on +31.202611791 or helpdesk@storecove.com.

Next, create an API key. To do this, navigate to https://www.storecove.com/en/settings/api_keys. You will typically need only one, but should you want to change the key every so often, you can create and use more than one during your migration period.

The authentication scheme used is the OAuth2.0 Bearer Token (RFC 6750). It requires an HTTP header “Authorization” with contents “Bearer <api_key>”, e.g.

Authorization: Bearer abababababababababababababababababababab

These headers are safe inside the TLS tunnel that protects the Storecove API.

The API endpoint is

https://api.storecove.com/.

2.2. Client Libraries

For a number of languages, we have client libraries available. The API is RESTful and communicates through JSON, so you can easily create your own client if we don’t have one ready to go and you don’t want to leverage the Swagger 2.0 API specification (see below).

The following shows how to setup each client.

No setup is necessary if you use this client.

To include the gem in your project, use

gem 'storecove', '~> 1.0'

Create config/initializers/storecove_api.rb:

StorecoveApi.configure do |config|
    config.api_key['Authorization'] = '<api_key>'
    config.api_key_prefix['Authorization'] = 'Bearer'
end

class StorecoveApiClient
    attr_accessor :invoice_submissions, :shop_accounts, :shop_account_requests, :shops
    def initialize
        @invoice_submissions = StorecoveApi::InvoiceSubmissionsApi.new
        @shop_accounts = StorecoveApi::ShopAccountsApi.new
        @shop_account_requests = StorecoveApi::ShopAccountRequestsApi.new
        @shops = StorecoveApi::ShopsApi.new
    end
end

2.3. Other Langauges

The easiest way to create a client for your favourite language is by leveraging our OpenAPI (previously known as Swagger) specification, which can be found on

https://www.storecove.com/api/v2/openapi.json

With this, it becomes easy to generate a client library in your favorite language. This is done through Swagger Codegen:

https://github.com/swagger-api/swagger-codegen

First, download the Java jar:

#wget http://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.2.1/swagger-codegen-cli-2.2.1.jar

Next, create the client library (in this example we generate a C# library):

#java -jar swagger-codegen-cli-2.2.1.jar generate -i https://www.storecove.com/api/v2/api-docs.json -l csharp -o csharp

Language support is extensive, amongst others:

  • C#

  • Java

  • Node.js

  • Objective-C

  • Perl

  • PHP

  • Python

  • Many others

3. Embedded Supplier Connections

3.1. Introduction

This API facilitates white label embedding Storecove Script Connections into your own service/product. This enables your users to manage the credentials with which Storecove retrieves invoices from suppliers, directly in your website.

To use this API, your key needs to have the embedded scope.

3.2. Use

The typical use-case is as follows:

  • You show your user a list of suppliers to choose from.

  • When they click on a supplier, they provide their username/password in a modal form.

  • When they save, you create a ShopAccount via the Storecove API

Don’t limit the list of suppliers to only suppliers the user does not yet have connected, since it is possible to have more than one connection to the same supplier (e.g. two mobile phone subscriptions with Vodafone with separate accounts).

The list of available suppliers can be found with this API call:

Get Shops

When a user connects a new supplier, you create a new ShopAccount with the following API call:

Create ShopAccount

We normally send invoices to email addresses provided with the ShopAccount. If you require a different method to send invoices (for example, you have an API to submit them to), then please contact us on apisupport@storecove.com or +31.202611791 about creating a custom Destination.

3.2.1. Timing

The jobs to retrieve the invoices run mostly during the night, so any invoices in the ShopAccount’s active period should be available the next day after the ShopAccount was created.

Invoices will be retrieved from one month before the moment on which the ShopAccount was created.

3.2.2. Authorization failures

If your user provides the wrong credentials, the connection with the supplier cannot be created and invoices are not retrieved. The user needs to take action. A call is available to receive a list of ShopAccounts that have been diagnosed with an authorization problem:

The following are the relevant fields in each ShopAccount: id, external_user_id, sign_in_error_confirmed, sign_in_error_confirmed_at. Poll daily and process the result:

  • If a ShopAccount is on your list, but no longer in the list returned, then either the problem was resolved or it was not resolved for too many days and the ShopAccount has therefore been dropped by Storecove (currently after 30 days). In both cases, remove the id from your list. To determine what happened, request the ShopAccount by its id. You will receive a 200 or a 404.

  • If a ShopAccount is not yet on your list, add it. You can now start the process that you want to follow to alert the user. For instance, you could email them and/or show the problem in your web interface.

  • When someone changes their credentials in your web interface, remove the id from your list immediately after updating the ShopAccount via the API.

3.2.3. ShopAccountRequest

To allow your users to request connections to suppliers that are not yet in the list, use the ShopAccountRequest API. Storecove will connect these suppliers and automatically convert the ShopAccountRequest to a real ShopAccount when ready.

4. Email Ingestion

4.1. Introduction

Email ingestion refers to Storecove receiving and processing your Customer’s invoice via an email to @peppol.storecove.com email addresses. This email should have an attachment that contains the data that makes up the invoice and optionally an attachment that has an image of the invoice, in PDF format.

4.2. From: Address

The address you send from needs to be whitelisted by Storecove, so before starting implementation it is important to contact Storecove at helpdesk@storecove.com to set this up.

4.3. Destination Identifiers

There are three types of identifiers that you can use:

  • PEPPOL/Simplerinvoicing Identifiers

  • Widget Identifiers

  • Fallback Email Addresses

The fallback email address will be used only when we could not send the invoice to any of the other identifiers. All identifiers are case-insensitive.

4.3.1. PEPPOL/Simplerinvoicing Identifiers

To send an invoice on the PEPPOL/Simplerinvoicing network via the Dutch chamber of Commerce number 59846933 use:

NL_KVK.59846933

You can use all the prefixes listed in <<>>, but since email addresses cannot contain the colon (‘:’) character, you need to replace it with an underscore (‘_’). The following is a shortlist of prefixes that you can use for Western Europe:

Scheme Description

BE_VAT

Belgium VAT number

DE_VAT

Germany VAT number

GB_VAT

United Kingdom VAT number

IBAN

SOCIETY FOR WORLDWIDE INTERBANK FINANCIAL, TELECOMMUNICATION S.W.I.F.T

NL_OIN

Dutch ‘OIN’ number

NL_KVK

Vereniging van Kamers van Koophandel en Fabrieken in Nederland

NL_VAT

Netherlands VAT number

The prefix is followed by a dot (‘.’) and the identifier.

4.3.2. Widget Identifiers

If you use the Storecove Widget (see section Destination Configuration), you can also include your own ID, prefixed with “WI_”. For instance:

WI_yourid123

4.3.3. Fallback Email Address

If none of the other identifiers could be used to send the invoice, the invoice will be sent to the fallback email address – if you provide one. The fallback email address is added as follows:

FB_fall.back?example.com

The question mark (‘?’) character replaces the at-sign in the original fallback email address. Next, ‘FB_’ is prefixed to facilitate recognition: fall.back@example.com becomes FB_fall.back?example.com (not case-sensitive).

This means that your fallback email address must not contain question marks.

4.4. To: Recipient

If you have only one destination identifier, the email address to send the invoice to is easy. Just use the identifier and append “@peppol.storecove.com”. For instance:

NL_KVK.59846933@peppol.storecove.com
WI_yourid123@peppol.storecove.com
FB_fall.back?example.com@peppol.storecove.com

are all valid destinations.

If you have multiple destinations (which is the rule, not the exception) then you have two options:

  • Local part packing

  • Carbon copying

The first method packs all the identifiers into the email address’ local part, which is the part of the email address before the ‘@’ sign. The second sends the email to a single TO: address and one or more CC: addresses. Each is discussed in more detail below.

4.4.1. Local Part Packing

The TO: email address contains the different identifiers that you have for your Customer, separated by a pipe (‘|’) symbol.

A complete email address may look like

TO: WI_YourId123|NL_KVK.59846933|FB_fall.back?example.com@peppol.storecove.com

Note that you can provide multiple PEPPOL identifiers.

The drawback of this method is that the local part (everything before the @peppol.storecove.com) can only be a maximum of 64 characters. This normally does not pose problems, unless you have a very long Widget Identifier, uncommonly many PEPPOL identifiers, or provide a fallback email address.

For these reasons, we recommend using the Carbon Copy method when a Widget Identifier or fallback email address is used.

4.4.2. Carbon Copying

When carbon copying, you provide one TO: address and multiple CC: addresses. For instance

TO: WI_YourId123@peppol.storecove.com
CC: NL_KVK.59846933@black.storecove.com
CC: FB_fall.back?example.com@black.storecove.com

Note the domain “black.storecove.com”. Do not CC: to “peppol.storecove.com” because your invoices will be processed multiple times.

4.5. Attachments

4.5.1. Data

For regulatory reasons, the invoice data cannot be extracted from the PDF. Therefore, you need to provide an attachment with the data contained in the invoice.

You can attach a UBL 2.0 or UBL 2.1 invoice. Even if these are not 100% compliant, we can probably process them. Contact us on helpdesk@storecove.com for a test.

Another format is the JSON structure used in the API, in an attachment with a filename that ends in ‘.json’.

{
  "invoice": {
    "invoiceNumber": "201610001",
    "issueDate": "2016-08-08",
    "documentCurrencyCode": "EUR",
    "accountingCustomerParty": {
      "party": {
        "companyName": "ManyMarkets Inc.",
        "address": {
          "street1": "Keizersgracht",
          "number": "316",
          "city": "Amsterdam",
          "zip": "1016EZ",
          "country": "NL"
        }
      }
    },
    "invoiceLines": [
      {
        "description": "Pilot G2 Premium Retractable Gel Roller Pens, Bold Point, Blue, 12/Pack (31257)",
        "amountExcludingVat": 8.07,
        "tax": {
          "amount": 1.69,
          "percentage": 21,
          "country": "NL"
        }
      },
      {
        "description": "Elmer's Clear Glue Stick Class Pack, .24oz, 30/Pack",
        "amountExcludingVat": 14.88,
        "tax": {
          "amount": 3.12,
          "percentage": 21,
          "country": "NL"
        }
      }
    ],
    "amountIncludingVat": 27.77
  }
}

If you wish to provide a different format this is possible, but please first contact us on helpdesk@storecove.com.

4.5.2. PDF

If you have a PDF image of the invoice, you can provide it as an attachment. This attachment’s filename should end in ‘.pdf’. If you do not have a PDF to attach, just leave it out.

5. API Ingestion

5.1. Introduction

We support the following workflows:

  1. Check and submit

  2. Submit and email

  3. Pull mode

5.1.1. Check and Submit

First use the

Preflight an invoice recipient

API call. It takes one parameter, an InvoiceRecipient object. This object contains the ids of the recipient of the invoice. When you call this endpoint, Storecove will:

  1. Query the European PEPPOL network (SimplerInvoicing in The Netherlands) whether the Customer has registered with this network.

  2. Check if the invoice is for an organization that has enabled one or more destinations in Storecove (setting these destinations is done through the Storecove Widget discussed in section Destination Configuration).

If the result code is ‘ok’, submit the invoice via the

Submit a new invoice

API call.

5.1.2. Submit and Email

When you call this endpoint, Storecove will:

  1. Query the European PEPPOL network (SimplerInvoicing in The Netherlands) whether the Customer has registered with this network. If so, the invoice is delivered via PEPPOL.

  2. Check if the invoice is for an organization that has enabled one or more destinations in Storecove (setting these destinations is done through the Storecove Widget discussed in section Destination Configuration). If so, the invoice is delivered to these destinations.

  3. If the invoice was not delivered through any of these methods, and a fallback email address is provided, the invoice is delivered via the fallback email address.

  4. If no action could be taken, you will receive an appropriate response to indicate this.

5.1.3. Pull Mode

In pull mode, you provide an API that Storecove uses to retrieve new invoices. We will periodically poll for new invoices, providing a timestamp to filter so as only to receive new invoices. From the returned list we will then determine which of these can be sent via PEPPOL/SimplerInvoicing or a Storecove destination.

If you wish to use pull mode, please contact us on helpdesk@storecove.com or +31.202611791.

5.2. Summary

The following is a list of items that you need to work with the Storecove invoice_submissions API:

Item Description Source

Two Storecove accounts

A development and a production account with API access and the “supplier” package. You will receive one of the items below for each account.

You can self-register, but Storecove will then configure the accounts for you. After self-registering, contact us.

supplierId

The id that identifies you.

Available in the web interface

legalSupplierId

If you have multiple sender identities, you need this.

Available in the web interface

token

The token to use in the Authentication header when doing API calls.

Create your own in the web interface

6. Destination Configuration

6.1. Introduction

If your Customer is a member of the PEPPOL/SimplerInvoicing network and you have one or more PEPPOL identifiers for the Customer, this Customer will automatically receive their invoices through the PEPPOL network without any setup necessary on their part.

In many cases, your Customer will not (yet) be a member of the PEPPOL/Simplerinvoicing network and in that case the Storecove Widget will allow your Customer to configure where they want their invoices sent, from inside your website.

6.2. Tag

The widget is included in a page via a script tag:

<script type="text/javascript">
  window.storecove = {
    scope: 'supplier/settings',
    version: '1',
    locale: 'nl',
    applicationKey: '<Storecove will provide this>',
    jwt: '<see below>',
    elementId: 'storecove_widget',
    errorCallback: function(code, text) {
      document.getElementById('storecove_widget').innerHTML = 'An error
occurred, status ' + code + ' , body ' + text
    }
  };
  !function() {
    var s = document.createElement('script');
    s.async = true;
    s.src = 'https://www.storecove.com/widgets/v' + window.storecove.version + '/bootloader.js';
    document.getElementsByTagName('head')[0].appendChild(s);
  }();
</script>

Please note that the errorCallback function reports information useful for debugging, but in production environment you will want to display a more non-descript error.

6.2.1. elementId

The above tag will instantiate the widget in the element with id ‘storecove_widget’. The widget will run in an <iframe/> element that is responsive and takes 100% of the available width. The height should be at least 600px.

6.2.2. locale

The widget will be presented in the locale that you provide. We currently support ‘nl’ and ‘en’. If you provide a non-existent locale, a 404 will be the result.

6.2.3. applicationKey

The applicationKey is a GUID that will be provided to you by Storecove.

6.2.4. errorCallback

Should something go wrong loading the widget, this function is called.

6.3. JWT

The jwt field is a Json Web Token (JWT). Through this token you certify to Storecove that your user is signed in, that the information provided in the token is correct and that your user is authorized for the information in the token.

A JWT consists of three sections:

  1. Header

  2. Claims

  3. Signature

The header contains token meta-data and the signature (created with a secret key provided by Storecove) ensures it was created by you and only you. This way, you effectively guarantee that the data (sent in the Claims section) is correct. The JWT for the Storecove widget should contain the following information in the Claims section:

data = {
    user: {
        company_name: '…',
        first_name: '…',
        last_name: '…',
        email: '…'
    },
    company: {
        public_ids: [
            {
                scheme: '…',
                id: '…'
            },
        id: '…'
        ]
    }
}

The work that you, as a developer, need to do is to collect this data. To create the actual JWT, you should have a library do the heavy lifting. There are many libraries available, for all platforms, a comprehensive list can be found on:

https://jwt.io

The data fields have the following meaning.

6.3.1. user

The information in the user object is used during the initial registration process. After that it is ignored. The registration screen looks as follows:

Note that the company_name field will typically be the name of the company the user represents (see below), however this company name does not affect the addressing of invoices that you send.

Although the user information is not mandatory (the screen will simply show empty fields if not available), we ask that you do provide whatever information you have, as it makes the registration process much easier for the user.

6.3.2. company

The company object contains the following items:

public_ids

A list of ids used in the public realm to identify this company. Most used are the chamber of commerce number and the VAT number. Also, because banks verify a legal entity when opening a bank account, IBAN numbers are used as company identifiers. Dutch government entities use an OIN number.

Please provide as many as you have, especially chamber of commerce and VAT. Public identifiers are used to identify the company on the PEPPOL/SimplerInvoicing network.

If you don’t have any of these available, provide an empty array. The widget will still function without them and you can always add them in the future.

id

The id that you use to identify this organization. If the company does not accept invoices via the PEPPOL/SimplerInvoicing network (or no registered public identifier was provided), Storecove will use this id to check whether the company has created one or more invoice destinations in the Storecove eInvoicing Widget.

The information in company object is used every time the widget is shown. The public identifiers are used to determine whether or not the user needs to configure invoice destinations in the widget (if the public identifier is known on the PEPPOL/SimplerInvoicing there is no need to configure anything and the widget will say so). The id is used to determine for which Storecove user to show the widget.

The full list of public identifier schemes is as follows:

Scheme Description

AD:VAT

Andorra VAT number

AL:VAT

Albania VAT number

AT:CID

Firmenidentifikationsnummer der Statistik Austri

AT:GOV

Österreichisches Verwaltungs bzw. Organisationskennzeichen

AT:KUR

Kennziffer des Unternehmensregisters

AT:VAT

Österreichische Umsatzsteuer-Identifikationsnummer

BA:VAT

Bosnia and Herzegovina VAT number

BE:VAT

Belgium VAT number

BG:VAT

Bulgaria VAT number

CH:VAT

Switzerland VAT number

CY:VAT

Cyprus VAT number

CZ:VAT

Czech Republic VAT number

DE:VAT

Germany VAT number

DK:CPR

Danish Ministry of the Interior and Health

DK:CVR

The Danish Commerce and Companies Agency

DK:P

Danish Chamber of Commerce

DK:SE

Danish Ministry of Taxation, Central Customs and Tax Administration

DK:VANS

Danish VANS providers

DUNS

Dun and Bradstreet Ltd

EE:VAT

Estonia VAT number

ES:VAT

Agencia Española de Administración Tributaria

EU:REID

Business Registers Network

EU:VAT

National ministries of Econom

FI:OVT

National Board of Taxes, (Verohallitus)

FR:SIRENE

Institut National de la Statistique et des Etudes Economiques, (I.N.S.E.E.)

FR:SIRET

DU PONT DE NEMOURS

GB:VAT

United Kingdom VAT number

GLN

GS1

GR:VAT

Greece VAT number

HR:VAT

Croatia VAT number

HU:VAT

Hungary VAT

IBAN

SOCIETY FOR WORLDWIDE INTERBANK FINANCIAL, TELECOMMUNICATION S.W.I.F.T

IE:VAT

Ireland VAT number

IS:KT

Icelandic National Registry

IT:CF

TAX Authority

IT:FTI

FTI - Ediforum Italia

IT:IPA

Indice delle Pubbliche Amministrazioni

IT:SECETI

Servizi Centralizzati SECETI S.p.A.

IT:SIA

SIA-Società Interbancaria per l’Automazione S.p.A.

IT:VAT

Ufficio responsabile gestione partite IVA

LI:VAT

Liechtenstein VAT number

LT:VAT

Lithuania VAT number

LU:VAT

Luxemburg VAT number

LV:VAT

Latvia VAT number

MC:VAT

Monaco VAT number

ME:VAT

Montenegro VAT number

MK:VAT

Macedonia, the former Yugoslav Republic of VAT number

MT:VAT

Malta VAT number

NL:OIN

Dutch ‘OIN’ number

NL:KVK

Vereniging van Kamers van Koophandel en Fabrieken in Nederland

NL:VAT

Netherlands VAT number

NO:ORGNR

Enhetsregisteret ved Bronnoysundregisterne

NO:VAT

Enhetsregisteret ved Bronnoysundregisterne

PL:VAT

Poland VAT number

PT:VAT

Portugal VAT number

RO:VAT

Romania VAT number

RS:VAT

Serbia VAT number

SE:ORGNR

The National Tax Board

SE:VAT

Swedish VAT number

SI:VAT

Slovenia VAT number

SK:VAT

Slovakia VAT number

SM:VAT

San Marino VAT number

TR:VAT

Turkey VAT number

VA:VAT

Holy See (Vatican City State) VAT number

6.4. JWT Signature

How to create your JWT with signature depends on the library that you use. But regardless of which library you use, you will always need to provide a number of items to it. In Ruby, the following creates the JWT for Storecove:

iat = Time.now.to_i
payload = {
  data: JSON.generate(data),
  encryption: 'none',
  iss: request.domain,
  exp: iat + 24 * 3600,
  nbf: iat,
  aud: 'storecove.com/widgets',
  sub: 'applicationKey (provided by Storecove)',
  iat: iat
}
jwt = JWT.encode payload, 'shared secret (provided by Storecove)', 'HS256'

The data is transformed into a JSON string. Encryption is set to ‘none’, since this data is only exchanged in the context of your user being signed in, so there is nothing secret about this data.

The ‘iss’ (issuer) field is the domain of the site the widget is running in. Don’t use the hostname or include protocol - set just the domain (e.g. ‘example.com’, ‘example.co.uk’). Note that the domain needs to be whitelisted.

The ‘exp’ (expiry) field determines how long the JWT is valid for. 24 hours is a good number. This allows the user to keep the page open for a while and return to it later without encountering problems.

The ‘nbf’ (not before) field says the JWT is not valid in the past. Which makes sense…

The ‘aud’ (audience) field is a fixed string, ‘storecove.com/widgets’.

The ‘sub’ (subject) field is the applicationKey that Storecove provides you with. It is the same applicationKey used in the <script/> tag to instantiate the widget.

The ‘iat’ (issued at) is the current unix time in seconds in UTC. If your server is in the wrong timezone, you are likely to run into problems. Also, your server should run ntp or in some other form ensure the datetime setting is not off by more than a few seconds. We do allow for leeway, but not much.

The shared secret is provided to you by Storecove.

The generated jwt is a string that can be directly placed in the jwt field of the <script/> tag that instantiates the widget.

6.5. Summary

If you use the Storecove Widget, you will neeed the following items:

Item Description Source

applicationKey

The id that identifies your widget.

Provided by Storecove

sharedSecret

The shared secret used to sign the JWT with.

Provided by Storecove

7. Resources

7.1. InvoiceSubmissions

7.1.1. Submit a new invoice

POST /invoice_submissions
Description

Submit an invoice for delivery.

TODO

The following contains most fields possible.

invoice_submission = StorecoveApi::InvoiceSubmission.new(
  mode: 'direct',
  supplierId: 1234567890,
  documentUrl: 'https://storecove.com/downloads/partner_manual.pdf',
  invoiceRecipient: StorecoveApi::InvoiceRecipient.new(id: @external_id_dev_support),
  invoice: StorecoveApi::Invoice.new(
    invoiceNumber: '201610001',
    issueDate: '2016-08-08',
    documentCurrencyCode: 'EUR',
    accountingCustomerParty: StorecoveApi::AccountingCustomerParty.new(
      party: StorecoveApi::Party.new(
        companyName: 'ManyMarkets Inc.',
        address: StorecoveApi::Address.new(
          department: 'Main Office',
          street1: 'Keizersgracht',
          number: '316',
          city: 'Amsterdam',
          zip: '1016EZ',
          country: 'NL'
        ),
        contact: StorecoveApi::Contact.new(
          firstName: 'Norm',
          lastName: 'Peters',
          email: 'norm@peters.example.com'
        ),
        accountId: 'SupplierAccountCode1234'
      )
    ),
    invoiceLines: [
      StorecoveApi::InvoiceLine.new(
        description: 'Pilot G2 Premium Retractable Gel Roller Pens, Bold Point, Blue, 12/Pack (31257)',
        id: 'ccvvffgg',
        itemPrice: 2.69,
        quantity: 3,
        amountExcludingVat: 8.07,
        tax: StorecoveApi::Tax.new(
          amount: 1.69,
          percentage: 21,
          country: 'NL'
        ),
        accountingCostCode: StorecoveApi::AccountingCostCode.new(
          code: '4206010',
          list: 'RGS',
          listVersion: '1.1',
          listAgency: 'SBR'
        ),
        invoicePeriod: '2016-07-01 - 2016-07-15'
      ),
      StorecoveApi::InvoiceLine.new(
        description: 'Elmer\'s Clear Glue Stick Class Pack, .24oz, 30/Pack',
        id: 'xxaabbcc',
        itemPrice: 4.8,
        quantity: 3.1,
        amountExcludingVat: 14.88,
        tax: StorecoveApi::Tax.new(
          amount: 3.12,
          percentage: 21,
          country: 'NL'
        ),
        accountingCostCode: StorecoveApi::AccountingCostCode.new(
          code: '4206011',
          list: 'RGS',
          listVersion: '1.1',
          listAgency: 'SBR'
        ),
        invoicePeriod: '2016-07-16 - 2016-07-31'
      )
    ],
    amountIncludingVat: 27.77,
    accountingCostCode: StorecoveApi::AccountingCostCode.new(
      code: '4206012',
      list: 'RGS',
      listVersion: '1.1',
      listAgency: 'SBR'
    ),
    dueDate: '2016-09-07',
    invoiceType: '380',
    invoicePeriod: '2016-07-01 - 2016-07-31',
    taxPointDate: '2016-08-08', # note: in some countries, like NL, this MUST match the issueDate
    buyerReference: 'a1234567',
    orderReference: 'b1234567',
    billingReference: 'c1234567',
    contractDocumentReference: 'd1234567',
    projectReference: 'e1234567',
    paymentMeansCode: nil,
    paymentMeansIban: 'NL00ABNA0123456789',
    paymentMeansPaymentId: '201610001 / XXXXX'
  )
)
begin
  client = StorecoveApiClient.new
  invoice_submission_result = client.invoice_submissions.create_invoice_submission(invoice_submission)
rescue StorecoveApi::ApiError => e
  # handle error - best use a queue manager!
  puts e.code
end

puts invoice_submission_result.guid

The following example contains only the mandatory fields.

invoice_submission = StorecoveApi::InvoiceSubmission.new(
  mode: 'direct',
  supplierId: 1234567890,
  invoiceRecipient: StorecoveApi::InvoiceRecipient.new(id: @external_id_dev_support),
  invoice: StorecoveApi::Invoice.new(
    invoiceNumber: '201610001',
    issueDate: '2016-08-08',
    documentCurrencyCode: 'EUR',
    accountingCustomerParty: StorecoveApi::AccountingCustomerParty.new(
      party: StorecoveApi::Party.new(
        companyName: 'ManyMarkets Inc.',
        address: StorecoveApi::Address.new(
          country: 'NL'
        )
      )
    ),
    invoiceLines: [
      StorecoveApi::InvoiceLine.new(
        description: 'Pilot G2 Premium Retractable Gel Roller Pens, Bold Point, Blue, 12/Pack (31257)',
        amountExcludingVat: 8.07,
        tax: StorecoveApi::Tax.new(
          amount: 1.69,
          percentage: 21,
          country: 'NL'
        )
      ),
      StorecoveApi::InvoiceLine.new(
        description: 'Elmer\'s Clear Glue Stick Class Pack, .24oz, 30/Pack',
        amountExcludingVat: 14.88,
        tax: StorecoveApi::Tax.new(
          amount: 3.12,
          percentage: 21,
          country: 'NL'
        )
      )
    ],
    amountIncludingVat: 27.77
  )
)
Parameters
Type Name Description Schema

Body

invoice_submission
required

Invoice to submit

InvoiceSubmission
Responses
HTTP Code Description Schema

200

Success

InvoiceSubmissionResult

401

Unauthorized

No Content

403

Forbidden

No Content

422

Unprocessable Entity

< ErrorModel > array
Consumes

  • application/json

7.1.2. Preflight an invoice recipient

POST /invoice_submissions/preflight
Description

Check whether Storecove can deliver an invoice for a list of ids.

TODO
invoice_recipient_preflight = StorecoveApi::InvoiceRecipientPreflight.new(
    supplierId: @shop.id,
    invoiceRecipient: StorecoveApi::InvoiceRecipient.new(
        publicIdentifiers: [
            StorecoveApi::PublicIdentifier.new(
                id: '810418052',
                scheme: 'NO:ORGNR'
            )
        ]
    )
)
client = StorecoveApiClient.new
begin
    preflight_invoice_recipient_result = client.preflight_invoice_recipient(invoice_recipient_preflight)
rescue StorecoveApi::ApiError => e
    # handle error - best use a queue manager!
    puts e.code
end

puts preflight_invoice_recipient_result.code # will be 'ok' or 'nok'
Parameters
Type Name Description Schema

Body

invoice_recipient_preflight
required

The invoice recipient to preflight

InvoiceRecipientPreflight
Responses
HTTP Code Description Schema

200

Success

PreflightInvoiceRecipientResult

401

Unauthorized

No Content

403

Forbidden

No Content

422

Unprocessable Entity

< ErrorModel > array
Consumes

  • application/json

7.2. ShopAccountRequests

7.2.1. Create ShopAccountRequest

POST /shop_account_requests
Description

Create a new ShopAccountRequest

TODO
shop_account_request_input = StorecoveApi::ShopAccountRequestInput.new
shop_account_request_input.username = 'username'
shop_account_request_input.password = 'secret'
shop_account_request_input.request_name = 'Storecove'
shop_account_request_input.password = 'https:/www.storecove.com/'
shop_account_request_input.external_user_id = '<your entity id>'
client = StorecoveApiClient.new
begin
    shop_account_request_result = client.shop_account_requests.create_shop_account_request(shop_account_request_input)
rescue StorecoveApi::ApiError => e
    # handle error - best use a queue manager!
    puts e.code
end
Parameters
Type Name Description Schema

Body

shop_account_request
required

ShopAccountRequest to add

ShopAccountRequestInput
Responses
HTTP Code Description Schema

200

Success

ShopAccountRequestResult

401

Unauthorized

No Content

403

Forbidden

No Content

422

Unprocessable Entity

< ErrorModel > array
Consumes

  • application/json

7.2.2. Get ShopAccountRequests

GET /shop_account_requests
Description

Retrieve all active ShopAccountRequests for one of your entities.

TODO
client = StorecoveApiClient.new
shop_account_requests = client.shop_account_requests.shop_account_requests_index('your_entity_id')
Parameters
Type Name Description Schema

Query

external_user_id
required

Filter by the external_user_id

string
Responses
HTTP Code Description Schema

200

Success

< ShopAccountRequestResult > array

401

Unauthorized

No Content

403

Forbidden

No Content

7.2.3. Get ShopAccountRequest

GET /shop_account_requests/{id}
Description

Show a specific ShopAccountRequest

TODO
client = StorecoveApiClient.new
shop_account_request = client.shop_account_requests.get_shop_account_request(1234567890)
Parameters
Type Name Description Schema

Path

id
required

shop_account_request id

integer(int32)
Responses
HTTP Code Description Schema

200

Success

ShopAccountRequestResult

401

Unauthorized

No Content

403

Forbidden

No Content

7.2.4. Delete ShopAccountRequest

DELETE /shop_account_requests/{id}
Description

Delete a specific ShopAccountRequest

TODO
client = StorecoveApiClient.new
begin
    client.shop_account_requests.delete_shop_account_request(1234567890)
rescue StorecoveApi::ApiError => e
    # handle error - best use a queue manager!
end
Parameters
Type Name Description Schema

Path

id
required

shop_account_request id

integer(int32)
Responses
HTTP Code Description Schema

204

Success

No Content

401

Unauthorized

No Content

403

Forbidden

No Content

7.2.5. Update ShopAccountRequest

PATCH /shop_account_requests/{id}
Description

Update a specific ShopAccountRequest

TODO
shop_account_request_update = StorecoveApi::ShopAccountUpdate.new
shop_account_request_update.username = 'newusername'
shop_account_request_update.password = 'newsecret'
shop_account_request_update.email = 'newsendto@example.com'
client = StorecoveApiClient.new
begin
    shop_account_request_result = client.shop_account_requests.update_shop_account_request(shop_account_request_update)
rescue StorecoveApi::ApiError => e
    # handle error - best use a queue manager!
    puts e.code
end
Parameters
Type Name Description Schema

Path

id
required

shop_account_request id

integer(int32)

Body

shop_account_request
required

ShopAccountRequest updates

ShopAccountRequestUpdate
Responses
HTTP Code Description Schema

200

Success

ShopAccountRequestResult

401

Unauthorized

No Content

403

Forbidden

No Content

422

Unprocessable Entity

< ErrorModel > array

7.3. ShopAccounts

7.3.1. Create ShopAccount

POST /shop_accounts
Description

Create a new ShopAccount.

TODO
shop_account_input = StorecoveApi::ShopAccountInput.new
shop_account_input.username = 'username'
shop_account_input.password = 'secret'
shop_account_input.shop_id = 123456789
shop_account_input.external_user_id = 'your_user_id'
shop_account_input.email = 'sendto@example.com'
client = StorecoveApiClient.new
begin
    shop_account_result = client.shop_accounts.create_shop_account(shop_account_input)
rescue StorecoveApi::ApiError => e
    # handle error - best use a queue manager!
    puts e.code
end
Parameters
Type Name Description Schema

Body

shop_account
required

ShopAccount to add

ShopAccountInput
Responses
HTTP Code Description Schema

200

Success

ShopAccountResult

401

Unauthorized

No Content

403

Forbidden

No Content

422

Unprocessable Entity

< ErrorModel > array
Consumes

  • application/json

7.3.2. Get ShopAccounts for an entity

GET /shop_accounts
Description

Retrieve all active ShopAccounts for one of your entities.

TODO
client = StorecoveApiClient.new
shop_accounts = client.shop_accounts.shop_accounts_index('your_entity_id')
Parameters
Type Name Description Schema

Query

external_user_id
required

Filter by the external_user_id

string
Responses
HTTP Code Description Schema

200

Success

< ShopAccountResult > array

401

Unauthorized

No Content

403

Forbidden

No Content

7.3.3. Get ShopAccounts with authorization failures

GET /shop_accounts/auth_failures
Description

Get ShopAccounts with authorization failures.

TODO
client = StorecoveApiClient.new
shop_accounts = client.shop_accounts.shop_accounts_auth_failures
Responses
HTTP Code Description Schema

200

Success

< ShopAccountResult > array

401

Unauthorized

No Content

403

Forbidden

No Content

7.3.4. Get ShopAccount

GET /shop_accounts/{id}
Description

Get a specific ShopAccount.

TODO
client = StorecoveApiClient.new
shop_account = client.shop_accounts.get_shop_account(1234567890)
Parameters
Type Name Description Schema

Path

id
required

shop_account id

integer(int32)
Responses
HTTP Code Description Schema

200

Success

ShopAccountResult

401

Unauthorized

No Content

403

Forbidden

No Content

7.3.5. Delete ShopAccount

DELETE /shop_accounts/{id}
Description

Delete a specific ShopAccount.

TODO
client = StorecoveApiClient.new
begin
    client.shop_accounts.delete_shop_account(1234567890)
rescue StorecoveApi::ApiError => e
    # handle error - best use a queue manager!
end
Parameters
Type Name Description Schema

Path

id
required

shop_account id

integer(int32)
Responses
HTTP Code Description Schema

204

Success

No Content

401

Unauthorized

No Content

403

Forbidden

No Content

7.3.6. Update ShopAccount

PATCH /shop_accounts/{id}
Description

Update a specific ShopAccount.

TODO
shop_account_update = StorecoveApi::ShopAccountUpdate.new
shop_account_update.username = 'newusername'
shop_account_update.password = 'newsecret'
shop_account_update.email = 'newsendto@example.com'
client = StorecoveApiClient.new
begin
    shop_account_result = client.shop_accounts.update_shop_account(shop_account_update)
rescue StorecoveApi::ApiError => e
    # handle error - best use a queue manager!
    puts e.code
end
Parameters
Type Name Description Schema

Path

id
required

shop_account id

integer(int32)

Body

shop_account
required

ShopAccount updates

ShopAccountUpdate
Responses
HTTP Code Description Schema

200

Success

ShopAccountResult

401

Unauthorized

No Content

403

Forbidden

No Content

422

Unprocessable Entity

< ErrorModel > array

7.4. Shops

7.4.1. Get Shops

GET /shops
Description

Get all available shops.

curl -X GET --header 'Accept: application/json' --header 'Authorization: <api_key>' 'https://api.storecove.com/api/v2/shops'

Response:

[
  {
    "id": 0,
    "name": "string",
    "logo": {
      "thumb": "string",
      "small": "string",
      "medium": "string"
    },
    "description": "string",
    "legal_entities": [
      {
        "name": "string",
        "line1": "string",
        "zip": "string",
        "city": "string",
        "county": "string",
        "country": "string",
        "identifiers": [
          {
            "identifier": "string",
            "scheme": "string",
            "scheme_agency": "string"
          }
        ]
      }
    ]
  }
]
client = StorecoveApiClient.new
shops = client.shops.shops_index
Responses
HTTP Code Description Schema

200

Success

< Shop > array

401

Unauthorized

No Content

8. Definitions

8.1. AccountingCostCode

The code in the chart of accounts used by the receiver of the invoice.

Name Description Schema

code
optional

Minimum length : 1

string

list
optional

Minimum length : 1

string

listAgency
optional

Minimum length : 1

string

listVersion
optional

Minimum length : 1

string

8.2. AccountingCustomerParty

The customer receiving the invoice.

Name Description Schema

accountId
optional

The account id you assigned to the customer.

string

party
required

Party

8.3. Country

An ISO 3166-1 alpha-2 country code.

Type : enum (AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW)

8.4. CurrencyCode

The ISO 4217 currency code.

Type : enum (AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, BWP, BYN, BYR, BZD, CAD, CDF, CHE, CHF, CHW, CLF, CLP, CNY, COP, COU, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MXV, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SRD, SSP, STD, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, USN, UYI, UYU, UZS, VEF, VND, VUV, WST, XAF, XAG, XAU, XBA, XBB, XBC, XBD, XCD, XDR, XFU, XOF, XPD, XPF, XPT, XSU, XTS, XUA, XXX, YER, ZAR, ZMW)

8.5. ErrorModel

Name Schema

details
optional

string

source
optional

string

8.6. InvoiceLine

Name Description Schema

accountingCostCode
optional

AccountingCostCode

amountExcludingVat
required

The amount excluding VAT. Should equal quantity x itemPrice (if these are both present). A difference of 5 cents or 1% between the calculated value and the provided value is allowed.

number

description
required

The description for this invoice line.
Minimum length : 1

string

groupArticlegroupAccount
optional

The articlegroup account number.
Minimum length : 1

string

groupArticlegroupCode
optional

The articlegroup code.
Minimum length : 1

string

groupArticlegroupDescription
optional

The description of the acticlegroup.
Minimum length : 1

string

groupCustomerAccount
optional

The account number the customer assigned to this customer code.
Minimum length : 1

string

groupCustomerCode
optional

The code the customer gave this item.
Minimum length : 1

string

groupCustomerDescription
optional

The description for the code the customer gave this item.
Minimum length : 1

string

groupNziAccount
optional

The NZI account number.
Minimum length : 1

string

groupNziCode
optional

The NZI (Nationale Zorg Instelling) code.
Minimum length : 1

string

groupNziDescription
optional

The description of the NZI code.
Minimum length : 1

string

id
optional

Your id for this invoice line.
Minimum length : 1

string

imageUrl
optional

A URL to an image for the product in the invoice line.

string(uri)

invoicePeriod
optional

The period (or specific date) to which the invoice line applies. Format: yyyy-mm-dd - yyyy-mm-dd.
Pattern : "^[0-9]{4}-[0-9]{2}-[0-9]{2} - [0-9]{4}-[0-9]{2}-[0-9]{2}$"

string

itemPrice
optional

The price per item (may be fractional)

number

quantity
optional

The number of items (may be fractional).

number

tax
optional

The tax for this invoice line.

Tax

Tax

Name Description Schema

amount
required

The amount of VAT. Should equal percentage x amountExcludingVat. A difference of 5 cents or 1% between the calculated value and the provided value is allowed.

number

country
required

Country

percentage
required

The percentage VAT. This should be a valid VAT percentage in the country at the time of the issueDate of this invoice.

number

8.7. InvoiceRecipient

Ids that identify this invoice recipient. The list of identifiers should match with the accountingCustomerParty. I.e., you should not be sending an invoice for one accountingCustomerParty to the publicIdentifier of another.

Name Description Schema

fallbackEmail
optional

The email address the invoice should be sent to if none of the other identifiers can be used

string(email)

id
optional

Your id for this organization. This should match the id that you use for the Storecove widget (if you use that).
Minimum length : 2

string

publicIdentifiers
optional

The public identifiers for this invoice recipient. Either an id, or one or more public identifiers must be given

PublicIdentifiers

8.8. InvoiceRecipientPreflight

Identifies the invoice recipient to preflight

Name Description Schema

invoiceRecipient
required

InvoiceRecipient

supplierId
required

The supplier id, provided by Storecove.

integer

8.9. InvoiceSubmission

The invoice you want Storecove to process, with some meta-data.

Name Description Schema

document
optional

The invoice in PDF form. The document should be base64 encoded and the enocded string length should not exceed 2MB (2097152 bytes).
Minimum length : 5

string

documentUrl
optional

A URL to retrieve the PDF document via HTTP GET. If the link expires, please allow at least 7 days of validity.

string(uri)

invoice
required

The invoice to send

Invoice

invoiceRecipient
required

InvoiceRecipient

legalSupplierId
optional

If a supplierId has more than one legal entity to send invoices from, specify the legal entity here. If you have not received one or more legal entities, don’t supply this field.

integer

mode
required

The mode in which to run this invoice submission.

enum (direct)

supplierId
required

The supplier id, provided by Storecove.

integer

Invoice

Name Description Schema

accountingCostCode
optional

AccountingCostCode

accountingCustomerParty
required

The receiving party

AccountingCustomerParty

amountIncludingVat
required

amountIncludingVat is important because of rounding differences. In many invoices, the sum of the line item amounts excluding VAT and the VAT amounts is not equal to first summing the line items without VAT, and then applying VAT. The difference is automatically calculated and included in the electronic invoice, so the receiving accounting package can process the electronic invoice without problems.

number

billingReference
optional

A reference to a commercial invoice or corrective invoice of which the current invoice is a correction.

string

buyerReference
optional

A reference provided by the buyer used for internal routing of the document.

string

contractDocumentReference
optional

A reference to a contract or framework agreement that this invoice relates to.

string

documentCurrencyCode
optional

The documentCurrencyCode is the currency for the entire invoice. We currently do not support invoices in multiple currencies. If left out, will default to EUR

CurrencyCode

dueDate
optional

Format: yyyy-mm-dd.
Pattern : "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"

string

invoiceLines
required

An array of invoice lines.

< InvoiceLine > array

invoiceNumber
required

The invoice number you assigned to the invoice. The invoiceNumber should be unique for the supplierId and year of the issueDate. This means invoice numbers can be reused in different years, as is customary in some countries.
Minimum length : 1

string

invoicePeriod
optional

The period (or specific date) to which the invoice applies. Format: yyyy-mm-dd - yyyy-mm-dd.
Pattern : "^[0-9]{4}-[0-9]{2}-[0-9]{2} - [0-9]{4}-[0-9]{2}-[0-9]{2}$"

string

invoiceType
optional

Use 380 for a regular invoice, 384 for a Corrective invoice.
Default : "380"

enum (380, 384)

issueDate
required

Format: yyyy-mm-dd.
Pattern : "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"

string

orderReference
optional

A reference to an order for this invoice.

string

paymentMeansCode
optional

Leave empty. Defaults to 31 if an IBAN is provided, otherwise defaults to 1. But leave empty.

string

paymentMeansIban
optional

The IBAN the amount payable should be transferred to

string

paymentMeansPaymentId
optional

The payment id that you will use to match the payment against the invoice.

string

projectReference
optional

Information about the project this invoice relates to.

string

taxPointDate
optional

The tax date is the date on which the supply of goods or of services was made or completed or the date on which the payment on account was made insofar as that date can be determined and differs from the date of the issue of the invoice. EU 2006-112 Article 226 Point 7. Note: For the Dutch TAX authorities the tac date should be the same as the issue date.
Pattern : "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"

string

vatReverseCharge
optional

Whether or not the invoice is reverse charged
Default : false

boolean

8.10. InvoiceSubmissionResult

The result of an invoice submission

Name Description Schema

guid
optional

A (V4) GUID for the invoice submission

string

8.11. LegalEntity

Name Schema

city
optional

string

country
optional

string

county
optional

string

identifiers
optional

< LegalEntityIdentifier > array

line1
optional

string

line2
optional

string

name
optional

string

zip
optional

string

8.12. LegalEntityIdentifier

Name Schema

identifier
optional

string

scheme
optional

string

scheme_agency
optional

string

8.13. Logos

Name Schema

medium
optional

string

small
optional

string

thumb
optional

string

8.14. Party

A party that can receive or send invoices

Name Description Schema

address
required

The company address

Address

companyName
required

The name of the company receiving the invoice
Minimum length : 2

string

contact
optional

The billing contact

Contact

Address

Name Description Schema

city
optional

The name of the city.
Minimum length : 2

string

country
required

Country

county
optional

An optional county name.

string

department
optional

The department the invoice is addressed to

string

number
optional

This number will be added to the street1 element. The number can be provided in this field OR in the street1 field, but not in both.

string

postbox
optional

The postbox number

string

street1
optional

The street name. The number can be provided in this fiedl OR in the number field, but not in both.
Minimum length : 2

string

street2
optional

The second street field. Use this if you used the first field for the building name.

string

zip
optional

The zipcode/postalzone.
Minimum length : 2

string

Contact

Name Schema

email
required

string(email)

firstName
optional

string

lastName
optional

string

8.15. PreflightInvoiceRecipientResult

The result of preflighting an invoice recipient

Name Description Schema

code
optional

The result code of the preflight request

enum (ok, nok)

8.16. PublicIdentifier

A public identifier for this customer.

Name Description Schema

id
required

The actual identifier.
Minimum length : 2

string

scheme
required

The scheme of the public identifier, e.g. chambre of commerce number (for The Netherlands: NL:KVK), VAT, IBAN, or NL:OIN (OIN is a Dutch government organizaton id). The full list can be found on https://joinup.ec.europa.eu/svn/peppol/TransportInfrastructure/PEPPOL_Policy%20for%20use%20of%20identifiers-300.pdf.
Minimum length : 3

string

8.17. PublicIdentifiers

A list of public identifiers that uniquely identifiy this customer.

Type : < PublicIdentifier > array

8.18. Shop

Name Schema

description
optional

string

id
optional

integer(int64)

legal_entities
optional

< LegalEntity > array

logo
optional

Logos

name
optional

string

8.19. ShopAccountInput

Name Description Schema

email
optional

This is email address determines where the invoices for all ShopAccounts in the same external_user_id group are sent. Each time you create or update a ShopAccount for an external_user_id and also provide email, the email destination for all the ShopAccounts in the external_user_id group are updated at the same time.

We suggest you provide an immutable email address. If your user can change the email address to which the invoices are to be sent, then you will need to do an update for one of the ShopAccounts for that user in order for Storecove to start using the new email address.

Note that this field is mandatory for the first ShopAccount that you create for an entity.

string

external_user_id
required

The external_user_id is what identifies the entity for which you create this ShopAccount. This could be a user, however, if your users can manage multiple organizations/administrations, then it is a better idea to put the organization/administration identifier in this field, because the external_user_id groups the ShopAccounts into a set that all deliver their invoices to the same destination (typically an email address).

string

password
required

The password for the account.

string

shop_id
required

The id of the Shop the account is for.

integer(int64)

username
required

The username for the account. The username needs to be unique in combination with the shop_id.

string

8.20. ShopAccountRequestInput

Name Schema

external_user_id
required

string

password
required

string

request_name
required

string

request_url
required

string

username
required

string

8.21. ShopAccountRequestResult

Name Schema

external_user_id
optional

string

id
optional

integer(int64)

request_name
optional

string

request_url
optional

string

username
optional

string

8.22. ShopAccountRequestUpdate

Name Schema

password
optional

string

request_name
optional

string

request_url
optional

string

username
optional

string

8.23. ShopAccountResult

Name Description Schema

email
optional

See ShopAccountInput.

string

external_user_id
optional

See ShopAccountInput.

string

from_date
optional

The date from invoices will be collected. This field defaults to the first day of the month the ShopAccount was created in.

string(date)

id
optional

The Storecove id for the ShopAccount

integer(int64)

shop
optional

See ShopAccountInput.

Shop

sign_in_error_confirmed
optional

Whether or not Storecove has detected and confirmed a sign-in failure. This field is reset to false each time a ShopAccount is updated and the username or password has changed.

boolean

sign_in_error_confirmed_at
optional

The date on which the sign-in error was confirmed.

string(date)

username
optional

See ShopAccountInput.

string

8.24. ShopAccountUpdate

Name Description Schema

email
optional

See ShopAccountInput.

string

password
optional

See ShopAccountInput.

string

username
optional

See ShopAccountInput.

string