Documentação API Infoproff - v3

Versão de interruptor V3

Começar

Serviço Web wsdl e esquemas estão aqui localizados:

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

Web service functions:

  • SimpleSearch - Pesquisar informação sobre empresas em diferentes países.
  • ChkFinance - Procurar demonstrações financeiras disponíveis.
  • Order - Cria um order_id e devolve duplicados. As duplicatas são seleccionadas pelos parâmetros seguintes: country, product, reg_code.
  • OrderCancellation - Se enviou um pedido de encomenda e recebeu o order_id, tem a oportunidade de cancelar esta encomenda (se não tiver entrado em produção).
  • OrderConfirmation - Depois de receber order_id terá de confirmar a sua encomenda dentro de 1 hora. Se não confirmar a sua encomenda no prazo de 1 hora, a encomenda será cancelada automaticamente.
  • ChkStatus - Verificar o estado da encomenda.
  • GetReport - Obter relatórios finais.
  • GetClassifiersFinancialStatements - Obter todos os documentos financeiros com todos os elementos: row_number, row_formated_description, row_lang_key e row_order.
  • GetLegalForms - Obtenha todas as formas legais para todos os países disponíveis.
  • GetActivityClassificators - Obtenha todos os códigos e descrições para o classificador de actividades específicas.
  • GetDictionaryStandardPhrases - Obtenha todas as frases padrão com chaves e linguagem.
  • GetAvailableProducts - Obter uma lista dos produtos disponíveis.
  • CreditOpinionCalculator - A calculadora de opinião de crédito ajuda a atribuir opinião de crédito sobre uma empresa.

A API fornece vários serviços:

  1. Relatórios de crédito online para os seguintes países: República da Finlândia (FIN), Reino da Suécia (SWE), Reino da Bélgica (BEL), Reino dos Países Baixos (NLD), República da Estónia (EST), República do Cazaquistão (KAZ), República da Polónia (POL), República do Quirguistão (KGZ), República Popular da China (CHN), Mongólia (MNG)
  2. Relatórios fora de linha para os seguintes países: Todos os países
  3. Calculadora de opinião de crédito

Como procurar uma empresa?

A pesquisa da empresa consiste em 2 opções:

  1. Pesquisa por nome de empresa,
  2. Search by company code.
Lista de países disponíveis: Bósnia e Herzegovina (BIH), Commonwealth da Austrália (AUS), Confederação Suíça (CHE), Emirados Árabes Unidos (ARE), Estado de Israel (ISR), Estado independente de Samoa (WSM), Federação Russa (RUS), Geórgia (GEO), Gronelândia (GRL), Grão-Ducado do Luxemburgo (LUX), Hong Kong (HKG), Ilha de Man (IMN), Irlanda (IRL), Japão (JPN), Kosovo (XXK), Mongólia (MNG), Nova Zelândia (NZL), O Bailiado de Jersey (JEY), Principado do Listenstaine (LIE), Principado do Mónaco (MCO), Reino Unido da Grã-Bretanha e da Irlanda do Norte (GBR), Reino da Bélgica (BEL), Reino da Dinamarca (DNK), Reino da Noruega (NOR), Reino da Suécia (SWE), Reino de Espanha (ESP), Reino de Marrocos (MAR), Reino dos Países Baixos (NLD), República Argentina (ARG), República Checa (CZE), República Democrática Popular da Argélia (DZA), República Eslovaca (SVK), República Federal da Alemanha (DEU), República Federativa do Brasil (BRA), República Francesa (FRA), República Helénica (GRC), República Italiana (ITA), República Popular da China (CHN), República Portuguesa (PRT), República da Albânia (ALB), República da Bielorrússia (BLR), República da Bulgária (BGR), República da China (TWN), República da Croácia (HRV), República da Eslovénia (SVN), República da Estónia (EST), República da Finlândia (FIN), República da Hungria (HUN), República da Islândia (ISL), República da Letónia (LVA), República da Moldávia (MDA), República da Polónia (POL), República da Sérvia (SRB), República da África do Sul (ZAF), República da Áustria (AUT), República das Maldivas (MDV), República das Seychelles (SYC), República de Chipre (CYP), República de Malta (MLT), República de Singapura (SGP), República de São Marino (SMR), República do Azerbaijão (AZE), República do Cazaquistão (KAZ), República do Equador (ECU), República do Paraguai (PRY), República do Quirguistão (KGZ), República do Tajiquistão (TJK), República do Uzbequistão (UZB), Roménia (ROU)
Informação importante:

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

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.

