Changelog

Latest changes

9/25/2019
  • Added new endpoints GET/ProformaInvoices/{id}/Account, which returns new issued invoice for accounting of proforma invoice, and POST/IssuedInvoices/Accounting, which creates new issued invoice and uses it for accounting of proforma invoice.
9/18/2019
  • Partner added to the model SalesReceiptApiModelExpand for GET/SalesReceipts/{id}/Expand and GET/SalesReceipts/Expand
8/28/2019
  • Added methods for copying a received, isssued and proforma invoice. Resp. ReceivedInvoices/{id}/Copy, IssuedInvoices/{id}/Copy, ProformaInvoices/{id}/Copy.
7/17/2019
  • We added an option to send a thank-you note for the payment.
  • SentPaymenntConfirmation added to the model for POST / IssuedInvoicePayments
  • Added endpoint POST / Mails / IssuedDocumentPayments / SendConfirmation / {id}
3/20/2018
  • Added methods for mails.
  • Added methods for reports.
  • Added list for vat reversecharge codes.
  • Added methods for bank statements including bank statement pairing.
2/7/2018
  • Cash vouchers can now have multiple items. Because of backwards compatibility, the old Item property still exists, but only returns the first item. If you want to use the API for cash vouchers with multiple items, use the new Items property. For update, the PATCH method was added. The PUT method will only work for cash vouchers with one item.
  • Sales receipts now have an optional partner. Both your and the partner's address were added to GET models. The partner's Id was added to the POST model.
12/14/2017
  • Added filters for legislation and deprecated properties. These filters do not have any effect on the behavior of the API, only on what you see in the documentation. Deprecated properties will not be included in future versions of the API, but will keep working in v2.
  • Fixed Agendas endpoints to work correctly with multiple user access. Added the Agendas/Current endpoint.
  • Added endpoints Attachments/GET, Attachments/PUT and Attachments/DELETE, which work for all supported entities based on the combination of Id and Document type. The existing attachment endpoints were deprecated.
10/4/2017
  • Added filters for contact id (PurchaserId or SupplierId) to GET methods for invoices.
8/30/2017
  • Added methods for working with stock movements.
  • Speed optimizations for GetExpand methods
  • Fixed date logic for ReceivedInvoices/POST. DateOfMaturity and DateOfTaxing were incorrectly set according to DateOfIssue. An unset DateOfIssue will no longer be set to the current date. An unset DateOfTaxing will no longer be set according to DateOfReceiving.
  • Further documentation improvements
6/27/2017
  • Fixed bugs in PUT/PATCH endpoints
  • Added BarCode property on pricelist models (GET, POST, PATCH)
4/10/2017
  • Documentation improvements - added the changelog and FAQ sections
  • Added stock balance to the pricelist model
  • Deleting pricelist items: When deleteIfReferenced=false is specified, exported items will not be deleted either.
  • Sales receipt model: Added properties related to accounted sales receipts: IsAccounted, CashVoucherItemId
  • Cash voucher model - Added properties related to accounted sales receipts: IsSummarySalesReceipt, SummarySalesReceiptDate
1/24/2017
  • Fix - removed validation for uniqueness of updated invoice item ids (it prevented adding more than one new item)
1/10/2017
  • Added support for multiple numeric sequences in issued invoices, proforma invoices and credit notes.
  • Added support for attachments in issued invoices, proforma invoices and credit notes. Attachments work the same way as in received invoices.

Quick start

For the quickest start with API

Postman

For a quicker start with the ItsMyBill API, we prepared a full collection of possible requests for you. You can start working with your data in a matter of minutes.
To test out accessing your data, we recommend the Postman REST API client. Next step »


Endpoint for API access

  • https://api.idoklad.cz
  • e.g.: https://api.idoklad.cz/v2/IssuedInvoices

Differences from v1

  • Instead of the secure token, version 2 uses the OAuth2 standard. To call an API endpoint, you need to have an access token. To test out the API, we recommend using the client credentials flow and the Postman client. More details can be found in the authorization section.

Receive invoices list

  1. GET method call api/v2/IssuedInvoices doc
  2. Response will contain invoice list in a field Data

Issued invoice createion

  1. Call api/v2/IssuedInvoices/Default doc
  2. Method returns filled issued invoice model with default settings of the user
  3. Complete necessary fields of the model
  4. Completed model serialize into the Body part of the request
  5. POST method call api/IssuedInvoices doc
  6. Request returns invoice and its recounted values


General rules

Conventions and backwards compatibility

HTTP response codes

    Signaling success:
  • 200 OK. The response is usually the created entity or the result of an operation, if necessary.
    Signaling an error:
  • The model is not valid (400 Bad Request).
  • An entity was not found (404 not found)
  • Exceeded rate limit (429 Too Many Requests). Retry-After values are returned in the response header in seconds
  • Scheduled maintenance (503 Service unavailable). The API is completely unavailable during maintenance.
  • Unspecified error (500 Internal Server Error) - in this case, contact us. We will be able to help you more quickly if you sent the whole request which is causing the error.
    Related to ItsMyBill subscriptions:
  • Expired or insufficient subscription (402 Payment Required)
  • A manual downgrade using the web interface is needed. (403 Forbidden)
  • Exceeded rate limit (429 Too Many Requests).
    Související s autentizací:
  • Expired/invalid token (401 Unauthorized)
  • Invalid refresh token (400 with the message "invalid_grant"). Refresh tokens do not expire, but can be revoked. When this error is received, an application must attempt to navigate the user back to the login screen.

