Neste documento, são demonstradas as formas de utilização dos endpoints de configuração de integrações entre produtos TOTVS, padrão REST/JSON.
Endpoint /Integrations
Recuperar lista de integrações
GET /totvseai/configurator/v1/integrations?order={order}&page={page}&pageSize={pageSize}
Onde:
- Order contém a definição de como a lista deve ser ordenada. Apresenta o nome de uma, ou mais, propriedades (Ex: name, description...). Será ordenação decrescente se o símbolo de negativo
for encontrado à frente da propriedade (Ex: -name). Caso contrário, subentende-se crescente.
- Page deve ser um valor numérico (maior que zero) representando a página solicitada
- PageSize deve ser um valor numérico (maior que zero) representando o total de registros retornados na consulta
{ "hasNext": false, "items": [ { "_expandables": ["routes"], "integrationId": "5e107c70-8e89-4da2-a5b9-543215432145", "name": "TOTVS Gestão de Frotas x Backoffice RM", "description": "O objetivo da integração do SIGAMNT x BackOffice RM e viabilizar que de forma automática os cadastros gerenciados pelo BackOffice sejam replicados no vertical e, de forma similar, que os processos geridos pelo Gestão de Ativos/Gestão de Frotas tenham suas informações levadas ao BackOffice. Desta forma as bases de dados se mantém espelhadas, atualizando estoque, permitindo emissão de notas fiscais e demais processos no BackOffice. ", "routes": [] }, { "_expandables": ["routes"], "integrationId": "52644D93-0D83-49D5-8D38-3B1030CA74A1", "name": "TOTVS Obras e Projetos x BackOffice Protheus", "description": "A gestao da obras e projetos e feita exclusivamente no TOP (cadastro dos projetos e estruturas associadas, cronogramas, necessidades de material, medições de contrato, etc.), módulos estes que realizam liberações para Suprimento/Faturamento, estas liberações são geradas no Back Office Protheus. O controle de estoques, compras, faturamento, financeiro, contábil e fiscal serão feitos no Back Office Protheus (módulos integrados: SIGACOM, SIGAFAT e SIGAEST). Os cadastros básicos, bem como os cadastros de Cliente e Fornecedor, Centro de Custo, Condição de Pagamento, Unidade de Medida, Produtos, Moeda / Cotação serão realizados sempre no Protheus e sincronizados para o RM.", "routes": [] }, { "_expandables": ["routes"], "integrationId": "d1f9477e-29a8-4a3b-9358-026d4f4be888", "name": "TOTVS PIMS MultiCultivos x BackOffice Protheus", "description": "O PIMSConnector é um esforço para componentizar e modularizar o desenvolvimento de novas integrações entre as aplicações PIMS e ERPs, como Protheus e Datasul, por exemplo. O PIMSConnector surgir com o objetivo de criar um ambiente único, ou seja, padronizar as formas de interação entre o segmento Agroindustrial com outros segmentos. Com isto, conseguimos facilitar os meios de comunicação entre as aplicações de nossos clientes e tornar o processo de integração mais simples, ágil, conectado, cloud e essencial. Outro ponto de vista é que este projeto tem como objetivo viabilizar a independência na comunicação entre diferentes tecnologias de integração permitindo, por exemplo, que uma aplicação envie dados para a integração através de acesso direto à base de dados enquanto outra aplicação, que receberá os dados, poderá fazê-lo através de uma Web Service. ", "routes": [] } ] }
Recuperar uma integração
GET /totvseai/configurator/v1/integrations/{integrationId}
Onde:
integrationId representa o código identificador único da integração.
{ "integrationId": "b0d4bdb3-5d56-53e9-b96d-10a5da6dfaf7", "name": "TINPROT", "description": "TOTVS Incorporação x BackOffice Protheus", "routes": [{ "transactionsFlow": [{ "transactionId": "COSTCENTER", "version": "2.000", "direction": "both" }, { "transactionId": "CUSTOMERVENDOR", "version": "2.002", "direction": "both" }, { "transactionId": "UPDATECONTRACTSTATUSPARCEL", "version": "1.000", "direction": "receive" }], "applicationPair": { "sourceApplication": { "appId": "SOURCEAPP@PRODUCT", "name": "NAME", "description": "DESCRIPTION", "sourceApplication": "SOURCEAPP", "productCode": "PRODUCT", "wsdlUrl": "", "user": "user", "password": "password", "monitorUrl": "http://monitorUrl", "enableRest": 1, "restEndpointUrl": "http://http://restEndpointUrl", "paramEndpoints": { "general": { "metadata": "/params/1.0/metadata", "values": "/params/1.0/value" }, "transaction": { "metadata": "/transactionParams", "values": "/transactionValues" } } }, "destinationApplication": { "appId": "SOURCEAPP@PRODUCT", "name": "NAME", "description": "DESCRIPTION", "sourceApplication": "SOURCEAPP", "productCode": "PRODUCT", "wsdlUrl": "", "user": "user", "password": "password", "monitorUrl": "http://monitorUrl", "enableRest": 1, "restEndpointUrl": "http://http://restEndpointUrl", "paramEndpoints": { "general": { "metadata": "/params/1.0/metadata", "values": "/params/1.0/value" }, "transaction": { "metadata": "/transactionParams", "values": "/transactionValues" } } } } }] }
Criar uma integração
PUT /totvseai/configurator/v1/integrations/{integrationId}
Onde:
integrationId representa o código identificador único da integração.
{ "integrationId": "b0d4bdb3-5d56-53e9-b96d-10a5da6dfaf7", "name": "TINPROT", "description": "TOTVS Incorporação x BackOffice Protheus", "routes": [{ "transactionsFlow": [{ "transactionId": "COSTCENTER", "version": "2.000", "direction": "both" }, { "transactionId": "CUSTOMERVENDOR", "version": "2.002", "direction": "both" }, { "transactionId": "UPDATECONTRACTSTATUSPARCEL", "version": "1.000", "direction": "receive" }], "applicationPair": { "sourceApplication": { "appId": "SOURCEAPP@PRODUCT", "name": "NAME", "description": "DESCRIPTION", "sourceApplication": "SOURCEAPP", "productCode": "PRODUCT", "wsdlUrl": "", "user": "user", "password": "password", "monitorUrl": "http://monitorUrl", "enableRest": 1, "restEndpointUrl": "http://http://restEndpointUrl", "paramEndpoints": { "general": { "metadata": "/params/1.0/metadata", "values": "/params/1.0/value" }, "transaction": { "metadata": "/transactionParams", "values": "/transactionValues" } } }, "destinationApplication": { "appId": "SOURCEAPP@PRODUCT", "name": "NAME", "description": "DESCRIPTION", "sourceApplication": "SOURCEAPP", "productCode": "PRODUCT", "wsdlUrl": "", "user": "user", "password": "password", "monitorUrl": "http://monitorUrl", "enableRest": 1, "restEndpointUrl": "http://http://restEndpointUrl", "paramEndpoints": { "general": { "metadata": "/params/1.0/metadata", "values": "/params/1.0/value" }, "transaction": { "metadata": "/transactionParams", "values": "/transactionValues" } } } } }] }
Deletar uma integração
DELETE /totvseai/configurator/v1/integrations/{integrationId}
Onde:
integrationId representa o código identificador único da integração.
Visão de Produto
Todas as operações realizadas acima serão aplicadas apenas no produto apontado, podendo criar integrações "quebradas". Por exemplo: ao fazer um PUT de uma integração "Protheus/RM" no endpoint do Protheus, apenas o Protheus terá recebido a integração. O RM continua desconfigurado. Portanto, é recomendável que esses serviços não sejam acionados diretamente, e sim através da UI do configurador, que possui lógica adicional para garantir a integridade das configurações em todos os produtos envolvidos.
Erros
Segue abaixo uma lista com os possíveis códigos de erro e seus siginificados:
- 400 (Bad Request): Erro relacionado ao pedido feito pelo usuário. Pode ter sido causado por formato inválido do JSON enviado no body da requisição HTTP ou alguma validação da regra de negócio.
- 401 (Unauthorized): Login/senha inválidos
- 403 (Forbidden): Falta de permissão de acesso
- 404 (Not Found): O recurso solicitado não existe (Verificar o verbo rest e URL)
- 500 (Internal Server Error): Erro não previsto na execução de alguma tarefa no serviço, contatar o suporte.