Infoproff API Documentation - v3

Getting Started

Web service wsdl and schemas are located here:

http://wsdfn.infoproff.com/v3/

Web service functions:

SimpleSearch - Search companies information in different countries.
ChkFinance - Search for available financial statements.
Order - Creates an order_id and returns duplicates. Duplicates are selected by next parameters: country, product, reg_code.
OrderCancellation - If you sent an order request and received the order_id, you have an opportunity to cancel this order (if is it not gone into production).
OrderConfirmation - After getting order_id you will have to confirm your order within 1 hour. If you don't confirm your order within 1 hour, the order will be cancelled automatically.
ChkStatus - Check order status.
GetReport - Get finished reports.

GetClassifiersFinancialStatements - Get all financial documents with all elements: row_number, row_formated_description, row_lang_key and row_order.
GetLegalForms - Get all legal forms for all available countries.
GetActivityClassificators - Get all codes and descriptions for specific activity classificator.
GetDictionaryStandardPhrases - Get all standard phrases with keys and language.
GetAvailableProducts - Get a list of available products.

CreditOpinionCalculator - Credit Opinion Calculator helps to assign credit opinion on a company.

API provides several services:

Online credit reports for the following countries: Finland (FIN), Sweden (SWE), Belgium (BEL), Netherlands (NLD), Estonia (EST), Kazakhstan (KAZ), Poland (POL), Kyrgyzstan (KGZ), China (CHN), Mongolia (MNG)
Offline reports for the following countries: All countries
Credit opinion calculator

How to search for a company?

The company search consists of 2 options:

Search by company name,
Search by company code.

List of available countries: Albania (ALB), Algeria (DZA), Angola (AGO), Argentina (ARG), Australia (AUS), Austria (AUT), Azerbaijan (AZE), Belarus (BLR), Belgium (BEL), Benin (BEN), Bolivia (BOL), Bosnia and Herzegovina (BIH), Botswana (BWA), Brazil (BRA), Bulgaria (BGR), Canada (CAN), Chile (CHL), China (CHN), Congo (COG), Croatia (HRV), Cyprus (CYP), Czech Republic (CZE), Denmark (DNK), Ecuador (ECU), Estonia (EST), Ethiopia (ETH), Finland (FIN), France (FRA), French Guiana (GUF), Gambia (GMB), Georgia (GEO), Germany (DEU), Greece (GRC), Greenland (GRL), Guadeloupe (GLP), Guinea (GIN), Guyana (GUY), Hong Kong (HKG), Hungary (HUN), Iceland (ISL), Ireland (IRL), Isle of Man (IMN), Israel (ISR), Italy (ITA), Ivory Coast (CIV), Japan (JPN), Jersey (JEY), Kazakhstan (KAZ), Kenya (KEN), Kosovo (XXK), Kyrgyzstan (KGZ), Latvia (LVA), Liechtenstein (LIE), Lithuania (LTU), Luxembourg (LUX), Madagascar (MDG), Maldives (MDV), Malta (MLT), Martinique (MTQ), Mauritius (MUS), Mayotte (MYT), Moldova (MDA), Monaco (MCO), Mongolia (MNG), Morocco (MAR), Namibia (NAM), Netherlands (NLD), New Zealand (NZL), Nigeria (NGA), Norway (NOR), Paraguay (PRY), Peru (PER), Philippines (PHL), Poland (POL), Portugal (PRT), Reunion (REU), Romania (ROU), Russia (RUS), Rwanda (RWA), Saint Martin (MAF), Samoa (WSM), San Marino (SMR), Serbia (SRB), Seychelles (SYC), Singapore (SGP), Slovakia (SVK), Slovenia (SVN), South Africa (ZAF), Spain (ESP), Sri Lanka (LKA), Sweden (SWE), Switzerland (CHE), Taiwan (TWN), Tajikistan (TJK), Tanzania (TZA), Thailand (THA), Togo (TGO), United Arab Emirates (ARE), United Kingdom (GBR), Uruguay (URY), Uzbekistan (UZB), Venezuela (VEN), Zambia (ZMB), Zimbabwe (ZWE)