Backwards compatibility

    The API client must be prepared to handle the following:
  • A property may be added to any model. Such a property will never be required.
  • The response can contain any documented status code, provided it makes sense in the given situation.
    The API client can assume the following:
  • A property will never be removed from a model. The only exception are major API versions (1.0/2.0/3.0) Výjimkou jsou major verze API (1.0/2.0/3.0) which require a nontrivial migration. Any change can occur between major versions.
  • No behavior will change unless the sent model is changed. What constitutes behavior:
    • A change in the returned status code, for example by adding a new validation.
    • A change in the returned model, with the abovementioned exception of added properties.
    This does not include e.g. a change in an algorithm, only its output format. Another exception are bug fixes.
    The API client cannot rely on the following:
  • Undocumented behavior. Mostly occurs in POST methods, where some properties are automatically set from settings even if not set. The Default method should be used before POSTing an entity. This method will return a model with the properties from settings already set. Nezdokumentované chování. Týká se hlavně POSTu, kde se některé vlastnosti automaticky berou z nastavení, i když nejsou vyplněny. Před POSTem by se měla použít metoda Default, která vrátí model dle nastavení.

HTTP convention

  • GET - obtaining data
  • PUT - update of the resource
  • PATCH - partial update
  • POST - new resource creation
  • DELETE - delete of the resource

Work with lists

All lists returns data using this structure

  • Data - requested resource list
  • TotalItems - total resources count in list
  • TotalPages - page count for request

Pagination

For pagination are used these parameters:

  • PageSize - items count on a page
  • Page - page number
  • Max item count per page is 200 and default is 20 200 and default is 20

Adding and updating record

Before POST-ing a new entity, prepare a model with your default settings by calling the Default method. It always returns a model suitable for POST. Make your needed changes to this model and send it.

PUT is used for a full update and required all of its properties to be specified. PATCH only updates what you specified. It is therefore easier to use and we recommend using PATCH over PUT.

While using PUT, POST, PATCH or DELETE request, add header Content-Type
e.g.: Content-Type: application/json



Authorization

Introductory information about the ItsByBill API authorization.

You can find an example Postman collection for authorization here.

Addresses

OAuth2

Version 2 of the ItsMyBill API uses authentication through the OAuth2 standard. To use the API, an access token is required. This token can be obtained through multiple ways according to the needs of your application. At this moment, the following modes of authentication are supported:

  • Authorization code flow
  • Client credentials flow
  • PIN flow (used by EET devices)

Access token authentication
Each request must contain the following header:

Authorization: Bearer your_access_token

Authorization code flow:

This flow is suitable for applications which need to use data from multiple users. The application will show the user the ItsMyBill login screen where the user will submit his login information. This authorizes the application to use his data.

The application must be registered in the Developer portal, where it can obtain its client id and client secret.

You can obtain the access token by following these steps:
Authorize endpoint request

https://identity.idoklad.cz/server/connect/authorize
                ?scope=idoklad_api%20offline_access
                &client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx
                &response_type=code
                &redirect_uri=http://test.test.com/
Parameter Value
scope see the scopes table
client_id from the Developer portal
response_type the string “code”
redirect_uri the address which will receive an authorization code after the user logs in. This code will be later exchanged for an access token. You will need to add this address to a list in the developer portal (client details - redirect uris tab)

User login

The user is shown a popup window where they log in to ItsMyBill. After the login, the browser will be redirected to the address specified in redirect_uri


Token endpoint request

POST https://identity.idoklad.cz/server/connect/token
                grant_type=authorization_code
                &client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx
                &client_secret=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyy
                &scope=idoklad_api%20offline_access
                &code=70ae4b57d835d3755a59b3aa2a729546
                &redirect_uri=http://test.test.com/

The response to a successful request is an access token (with a refresh token, if it was requested)

{
  "access_token": "eyJ0eXAi...",
  "expires_in": 6000,
  "token_type": "Bearer",
  "refresh_token": "abcd..."
}
Parameter Value
grant_type the string “authorization_code”
client_id from the Developer portal
response_type from the Developer portal
scope see the scopes table
code the authorization code returned after the redirect to redirect_uri. This code is only valid for one use. To avoid repeating the login step, a refresh token can be used.
redirect_uri The address which was specified in the authorize endpoint request

Refresh token

POST https://identity.idoklad.cz/server/connect/token
                grant_type=refresh_token
                &client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx
                &client_secret=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyy
                &scope=idoklad_api%20offline_access
                &redirect_uri=http://test.test.com/
                &refresh_token=f4bcdc2e6d964f519cd74e2ac4a2105f
Parameter Meaning
grant_type the string “refresh_token”
refresh_token from the Developer portal
other identical to the access token request

Client credentials flow

Each user can generate a client id and client secret in his user settings without the need to register as an external application. The use of client credentials is only suitable when the client secret is stored securely, such as server-to-server communication. It is also the simplest flow and can be used to quickly test the API through the Postman client.

Access token

Parameter Value
scope idoklad_api
grant_type client_credentials
client_id z nastavení idokladu
client_secret z nastavení idokladu

Client credentials does not use refresh tokens

EET - Pin flow

POST https://app.idoklad.cz/identity/server/connect/token
                scope=eet+offline_access
                &client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx
                &client_secret=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyy
                &grant_type=pin
                &pin=12345678
Parameter Value Note
scope eet offline_acccess
grant_type the string “pin”
client_id from the Developer portal
client_secret from the Developer portal
pin code of the external device

Important note

  • When using the EET flow, it is necessary to save your refresh token. By generating an access token, the device will be paired and unpairing is only possible manually in ItsMyBill. It is only possible to get another access token for a paired device through the refresh token.
POST https://identity.idoklad.cz/server/connect/token
    scope=eet+offline_access
    &client_id=a05743fa-f043-42f2-a26b-7c75194762d0
    &client_secret=510e5d46-0566-48b2-8e30-71a28abeb077
    &grant_type=refresh_token
    &refresh_token=397e08355318cc85dd890e3bc33b0cc1

Refresh token

Parameter Value
scope eet offline_acccess
grant_type the string “refresh_token”
refresh_token the value of the first issued refresh token
client_id from the Developer portal
client_secret from the Developer portal

* the PIN is not required again when requesting a refresh token

Scopes