O registo da Noruega não permite pesquisar empresas apagadas por nomes. Por conseguinte, não podemos fornecer um SimpleSearch por nomes dentro de empresas eliminadas na Noruega.

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

Abaixo pode encontrar o exemplo:

Função SimpleSearch

Opção 2: Pesquisa por código de registo

Função SimpleSearch

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

Função UnifiedSearch

Como encomendar um relatório de crédito?

List of available countries for online credit reports: Federação Russa (RUS), Mongólia (MNG), Reino da Bélgica (BEL), Reino da Suécia (SWE), Reino dos Países Baixos (NLD), República Popular da China (CHN), República da Estónia (EST), República da Finlândia (FIN), República da Polónia (POL), República do Cazaquistão (KAZ), República do Quirguistão (KGZ)
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:

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

Função SimpleSearch

To order an Online/Offline with identification report you need to receive "<search_result_id>".
To do so, please follow the link: Como procurar uma empresa?

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))

Função 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))

Função 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))

Função 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))

Função 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.

Os seguintes estados são utilizados para relatórios:

  • Em curso - Relatório na fase de produção
  • Canceled - Ordem cancelada
  • Finished - O relatório está pronto
  • Updated - A informação foi acrescentada ao relatório final
  • Rejected - Order is rejected (Insufficient funds, incorrect order details or other reason).
  • Technical Error - Ocorreu um erro técnico no nosso sistema. Isto significa que somos informados sobre este erro e que o iremos corrigir o mais rapidamente possível. Será informado quando puder receber a encomenda.

Se o estado de execução for Finished ou Updated, então poderá obter uma encomenda.

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

Função GetReport
Lista das línguas disponíveis: bg (búlgaro), cs (Checo), da (Dinamarquesa), de (alemão), el (grego), en (Inglês), es (Espanhol), et (Estónio), fi (finlandês), fr (francês), hu (húngaro), id (indonésio), it (italiano), ja (Japonês), ko (coreano), lt (lituano), lv (letão), nb (Norueguês Bokmål), nl (holandês), pl (Polaco), pt (Português), ro (romeno), ru (Russo), sk (Eslovaco), sl (esloveno), sr (Српски), sv (Sueco), tr (Turco), uk (ucraniano), zh (Chinês)

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

Função 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))

Função 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))

Função 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))

Função ChkStatus
For offline orders checking order status once every 30 minutes is acceptable frequency.

Os seguintes estados são utilizados para relatórios:

  • Em curso - Relatório na fase de produção
  • Canceled - Ordem cancelada
  • Finished - O relatório está pronto
  • Updated - A informação foi acrescentada ao relatório final
  • Rejected - Order is rejected (Insufficient funds, incorrect order details or other reason).
  • Technical Error - Ocorreu um erro técnico no nosso sistema. Isto significa que somos informados sobre este erro e que o iremos corrigir o mais rapidamente possível. Será informado quando puder receber a encomenda.

Se o estado de execução for Finished ou Updated, então poderá obter uma encomenda.

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

Função GetReport
Lista das línguas disponíveis: bg (búlgaro), cs (Checo), da (Dinamarquesa), de (alemão), el (grego), en (Inglês), es (Espanhol), et (Estónio), fi (finlandês), fr (francês), hu (húngaro), id (indonésio), it (italiano), ja (Japonês), ko (coreano), lt (lituano), lv (letão), nb (Norueguês Bokmål), nl (holandês), pl (Polaco), pt (Português), ro (romeno), ru (Russo), sk (Eslovaco), sl (esloveno), sr (Српски), sv (Sueco), tr (Turco), uk (ucraniano), zh (Chinês)

Como encomendar demonstrações financeiras em linha?

STEP 1: Find a company

Função SimpleSearch

To order an online financial statements, you need to receive "<search_result_id>".
To do so, please follow the link: Como procurar uma empresa?

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: Pesquisa de demonstrações financeiras disponíveis

Função ChkFinance

Esta função só é necessária quando se encomenda um produto: finances (Financial statements) com delivery_term = 'o'.

Lista de países disponíveis: República da Estónia (EST), Reino da Suécia (SWE)