The search for other countries is performed only in the database of archived reports. If you do not find the desired company, enter the company details manually.

Important information:

search_result_id can be acquired here for orders with delivery_term = "o" or delivery_term = "a".

It may take up to 20 seconds to respond to a search request in the following countries: United Kingdom, Ireland, France, Spain, Portugal, Germany, Italy, Austria, Switzerland.

Norway register does not allow to search deleted companies by names. Therefore, we cannot provide a SimpleSearch by names within deleted companies in Norway.

Field's length:
company_name varchar(512)
company_code varchar(64)

Below you can find the example:

Option 1: Search by company name

Function SimpleSearch

Option 2: Search by registration code

Function SimpleSearch

Option 3: Search by query (by name or code)

Function UnifiedSearch

How to order a credit report?

List of available countries for online credit reports: Austria (AUT), Azerbaijan (AZE), Belgium (BEL), Bulgaria (BGR), China (CHN), Croatia (HRV), Czech Republic (CZE), Estonia (EST), Finland (FIN), France (FRA), Germany (DEU), Greece (GRC), Hungary (HUN), Ireland (IRL), Italy (ITA), Kazakhstan (KAZ), Kyrgyzstan (KGZ), Luxembourg (LUX), Malta (MLT), Moldova (MDA), Mongolia (MNG), Netherlands (NLD), Norway (NOR), Poland (POL), Portugal (PRT), Russia (RUS), Slovakia (SVK), Slovenia (SVN), Spain (ESP), Sweden (SWE), Switzerland (CHE), United Kingdom (GBR)

Field's length:
business_name varchar(512)
reg_code varchar(64)
vat_code varchar(64)
address varchar(512)
phone varchar(256)
email varchar(256)
additional_info varchar(512)
ref_code varchar(64)

Below you can find the example of how to order and download reports:

Online/Offline Order Example (with search_result_id)
Offline Order Example (without search_result_id)

STEP 1: Find a company (Online/Offline Order (with search_result_id))

Function SimpleSearch

To order an Online/Offline with identification report you need to receive "<search_result_id>".
To do so, please follow the link: How to search for a company?

The search allows you to accurately identify the company you wish to place an order for. For example, in some countries, there may be several companies with one registration number, or the same official name may belong to several companies.

STEP 2: Order a report (Online/Offline Order (with search_result_id))

Function Order

If you won't use the element confirm_order, then you will receive <last_duplicates> in the XML response, so that you can decide if you really need to place an order.

STEP 3: Order cancellation (Optional) (Online/Offline Order (with search_result_id))

Function OrderCancellation

If you wish to cancel the order, you can use this OrderCancellation function. If the order is already in progress, then you won't be able to cancel it.

STEP 4: Order confirmation (Online/Offline Order (with search_result_id))

Function OrderConfirmation

If you didn't use the element "confirm_order", then you need to confirm your order.

STEP 5: Check order status (Online/Offline Order (with search_result_id))

Function ChkStatus

- For offline orders checking order status once every 30 minutes is acceptable frequency.
- For online orders checking order status once every 5 seconds is acceptable frequency.

The following statuses are used for reports:

In progress - Report at the production stage
Identification pending - Preparation of report in on hold. Requires additional data from the client.
Canceled - Canceled order
Finished - The report is ready
Updated - Information was added to the finished report
Rejected - Order is rejected (Insufficient funds, incorrect order details or other reason).
Technical Error - A technical error has occurred in our system. This means, that we are informed about this error and will fix it ASAP. You will be informed when you will be able to receive the order.

If the execution status is Finished or Updated, then you can get an order.

STEP 6: Get report (Online/Offline Order (with search_result_id))

Function GetReport