Scope Meaning
idoklad_api read/write access to the API
offline_access required when requesting a refresh token
eet used in the EET PIN flow


Filtering data

Syntax for filters

Url syntax

url/v2/controller/endpoint
   ?filter=FILTER_SYNTAX
    &sort=SORT_SYNTAX
    &page={int}
    &pagesize={int}
    &filtertype=(and|or)
Parameter Default value
filter -
sort id~asc
pagesize 20
page 1
filtertype and
  • the order of query string paramters is not significant
  • multiple filters can be applied to the same property

Filter syntax

FILTER_SYNTAX =
{PROPERTY_NAME}~{OPERATOR}~{PROPERTY_VALUE}
    | // filter separator
{PROPERTY_NAME}~{OPERATOR}~{PROPERTY_VALUE}
    | ...

Operators

Operator Meaning Supported data types
lt < int, datetime
lte <= int, datetime
gt > int, datetime
gte >= int, datetime
eq == all
!eq != all
ct contains string
!ct !contains string

Enum properties can be filtered according to their string value, e.g.

movementType~eq~Received is equivalent to movementType~eq~1

Sort syntax

{PROPERTY_NAME}~{SORT_ORDER}
        |  // sort separator
{PROPERTY_NAME}~{SORT_ORDER}

SORT_ORDER

Operátor Význam
asc ascending (123)
desc descending (321)

Request example:

GET
/v2/IssuedInvoices
   ?filter=DocumentNumber~ct~2016|Price~gt~50
    &sort=Id~desc
    &page=2
    &pagesize=30
    &filtertype=or

A list of filterable properties can be found in the full documentation of each method.

FAQ

Frequently asked questions

Authorization

Question:
A request to the authorize endpoint returns The requested resource does not support http method 'GET'

Answer:

Authorize endpoint requests are POST requests


Question:
A request to the token endpoint returns "error": "invalid_scope"

Answer:

Check the required scopes in the documentation or the sample Postman collection. Watch out for extra spaces.


Question:
A request to the token endpoint returns "error": "invalid_client"

Answer:

Check the following:

  • Whether the sent parameters are correct (typos, extra spaces).
  • In the case of client credentials, verify you saved your user settings after generating them.
  • In the case of client credentials, it is possible you regenerated your credentials and invalidated the old ones.


Question:
A request to the token endpoint returns "error": "invalid_grant"

Answer:

In the authorization code flow (access token request) - the code retrieved after the user's login is only valid for one use. Repeated usage will return this error.


Question:
A token endpoint request returns "error": "unsupported_grant_type"

Answer:

Incorrect grant_type parameter. You can find the valid value in the documentation or the example Postman collection.


Question:
When should I use client id and client secret from the Developer portal and when the ones from the ItsMyBill settings?

Answer:

Credentials from the Developer portal identify an application. Use them when you want to develop an application used by multiple ItsMyBill users. The users authorize the application to use their data (by logging in). The application itself does not own any data. The Developer and ItsMyBill accounts are not linked, even if their login e-mails are the same.
Credentials from the ItsMyBill settings identify a particular combination of company (agenda) and user. They are only used for the client credentials flow. Their ideal use case is for working with your own data or in an automated environment, where a manual login is not an option.


Other

Question:
My report is not returned in the language I want.

Answer:

For most reports, you can use the HTTP header Accept-Lanuage. Acceptable values are one of en-US, de-DE, sk-SK a cs-CZ. In the case of issued invoices, proforma invoices and credit notes, the language of the report is taken from the property LanguageCode with which the invoice was saved.


Libraries and extensions

We developers stick together. We appreciate that you keep sharing the results of your efforts and make life easier for everyone.

C#

The C# SDK by Miroslav Holec can be found on his Github. It is also available as a NuGet package.


PHP

Honza Malcánek created an open source library for easy integration of PHP applications with the ItsMyBill API and gave it for everyone to use for free. Thank you, it is very good work! You can find it here.


Other

Do you also have an application or library using ItsMyBill? Register it here!

Full documentation

Everything else to know.

Main entities

Agendas

Methods for working with agendas.

GET v2/Agendas

List of agendas.

GET v2/Agendas/{id}

Detail of the agenda by Id.

GET v2/Agendas/Current

Detail of an agenda by Id.

GET v2/Agendas/GetActualMonthInvoicing

Method calculates statistics data for actual month

GET v2/Agendas/GetAgendaBankAccounts

List of bank accounts for agenda.

GET v2/Agendas/GetAgendaContact

Contact information for agenda.

GET v2/Agendas/GetAgendaContactExpand

Contact information for agenda. Expanded edition.

GET v2/Agendas/GetAgendaSummary

Summary of the user documents for agenda.

GET v2/Agendas/GetInvoicingForPeriod

Method calculates statistics data for issued and received invoices

GET v2/Agendas/GetInvoicingForYear

Method calculates statistics data for issued and received invoices

GET v2/Agendas/GetStatisticForContact/{id}

Statistics for contact

GET v2/Agendas/GetSummaryQuarters

Sum of the invoice amount for the quarters.

GET v2/Agendas/GetTopPartners

Method calculates best partners by issued invoices sum.

BankStatements

Methods for working with bank statements.

GET v2/BankStatements

Returns list of bank statements. Filters are optional.

GET v2/BankStatements/{id}

Returns information about a bank statement with the given id.

POST v2/BankStatements/Pair

Pairs a model with an invoice according to the variable symbol and currency.

CashVouchers

Methods for working with cash vouchers.

Multiple items on cash vouchers

Cash vouchers can have multiple items since 7.2.2018. Because of backwards compatibility, models still have the Item property. If you want to use cash vouchers with multiple items, you must start using the Items property. To update these cash vouchers, use the PATCH endpoint, which only works with Items.
Additionally, VariableSymbol was moved from the Item to the header of the cash voucher. The old variable symbol on individual items is redundant and will always match the one in the header.

GET v2/CashVouchers

Returns list of cash vouchers. Filters are optional.

