InvoiceXpress API

Getting Started

Welcome to our API v2 in JSON. If you're reading this, let me guess, you need to issue invoices but don't want to lose focus from building a great solution and writing amazing code. Did we cover your scenario? Ok, great. Let's do this.

Quick Start:

  1. Sign up FREE for 30 days
  2. Get your API key
  3. Create an Invoice

If you're looking for the API v1 in XML, click here.


Authentication

In order to authenticate a user through our API, an API key must be used. All API endpoints are available via HTTPS. HTTP access is denied. Each API key authenticates a user inside an account, and it’s composed by arbitrary characters.

This key must be passed on the query string in each HTTPS request to authenticate the user. Although all endpoints are accessed through HTTPS, please keep this token as secure as possible in order to avoid third party’s to access your InvoiceXpress data.

We strongly recommend you re-generate your API key from time to time.

Example:

https://ACCOUNT_NAME.app.invoicexpress.com/invoices.json?api_key=API_KEY

You can find your ACCOUNT_NAME and API_KEY here: https://www.app.invoicexpress.com/users/api

On POST and PUT requests do not forget to specify on the Header:

"Content-Type: application/json; charset=utf-8"

Example Languages

In this API Documentation, you'll be able to quickly see and copy-paste code examples in various languages. The following languages are currently supported:

  • curl
  • Ruby
  • Node
  • Python
  • PHP
  • Go

Request Limits

You can perform up to 100 requests per minute for each Account. If you exceed this limit, you’ll get a 429 Too Many Requests response for subsequent requests.

We recommend you handle 429 responses so your integration retries requests automatically.


Change Log

2017, October 11

  • New endpoint: Create an Account for an existing user. Check it out here.

2017, September 28

  • Launch date of the API v2.

Error Codes & Responses

HTTP Status Codes

Code Text Description
200 OK Success!
201 Created Resource created successfully.
401 Access denied The API Key parameter is missing or is incorrectly entered.
404 Not Found The requested resource does not exist.
406 Not Acceptable The :document-id provided is in an invalid state.
422 Unprocessable Entity Some parameters were incorrect.

Possible errors for HTTP Status Code 422:

Invoices, Estimates, Guides and Purchase Orders

Send by Email

  • No content type or wrongly specified
  • Email: is an invalid email
  • Cc: is an invalid email
  • Bcc: is an invalid email

Create or Update

  • Items element should be of type array
  • Country Germani was not found
  • Retention must be a number between 0 and 99.99
  • Invoice items is invalid
  • Client is invalid
  • Due date must be later than date
  • Email must be an email address
  • Discount is not a number
  • Quantity must be a number greater than 0
  • Unit price must be a number
  • Unit kg is not included in the list of accepted units
  • Option to generate MB reference is set but no payment provider is configurated
  • Invoice has been settled so can't be changed anymore

Change State

  • Invalid state
  • Cancel message can't be blank

Clients

  • Name has already been taken
  • Client contact is invalid
  • Send options is not a number
  • Send options must be within 1 and 3
  • Preferred contact: email must be an email
  • Country Germani was not found

Accounts

  • Postal Code must have the following format DDDD-DDD
  • Email is invalid
  • Vat Number can't be changed
  • Vat Number is already used in another account
  • Terms and Conditions must be accepted

Items

  • Name has already been taken
  • Unit price can't be blank
  • Unit price is not a number
  • Unit kg is not included in the list of accepted units

Taxes

  • Name has already been taken
  • Value can't be blank
  • Value must be a number between 0 and 99.99
  • Tax region is empty
  • Tax region is not valid

Sequences

  • Serie has already been taken
  • The sequence name is invalid

SAF-T

  • That option is not available during the trial period, it becomes so only after the first payment.
  • There aren't any documents to export on the selected period.
  • Warning! There is required information missing from Company information. Before you export the SAF-T PT, please go to Company information and fill out the missing fields.
  • You need to send the month in the request body. ***

Appendix

IVA Exemption Codes