List of available languages: bg (Bulgarian), cs (Czech), da (Danish), de (German), el (Greek), en (English), es (Spanish), et (Estonian), fi (Finnish), fr (French), hu (Hungarian), id (Indonesian), it (Italian), ja (Japanese), ko (Korean), lt (Lithuanian), lv (Latvian), nb (Norwegian Bokmål), nl (Dutch), pl (Polish), pt (Portuguese), ro (Romanian), ru (Russian), sk (Slovak), sl (Slovenian), sr (Српски), sv (Swedish), tr (Turkish), uk (Ukrainian), zh (Chinese)

STEP 1: Order a report (Offline Order (without search_result_id))

Function Order

If you won't use the element confirm_order, then you will receive <last_duplicates> in the XML response, so that you can decide if you really need to place an order.

STEP 2: Order cancellation (Optional) (Offline Order (without search_result_id))

Function OrderCancellation

If you wish to cancel the order, you can use OrderCancellation function. If the order is already in progress, then you won't be able to cancel it.

STEP 3: Order confirmation (Offline Order (without search_result_id))

Function OrderConfirmation

If you didn't use the element "confirm_order", then you need to confirm your order.

STEP 4: Status Checking (Offline Order (without search_result_id))

Function ChkStatus

For offline orders checking order status once every 30 minutes is acceptable frequency.

The following statuses are used for reports:

In progress - Report at the production stage
Identification pending - Preparation of report in on hold. Requires additional data from the client.
Canceled - Canceled order
Finished - The report is ready
Updated - Information was added to the finished report
Rejected - Order is rejected (Insufficient funds, incorrect order details or other reason).
Technical Error - A technical error has occurred in our system. This means, that we are informed about this error and will fix it ASAP. You will be informed when you will be able to receive the order.

If the execution status is Finished or Updated, then you can get an order.

STEP 5: Get report (Offline Order (without search_result_id))

Function GetReport

How to order an archived credit report?

Purchase of an archived report is available for all countries.

Below you can find the example of how to order and download archived reports:

STEP 1: Find a company

Function SimpleSearch

To order an archived report you need to receive "<search_result_id>" which has an "<archived_reports>" section that contains a product you need.
To do so, please follow the link: How to search for a company?

Example companies with archived reports:

Country: EST, Reg. Code: 12309116

Country: EST, Reg. Code: 12854256

Country: EST, Reg. Code: 12830238

Country: USA, Company name: Apple

STEP 2: Order a report

Function Order

STEP 3: Order cancellation (Optional)

Just like the online/offline reports.

STEP 4: Order confirmation

Just like the online/offline reports.

STEP 5: Check order status

Just like the online/offline reports.

For archived orders checking order status once every 5 seconds is acceptable frequency.

STEP 6: Get report

Just like the online/offline reports.

How to order online financial statements?

STEP 1: Find a company

Function SimpleSearch

To order an online financial statements, you need to receive "<search_result_id>".
To do so, please follow the link: How to search for a company?

The search allows you to accurately identify the company you wish to place an order for. For example, in some countries, there may be several companies with one registration number, or the same official name may belong to several companies.

STEP 2: Search for available financial statements

Function ChkFinance

This function is only needed when ordering a product: finances (Financial statements) with delivery_term = 'o'.

List of available countries: Estonia (EST), Sweden (SWE)

STEP 3: Order financial statements

Function Order

If you won't use the element confirm_order, then you will receive <last_duplicates> in the XML response, so that you can decide if you really need to place an order.

STEP 4: Order cancellation (Optional)

Function OrderCancellation

If you wish to cancel the order, you can use this OrderCancellation function. If the order is already in progress, then you won't be able to cancel it.
To see the examples of xml request/response, please follow the link: How to cancel the order?

STEP 5: Order confirmation

Function OrderConfirmation

If you didn't use the element "confirm_order", then you need to confirm your order.
To see the examples of xml request/response, please follow the link: How to confirm the order?

STEP 6: Check order status

Function ChkStatus

- For online orders checking order status once every 5 seconds is acceptable frequency.