GET v2/CashVouchers/{id}

Returns information about a cash voucher.

GET v2/CashVouchers/{id}/Expand

Returns cash voucher with related entities by Id.

GET v2/CashVouchers/{id}/GetCashVoucherPdf

Returns Pdf file with Cash voucher report. File is Base64 encoded and is returned as string.

GET v2/CashVouchers/{id}/GetCashVoucherPdfCompressed

Returns zipped Pdf file with Cash voucher report. File is Base64 encoded and is returned as string.

GET v2/CashVouchers/Default/{movementType}

Method returns empty cash voucher with default values. Returned resource is suitable for creation of a new cash voucher.

GET v2/CashVouchers/Default/{movementType}/{invoiceType}/{invoiceId}

Method returns empty cash voucher with default values. Returned resource is suitable for creation of a new cash voucher.

GET v2/CashVouchers/Expand

Returns cash voucher with related entities by Id.

POST v2/CashVouchers

Create new cash voucher.

POST v2/CashVouchers/Pair/{cashVoucherId}/{invoiceType}/{invoiceId}

Spáruje pokladní doklad s neuhrazenou fakturou. Při párování se vytvoří úhrada k dané faktuře.

POST v2/CashVouchers/Pair/{invoiceType}/{invoiceId}

Spáruje pokladní doklad s neuhrazenou fakturou. Při párování se vytvoří úhrada k dané faktuře.

PUT v2/CashVouchers/{id}

Updates a cash voucher by Id.

PUT v2/CashVouchers/{id}/Exported/{exported}

Updates the Exported property of the cash voucher.

PATCH v2/CashVouchers/{id}

Updates a cash voucher by Id.

DELETE v2/CashVouchers/{id}

Deletes cash voucher by Id.

Contacts

Methods for working with contacts.

Terminology

A Contact is a contact in your contact list. A DocumentAddress is created when your document is created - one for the purchaser and one for the supplier. The information on the invoice does not have to correspond with the information on the contact (when you change a contact, DocumentAddress is not changed). DocumentAddress can be changed by using the PATCH/DocumentAddresses method, which allows partial updates.

Useful tips

The contact id is required for invoices. It is either PurchaserId for issued invoices or a SupplierId on received invoices.

GET v2/Contacts

List of contacts.

GET v2/Contacts/{id}

Returns contact by Id.

GET v2/Contacts/{id}/Expand

Returns contact with related entities by contact Id.

GET v2/Contacts/Default

Returns default contact. This resource is suitable for creation of new contact by the POST method.

GET v2/Contacts/Expand

List of contacts with related entities.

POST v2/Contacts

Add new contact.

PUT v2/Contacts/{id}

Fully updates a contact.

PATCH v2/Contacts/{id}

Update contact. Partial update is also possible.

DELETE v2/Contacts/{id}

Deletes contact.

CreditNotes

Methods for working with credit notes.

GET v2/CreditNotes

Returns list of credit notes. Filters are optional.

GET v2/CreditNotes/{id}

Returns information about credit note including summaries.

GET v2/CreditNotes/{id}/Expand

Returns Credit note with related entities by Id.

GET v2/CreditNotes/{id}/GetAttachment

Returns attachment for a credit note. File is Base64 encoded and is returned as string.

GET v2/CreditNotes/{id}/GetAttachmentCompressed

Returns compressed attachment for a credit note. File is Base64 encoded and is returned as string.

GET v2/CreditNotes/Expand

Returns credit note list with related entities such as contact information etc.

PUT v2/CreditNotes/{id}/Exported/{exported}

Method updates Exported property of the invoice.

PUT v2/CreditNotes/{id}/FullyPay

Method sets credit note as paid.

PUT v2/CreditNotes/{id}/FullyUnpay

Method sets credi note as unpaid.

PUT v2/CreditNotes/SetAttachment/{invoiceId}

Sets an attachment to the given credit note. If an attachment already exists, it will be overwritten.

DELETE v2/CreditNotes/DeleteAttachment/{invoiceId}

Deletes a credit note attachment.

IssuedDocumentPayments

Methods for working with issued document payments.

GET v2/IssuedDocumentPayments

Returns list of payments. Filters are optional.

GET v2/IssuedDocumentPayments/{id}

Returns information about a payment.

GET v2/IssuedDocumentPayments/{id}/Expand

Returns payment with related entities by Id.

GET v2/IssuedDocumentPayments/Default/{documentId}

Method returns default payment for given document. Returned model is suitable for new payment creation.

GET v2/IssuedDocumentPayments/Expand

Returns list of payments with related entities such as document of payment.

POST v2/IssuedDocumentPayments

Create new payment. Payment should contains id of payed document.

PUT v2/IssuedDocumentPayments/{id}/Exported/{exported}

Method updates Exported property of the payment.

DELETE v2/IssuedDocumentPayments/{id}

Deletes payment by Id. If payment has cash voucher, it is deleted as well.

IssuedInvoices

Methods for working with issued invoices.

GET v2/IssuedInvoices

Returns list of issued invoices. Filters are optional.

GET v2/IssuedInvoices/{contactId}/IssuedInvoices

Returns invoice list for a specific contact.

GET v2/IssuedInvoices/{id}

Returns information about issued invoice including summaries.

GET v2/IssuedInvoices/{id}/Copy

Method returns copy of issued invoice. Returned resource is suitable for new invoice creation.

GET v2/IssuedInvoices/{id}/Expand

Returns Issued invoice with related entities by Id.

GET v2/IssuedInvoices/{id}/GetAttachment

Returns attachment for invoice. File is Base64 encoded and is returned as string.

GET v2/IssuedInvoices/{id}/GetAttachmentCompressed

Returns compressed attachment for invoice. File is Base64 encoded and is returned as string.

GET v2/IssuedInvoices/{id}/GetCashVoucherPdf

Returns Pdf file with Cash voucher report for the invoice. File is Base64 encoded and is returned as string.

