EZcount Document Creation API

EZcount Document Creation API

API Version: 1.3.8

Introduction

General Information

• EZcount API is a REST API that works for both POST and JSON requests
  • JSON requests must be sent with application/json header (recommended)
  • POST requests can be sent as normal POST
• The API has a demo environment – please register freely and get your API key
• API connection must be established through SSL (port 443)
• Make sure your connection timeout settings are above 30 seconds. Generally responses return in several milliseconds, but when the server is busy it might take several seconds

API Domains

• demo.ezcount.co.il – used for testing
• api.ezcount.co.il – used for production

Requirements

1. Fully setup account with digital signature in EZcount.co.il / demo
2. API key from the system settings → API menu

Testing API Key

To acquire an API key for testing, you may register (for free, forever) to demo.ezcount.co.il and get an API key and customize your account.

If you want quick and dirty, and you don’t care about the UI/look of the invoices during development, you may use the following testing API key:

f1c85d16fc1acd369a93f0489f4615d93371632d97a9b0a197de6d4dc0da51bf

Code Samples (SDKs)

We’ve built SDKs to make your life much easier. You can now connect with simple copy-paste from the SDK demo.

You may download the SDKs from the following links:

• C#.NET
• VB.NET
• PHP
• JAVA
• ASP
• Python
• Ruby
• Node.js

Creating a New Document

Base Document Parameters

Requirement Notation:

• V – always required
• !R – required in all documents except receipt
• ?R – optional in all documents except receipt

📦 Create Document – Add Item

item must be an array of items. For example, if we want to send 2 items, we will send the following array as JSON:

{
  "item": [
    {
      "catalog_number": "MKT1",
      "details": "1 kg of Internet",
      "amount": 1,
      "price": 12.44
    },
    {
      "details": "infinite amount of love",
      "amount": 1,
      "price": 99,
      "vat_type": "INC"
    }
  ]
}

Create Document – Add Payment

Must be an array of payment with the following values as JSON:

{
  "payment": [
    {
      "payment_type": "1",
      "date": "10/10/2010",
      "payment": 250
    },
    {
      "payment_type": 3,
      "date": "10/10/2010",
      "payment": 250,
      "cc_type": 0,
      "cc_type_name": "ויזה"
    }
  ]
}

!PT[n] – required for payment type n. For example, a field which is required for checks will be marked as !PT2 because checks is payment type 2

Document Creation API Response

API response will be a JSON string

On Error:

The API will return error number and related message, for example:

{
  "errNum": 1,
  "errMsg": "api key is malformatted"
}

On Success:

{
  "pdf_link": "https://demo.ezcount.co.il/front/documents/get/0f2a3f82-afe0-41e9-8235-adb5f17bdfb6",
  "pdf_link_copy": "https://demo.ezcount.co.il/front/documents/get/0f2a3f82-afe0-41e9-8235-adb5f17bdfb6/copy",
  "doc_number": "60002",
  "doc_uuid": "0f2a3f82-afe0-41e9-8235-adb5f17bdfb6",
  "sent_mails": [
    "demo@example.com"
  ],
  "success": true
}

• pdf_link – link to the origin document, this link been sent to client if ordered to
• pdf_link_copy – the copy document (העתק נאמן למקור)
• doc_number – the document number
• doc_uuid – each document in the system has a unique ID
• sent_mails – the emails this document has been sent to

Moving to Production

In order to move to production:

1. Create an account in production and fetch the api_key for this account
2. If you are sending docs on behalf of other EZcount accounts which are not you, please add a dev_master_key field and set there your account api_key
3. Set your requests to https://api.ezcount.co.il/api/createDoc...

Debugging Tools

In order to debug your code we’ve built some quick tools:

1. Use https://demo.ezcount.co.il to create some documents from the UI. Our UI uses the API, so you will understand easily and more intuitively the API’s full features
2. Check how the server sees your request:
   1. When you are sending a request, add the debug_key parameter with any value you wish to the request URL:
      https://demo.ezcount.co.il/api/createDoc?debug_key=A1B2C3
   2. After the request been sent, go to:
      https://demo.ezcount.co.il/api/getLastAPIRequestData?debug_key=A1B2C3&api_key=[your api key]&developer_email=your_email@demo.com
      Here you will get a dump of what the server received:
      • POST – the POST array
      • RAWDATA – the RAW data (used mainly when you send a JSON request)
      • REQUEST_HEADERS – the request headers as the server sees them

Advanced API Methods

The methods described here are more advanced and are not part of our code samples and SDKs, but we do maintain them.

Creating Doc on Behalf of Non-Owner Account

How to Use It:

It is possible to create a document on behalf of one of the accounts of the company (in case you have multiple businesses under the same user ID)

1. Create another business and set the invoice details for this business
2. Now go to this address:
   https://[demo\www].ezcount.co.il/backoffice/accounts?show_hidden_fields=1
3. You will see a unique identifier (UUID) next to each of the accounts
4. Add the ua_uuid field to the invoice creation and set the value to be the UUID of the account you want to create on behalf of (XXXX-XXXX-XXXX-XXXXXXXX)
5. Now the invoice will be created with the details of that user

Common Errors:

1. Calling the API with wrong credentials:
   The account UUIDs in the demo are different from the accounts in production. Please make sure you have separation between the environments.