The following statuses are used for reports:

In progress - Report at the production stage

Identification pending - Preparation of report in on hold. Requires additional data from the client.

Canceled - Canceled order

Finished - The report is ready

Updated - Information was added to the finished report

Rejected - Order is rejected (Insufficient funds, incorrect order details or other reason).

Technical Error - A technical error has occurred in our system. This means, that we are informed about this error and will fix it ASAP. You will be informed when you will be able to receive the order.

If the execution status is Finished or Updated, then you can get an order.

To see the examples of xml request/response, please follow the link: How to check order status?

STEP 7: Get report

Function GetReport

List of available languages: bg (Bulgarian), cs (Czech), da (Danish), de (German), el (Greek), en (English), es (Spanish), et (Estonian), fi (Finnish), fr (French), hu (Hungarian), id (Indonesian), it (Italian), ja (Japanese), ko (Korean), lt (Lithuanian), lv (Latvian), nb (Norwegian Bokmål), nl (Dutch), pl (Polish), pt (Portuguese), ro (Romanian), ru (Russian), sk (Slovak), sl (Slovenian), sr (Српски), sv (Swedish), tr (Turkish), uk (Ukrainian), zh (Chinese)
To see the examples of xml request/response, please follow the link: How to get finished order?

How to download standard reports (in formats other than XML)?

Types of standard product: Basic Report, Mini Report, Linkages, Registration Data Report, Full report (private person), Short report (private person), Full report (with research), Financials (bank), Short Report, Real estate ownership search, Extended report, Full Report, KYC Report, Linked persons, Credit Opinion, Financial statements.

The request consist of 3 parts:

Fixed part https://www.infoproff.com/en/orders/files/

Your unique hash, which we provide in response

And fixed part at the end /report?&lang=en&doc_type=pdf&currency_position=left&preferred_currency=EUR

https://www.infoproff.com/en/orders/files/<order_hash>/report?&lang=en&doc_type=pdf&currency_position=left&preferred_currency=EUR
lang: en, et, ru, lv, bg, cs, da, de, el, fi, fr, hu, id, it, ja, ko, lt, nl, nb, pl, pt, ro, sk, sl, es, sr, sv, tr, uk, zh
doc_type: pdf, html, docx, xlsx
currency_position: left, right
preferred_currency: XXX - Original (no exchange), EUR, USD, AUD, BGN, BRL, CAD, CHF, CNY, CZK, DKK, GBP, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KRW, MXN, MYR, NOK, NZD, PHP, PLN, RON, RUB, SEK, SGD, THB, TRY, ZAR

How to download non-standard products?

Types of non-standard product: Marketing database (special offer), Site visit - non-capital city, Extract from registry, Site visit - capital city, Due Diligence, non-standard, Shareholder document, Memorandum of Association, Certificate of incorporation.

The request consist of 3 parts:

Fixed part https://www.infoproff.com/en/orders/files/

Your unique hash, which we provide in response

And fixed part at the end /download

How to get credit opinion?

Function CreditOpinionCalculator

How to get additional information?

Function GetClassifiersFinancialStatements

Function GetLegalForms

Function GetActivityClassificators

Function GetDictionaryStandardPhrases

Function GetAvailableProducts

delivery_term:

"o" = "Online"

"n" = "Normal"

"f" = "Flash"

"s" = "SuperFlash"

Possible errors

These errors may occur while making request to our web service.

All functions

Incorrect username/password or you have no permissions.

You are entering wrong credentials or your API access is blocked.

Function SimpleSearch

You don't have permissions to search in this country.