GET v2/IssuedInvoices/{id}/GetCashVoucherPdfCompressed

Returns zipped Pdf file with Cash voucher report for the invoice. File is Base64 encoded and is returned as string.

GET v2/IssuedInvoices/{id}/GetPdf

Returns Pdf file with Issued Invoice. File is Base64 encoded and is returned as string.

GET v2/IssuedInvoices/{id}/GetPdfCompressed

Returns zipped Pdf file with Issued Invoice report. File is Base64 encoded and is returned as string.

GET v2/IssuedInvoices/{id}/GetPdfWithPayments

Returns Pdf file with Issued Invoice with payments. File is Base64 encoded and is returned as string.

GET v2/IssuedInvoices/{id}/GetPdfWithPaymentsCompressed

Returns zipped Pdf file with Issued Invoice report with payments. File is Base64 encoded and is returned as string.

GET v2/IssuedInvoices/{id}/MyDocumentAddress

Contact information of the supplier for invoice.

GET v2/IssuedInvoices/{id}/PurchaserDocumentAddress

Contact information of the purchaser for invoice.

GET v2/IssuedInvoices/Default

Method returns empty invoice with default values. Returned resource is suitable for new invoice creation.

GET v2/IssuedInvoices/Expand

Returns Issued invoice list with related entities such as contact information etc.

POST v2/IssuedInvoices

Create new issued invoice. Invoice should contains only items with ItemTypeNormal.

POST v2/IssuedInvoices/{id}/Recount

Method recounts summaries of the invoice model for update. Invoice should contains only items with ItemTypeNormal.

POST v2/IssuedInvoices/Accounting

Creates new issued invoice and uses it for accounting of proforma invoice. The proforma invoice must be fully paid.

POST v2/IssuedInvoices/Recount

Method recounts summaries of the invoice model for creation. Invoice should contains only items with ItemTypeNormal.

PUT v2/IssuedInvoices/{id}

Method updates issued invoice by Id. Also possible to update single preperties of invoice. Invoice should contains only items with ItemTypeNormal.

PUT v2/IssuedInvoices/{id}/Exported/{exported}

Method updates Exported property of the invoice.

PUT v2/IssuedInvoices/{id}/FullyPay

Method sets invoice as paid.

PUT v2/IssuedInvoices/{id}/FullyUnpay

Method sets invoice as unpaid.

PUT v2/IssuedInvoices/{id}/MyDocumentAddress

Method Updates contact informations of the supplier.

PUT v2/IssuedInvoices/{id}/PurchaserDocumentAddress

Method Updates contact informations of the purchaser.

PUT v2/IssuedInvoices/{id}/SendMailToPurchaser

Method sends email with issued invoice to the purchaser.

PUT v2/IssuedInvoices/SetAttachment/{invoiceId}

Sets an attachment to the given issued invoice. If an attachment already exists, it will be overwritten.

PATCH v2/IssuedInvoices/{id}

Method updates issued invoice by Id. Also possible to update single preperties of invoice. Invoice should contains only items with ItemTypeNormal.

DELETE v2/IssuedInvoices/{id}

Deletes issued invoice by Id.

DELETE v2/IssuedInvoices/DeleteAttachment/{invoiceId}

Deletes an issued invoice attachment.

PriceListItems

Methods for working with price list items.

Useful tips

For more efficient work with the pricelist, you can use batch operations for insert and delete.

GET v2/PriceListItems

Returns price list with pages.

GET v2/PriceListItems/{id}

Returns price list item by Id.

GET v2/PriceListItems/{id}/Expand

Method returns price list item by its Id with extended entities.

GET v2/PriceListItems/Default

Method returns default price list item that is suitable for new item creation.

GET v2/PriceListItems/Expand

Price list with related entities.

POST v2/PriceListItems

Insert new price item into the price list.

POST v2/PriceListItems/Batch

Insert new price item into the price list. Batch version.

PUT v2/PriceListItems/{id}

Method updates price list item.

PUT v2/PriceListItems/Batch

Updates price list items. Batch operation.

PATCH v2/PriceListItems/{id}

Method updates price list item.

PATCH v2/PriceListItems/Batch

Updates price list items. Batch operation.

DELETE v2/PriceListItems/{id}/{deleteIfReferenced}

Deletes a price list item.

DELETE v2/PriceListItems/Batch/{deleteIfReferenced}

Deletes multiple price list items.

ProformaInvoices

Methods for working with proforma invoices.

GET v2/ProformaInvoices

Returns list of proforma invoices. Filters are optional.

GET v2/ProformaInvoices/{contactId}/Invoices

Returns invoice list for specific contact.

GET v2/ProformaInvoices/{id}

Returns information about a proforma invoice, including summaries.

GET v2/ProformaInvoices/{id}/Account

Returns new issued invoice for accounting of proforma invoice with given id. The proforma invoice must be fully paid.

GET v2/ProformaInvoices/{id}/Copy

Method returns copy of proforma invoice. Returned resource is suitable for new invoice creation.

GET v2/ProformaInvoices/{id}/Expand

Returns Proforma invoice with related entities by Id.

GET v2/ProformaInvoices/{id}/GetAttachment

Returns attachment for invoice. File is Base64 encoded and is returned as string.

GET v2/ProformaInvoices/{id}/GetAttachmentCompressed

Returns compressed attachment for invoice. File is Base64 encoded and is returned as string.

GET v2/ProformaInvoices/{id}/GetCashVoucherPdf

Returns Pdf file with Cash voucher report for the invoice. File is Base64 encoded and is returned as string.

GET v2/ProformaInvoices/{id}/GetCashVoucherPdfCompressed

Returns zipped Pdf file with Cash voucher report for the invoice. File is Base64 encoded and is returned as string.

GET v2/ProformaInvoices/{id}/GetPdf

Returns Pdf file with Proforma Invoice. File is Base64 encoded and is returned as string.