STEP 3: Encomendar demonstrações financeiras

Função 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)

Função 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

Função 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

Função ChkStatus
  • - For online orders checking order status once every 5 seconds is acceptable frequency.

Os seguintes estados são utilizados para relatórios:

  • Em curso - Relatório na fase de produção
  • Canceled - Ordem cancelada
  • Finished - O relatório está pronto
  • Updated - A informação foi acrescentada ao relatório final
  • Rejected - Order is rejected (Insufficient funds, incorrect order details or other reason).
  • Technical Error - Ocorreu um erro técnico no nosso sistema. Isto significa que somos informados sobre este erro e que o iremos corrigir o mais rapidamente possível. Será informado quando puder receber a encomenda.

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

Função GetReport
Lista das línguas disponíveis: bg (búlgaro), cs (Checo), da (Dinamarquesa), de (alemão), el (grego), en (Inglês), es (Espanhol), et (Estónio), fi (finlandês), fr (francês), hu (húngaro), id (indonésio), it (italiano), ja (Japonês), ko (coreano), lt (lituano), lv (letão), nb (Norueguês Bokmål), nl (holandês), pl (Polaco), pt (Português), ro (romeno), ru (Russo), sk (Eslovaco), sl (esloveno), sr (Српски), sv (Sueco), tr (Turco), uk (ucraniano), zh (Chinês)
To see the examples of xml request/response, please follow the link: How to get finished order?