List of available countries: Albania (ALB), Algeria (DZA), Angola (AGO), Argentina (ARG), Australia (AUS), Austria (AUT), Azerbaijan (AZE), Belarus (BLR), Belgium (BEL), Benin (BEN), Bolivia (BOL), Bosnia and Herzegovina (BIH), Botswana (BWA), Brazil (BRA), Bulgaria (BGR), Canada (CAN), Chile (CHL), China (CHN), Congo (COG), Croatia (HRV), Cyprus (CYP), Czech Republic (CZE), Denmark (DNK), Ecuador (ECU), Estonia (EST), Ethiopia (ETH), Finland (FIN), France (FRA), French Guiana (GUF), Gambia (GMB), Georgia (GEO), Germany (DEU), Greece (GRC), Greenland (GRL), Guadeloupe (GLP), Guinea (GIN), Guyana (GUY), Hong Kong (HKG), Hungary (HUN), Iceland (ISL), Ireland (IRL), Isle of Man (IMN), Israel (ISR), Italy (ITA), Ivory Coast (CIV), Japan (JPN), Jersey (JEY), Kazakhstan (KAZ), Kenya (KEN), Kosovo (XXK), Kyrgyzstan (KGZ), Latvia (LVA), Liechtenstein (LIE), Lithuania (LTU), Luxembourg (LUX), Madagascar (MDG), Maldives (MDV), Malta (MLT), Martinique (MTQ), Mauritius (MUS), Mayotte (MYT), Moldova (MDA), Monaco (MCO), Mongolia (MNG), Morocco (MAR), Namibia (NAM), Netherlands (NLD), New Zealand (NZL), Nigeria (NGA), Norway (NOR), Paraguay (PRY), Peru (PER), Philippines (PHL), Poland (POL), Portugal (PRT), Reunion (REU), Romania (ROU), Russia (RUS), Rwanda (RWA), Saint Martin (MAF), Samoa (WSM), San Marino (SMR), Serbia (SRB), Seychelles (SYC), Singapore (SGP), Slovakia (SVK), Slovenia (SVN), South Africa (ZAF), Spain (ESP), Sri Lanka (LKA), Sweden (SWE), Switzerland (CHE), Taiwan (TWN), Tajikistan (TJK), Tanzania (TZA), Thailand (THA), Togo (TGO), United Arab Emirates (ARE), United Kingdom (GBR), Uruguay (URY), Uzbekistan (UZB), Venezuela (VEN), Zambia (ZMB), Zimbabwe (ZWE)

Function Order

This product is not available.

Such product can't be found and it is not possible to order.

You can't order report on company with legal form: "legal_form"

This error only applies to: Sweden (SWE)
In Sweden it is not possible to order online report (delivery_term = "o") with the next legal forms:

enskild näringsidkare

kommanditbolag

handelsbolag

When delivery term is Online, please use order_details_by_id with search_result_id.

This error only appears if you are trying to order online report without search_result_id.
It is important yo use order_details_by_id in OrderReportRequest

Business Name or Reg Code is required

When ordering offline report (delivery_term = "n", "f" or "s") "Business Name" or "Reg Code" is required.

Reg Code is required when delivery term is Online

When ordering online report (delivery_term = "o") "Reg Code" is required.

Function GetReport

This language is not supported.

List of available languages for Online reports: bg (Bulgarian), cs (Czech), da (Danish), de (German), el (Greek), en (English), es (Spanish), et (Estonian), fi (Finnish), fr (French), hu (Hungarian), id (Indonesian), it (Italian), ja (Japanese), ko (Korean), lt (Lithuanian), lv (Latvian), nb (Norwegian Bokmål), nl (Dutch), pl (Polish), pt (Portuguese), ro (Romanian), ru (Russian), sk (Slovak), sl (Slovenian), sr (Српски), sv (Swedish), tr (Turkish), uk (Ukrainian), zh (Chinese)

Functions GetReport ChkStatus

Incorrect order_id.

Order ID can't be found. You get order ID when you use Order function.

Function OrderCancellation

Your order is already canceled.

You don't have permission to cancel the order anymore.

Function OrderConfirmation

You don't have permission to confirm the order anymore. Confirmation can be done within one hour after you recieved 'order_id'.

SOAP (Version 3) changes compared to SOAP (Version 2)