GET v2/ProformaInvoices/{id}/GetPdfCompressed

Returns zipped Pdf file with Proforma Invoice report. File is Base64 encoded and is returned as string.

GET v2/ProformaInvoices/{id}/GetPdfWithPayments

Returns Pdf file with Issued Invoice with payments. File is Base64 encoded and is returned as string.

GET v2/ProformaInvoices/{id}/GetPdfWithPaymentsCompressed

Returns zipped Pdf file with Issued Invoice report with payments. File is Base64 encoded and is returned as string.

GET v2/ProformaInvoices/{id}/MyDocumentAddress

Contact information of the supplier for invoice.

GET v2/ProformaInvoices/{id}/PurchaserDocumentAddress

Contact information of the purchaser for invoice.

GET v2/ProformaInvoices/Default

Method returns empty proforma invoice with default values. Returned resource is suitable for new invoice creation.

GET v2/ProformaInvoices/Expand

Returns proforma invoice list with related entities such as contact information etc.

POST v2/ProformaInvoices

Create new proforma invoice. Invoice should contains only items with ItemTypeNormal.

POST v2/ProformaInvoices/{id}/Recount

Method recounts summaries of the invoice model for update. Invoice should contains only items with ItemTypeNormal.

POST v2/ProformaInvoices/Recount

Method recounts summaries of the invoice model for creation. Invoice should contains only items with ItemTypeNormal.

PUT v2/ProformaInvoices/{id}

Method fully updates proforma invoice by Id.

PUT v2/ProformaInvoices/{id}/Account

Accounts the proforma invoice with given id. The invoice must be fully paid.

PUT v2/ProformaInvoices/{id}/Exported/{exported}

Method updates Exported property of the invoice.

PUT v2/ProformaInvoices/{id}/FullyPay

Method sets proforma invoice as paid.

PUT v2/ProformaInvoices/{id}/FullyUnpay

Sets proforma invoice as unpaid.

PUT v2/ProformaInvoices/{id}/SendMailToPurchaser

Sends email with proforma invoice as an attachment to the purchaser.

PUT v2/ProformaInvoices/SetAttachment/{invoiceId}

Sets an attachment to the given proforma invoice. If an attachment already exists, it will be overwritten.

PATCH v2/ProformaInvoices/{id}

Method updates proforma invoice by Id. Also possible to update single preperties of invoice. Invoice should contains only items with ItemTypeNormal.

DELETE v2/ProformaInvoices/{id}

Deletes proforma invoice by Id.

DELETE v2/ProformaInvoices/DeleteAttachment/{invoiceId}

Deletes a proforma invoice attachment.

ReceivedDocumentPayments

Methods for working with received invoice payments.

GET v2/ReceivedDocumentPayments

Returns list of payments. Filters are optional.

GET v2/ReceivedDocumentPayments/{id}

Returns information about a payment.

GET v2/ReceivedDocumentPayments/{id}/Expand

Returns payment with related entities by Id.

GET v2/ReceivedDocumentPayments/Default/{documentId}

Method returns default payment for given document. Returned model is suitable for new payment creation.

GET v2/ReceivedDocumentPayments/Expand

Returns list of payments with related entities such as document of payment.

POST v2/ReceivedDocumentPayments

Create new payment. Payment should contains id of payed document.

PUT v2/ReceivedDocumentPayments/{id}/Exported/{exported}

Method updates Exported property of the payment.

DELETE v2/ReceivedDocumentPayments/{id}

Deletes payment by Id. If payment has cash voucher, it is deleted as well.

ReceivedInvoices

Methods for working with received invoices.

GET v2/ReceivedInvoices

Returns list of received invoices. Filters are optional.

GET v2/ReceivedInvoices/{id}

Returns information about received invoice including summaries.

GET v2/ReceivedInvoices/{id}/Copy

Method returns copy of received invoice. Returned resource is suitable for new invoice creation.

GET v2/ReceivedInvoices/{id}/Expand

Returns Received invoice with related entities by Id.

GET v2/ReceivedInvoices/{id}/GetAttachment

Returns attachment for invoice. File is Base64 encoded and is returned as string.

GET v2/ReceivedInvoices/{id}/GetAttachmentCompressed

Returns compressed attachment for invoice. File is Base64 encoded and is returned as string.

GET v2/ReceivedInvoices/{id}/GetPdf

Returns a pdf of the received invoice. The document is encoded in Base64 encoding and returned as a string.

GET v2/ReceivedInvoices/{id}/GetPdfCompressed

Returns a pdf of the received invoice. This pdf is compressed into a zip file. The archive is encoded in Base64 encoding.

GET v2/ReceivedInvoices/{id}/MyDocumentAddress

Contact information of the purchaser for invoice.

GET v2/ReceivedInvoices/{id}/SupplierDocumentAddress

Contact information of the supplier for invoice.

GET v2/ReceivedInvoices/{supplierId}/ReceivedInvoices

Returns received invoice list for specific contact.

GET v2/ReceivedInvoices/Default

Method returns empty invoice with default values. Returned resource is suitable for new invoice creation.

GET v2/ReceivedInvoices/Expand

Returns list of received invoices with related entities.

POST v2/ReceivedInvoices

Create new Received Invoice.

POST v2/ReceivedInvoices/{id}/Recount

Method recounts summaries of the invoice model for update.

POST v2/ReceivedInvoices/Recount

Method recounts summaries of the invoice model for creation.

PUT v2/ReceivedInvoices/{id}

Method updates received invoice by Id.

PUT v2/ReceivedInvoices/{id}/Exported/{exported}

Method updates Exported proterty of the invoice.

PUT v2/ReceivedInvoices/{id}/FullyPay

Method sets invoice as paid.

PUT v2/ReceivedInvoices/{id}/FullyUnpay

Method sets invoice as unpaid.

PUT v2/ReceivedInvoices/{id}/MyDocumentAddress

Updates contact informations of the purchaser.

