Invoice API documentation

You can automatically generate invoices through the Invoice API

Introduction

By using the Invoice API, other programs and applications will be able to use the Invoicing features of MiniCRM.

The identification occurs via standard “http” protocol - HTTP Auth.

To do the authentication, the following will be necessary:

Identification number of the system used (SystemID)
API key that can be requested as an admin in the System settings. (Settings > System - “Generate API key” button)

System setting page to where the API key can be generated

The API also can be used via HTTP Secure connection, by using “https://” as the prefix.

The API Url could be the following:

**If HTTP is used:**

https://SystemId:APIKey@r3.minicrm.hu/Api/Invoice
**If HTTPS is used:**

https://SystemId:APIKey@r3.minicrm.hu/Api/Invoice

###Character coding###
The character coding of the API is UTF-8. Every request is accepted in UTF-8 coding, and every response will be given in UTF-8.

###Formats###
The formats of both the input and the output will be in JSON serialized arrays.

###Invoice types###

The Invoice module and the Invoice API are only able to handle electronic documents (electronic invoice).

Available services

###Requesting for invoice data###
Example URL for the identification:

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/Invoice/12

By using this function, you can access the information recorded on the invoice in the system. The parameter is expecting the ID of an already existing document.

The ID of the document and the ID of the project (opportunity card) connected to the document does not match!

Example answer for this request:

{
    "Id": "12",
    "Number": "2013-E/00014",
    "Type": "Invoice",
    "Media": "PKI",
    "Customer": {
        "Name": "Test User",
        "CountryId": "36",
        "PostalCode": "1234",
        "City": "Budapest",
        "Address": "Teszt street 1.",
        "AccountNumber": "12345678-12345678-12345678",
        "VatNumber": "12345678-12-1"
    },
    "Vendor": {
        "Name": "Invoice Zrt.",
        "CountryId": "36",
        "PostalCode": "1234",
        "City": "Budapest",
        "Address": "Petőfi u. 8.",
        "AccountNumber": "87654321-87654321-87654321",
        "VatNumber": "87654321-02-3",
        "RegistrationNumber": "",
        "Miscellaneous": ""
    },
    "Subject": "",
    "PaymentMethod": "Cash",
    "Issued": "2013-11-27",
    "Performance": "2013-11-27",
    "Prompt": "2013-11-27",
    "Paid": "0000-00-00",
    "CurrencyCode": "HUF",
    "AmountNet": "2000.00",
    "AmountVat": "540.00",
    "Amount": "2540.00",
    "IsReverseCharge": "0",
    "DocumentUrl": "https://d1hj6taljsfeus.cloudfront.net/doc/2013/11-27/_/q/_qm-PaZTjYqdbkGEr_hbSg-50",
    "DocumentFileName": "invoice-50-2013-e-00014-1.pdf",
    "Items": [
        {
            "Name": "Exampe product",
            "Description": "",
            "PriceNet": "1 000,00",
            "VAT": "27%",
            "Quantity": "2",
            "Unit": "unit",
            "PriceNetTotal": "2 000,00",
            "PriceTotal": "2 540,00"
        }
    ]
}

Creating the invoice

With this function, a new document can be created in the system. This function expects a similar format as the previous request, and can be accessible via POST method. The data are expected in JSON encode format.
Example request for the POST method:

$ curl -XPOST https://SystemId:APIKey@r3.minicrm.hu/Api/Invoice/ -d '{
    "Type": "Invoice",
    "CustomerId": 98,
    "Customer": {
        "Name": "Test User",
        "Country": "Hungary",
        "PostalCode": "1234",
        "City": "Budapest",
        "Address": "Teszt utca 1.",
        "AccountNumber": "12345678-12345678-12345678",
        "VatNumber": "12345678-12-1"
    },
    "PaymentMethod": "Cash",
    "Issued": "2013-11-27",
    "Performance": "2013-11-27",
    "Prompt": "2013-11-30",
    "CurrencyCode": "HUF",
    "IsReverseCharge": "0",
    "Items": [
        {
            "Name": "Example product",
            "PriceNet": "1 000,00",
            "VAT": "27%",
            "Quantity": "2",
            "Unit": "darab"
        }
    ]
}'

CustomerID and ReferenceID are always required!

ContactId: The identification number of the contact in the address book of the system.
ReferenceId: The identification number of the project (opp. card) previously created by the XML sync.

The billing address will be used for the invoicing. If there is no billing address in the system, the primary address will be used.

Customer Array is optional. By using it, you can record the information about the customer. If the address given here is already in the system, the system will use it. If it is not in the system, the address given here will be recorded as the billing address.

The VatNumber and AccountNumber will be overwritten every time!

Example response in case of successful POST request:

{
    "Id": "13",
    "Number": "2013-E/00015",
    "Type": "Invoice",
    "Media": "PKI",
    "Customer": {
        "Name": "Teszt User",
        "CountryId": "36",
        "PostalCode": "1234",
        "City": "Budapest",
        "Address": "Teszt utca 1.",
        "AccountNumber": "12345678-12345678-12345678",
        "VatNumber": "12345678-12-1"
    },
    "Vendor": {
        "Name": "Invoice Zrt.",
        "CountryId": "36",
        "PostalCode": "1234",
        "City": "Budapest",
        "Address": "Petőfi u. 8.",
        "AccountNumber": "87654321-87654321-87654321",
        "VatNumber": "87654321-02-3",
        "RegistrationNumber": "",
        "Miscellaneous": ""
    },
    "Subject": "",
    "PaymentMethod": "Cash",
    "Issued": "2013-11-27",
    "Performance": "2013-11-27",
    "Prompt": "2013-11-30",
    "Paid": "0000-00-00",
    "CurrencyCode": "HUF",
    "AmountNet": "2000.00",
    "AmountVat": "540.00",
    "Amount": "2540.00",
    "IsReverseCharge": "0",
    "DocumentId": "66",
    "DocumentUrl": "https://d1hj6taljsfeus.cloudfront.net/doc/2013/11-27/7/m/7mgnkSkFG3YwHGcus2YEcg-50",
    "DocumentFileName": "szamla-50-2013-e-00015-1.pdf",
    "Items": [
        {
            "Name": "Példa termék",
            "Description": "",
            "PriceNet": "1 000,00",
            "VAT": "27%",
            "Quantity": "2",
            "Unit": "darab",
            "PriceNetTotal": "2 000,00",
            "PriceTotal": "2 540,00"
        }
    ]
}

Marking an invoice as paid

This method changes the status of an invoice to Paid. In case of a pro-forma, it also generates a paid invoice. This function uses POST request similar to the one before.

Example URL for the request:

$ curl -XPOST https://SystemId:APIKey@r3.minicrm.hu/Api/Invoice/16/Paid -d '{
    "Customer": {
        "Name": "Teszt User",
        "CountryId": "36",
        "PostalCode": "1234",
        "City": "Budapest",
        "Address": "Teszt utca 1.",
        "AccountNumber": "12345678-12345678-12345678",
        "VatNumber": "12345678-12-1"
    },
}'

You can use more Customer arrays if any information has been changed since the pro-forma was created and you want to create the invoice with up-to-date data.

Example response for this request:

{
    "Id": "17",
    "Number": "2013-E/00016",
    "Type": "Invoice",
    "Media": "PKI",
    "Customer": {
        "Name": "Teszt User",
        "CountryId": "36",
        "PostalCode": "1234",
        "City": "Budapest",
        "Address": "Teszt utca 1.",
        "AccountNumber": "12345678-12345678-12345678",
        "VatNumber": "12345678-12-1"
    },
    "Vendor": {
        "Name": "Invoice Zrt.",
        "CountryId": "36",
        "PostalCode": "1234",
        "City": "Budapest",
        "Address": "Petőfi u. 8.",
        "AccountNumber": "87654321-87654321-87654321",
        "VatNumber": "87654321-02-3",
        "RegistrationNumber": "",
        "Miscellaneous": ""
    },
    "Subject": "DK2013-E/00002 számú díjbekérő alapján készült.",
    "PaymentMethod": "Cash",
    "Issued": "2013-11-27",
    "Performance": "2013-11-27",
    "Prompt": "2013-11-27",
    "Paid": "2013-11-27",
    "CurrencyCode": "HUF",
    "AmountNet": "12000.00",
    "AmountVat": "3240.00",
    "Amount": "15240.00",
    "IsReverseCharge": "0",
    "DocumentId": "68",
    "DocumentUrl": "https://d1hj6taljsfeus.cloudfront.net/doc/2013/11-27/g/o/go9SWT-_mUVFKQD2-m5-5w-50",
    "DocumentFileName": "szamla-50-2013-e-00016-1.pdf",
    "Items": [
        {
            "Name": "Teszt cikk 1",
            "Description": "",
            "PriceNet": "12 000,00",
            "VAT": "27%",
            "Quantity": "1",
            "Unit": "darab",
            "PriceNetTotal": "12 000,00",
            "PriceTotal": "15 240,00"
        }
    ]
}

Reversing the Invoice (Storno)

You can storno a specific invoice already created in the system. This function works via POST method.

Example URL for the request:

$ curl -XPOST https://SystemId:APIKey@r3.minicrm.hu/Api/Invoice/17/Storno

If an invoice is reversed, the system automatically generates a Storno invoice.

The response here will be the data of this Storno invoice:

{
    "Id": "17",
    "Number": "2013-E/00016",
    "Type": "Invoice",
    "Media": "PKI",
    "Customer": {
        "Name": "Test User",
        "CountryId": "36",
        "PostalCode": "1234",
        "City": "Budapest",
        "Address": "Teszt utca 1.",
        "AccountNumber": "12345678-12345678-12345678",
        "VatNumber": "12345678-12-1"
    },
    "Vendor": {
        "Name": "Invoice Zrt.",
        "CountryId": "36",
        "PostalCode": "1234",
        "City": "Budapest",
        "Address": "Petőfi u. 8.",
        "AccountNumber": "87654321-87654321-87654321",
        "VatNumber": "87654321-02-3",
        "RegistrationNumber": "",
        "Miscellaneous": ""
    },
    "Subject": "Storno invoice of invoice: DK2013-E/00002",
    "PaymentMethod": "Cash",
    "Issued": "2013-11-27",
    "Performance": "2013-11-27",
    "Prompt": "2013-11-27",
    "Paid": "2013-11-27",
    "CurrencyCode": "HUF",
    "AmountNet": "12000.00",
    "AmountVat": "3240.00",
    "Amount": "15240.00",
    "IsReverseCharge": "0",
    "DocumentId": "68",
    "DocumentUrl": "https://d1hj6taljsfeus.cloudfront.net/doc/2013/11-27/g/o/go9SWT-_mUVFKQD2-m5-5w-50",
    "DocumentFileName": "invoice-50-2013-e-00016-1.pdf",
    "Items": [
        {
            "Name": "Example product 1",
            "Description": "",
            "PriceNet": "12 000,00",
            "VAT": "27%",
            "Quantity": "1",
            "Unit": "darab",
            "PriceNetTotal": "12 000,00",
            "PriceTotal": "15 240,00"
        }
    ]
}

Error messages and error handling

The invoice API will respond with HTTP status codes if any error occurs. If the response is 200 - OK, the request was successful. If an error occurs, the answer will not be JSON, but plain text.

Some error codes

400 - Bad Request: In the request sent, the parameter is not allowed, or cannot be processed. Also, this code will be the response when the API expects a parameter, but it’s not in the request.
404 - Not Found: The requested URL is not in the system. (This is the most common error - mistyped or not existing url.)
405 - Method Not Allowed: If the method is not allowed or simply not usable for an URL
500 - Internal Server Error: Error occurs during the processing. (In most cases, when the data is sent in a wrong format, or not allowed data is sent. Also occurs when the field requested does not exist or is empty.)

Example program

In the following Php example, we are going to use the API via the curl.
SystemID: 50
API key: ZxPPCqDItuQhoaLeBM2679mT3iG5NgH1

//Creating the Url
$Url = 'https://50:ZxPPCqDItuQhoaLeBM2679mT3iG5NgH1@r3.minicrm.hu/Api/Invoice/';

//Defining the parameters with the array
$Params = array(
    'CustomerId' => 12,
    'Type' => 'ProForma',
    'PaymentMethod' => 'WiredTransfer',
    'Issued' => '2013-11-27',
    'Performance' => '2013-11-27',
    'Prompt' => '2013-11-27',
    'CurrencyCode' => 'HUF',
    'IsReverseCharge' => 0,
    'Customer' => array(
        'Name' => 'PHP Teszt User',
        'Country' => 'Magyarország',
        'PostalCode' => 1111,
        'City' => 'Budapest',
        'Address' => 'Példa köz 3.',
        'AccountNumber' => '11111111-2222222-3333333',
        'VatNumber' => '13579135-13-5'
    ),
    'Items' => array(
        0 => array(
            'Name' => 'Teszt szolgáltatás',
            'Unit' => 'darab',
            'Quantity' => 1,
            'VAT' => 27,
            'PriceNet' => 5000
        )
    )
);

//Initializing the Curl
$Curl = curl_init();
curl_setopt($Curl, CURLOPT_RETURNTRANSFER , true);
curl_setopt($Curl, CURLOPT_SSL_VERIFYPEER , false);

//Encode the parameters as JSON
$Params = json_encode($Params);

//Setting up the headers (type of data, lenght and character encoding)
curl_setopt($Curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json','Content-Length: '.strlen($Params), 'charset=UTF-8'));

//Set the request type as POST
curl_setopt($Curl, CURLOPT_POST, 1);

//Handover the parameters to the Curl
curl_setopt($Curl, CURLOPT_POSTFIELDS, $Params);

/Handover the URL to the Curl
curl_setopt($Curl, CURLOPT_URL, $Url);

//Execute the Curl request
$Response = curl_exec($Curl);

//Check if any error occured
if(curl_errno($Curl)) $Error = "Hiba a Curl futtatásakor: ".curl_error($Curl);

//Requesting the HTTP response code for the API
$ResponseCode = curl_getinfo($Curl, CURLINFO_HTTP_CODE);
if($ResponseCode != 200) $Error = "API Error code: {$ResponseCode} - Message: {$Response}";

//Closing the Curl
curl_close($Curl);