Data Integration accessing Demander webservices
Purpose Describe the necessary implementations for direct integration (without using the Demander Synchronizer) between the ERP and Demander.
Control fields in ERP To implement direct integration between ERP and Demander, it is necessary to create two control fields, one to register the company token in Demander (varchar field with size 200) and another to register the last date/time of data search in Demander (datetime field)
Field separator The default Demander integration layout is a text file in which the field separator is |
It is important to consider when generating data, in the text fields, that there is the possibility that the user has used a | when registering any information in the ERP, this | it must be removed when exporting data to avoid causing integration problems.
Data encode Demander works with the UTF8 encode.
In the routine of generating data to be sent to Demander, it is necessary to observe the generation of files in UTF8, eventually some programming languages or even operating systems work by default with other encodes, therefore, we suggest forcing the generation of data to be in UTF8 to ensure that the integration is not affected.
In practice, not using the UTF8 encode in the data to be sent to Demander will only cause the data imported by Demander to be imported with special characters and not with the appropriate letters, for example: ç, ã, é, … which will not be shown and special characters will be shown instead.
In the routine of importing data into the ERP, in the same way as when exporting data, it is suggested that opening the file to read the information is forced to use the UTF8 encode, ensuring that the data is imported appropriately into the ERP.
Creating companies on Demander If it is necessary to create a company on Demander web for a token to be generated for it, this generation can be done in two ways, manually or via integration.
Manual registration This documentation is still being detailed and the link to it will be added in the future, while it does not happen, follow the instructions below.
On Demander web to register a company, use the link below, if necessary to fill in the data (only the partner has access to this screen, if you are the ERP of a company that is integrating, request the token for the company or for Demander: sistema.demander.com.br/dinamico/empresas
After the company has registered, it will be necessary to generate the token (integration tab) using the link below, this operation takes place on two screens as only the partner or Demander has access to the first and the company also has access to the second, as this is the Demander configuration screen: sistema.demander.com.br/dinamico/configuracoes-da-empresa
Integration via webservice For integration via webservice, see documentation below: https://atendimento.demander.com.br/kb/article/140100/api-do-parceiro
Sending data from ERP to Demander Data sending request The link below describes how to request SEND information on Demander: https://atendimento.demander.com.br/kb/article/185185/api-demander-enviar-dados-para-o-demander?ticketId=&q=
Layouts to be integrated The layouts to be integrated depend on the functionalities that the company will use, below the link to all the possible integration tables of Demander, note that there are tables that Demander only imports, others that Demander only exports and others that are imported and exported by Demander. https://atendimento.demander.com.br/kb/pt-br/article/131110/layout-de-integracao
Generation of files using tables Each file to be generated and sent to Demander must contain the version on which the generation was based in the first line. When starting the integration, ask the implementation team which code this should be.
When generating the file with the data, we suggest that files be generated separately, as if the company’s data volume is very large, a time-out may occur when sending data, so with smaller files, this possibility becomes much smaller.Some tables must be in the same data file, below is a list of tables, those not mentioned may be in different files. 16-Order + 17-Order Items + 26-Order Items Grid 41-Tax client type + 42-Taxation 31-Commission Levels + 32-Commission 51-Sales team + 52-Sales team salespeople + 53-Sales team managers 60-Perspective goals + 61-Target levels + 62-Target values 09-Price table + 13-prices + 15-products 20-Route + 21-Route customers 19-Financial securities 57-Stock ready for delivery 180-Flex range per price list
Export Logs In the link below we can see the list of files that the ERP sent to Demander in the last 3 months, which is the time we keep logs: sistema.demander.com.br/dinamico/arquivos-recedos-do-erp
Demander data search for ERP Data search request The link below describes how to make a SEARCH request for information on Demander: https://atendimento.demander.com.br/kb/article/185186/api-demander-receber-dados-do-demander?ticketId=&q=
Control date of last search In the downloaded file, the first line contains important information, below is an example of the first line that all files that will be made available by Demander will have: DADOS_SYNCHRONIZATION|71408323|03/30/2021 13:07:42|03/30/2021 13:09:21|
where: DADOS_SYNCRONIZATION -> first field, is fixed text 71408323 -> second field, is the Id of the integration log in Demander, the text file made available has the same name 03/30/2021 13:07:42 -> The third field is the date/time that was sent (and which is saved in the ERP as described in ‘Control fields in the ERP’) in the information search request in Demander. 03/30/2021 13:09:21 -> fourth field, is the date/time that the search request arrived at Demander, so the file in question has data that was included or changed between the date/time of field 3 and field 4. This content must be saved in the created field (as described in ‘Control fields in ERP’), as this date/time must be sent in the next data search request in Demander.
Import logs In the link below we can see the list of files that the ERP fetched from Demander in the last 3 months, which is how long we keep the log: sistema.demander.com.br/dinamico/arquivos-recedos-do-erp
Logs returned in search and send requests The return of send and fetch requests is text. Depending on the error, in the case of sending data, sending the file is necessary.
Possible returns: Return starting with ‘ERROR 01: No company found with the Token’ -> There is no company on Demander with this token
Return starting with ‘ERROR 02:’ -> Inactive company on Demander (needs to resend the file)
Return starting with ‘ERROR 03:’ -> Parameter File is not in the request (need to resend the file)
Return starting with ‘ERROR 04:’ -> Problem uploading the file (need to resend the file)
Return starting with ‘ERROR 05:’ -> Defaulting company on Demander (needs to resend the file)
Return starting with ‘ERROR 08:’ -> Company out of Demander testing time (needs to resend the file)
Return starting with ‘ERROR: The first line of the file must be the Integration Layout version.’ -> Each file to be sent to Demander must contain the version on which the data generation was based (you need to resend the file)
Return starting with ‘ERROR on line’ -> There is an error in some record in the file, for example: a customer came without a business name. This error needs to be dealt with on a case-by-case basis, the ideal is to log in and instruct someone to look at this log, or just instruct them to look at the logs from time to time via Demander web.
Return starting with ‘The company is not configured to import orders, if necessary, contact Demander support.’ -> as the return of orders to Demander (coming from the ERP) requires approval, this option is only released when Retta is asked to do so, even to monitor this integration. (activate configuration and resend the file)Return starting with ‘ERROR=The company is not configured to calculate IPI and/or ICMS ST. The configuration was not imported.’ -> When sending taxation data (table 41 and 42), we will only import them if the company is configured to calculate taxes. (activate configuration and resend the file)
Return starting with ‘Demander skipped importing this file.’ -> When we import data from a file, we generate a hash of the file’s content, and if this file has already been imported in the last 6 hours, it is ignored. The objective of this is to improve the solution’s response time, not processing data that has already been processed previously. If the company sends only data changes, contact Demander Deployment for guidance.
Return starting with ’ Upload time s3: ’ -> indicates that the file was sent successfully Return starting with ’Time: ’ -> indicates the time it took to process the file Return starting with ‘File processed.’ -> means the file has been processed Return starting with ‘SUCCESS=’ -> It means the process was completed successfully
In practice, the concern should be with logs in which the file as a whole was not processed (except ignoring files), and in this case, the file should be resent at a second time.
Ideally, the file should be in a folder and when starting the process, if a file is in the folder, it must first be sent and then only a new data file will be sent.
We also suggest that if an error occurs, that someone is notified by email of the error, so that there is a proactive assessment.