PUT v2/ReceivedInvoices/{id}/SupplierPurchaserDocumentAddress

Method Updates contact informations of the supplier.

PUT v2/ReceivedInvoices/SetAttachment/{invoiceId}

Sets an attachment to the given received invoice. If an attachment already exists, it will be overwritten.

PATCH v2/ReceivedInvoices/{id}

Updates received invoice by Id.

DELETE v2/ReceivedInvoices/{id}

Deletes received invoice by Id.

DELETE v2/ReceivedInvoices/DeleteAttachment/{invoiceId}

Deletes a received invoice attachment.

RegisteredSale

Methods for working with registered sales.

GET v2/RegisteredSales

Returns information about registered sales.

GET v2/RegisteredSales/{type}/{id}

Returns information about a registered sale.

GET v2/RegisteredSales/{type}/{id}/Expand

Returns information about a registered sale with related entities.

GET v2/RegisteredSales/Default

Method returns empty registered sale with default values. Returned resource is suitable for creation of a new registered sale.

GET v2/RegisteredSales/Expand

Returns information about registered sales with related entities.

POST v2/RegisteredSales/{type}/{id}

Create new registered sale.

SalesReceipts

Methods for working with sales receipts.

GET v2/SalesReceipts

Returns list of sales receipts. Filters are optional.

GET v2/SalesReceipts/{id}

Returns information about a sales receipt.

GET v2/SalesReceipts/{id}/Expand

Returns sales receipt with related entities by Id.

GET v2/SalesReceipts/{id}/GetPdf

Returns Pdf file with sales receipt report. File is Base64 encoded and is returned as string.

GET v2/SalesReceipts/{id}/GetPdfCompressed

Returns zipped Pdf file with sales receipt report. File is Base64 encoded and is returned as string.

GET v2/SalesReceipts/Default

Method returns empty sales receipt with default values. Returned resource is suitable for creation of a new sales receipt.

GET v2/SalesReceipts/Expand

Returns sales receipt with related entities by Id.

POST v2/SalesReceipts

Create new sales receipt.

POST v2/SalesReceipts/{id}/Recount

Method recounts summaries of the sales receipt model for update.

POST v2/SalesReceipts/Recount

Method recounts summaries of the sales receipt model for creation.

PUT v2/SalesReceipts/{id}

Method updates sales receipt by Id.

PUT v2/SalesReceipts/{id}/EetStatus/{eetStatus}

Updates the EetStatus property of the sales receipt.

PUT v2/SalesReceipts/{id}/Exported/{exported}

Updates the Exported property of the sales receipt.

PUT v2/SalesReceipts/{id}/Imported/{value}

Updates the Imported property of the sales receipt.

PATCH v2/SalesReceipts/{id}

Method updates sales receipt by Id.

DELETE v2/SalesReceipts/{id}

Deletes sales receipt by Id.

StockMovements

Methods for working with stock movements.

Useful tips

  • Stock movements are made automatically if you use a stock item on your invoice.
  • For more efficient request usage, you can POST movements in batches.
GET v2/StockMovements

Returns a paged list of stock movements.

GET v2/StockMovements/{id}

Returns the stock movement with the specified id.

GET v2/StockMovements/Default/{priceListItemId}

Returns a stock movement model according to agenda settings.

POST v2/StockMovements

Creates a new stock movement. To decrease stock balance, use a negative amount. In case the pricelist item is not marked as a stock item, it will be updated to a stock item.

POST v2/StockMovements/Batch

Creates new stock movements. The movements can be for different pricelist items. To decrease stock balance, use a negative amount.

PATCH v2/StockMovements/{id}

Method updates price list item.

DELETE v2/StockMovements/{id}

Deletes the stock movement with the provided id.


Secondary entities

CashRegisters

Methods for working with cash registers.

Terminology

A cash register is not the same as a POS equipment. If you are looking for a SalesPosEquipmentId for EET, use the GET/SalesPosEquipments method.

GET v2/CashRegisters

Returns list of cash registers.

GET v2/CashRegisters/{id}

Returns information a cash register.

GET v2/CashRegisters/{id}/Expand

Returns cash register with related entities by Id.

GET v2/CashRegisters/Expand

Returns list of cash registers with related entities.

DocumentAddresses

Methods for working with document contact information.

Terminology

A Contact is a contact in your contact list. A DocumentAddress is created when your document is created - one for the purchaser and one for the supplier. The information on the invoice does not have to correspond with the information on the contact (when you change a contact, DocumentAddress is not changed). DocumentAddress can be changed by using the PATCH/DocumentAddresses method, which allows partial updates.

GET v2/DocumentAddresses/{id}

Returns document contact information. Every invoice has two of these entities - one for the supplier and one for the purchaser.

PUT v2/DocumentAddresses/{id}

Updates contact information on the invoice by DocumentAddressId.

PATCH v2/DocumentAddresses/{id}

Updates contact information on the invoice by DocumentAddressId.

NumericSequences

Methods for working with numeric sequences.

Useful tips

In case you want to put documents into the default numeric sequence for the given document type, you don't have to specify the NumericSequenceId.

GET v2/NumericSequences

Returns a paged list of numeric sequences.

GET v2/NumericSequences

Returns the numeric sequence with the provided Id.

SalesOffice

Methods for working with sales offices.

GET v2/SalesOffice

Returns list of sales offices. Filters are optional.

SalesPosEquipment

Methods for working with POS equipments.

GET v2/SalesPosEquipment

Returns list of POS equipments. Filters are optional.

GET v2/SalesPosEquipment/Expand

Returns POS equipments list with related entities.

GET v2/SalesPosEquipment/Info

Returns information about the paired device, including numeric sequence info.


Lists

Banks

List of banks.

GET v2/Banks

Method returns list of banks.

GET v2/Banks/{id}

Method returns bank by Id.

GET v2/Banks/GetChanges

Method returns list of banks, that were changed.

ConstantSymbols