Code Description on the Invoice Where does it apply?
M01 Artigo 16.º n.º 6 alínea c) do CIVA Artigo 16.º n.º 6 alínea c) do CIVA
M02 Artigo 6.º do Decreto‐Lei n.º 198/90, de 19 de Junho Artigo 6.º do Decreto‐Lei n.º 198/90, de 19 de Junho
M03 Exigibilidade de caixa Decreto‐Lei n.º 204/97, de 9 de Agosto; Decreto‐Lei n.º 418/99, de 21 de Outubro; Lei n.º 15/2009, de 1 de Abril;
M04 Isento Artigo 13.º do CIVA Artigo 13.º do CIVA
M05 Isento Artigo 14.º do CIVA Artigo 14.º do CIVA
M06 Isento Artigo 15.º do CIVA Artigo 15.º do CIVA
M07 Isento Artigo 9.º do CIVA Artigo 9.º do CIVA
M08 IVA – Autoliquidação Artigo 2.º n.º 1 alínea i) do CIVA; Artigo 2.º n.º 1 alínea j) do CIVA; Artigo 6.º do CIVA; Artigo 2.º n.º 1 alínea l) do CIVA; Decreto‐Lei n.º 21/2007, de 29 de Janeiro; Decreto‐Lei n.º 362/99, de 16 de Setembro;
M09 IVA ‐ não confere direito a dedução Artigo 60.º CIVA; Artigo 72.º n.º 4 do CIVA;
M10 IVA – Regime de isenção Artigo 53.ºdo CIVA
M11 Regime particular do tabaco Decreto-Lei n.º 346/85, de 23 de Agosto
M12 Regime da margem de lucro – Agências de Viagens Decreto‐Lei n.º 221/85, de 3 de Julho
M13 Regime da margem de lucro – Bens em segunda mão Decreto‐Lei n.º 199/96, de 18 de Outubro
M14 Regime da margem de lucro – Objetos de arte Decreto‐Lei n.º 199/96, de 18 de Outubro
M15 Regime da margem de lucro – Objetos de coleção e antiguidades Decreto‐Lei n.º 199/96, de 18 de Outubro
M16 Isento Artigo 14.º do RITI Artigo 14.º do RITI
M99 Não sujeito; não tributado (ou similar)

Payment Mechanisms

This list shows the possible values for the payment mechanism when doing a partial payment:

  • CC: Credit card
  • CD: Debit card
  • CH: Bank check
  • CO: Check or voucher
  • CS: Current account balance compensation
  • DE: e-Cash
  • LC: Commercial paper
  • MB: Multibanco payment references
  • NU: Cash
  • OU: Other methods not mentioned here
  • PR: Exchange of properties
  • TB: Bank transfer or authorized direct debit
  • TR: Restaurant ticket

Country List

