A API irá automatizar o envio de XML ao escritório de Contabilidade, não tendo mais a necessidade do lojista/cliente do ERP estar tendo que enviar os Documentos Fiscais para a Contabilidade.
Como faço para iniciar a Integração?
A Domínio Sistemas - Thomson Reuters irá demonstrar como é a programação na API?
Sim, iremos demonstrar o funcionamento da API através do aplicativo “Postman”. Este aplicativo é gratuito e pode ser baixado pelo próprio site do Postman.
Fluxo da Integração API
-
Criação do Token;
-
Confirmar se a Key disponibilizada é do seu cliente com os seus dados, Nome da Contabilidade, CNPJ do cliente e nome do Cliente;
-
Com a Key do cliente será gerada uma nova Key, Integration Key. Está nova chave será utilizada para envio de nota junto ao Token;
-
Envio do XML para API;
-
Consulta do Envio para avaliar se o XML foi armazenado corretamente na API.
As chaves como Key do cliente, Integration Key e Token de envio do XML são fixos e não possui vencimento, uso exclusivo para o referido cliente.
Cada cliente terá a sua Key e o Integration Key já o Token será fixo do sistema ERP com necessidade de renovação a cada 24 horas.
Como faço para criar o Token?
2 - Na guia Params não é necessário nenhuma alteração;
3 - Clique na guia “Authorization”, no campo Type informe “Basic Auth”, no campo ao lado em Username você deverá informar o “Client ID” já no campo Password informe o “Client Secret”. Esses IDs serão fornecidos pela Domínio Sistemas e são exclusivos do sistema ERP;
4 - Clique na guia “Headers” e Insira a seguinte Key: “Content-Type” no campo value informe “application/x-www-form-urlencoded”;
5 - Adicione também abaixo a key “Cookie” com o value“did=s%3Av0%3A145b8a90-ea57-11eb-ae8a-877f15a4a518.QhUcTCGsMP28yWAB%2BYsUUZ5Gw4Srxf%2F0IDRkKPUQQHs; did_compat=s%3Av0%3A145b8a90-ea57-11eb-ae8a-877f15a4a518.QhUcTCGsMP28yWAB%2BYsUUZ5Gw4Srxf%2F0IDRkKPUQQHs”;
6 - Clique na guia “Body”, marque a opção “X-WWW-FORM-URLENCODED”, após adicione as seguintes KEYs:
-
grant_type - client_credentials;
-
client_id – Este ID será uso exclusivo fornecido pela Domínio;
-
client_secret – Este ID será uso exclusivo fornecido pela Domínio;
-
audience - 409f91f6-dc17-44c8-a5d8-e0a1bafd8b67;
7 - Após o preenchimento da guia Body, o restante das guias não é necessário nenhuma alteração;
8 - Clique em “Send” para efetuar a criação do Token.
OBS: O Access Token, é o Token utilizado para efetuar o envio do XML para a API, possui validade 24 horas, após 24 horas necessários realizar o mesmo processo para gerar um novo token "renovação do mesmo". Somente relembrando que o token será Fixo do ERP.
IMPORTANTE! A requisição do TOKEN deve ser realizada somente 1x ao dia.
Em casos que o ERP estiver realizando o consumo excessivo de requisições será feito contato com o mesmo para ajuste da situação e caso situação ser frequente ou não ajustada será avaliado desativação das chaves.
Confirmar a Key do Cliente
O contador do cliente do sistema irá fornecer a Key dos seus clientes que emitem a nota no ERP integrado, onde é necessário antes de gerar a Integration Key, confirmar se essa Key é realmente do cliente que está fazendo a integração. Para confirmar a empresa segue abaixo as requisições:
2 - Nas guias Params e Authorization não é necessário preenchimento;
3 - Na guia Headers adicione as seguintes Keys:
-
Authorization - Bearer após a palavra Bearer deverá ser informado o access Token que foi gerado no tópico anterior conforme imagem abaixo;
-
x-integration-key – Inserir a chave que o contador do cliente fornecer;
4 - Após clicando em Send teremos o resultado Nome do Escritório de Contabilidade, Nome do Cliente do escritório e CNPJ do cliente do escritório.
Gerar a Key de Integração “integrationKey”:
2 - As guias Params e Authorization não é necessário preenchimento;
3 - Na guia Headers adicionar as seguintes Keys:
-
Authorization - Bearer após a palavra Bearer deverá ser informado o Access Token que foi gerado no tópico anterior conforme imagem abaixo;
-
x-integration-key – Inserir a chave que o contador do cliente fornecer;
4 - Após clicando em Send teremos a “integrationKey”, onde será utilizada junto ao token para o envio do XML.
Envio do XML:
2 - As guias Params e Authorization não é necessário preenchimento;
3 - Na guia Headers adicionar as seguintes Keys:
Importante! Nessa requisição não deve ser informada a Key que veio do Contador.
-
x-integration-key – Informar a integrationKey que foi gerada na requisição anterior;
-
Authorization – Bearer junto Acess Token igual realizado em requisições anteriores;
4 - Clique na guia “Body”, marque a opção “FORM-DATA” e adicione as seguintes Keys:
-
file[] – Marque a opção File - application/xml;
-
query – Marque a opção Text - {"boxeFile": false} - application/json;
-
fileComplement[] Marque a opção File
OBS: Caso o contador tenha o BOX-e ativo no seu contrato o mesmo deverá utilizar como: {"boxeFile": true}. Somente utilizar FALSE caso o contador não tenha o BOX-e ativo. Independente da opção que for selecionada não altera na funcionalidade da API. O BOX-e é um serviço extra da Domínio Sistemas para salvar os arquivos XMLs na nuvem por um período de 5 anos.
5 - Caso o seu Postman não venha com a guia “CONTENT TYPE” você pode estar habilitando a mesma conforme imagem abaixo:
OBS: A opção fileComplement[] é opcional, pode ser utilizada para enviar o arquivo xml com leiaute especifico, com os códigos do produto conforme ERP para que assim fique lançado no Domínio com os mesmos códigos que utilizados no ERP.
6 - Após selecionar o arquivo XML no campo “Value”, clique na botão “Send”;
Podemos observar que ao enviar o
OBS: Referente ao XML, o servidor retorna com a seguinte mensagem "Aguardando processamento. Por favor aguarde o arquivo ser processado.;
7 - Com o envio realizado, podemos estar fazendo a consulta do ID de envio que foi gerado, para avaliarmos se o XML foi armazenado corretamente na API.
Realizar a consulta do Envio do XML:
2 - Após a / deverá ser inserido o ID de envio, exemplo:
3 - Na guia “Params” não é necessário nenhuma alteração;
4 - Na guia “Authorization”, no campo Type, selecione a opção “Bearer Token”, no campo ao lado informe o mesmo Token que foi utilizado para realizar o envio do XML;
OBS: Caso você deseje realizar novamente a consulta após 24 horas, deverá utilizar o novo token gerado. Para consultas sempre serão válidas o último token válido e ativo.
5 - Na guia “Headers” adicione as seguintes Keys:
-
x-integration-key – Informar a integrationKey “mesma key do envio do XML”;
-
Authorization – Bearer junto Acess Token igual realizado em requisições anteriores;
6 - Após o preenchimento podemos clicar em “Send”;
7 - Conforme imagem acima, sempre que obtivermos o retorno “Arquivo armazenado na API” significa que o arquivo foi enviado com êxito para API.
Como utilizar o ambiente de Homologação
- O ERP deve solicitar via e-mail ou whatsapp da API para que seja gerado uma chave de homologação para testes. Para isso deve encaminhar um CNPJ de exemplo que gostaria de enviar as notas e testar.