Como descarregar relatórios padrão (em formatos diferentes de 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.

O pedido é composto por 3 partes:

  1. Parte fixa https://www.infoproff.com/en/orders/files/
  2. O seu haxixe único, que nós fornecemos em resposta
  3. 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 (sem troca), 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

Como descarregar produtos não normalizados?

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.

O pedido é composto por 3 partes:

  1. Fixed part https://www.infoproff.com/en/orders/files/
  2. O seu haxixe único, que nós fornecemos em resposta
  3. E parte fixa no final /download

Como obter a opinião de crédito?

Função CreditOpinionCalculator

Como obter informações adicionais?

Função GetClassifiersFinancialStatements
Função GetActivityClassificators
Função GetDictionaryStandardPhrases
Função GetAvailableProducts

delivery_term:

  1. "o" = "Online"
  2. "n" = "Normal"
  3. "f" = "Flash"
  4. "s" = "SuperFlash"

Possíveis erros

Estes erros podem ocorrer ao fazer o pedido ao nosso serviço web.

Todas as funções
  • Incorrect username/password or you have no permissions.
    Está a introduzir credenciais erradas ou o seu acesso API está bloqueado.
Função SimpleSearch
  1. You don't have permissions to search in this country.
    Lista de países disponíveis: Bósnia e Herzegovina (BIH), Commonwealth da Austrália (AUS), Confederação Suíça (CHE), Emirados Árabes Unidos (ARE), Estado de Israel (ISR), Estado independente de Samoa (WSM), Federação Russa (RUS), Geórgia (GEO), Gronelândia (GRL), Grão-Ducado do Luxemburgo (LUX), Hong Kong (HKG), Ilha de Man (IMN), Irlanda (IRL), Japão (JPN), Kosovo (XXK), Mongólia (MNG), Nova Zelândia (NZL), O Bailiado de Jersey (JEY), Principado do Listenstaine (LIE), Principado do Mónaco (MCO), Reino Unido da Grã-Bretanha e da Irlanda do Norte (GBR), Reino da Bélgica (BEL), Reino da Dinamarca (DNK), Reino da Noruega (NOR), Reino da Suécia (SWE), Reino de Espanha (ESP), Reino de Marrocos (MAR), Reino dos Países Baixos (NLD), República Argentina (ARG), República Checa (CZE), República Democrática Popular da Argélia (DZA), República Eslovaca (SVK), República Federal da Alemanha (DEU), República Federativa do Brasil (BRA), República Francesa (FRA), República Helénica (GRC), República Italiana (ITA), República Popular da China (CHN), República Portuguesa (PRT), República da Albânia (ALB), República da Bielorrússia (BLR), República da Bulgária (BGR), República da China (TWN), República da Croácia (HRV), República da Eslovénia (SVN), República da Estónia (EST), República da Finlândia (FIN), República da Hungria (HUN), República da Islândia (ISL), República da Letónia (LVA), República da Moldávia (MDA), República da Polónia (POL), República da Sérvia (SRB), República da África do Sul (ZAF), República da Áustria (AUT), República das Maldivas (MDV), República das Seychelles (SYC), República de Chipre (CYP), República de Malta (MLT), República de Singapura (SGP), República de São Marino (SMR), República do Azerbaijão (AZE), República do Cazaquistão (KAZ), República do Equador (ECU), República do Paraguai (PRY), República do Quirguistão (KGZ), República do Tajiquistão (TJK), República do Uzbequistão (UZB), Roménia (ROU)
Função Order
  1. This product is not available.
    Tal produto não pode ser encontrado e não é possível encomendar.
  2. You can't order report on company with legal form: "legal_form"
    Este erro só se aplica a: Reino da Suécia (SWE)
    Na Suécia não é possível encomendar o relatório online (delivery_term = "o") com as próximas formas legais:
    • enskild näringsidkare
    • kommanditbolag
    • handelsbolag
  3. 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
  4. Business Name or Reg Code is required
    Ao encomendar relatório offline (delivery_term = "n", "f" ou "s") é necessário "Nome da empresa" ou "Reg Code".
  5. Reg Code is required when delivery term is Online
    Ao encomendar o relatório online (delivery_term = "o") "Reg Code" é necessário.
Função GetReport
  1. This language is not supported.
    Lista de línguas disponíveis para relatórios online: bg (búlgaro), cs (Checo), da (Dinamarquesa), de (alemão), el (grego), en (Inglês), es (Espanhol), et (Estónio), fi (finlandês), fr (francês), hu (húngaro), id (indonésio), it (italiano), ja (Japonês), ko (coreano), lt (lituano), lv (letão), nb (Norueguês Bokmål), nl (holandês), pl (Polaco), pt (Português), ro (romeno), ru (Russo), sk (Eslovaco), sl (esloveno), sr (Српски), sv (Sueco), tr (Turco), uk (ucraniano), zh (Chinês)
Funções GetReport ChkStatus
  1. Incorrect order_id.
    Não é possível encontrar a identificação da encomenda. Obtém-se o ID de encomenda quando se utiliza a função Order.
Função OrderCancellation
  1. Your order is already canceled.
    Já não tem autorização para cancelar a encomenda.
Função OrderConfirmation
  1. You don't have permission to confirm the order anymore. Confirmation can be done within one hour after you recieved 'order_id'.

Alterações do SOAP (Versão 3) em relação ao SOAP (Versão 2)

Alterações do SOAP (Versão 3) em relação ao SOAP (Versão 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: Bósnia e Herzegovina (BIH), Commonwealth da Austrália (AUS), Confederação Suíça (CHE), Emirados Árabes Unidos (ARE), Estado de Israel (ISR), Estado independente de Samoa (WSM), Federação Russa (RUS), Geórgia (GEO), Gronelândia (GRL), Grão-Ducado do Luxemburgo (LUX), Hong Kong (HKG), Ilha de Man (IMN), Irlanda (IRL), Japão (JPN), Kosovo (XXK), Mongólia (MNG), Nova Zelândia (NZL), O Bailiado de Jersey (JEY), Principado do Listenstaine (LIE), Principado do Mónaco (MCO), Reino Unido da Grã-Bretanha e da Irlanda do Norte (GBR), Reino da Bélgica (BEL), Reino da Dinamarca (DNK), Reino da Noruega (NOR), Reino da Suécia (SWE), Reino de Espanha (ESP), Reino de Marrocos (MAR), Reino dos Países Baixos (NLD), República Argentina (ARG), República Checa (CZE), República Democrática Popular da Argélia (DZA), República Eslovaca (SVK), República Federal da Alemanha (DEU), República Federativa do Brasil (BRA), República Francesa (FRA), República Helénica (GRC), República Italiana (ITA), República Popular da China (CHN), República Portuguesa (PRT), República da Albânia (ALB), República da Bielorrússia (BLR), República da Bulgária (BGR), República da China (TWN), República da Croácia (HRV), República da Eslovénia (SVN), República da Estónia (EST), República da Finlândia (FIN), República da Hungria (HUN), República da Islândia (ISL), República da Letónia (LVA), República da Moldávia (MDA), República da Polónia (POL), República da Sérvia (SRB), República da África do Sul (ZAF), República da Áustria (AUT), República das Maldivas (MDV), República das Seychelles (SYC), República de Chipre (CYP), República de Malta (MLT), República de Singapura (SGP), República de São Marino (SMR), República do Azerbaijão (AZE), República do Cazaquistão (KAZ), República do Equador (ECU), República do Paraguai (PRY), República do Quirguistão (KGZ), República do Tajiquistão (TJK), República do Uzbequistão (UZB), Roménia (ROU)

- 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: Federação Russa (RUS), Mongólia (MNG), Reino da Bélgica (BEL), Reino da Suécia (SWE), Reino dos Países Baixos (NLD), República Popular da China (CHN), República da Estónia (EST), República da Finlândia (FIN), República da Polónia (POL), República do Cazaquistão (KAZ), República do Quirguistão (KGZ)

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

3) Function: GetReport

- Changes in of available languages: bg (búlgaro), cs (Checo), da (Dinamarquesa), de (alemão), el (grego), en (Inglês), es (Espanhol), et (Estónio), fi (finlandês), fr (francês), hu (húngaro), id (indonésio), it (italiano), ja (Japonês), ko (coreano), lt (lituano), lv (letão), nb (Norueguês Bokmål), nl (holandês), pl (Polaco), pt (Português), ro (romeno), ru (Russo), sk (Eslovaco), sl (esloveno), sr (Српски), sv (Sueco), tr (Turco), uk (ucraniano), zh (Chinês)


Alterações do SOAP (Versão 3) em relação ao SOAP (Versão 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

Novos elementos:

  • - search_result_id (is required for order with delivery_term = 'o')
  • - name_transliteration
  • - reg_code
  • - vat_code
  • - unified_legal_form

Webhooks Settings

Visão geral

Um webhook é uma forma de uma aplicação fornecer a outras aplicações informações em tempo real. A nossa funcionalidade de webhook implementa chamadas de retorno HTTP configuradas com um URL. Um payload HTTP POST é enviado para este URL em formato JSON sempre que ocorre um evento especificado. No contexto do nosso projeto, concebemos a função webhook para desencadear eventos específicos.

Configurar um Webhook

Para configurar um webhook para a sua aplicação, navegue até à página de definições da aplicação e procure a secção "Definições de webhooks". E forneça as seguintes informações:

  1. O "URL do webhook" é o URL onde o seu servidor receberá os pedidos POST do webhook.
  2. "Máximo de tentativas de entrega" é a definição que define o número máximo de tentativas de repetição que devem ser efectuadas para entregar um evento webhook quando a tentativa de entrega inicial falha.
  3. O "Tempo limite de nova tentativa de entrega" é uma definição que permite especificar o intervalo de tempo entre novas tentativas quando uma tentativa de entrega de um webhook falha.

Depois de fornecer estes dados, clique em "Guardar".

Tipos de eventos Webhook

  1. Novo estatuto da encomenda

Carga do Webhook

Quando ocorre um evento, enviamos um pedido HTTP POST para o URL de carga com um corpo JSON que contém informações sobre o evento.

Aqui está um exemplo de carga útil:
Exemplo de carga útil do novo estatuto da encomenda
Valores possíveis do campo "new_status":
  • "Finished" - uma encomenda está concluída. Uma encomenda pode ser levantada;
  • "Updated" - uma ordem actualizada, dados adicionados a uma ordem concluída;
  • "Canceled" - uma encomenda é cancelada a pedido (ou com o consentimento) de um cliente;
  • "Rejected" - uma encomenda é rejeitada. Geralmente porque é impossível identificar uma empresa.

Proteger os Webhooks

É importante verificar se os pedidos POST enviados para o URL de carga útil são da nossa aplicação. Para ajudar com isso, cada pedido de webhook inclui um cabeçalho X-Signature.

Descrição da assinatura

Para a assinatura, utilizamos o HMAC com o algoritmo SHA512.

O segredo é uma concatenação da ID da aplicação e da chave secreta das definições dos webhooks.

É possível adicionar os seus próprios parâmetros get ao ponto final para identificar o remetente, se necessário.

Resolução de problemas

Um servidor tem de responder no prazo de 10 segundos e devolver um código HTTP 2XX; caso contrário, a entrega do webhook é considerada falhada. Em caso de falha, a funcionalidade tentará reenviar o pedido de acordo com a política de entrega.