This list shows the countries accepted when creating a client or an account:

  • Portugal
  • Ireland
  • UK
  • Canada
  • United States
  • Afghanistan
  • Albania
  • Algeria
  • American Samoa
  • Andorra
  • Angola
  • Anguilla
  • Antigua and Barbuda
  • Argentina
  • Armenia
  • Aruba
  • Australia
  • Austria
  • Azerbaijan
  • Bahamas
  • Bahrain
  • Bangladesh
  • Barbados
  • Belarus
  • Belgium
  • Belize
  • Benin
  • Bermuda
  • Bhutan
  • Bolivia
  • Bosnia-Herzegovina
  • Botswana
  • Brazil
  • British Indian Ocean Territory
  • Brunei
  • Bulgaria
  • Burkina Faso
  • Burma
  • Burundi
  • Cambodia
  • Cameroon
  • Canton and Enderbury Islands
  • Cape Verde
  • Cayman Islands
  • Central African Republic
  • Chad
  • Chile
  • China
  • Christmas Island
  • Cocos (Keeling) Islands
  • Colombia
  • Comoros
  • Congo
  • Congo, Democratic Republic
  • Cook Islands
  • Costa Rica
  • Côte d’Ivoire
  • Croatia
  • Cuba
  • Curaçao
  • Cyprus
  • Czech Republic
  • Denmark
  • Djibouti
  • Dominica
  • Dominican Republic
  • Dronning Maud Land
  • East Timor
  • Ecuador
  • Egypt
  • El Salvador
  • Equatorial Guinea
  • Eritrea
  • Estonia
  • Ethiopia
  • Faeroe Islands (Føroyar)
  • Falkland Islands
  • Fiji
  • Finland
  • France
  • French Guiana
  • French Polynesia
  • Gabon
  • Gambia
  • Georgia
  • Germany
  • Ghana
  • Gibraltar
  • Great Britain
  • Greece
  • Greenland
  • Grenada
  • Guadeloupe
  • Guam
  • Guatemala
  • Guernsey
  • Guinea-Bissau
  • Guinea
  • Guyana
  • Haiti
  • Heard and McDonald Islands
  • Honduras
  • Hong Kong
  • Hungary
  • Iceland
  • India
  • Indonesia
  • International Monetary Fund
  • Iran
  • Iraq
  • Isle of Man
  • Israel
  • Italy
  • Ivory Coast
  • Jamaica
  • Japan
  • Jersey
  • Johnston Island
  • Jordan
  • Kampuchea
  • Kazakhstan
  • Kenya
  • Kiribati
  • Korea, North
  • Korea, South
  • Kuwait
  • Kyrgyzstan
  • Laos
  • Latvia
  • Lebanon
  • Lesotho
  • Liberia
  • Libya
  • Liechtenstein
  • Lithuania
  • Luxembourg
  • Macau
  • Macedonia (Former Yug. Rep.)
  • Madagascar
  • Malawi
  • Malaysia
  • Maldives
  • Mali
  • Malta
  • Marshall Islands
  • Martinique
  • Mauritania
  • Mauritius
  • Mayotte
  • Micronesia
  • Midway Islands
  • Mexico
  • Moldova
  • Monaco
  • Mongolia
  • Montenegro
  • Montserrat
  • Morocco
  • Mozambique
  • Myanmar
  • Nauru
  • Namibia
  • Nepal
  • Netherlands Antilles
  • Netherlands
  • New Caledonia
  • New Zealand
  • Nicaragua
  • Niger
  • Nigeria
  • Niue
  • Norfolk Island
  • Northern Mariana Islands
  • Norway
  • Oman
  • Pakistan
  • Palau
  • Palestine
  • Panama
  • Papua New Guinea
  • Paraguay
  • Peru
  • Philippines
  • Pitcairn Island
  • Poland
  • Puerto Rico
  • Qatar
  • Reunion
  • Romania
  • Russia
  • Rwanda
  • Samoa (Western)
  • Samoa (America)
  • San Marino
  • São Tomé and Príncipe
  • Saudi Arabia
  • Sénégal
  • Serbia
  • Seychelles
  • Sierra Leone
  • Singapore
  • Slovakia
  • Slovenia
  • Solomon Islands
  • Somalia
  • South Africa
  • Spain
  • Sri Lanka
  • St. Helena
  • St. Kitts and Nevis
  • St. Lucia
  • St. Vincent and the Grenadines
  • Sudan
  • Suriname
  • Svalbard and Jan Mayen Islands
  • Swaziland
  • Sweden
  • Switzerland
  • Syria
  • Tahiti
  • Taiwan
  • Tajikistan
  • Tanzania
  • Thailand
  • Timor-Leste
  • Togo
  • Trinidad and Tobago
  • Tunisia
  • Turkey
  • Turkmenistan
  • Turks and Caicos Islands
  • Tuvalu
  • Uganda
  • Ukraine
  • United Arab Emirates
  • Upper Volta
  • Uruguay
  • Uzbekistan
  • Vanuatu
  • Vatican
  • Venezuela
  • Vietnam
  • Virgin Islands
  • Wake Island
  • Wallis and Futuna Islands
  • Western Sahara
  • Western Samoa
  • Yemen
  • Zaïre
  • Zambia
  • Zimbabwe

Need Some Help?

If you're having trouble understanding how to create Invoices you can check out a detailed walkthrough here.

You can also send us an email to support@invoicexpress.com and we'll be glad to help you out with your integration.