Integracao Touch Comp ERP Terceiros (API/Endpoints)

Fonte: Touch ERP
Saltar para a navegação Saltar para a pesquisa

Página_principal

A Touch Comp possibilita diversas integrações com terceiros através de Web Services com o conceito de API.

Os aplicativos de terceiros integram-se através de webservices do tipo Rest (https://www.devmedia.com.br/introducao-a-web-services-restful/37387). A autenticação em si, dependerá do webservice em questão, bem como as limitações do Software Terceiro. Normalmente, a autenticação se dá por usuário, senha e empresa, onde é disponibilizado um token (bearer token) ao integrador para se integrar aos demais serviços.

Nos casos em que o Touch Comp ERP está instalado no servidor do cliente, é necessário um mapeamento NAT para comunicação externa. Veja o link Case_Wildfly e Manual_Instalacao_ERP#Acesso_Externo_-_WEB para detalhes de configuração para acesso externo.

Documentação Swagger

Para cada webservice e integração, poderá haver variações estruturais. Logo consulte a documentação disponibilizada sobre a integração em questão, para detalhes, limitações e informações conforme o serviço que deseja integrar.

A Touch Comp fornece API's para todos os seus serviços, desde que a empresa em que você prestará serviços, libere pra você. Disponibilizamos de forma online e integrada com a nossa API a documentação de todas as API's e endpoints disponíveis, acesse a API de nosso cliente: 

http://{endereco_servidor}:{porta_comunicacao}/touch-erp/swagger-ui/index.html

Premissas

Alguns entendimentos devem estar claros antes de você continuar:

  • Você somente poderá acessar as API's se autenticado
  • Você deve possuir Usuario/Login, Senha e Token de autenticação a ser disponibilizado pelo nosso cliente. É o nosso cliente que configura estes dados, criando um usuário para você em 54_Usuarios
  • Você somente poderá acessar recursos/API/Endpoints se possuir permissões para tal. Estas permissões são realizadas no recurso 53_Grupo_Usuarios. Ou seja, se irá integrar com API's do recurso de 1180_Pedido_Clientes, no grupo de usuários do usuário de integração deve estar liberado este recurso.
  • Após autenticado, será disponibilizado um Token(Bearer Token) que você utilizará em todas as requisições realizadas.
  • Este token possuirá uma validade, configurada por nosso cliente. Você deve combinar com o cliente, a validade desta autenticação e bem como se preparar para autenticar novamente no futuro quando o token expirar.
  • Todos os Endpoints são do tipo REST
  • Todas as solicitações por put, post e afins são encapsuladas no arquivo json, bem como as respostas. Principalmente sobre as respostas, você deve sempre verificar o código de resposta, a fim de verificar por erros(Veja a seção Encapsulamento).
  • A maioria das mensagens trocadas, é utilizado o tipo de arquivo json.

Encapsulamento

As mensagens enviadas e retornadas são enviadas encapsuladas dentro do arquivo json. Este encasulamento se deve, para que informações e status adicionais sejam enviados junto a estas mensagens.

Observe a seção Autenticação e o retorno da requisição: 

{
  "@type": "WebDTOResult",
  "status": "SUCESSO",
  "messages": [],
  "result": {
   },
   "countOf": 1,
   "name": null,
   "message": null,
   "detailMessage": null
 }

O resultado da consulta está em "result". Todos os demais dados são adicionais:

  • "status": SUCESSO ou ERRO
  • "messages": mensagens adicionais, em formato de lista, a serem exibidos ao usuário, se necessário.
  • "countOf": número de registros retornados
  • "message": mensagem de erro resumida
  • "detailMessage": mensagem de erro detalhada.

Autenticação

Nosso cliente em comum, deve criar um usuário para você em 54_Usuarios, onde deve ser definido seu grupo de usuários, com quais recursos, ou seja, API's que você poderá acessar. Após criado e em posse destes dados, prossiga.

Atenção: O token possui um tempo de expiração, onde você deve-se autenticar novamente após o tempo estabelecido. O cliente em questão pode configurar os tempos de timeout no cadastro do 54_Usuarios. Verifique com o cliente qual o melhor tempo de timeout de acordo com suas necessidades.

Para se autenticar, você precisa enviar as seguintes informações: 

* username: nome do usuario/login;
* password: senha;
* userAccessToken: token de acesso;
* company: identificador da empresa;

Estas informações serão enviadas para o seguinte endpoint: 

http://{ip_servidor}:{porta}/touch-erp/noauth/authenticate

Exemplo: 

{
   	"company": 1,
   	"username": "admin",
   	"password": "123",
       "userAccessToken":"8H@rm0@FXiD@m2hRs5Xj"
 }

Todos estes dados serão disponibilizados por nosso cliente. Após autenticado, será retornado os seguintes dados: 

{
   "@type": "WebDTOResult",
   "status": "SUCESSO",
   "messages": [],
   "result": {
       "token": "XXXXX",
       "dataEmissaoToken": "28-03-2022 16:44:12.296",
       "dataValidadeToken": "29-03-2022 02:44:12.296",
       "usuario": {
           "identificador": 9,
           "loginLogin": "adm",
           "empresas": [
               {
                   "identificador": 43,
                   "nomeEmpresa": null
               },
               {
                   "identificador": 44,
                   "nomeEmpresa": null
               }
           ],
           "pessoaIdentificador": 55,
           "pessoaNome": "USUARIO",
           "codigoRegistro": "17254557000151/32/1222;",
           "tokenAcessoLogin": "xxxx",
           "grupo": {  },
           "idEmpresaLogada": 1,
           "nomeEmpresaLogada": "TOUCHCOMP SISTEMAS"
       }
   },
   "countOf": 1,
   "name": null,
   "message": null,
   "detailMessage": null
}

Tipos de Recursos/API

No Touch Comp ERP existem basicamente dois tipos de recursos disponibilizados na API:

  • Recursos cadastros/CRUD. Nestes recursos são tratados entidades que são persistidas no banco de dados.
  • Recursos de processamento. Nestes recursos são tratados processamentos, geração de relatórios, de arquivos fiscais, dentre outros.

Para melhor detalhamento, consulte este documento: Integracao_Touch_Comp_ERP_Terceiros_(API/Endpoints)/Tipos_Recursos_API

Tratamento de Erros

Você deve tratar dois tipos de erros/status/retorno da chamada a API.

Erros de regras de negócio, e esperados são retornados no json da mensagem, com o status "ERRO".

Porém, existem outros erros inesperados, seja pela aplicação ou até por problemas de conexão, internet e problemas no servidor. Estes erros são retornados nativamente pelo protocolo HTTP, o response code. Um dos mais famosos talvez seja o 404 - Not Found, que significa que o recurso solicitado não existe no servidor. Disponibilizamos uma tabela com todos estes códigos, disponível em: Case_Codigos_Erros_Web.

Trate estes erros e exiba ao usuário quando os mesmos ocorrerem.

Acesso Negado - Forbidden

O usuário deve estar autenticado, com um token valido, não expirado para poder acessar a API. Ele também deve possuir acesso ao recurso, vinculado a URL. Caso contrário, terá o acesso negado.

Testes

Para facilitar os testes e exemplificar a conexão, utilize o programa Postman(https://www.postman.com/), ou outro similar de sua preferência. Nele você pode simular chamadas, realizar testes sem a necessidade de desenvolvimento em si.

Sugerimos fortemente o uso prévio do Postman, para depois iniciar o desenvolvimento.

No Postman, siga este caminho:

  • Autentique-se, para solicitar um Bearer Token
  • Com o token, chame a API em questão, passando os parâmetros desejados.
Autenticacao postman.png
Autenticacao postman 2.png
Autenticacao postman 3.png

API's Específicas

Obtida de "https://touchcomp.mywikis.wiki/w139/index.php?title=Integracao_Touch_Comp_ERP_Terceiros_(API/Endpoints)&oldid=6411"