SOAP (Version 3) changes compared to SOAP (Version 2) [Overview]

1) New function: ChkFinance

Allows you to search for available financial statements.
Currently available only in EST (Estonia), SWE (Sweden)

2) Function: SimpleSearch

- Changes in list of available countries: Albania (ALB), Algeria (DZA), Angola (AGO), Argentina (ARG), Australia (AUS), Austria (AUT), Azerbaijan (AZE), Belarus (BLR), Belgium (BEL), Benin (BEN), Bolivia (BOL), Bosnia and Herzegovina (BIH), Botswana (BWA), Brazil (BRA), Bulgaria (BGR), Canada (CAN), Chile (CHL), China (CHN), Congo (COG), Croatia (HRV), Cyprus (CYP), Czech Republic (CZE), Denmark (DNK), Ecuador (ECU), Estonia (EST), Ethiopia (ETH), Finland (FIN), France (FRA), French Guiana (GUF), Gambia (GMB), Georgia (GEO), Germany (DEU), Greece (GRC), Greenland (GRL), Guadeloupe (GLP), Guinea (GIN), Guyana (GUY), Hong Kong (HKG), Hungary (HUN), Iceland (ISL), Ireland (IRL), Isle of Man (IMN), Israel (ISR), Italy (ITA), Ivory Coast (CIV), Japan (JPN), Jersey (JEY), Kazakhstan (KAZ), Kenya (KEN), Kosovo (XXK), Kyrgyzstan (KGZ), Latvia (LVA), Liechtenstein (LIE), Lithuania (LTU), Luxembourg (LUX), Madagascar (MDG), Maldives (MDV), Malta (MLT), Martinique (MTQ), Mauritius (MUS), Mayotte (MYT), Moldova (MDA), Monaco (MCO), Mongolia (MNG), Morocco (MAR), Namibia (NAM), Netherlands (NLD), New Zealand (NZL), Nigeria (NGA), Norway (NOR), Paraguay (PRY), Peru (PER), Philippines (PHL), Poland (POL), Portugal (PRT), Reunion (REU), Romania (ROU), Russia (RUS), Rwanda (RWA), Saint Martin (MAF), Samoa (WSM), San Marino (SMR), Serbia (SRB), Seychelles (SYC), Singapore (SGP), Slovakia (SVK), Slovenia (SVN), South Africa (ZAF), Spain (ESP), Sri Lanka (LKA), Sweden (SWE), Switzerland (CHE), Taiwan (TWN), Tajikistan (TJK), Tanzania (TZA), Thailand (THA), Togo (TGO), United Arab Emirates (ARE), United Kingdom (GBR), Uruguay (URY), Uzbekistan (UZB), Venezuela (VEN), Zambia (ZMB), Zimbabwe (ZWE)

- Each time you place an request we asaign a new 'search_result_id' for each company. You need to use this 'search_result_id' to place online orders.

Also you can place offline (delivery_term = 'n', 'f' or 's') orders with 'search_result_id', if you desire.

3) Function: Order

Identification is required!

To place an online order, you need to recieve 'search_result_id' from function 'SimpleSearch', and only after that you can place an online (delivery_term = 'o') order.

- Changes in list of available countries for online credit reports: Austria (AUT), Azerbaijan (AZE), Belgium (BEL), Bulgaria (BGR), China (CHN), Croatia (HRV), Czech Republic (CZE), Estonia (EST), Finland (FIN), France (FRA), Germany (DEU), Greece (GRC), Hungary (HUN), Ireland (IRL), Italy (ITA), Kazakhstan (KAZ), Kyrgyzstan (KGZ), Luxembourg (LUX), Malta (MLT), Moldova (MDA), Mongolia (MNG), Netherlands (NLD), Norway (NOR), Poland (POL), Portugal (PRT), Russia (RUS), Slovakia (SVK), Slovenia (SVN), Spain (ESP), Sweden (SWE), Switzerland (CHE), United Kingdom (GBR)

