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.
• 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 (acima de 40) será feito bloqueio e caso a situação ser frequente ou não ajustada será avaliado desativação da integração;
• Todos os clientes do ERP irão utilizar o mesmo acess token gerado no dia e não deve gerar um acess token para cada cliente
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.
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:
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
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:
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.