List of constant symbols.

GET v2/ConstantSymbols

Method returns list of constant symbols.

GET v2/ConstantSymbols/{id}

Method returns constant symbol by Id.

GET v2/ConstantSymbols/GetChanges

Method returns list of constant symbols, that were changed.

Countries

List of countries.

GET v2/Countries

Method returns list of countries.

GET v2/Countries/{id}

Method returns country by Id.

GET v2/Countries/GetChanges

Method returns list of countries, that were changed.

Currencies

List of currencies.

GET v2/Currencies

Method returns list of currencies.

GET v2/Currencies/{id}

Method returns currency by Id.

GET v2/Currencies/GetChanges

Method returns list of currencies, that were changed.

ExchangeRates

List of exchange rates.

GET v2/ExchangeRates

Method returns list of exchange rates.

GET v2/ExchangeRates/{id}

Method returns exchange rate by Id.

GET v2/ExchangeRates/GetChanges

Method returns list of exchange rates, that were changed.

PaymentOptions

List of payment options.

GET v2/PaymentOptions

Method returns list of payment options.

GET v2/PaymentOptions/{id}

Method returns payment option by Id.

GET v2/PaymentOptions/GetChanges

Method returns list of payment options, that were changed.

System

System functions for working with lists.

GET v2/System/GetCodeBooks

Returns all code books

GET v2/System/GetCodeBooksChanges

Provides information about system tables changes.

VatCodes

Method for work with Vat codes.

GET v2/VatCodes

Method returns list of Vat codes.

GET v2/VatCodes/{id}

Method returns Vat code by Id.

GET v2/VatCodes/GetChanges

Method returns list of the VAT codes that were changed.

VatRates

List of VAT rates.

GET v2/VatRates

Method returns list of Vat rates.

GET v2/VatRates/{id}

Method returns Vat rate by Id.

GET v2/VatRates/GetChanges

Method returns list of the VAT rates that were changed.

VatReverseChargeCodes

List of VAT reverse charge codes.

GET v{version:apiVersion}/VatReverseChargeCodesVersion2

No documentation available.

GET v2/VatReverseChargeCodes

Method returns list of vat reverse charge codes.

GET v2/VatReverseChargeCodes/{id}

Returns the VAT reverse charge code with the given id.



Other

Attachments

Methods for working with attachments.

Useful tips

  • Uncompressed attachments are encoded using Base64.
  • Compressed attachments are zipped. The zip archive is encoded using Base64.
  • The maximum attachment size is 5MB.
  • Attachment upload is done by using the multipart/form-data content-type. If you are getting a 415 Unsupported Media Type error, check your request headers.
GET v2/Attachments/{documentId}/{documentType}/{compressed}

Returns the attachment for the requested document.

PUT v2/Attachments/{documentId}/{documentType}

Sets an attachment to the given document. If an attachment already exists, it will be overwritten.

DELETE v2/Attachments/{documentId}/{documentType}

Deletes an attachment.

Batch

Batch operations.

PUT v2/Batch/Exported

Updates an entity's Exported property. Used in communication with external accounting software.

Mails

Methods for working with e-mails.

Useful tips

  • You can change the language of a sent invoice through the Language property. You can also specify a custom template in a foreign language and send e-mails to foreign clients.
  • The custom template can contain the same placeholders as the web application.

Careful

  • Not all properties are the same across entities (for example, a received invoice cannot be sent via link).
POST v2/Mails/CreditNote/Send

Send a credit note.

POST v2/Mails/IssuedDocumentPayments/SendConfirmation/{id}

Send payment confirmation

POST v2/Mails/IssuedInvoice/Send

Send an issued invoice.

POST v2/Mails/ProformaInvoice/Send

Send a proforma invoice.

POST v2/Mails/ReceivedInvoice/Send

Send a received invoice.

POST v2/Mails/SalesOrder/Send

Send a sales order.

Reports

Methods for working with reports.

Useful tips

  • Each method contains the following optional parameters:
    • Language - the language of the returned report (allowed values are jsou Cz, Sk, De, En). The parameter takes the highest priority.
    • Compressed - further compress the file to a zip archive. The archive is returned encoded using Base64.
GET v2/Reports/CashVoucher/{id}/Pdf

Returns a pdf file of the requested cash voucher.

GET v2/Reports/CreditNote/{id}/Pdf

Returns a Pdf file with the requested credit note.

GET v2/Reports/CreditNote/{id}/PdfWithPayments

Returns a pdf file with the requested credit mote and its payments.

GET v2/Reports/IssuedInvoice/{id}/CashVoucherPdf

Returns a pdf file with the cash voucher for the requested invoice.

GET v2/Reports/IssuedInvoice/{id}/Pdf

Returns a pdf of the requested invoice.

GET v2/Reports/IssuedInvoice/{id}/PdfWithPayments

Returns a pdf file with the requested invoice and its payments.

GET v2/Reports/ProformaInvoice/{id}/CashVoucherPdf

Returns a pdf file with with the cash voucher for the requested proforma invoice.

GET v2/Reports/ProformaInvoice/{id}/Pdf

Returns a pdf file with the requested proforma invoice.

GET v2/Reports/ReceivedInvoice/{id}/Pdf

Returns a pdf of the requested received invoice.

GET v2/Reports/SalesReceipt/{id}/Pdf

Returns a pdf file with the requested sales receipt.

Test

Endpoints used for testing.

GET v{version:apiVersion}/TestVersion2

Does not perform any action, only returns the provided query string in the response. Can be used as a redirect url for oauth callback in authorization code flow.

GET v2/Test/DowngradeNeeded

Always returns the status code indicating that your subscription needs to be manually downgraded in the application.

GET v2/Test/GetActualApiLimit

Returns the current API request count.

GET v2/Test/PaymentRequired

Always returns the status code indicating that a subscription needs to be purchased.

GET v2/Test/RateLimitExceeded

Always returns the status code used for exceeded rate limits.