- Available to download financial statements (using product: finances) in online mode: Estonia (EST), Sweden (SWE)

3) Function: GetReport

- Changes in of available languages: bg (Bulgarian), cs (Czech), da (Danish), de (German), el (Greek), en (English), es (Spanish), et (Estonian), fi (Finnish), fr (French), hu (Hungarian), id (Indonesian), it (Italian), ja (Japanese), ko (Korean), lt (Lithuanian), lv (Latvian), nb (Norwegian Bokmål), nl (Dutch), pl (Polish), pt (Portuguese), ro (Romanian), ru (Russian), sk (Slovak), sl (Slovenian), sr (Српски), sv (Swedish), tr (Turkish), uk (Ukrainian), zh (Chinese)

SOAP (Version 3) changes compared to SOAP (Version 2) [WSDL and XSD]

File: report.xsd

New elements:

- report/negative_information/debts/item/remainder_range

- report/negative_information/debts/item/remainder_non_standard_range

File: report.wsdl

New function:

- ChkFinance

Function that allows you to search for available financial statements.

NB: This function is only needed when ordering a product: finances (Financial statements) with delivery_term = 'o'.

File: order.xsd

1) OrderReportRequest has a choice:

- order_details:

Using general information: business_name, reg_code, vat_code, address, phone, email, additional_info

NB:
* Business Name or Registration Code is required
* Only for orders with delivery_term: 'n', 'f' and 's' (credit reports in offline mode)

- order_details_by_id:

Using 'search_result_id'

NB:
* 'search_result_id' can be obtained with function: 'SimpleSearch'
* each new search generates new 'search_result_id'

2) order_details

New element:

- preferable_finances

NB: This element is required only ordering a product: finances (Financial statements) with delivery_term = 'o'.

3) SimpleSearchRequest

Removed element:

search_block.reg_code

New element:

search_block->company_code

NB: in some countries we allow to search companies by vat_code.

4) SimpleSearchResponse

Removed elements

- code

New elements:

- search_result_id (is required for order with delivery_term = 'o')

- name_transliteration

- reg_code

- vat_code

- unified_legal_form

Webhooks Settings

Overview

A webhook is a way for an application to provide other applications with real-time information. Our webhook feature implements HTTP callbacks configured with a URL. An HTTP POST payload is sent to this URL in JSON format whenever a specified event occurs. In the context of our project, we have designed the webhook function to trigger specific events.

Setting up a Webhook

To set up a webhook for your application, navigate to the application settings page and look for the 'Webhooks Settings' section. And provide the following information:

"Webhook URL" is the URL where your server will receive webhook POST requests.

"Delivery max attempts" is the setting that defines the maximum number of retry attempts that should be made for delivering a webhook event when the initial delivery attempt fails.

"Delivery retry timeout" is a setting that allows you to specify the time interval between retries when a webhook delivery attempt fails.

After providing these details, click on 'Save'.

Webhook Event Types

New status of order

Webhook Payload

When an event occurs, we'll send a HTTP POST request to the payload URL with a JSON body containing information about the event.

Here's an example payload:

Payload example of new status of order

Possible values of "new_status" field:

"Finished" - an order is complete. An order can be picked up;

"Updated" - an order updated, data added to a completed order;

"Canceled" - an order is canceled at a customer's request (or consent);

"Rejected" - an order is rejected. Usually because it is impossible to identify a company.

Securing your Webhooks

It's important to verify that POST requests sent to the payload URL are from our application. To assist with this, every webhook request includes a X-Signature header.

Signature Description

For signing we use HMAC with SHA512 algorithm.

Secret is a concatenation of App ID and Secret Key from the webhooks settings.

It is possible to add your own get params to the endpoint to identify the sender if necessary.

Troubleshooting

A server must respond within 10 seconds and return a 2XX HTTP code; otherwise, webhook delivery is considered failed. In case of failure, the feature will attempt to resend the request up according delivery policy.