Esta integração foi construída para efetuar o envio de dados entre TOTVS Agro Bioenergia (módulo de Pagadoria) para Salesforce com foco em "dados mestres" de Fazenda (Nível 1), Setor (Nível 2) e Talhão (Nível 3), quando inseridos ou atualizados via aplicação (Bioenergia/Pagadoria).
A partir destes eventos, dados mestres de Locais de Produção são compartilhados com a plataforma Salesforce, possibilitando a criação de novos contratos (no Salesforce). Desta forma, esta documentação técnica fornece detalhes arquiteturais e de tecnologia para tal integração (via TOTVS Agro Plataforma e TOTVS Agro Conecta Dados).
Salesforce Integration - Guia de Referência
TOTVS Agro Bioenergia (Pagadoria APIs) - Configuração IIS
Na representação arquitetural e dos componentes envolvidos, pode-se conhecer, em detalhes técnicos, o fluxo geral de eventos/dados, desde sua saída do (1) TOTVS Agro Bioenergia (módulo de Pagadoria) até chegar para Salesforce, passando pelo (2) TOTVS Agro Connector Client (componente/agent On-Premise que realiza captura de dados CDC - Change Data Capture) que compartilha dados com (3) TOTVS Agro Connector Server (aplicação SaaS no domínio TOTVS), que compartilha dados com (4) TOTVS Agro Plataforma (aplicação SaaS no domínio TOTVS) e, por fim, à chamada de APIs da Salesforce pelo (5) TOTVS Agro Conecta Dados (aplicação SaaS no domínio TOTVS - via "Conector Salesforce"):
O fluxo de integração e seus principais componentes são:
O TOTVS Agro Connector Client é um aplicação On-Premise, que é instalado localmente no ambiente do cliente com um TENTANT_ID que é disponibilizado pela equipe do TOTVS Agro e atualmente possui uma interface do Swagger e a sua própria base de dados.
No Swagger, cadastra-se a base de dados do produto, no caso TOTVS Agro Bioenergia.
Atualmente, o modelo de dados utiliza de Schemas Definitions, que é o mapeamento de tabelas e colunas que serão enviadas para parceira, conforme solicitação, a equipe TOTVS Agro realiza esse cadastro e será enviado os seguintes dados:
| UPNIVEL1 | UPNIVEL2 | UPNIVEL3 |
|---|---|---|
| CD_UPNIVEL1 | CD_UPNIVEL1 + CD_UPNIVEL2 | CD_SAFRA + CD_UPNIVEL1 + CD_UPNIVEL2 + CD_UPNIVEL3 |
| CD_UPNIVEL1 | CD_UPNIVEL1 | CD_SAFRA |
| CD_MUNIC | CD_UPNIVEL2 | CD_UPNIVEL1 |
| CD_FORNEC | CD_MUNIC | CD_UPNIVEL2 |
| DE_UPNIVEL1 | DE_UPNIVEL2 | CD_UPNIVEL3 |
| DE_ENDERECO | QT_AREA_TOT | CD_TP_PROPR |
| NO_TELEFONE | QT_AREA_PROD | DS_TERRA |
| NO_CGC_CPF | DS_ASFALTO | |
| NO_INCRA | DS_HIDROVIA | |
| NO_INSC_PROD | CD_SIST_COLH | |
| NO_CEP | DT_PLANTIO | |
| FG_TP_PESS | CD_OCUP | |
| QT_AREA_TOT | CD_VARIED | |
| QT_AREA_PROD | CD_ESTAGIO | |
| CD_INT_ERP | CD_ESPACAM | |
| INSTANCIA | CD_SIST_PLAN | |
| FG_ATIVO | QT_AREA_PROD | |
| CD_OCUP_ANT | ||
| FG_TP_PLANTIO |
Após o cadastro, vincula-se a base de dados com o Schema Definition (LocalProducao1, LocalProducao2 e LocalProducao3), esses Schemas Definitions (dados que serão enviados), após efetuar esse vínculo é criado uma trigger que monitora cada insert/update que foi cadastrado conforme a tabela acima. Quando é realizado algum INSERT ou UPDATE esse dado é processado através de tabelas do TOTVS Agro Connector Client e enviado por API como JSON para o TOTVS Agro Connector Server. Em caso de perda de conexão (serviço desligado) o registro fica em uma tabela criada chamada TCC_EVENT com status de UNPROCESSED, assim que serviço é ligado novamente o dado é processado e enviado, isso para garantir que não haja perca de dados.
O TOTVS Agro Connector Server é uma aplicação que fica nos ambientes TOTVS Apps e é utilizado pela equipe TOTVS Agro para realizar os cadastros dos clientes, gerando o TENANT_ID (para os clientes conseguirem realizar instalação do TOTVS Agro Connector Client) e os cadastros dos Schemas Definitions que foram citados Anteriormente.
Também é responsável por receber os dados que o TOTVS Agro Connector Client envia. Com esse JSON recebido, ele é enviado para uma fila de mensageria da TOTVS por meio do RabbitMQ para o TOTVS Agro Plataforma.
{
"header":{
"type":"LocalProducao1",
"generatedOn":"2023-03-02T12:45:19.000688Z",
"locale":"pt_BR"
},
"content":{
"originApp":"PIMSCS",
"appVersion":"12.1.2301",
"schemaName":"LocalProducao1",
"schemaVersion":"12.1.2301",
"action":"INSERT",
"data":{
"id":{
"id":"TESTE"
},
"nome":"TESTE1",
"codigo":"TESTE",
"originId":"Q0RfVVBOSVZFTDE9VEVTVEU="
},
"createdAt":"2023-03-02T12:45:19.303637Z",
"token":"8c12da2baca8de2e6b5dd2f6999c6998cbc7b563e5c24e043fa26b72f1f406e8"
}
} |
O TOTVS Agro Plataforma está disponível nos ambientes do TOTVS Apps, porém ele não possuí uma interface gráfica. Ele é responsável por receber as mensagens do TOTVS Connector Server que foi processado na fila do RabbitMQ, então ele pega o JSON recebido, insere os dados na própria base de dados para haver controles de chaves primárias, foreign key e garantir a integridade das tabelas e relacionamentos. Após conclusão de inserção com sucesso, novamente esse JSON é enviado para outra fila via RabbitMQ, que será processado pelo TOTVS Agro Conecta Dados.
{
"header":{
"type":"FazendaCriada",
"tenantId":"8c12da2baca8de2e6b5dd2f6999c6998cbc7b563e5c24e043fa26b72f1f406e8",
"generatedOn":"2023-03-22T14:12:21.428785Z",
"locale":"pt_BR"
},
"content":{
"originId":"Q0RfVVBOSVZFTDE9NjAwODZB",
"metadata":{
},
"codigo":"FazendaA1",
"descricao":"Fazenda Teste",
"documento":null,
"instanciaOriginId":null,
"cdMunicipio":"2308",
"cdFornecedores":"94500",
"endereco":"Fazenda Teste",
"telefone":null,
"cnpjCpf":"12345678",
"incra":null,
"inscricaoProdutorRural":"123.456.789-10",
"cep":"111111",
"tipoPessoa":"J",
"qtdAreaTotal":"24",
"qtdAreaProdutiva":"24",
"cdIntErp":null
}
} |
Para realizar as requisições é necessário passar o token recuperado, após autenticação. |
Destacam-se as tabelas disponibilizadas para nós com base na API deles, ou seja o que se deve informar no body da requisição como JSON e exemplos de como se utilizam cada uma no Postman:
Modelo à ser enviado: FAZENDA (Local de Produção 1) para Salesforce.
| API | Tipo | Descrição |
|---|---|---|
| IdConta__c | texto | Id Fazenda |
| CodigodaPropriedade__c | Texto(6) (ID Externo) | Cod Fazenda |
| Municipio__r.codigoMunicipio__c | Pesquisa | Cod Municipo PIMS |
| codigoFornecedor__c | Numero(8) | Cod Fornecedor |
| descricaoCompleta__c | texto(70) | Descrição Completa |
| BillingStreet | texto(70) | Endereço |
| Phone | texto(70) | Telefone |
| cnpjCPF__c | texto(18) | CNPJ ou CPF |
| numeroIncra__c | texto(15) | N° INCRA |
| numeroInscricaoProdutorRural__c | texto(20) | N° Insc.Produtor Rural |
| Cep__c | texto(16) | N° cep |
| Tipo_de_Pessoa__c | texto(1) | |
| QtdeAreaTotalHA__c | numero(7,2) | |
| QtdeAreaTotalProdHectares__c | numero(7,2) | |
| codigoInternoErp__c | texto(15) | |
| Instancia__r.CodigoInstanciaPIMS__c | texto(5) | |
| flagAtivo__c | Lista de Opçoes |
Modelo à ser enviado: SETOR (Local de Produção 2) para Salesforce.
| API | Tipo | Descrição |
|---|---|---|
| IdBloco__c | Texto(6) (ID Externo) | Id Bloco |
| Conta__r.IdConta__c | Pesquisa(Conta) | Cod Fazenda |
| codigoBloco__c | Texto(6) (ID Externo) | Cod Bloco |
| Municipio__r.codigoMunicipio__c | Pesquisa | Cod Municipo PIMS |
| Name | Name | Descrição do Bloco |
| Hectares__c | Number(16,2) | Qtde de Area Total em Hectares |
| AreaProdutivaHA__c | Number(16,2) | Qtde de Area Produtiva em Hectares |
Modelo à ser enviado: TALHÃO (Local de Produção 3) para Salesforce.
| API | Tipo | Descrição |
|---|---|---|
| IdTalhao__c | Texto | Id Talhão |
| Safra__c | Numero(5) | Codigo da Safra |
| Conta__r.IdConta__c | Texto(6) | Cod Fazenda |
| Bloco__r.IdBloco__c | Pesquisa | Cod Bloco |
| codigoTalhao__c (ID Externo) | Texto(6) | Cod Talhão |
| CodigoTipoPropriedade__c | Lista de Opções | Cod Tipo de Propriedade |
| DistanciaTerra__c | Numero(4,1) | Distância Terra |
| DistanciaAsfalto__c | Numero(4,1) | Distância Asfalto |
| DistanciaHidrovia__c | Numero(4,1) | Distância Hidrovia |
| CodigoSistemaColheita__c | Lista de Opções | Codigo de Sistema de Colheita |
| DataPlantio__c | Date | Data do Plantio |
| CodigoOcupacao__c | Lista de Opções | Codigo de Ocupação |
| CodigoVariedade__c | Lista de Opções | Codigo de Variedade |
| CodigoEstagio__c | Lista de Opções | Codigo de Estagio |
| CodigoEspacamento__c | Lista de Opções | Codigo de Espaçamento |
| CodigoSistemaPlantio__c | Lista de Opções | Codigo de Sistema de Plantio |
| AreaProdutivaHA__c | Number(7,2) | Qtde de Area Produtiva em Hectares |
| CodigoOcupacaoAnterior__c | Lista de Opções | Codigo de Sistema de Plantio Anterior |
| FlagTipoPlantio__c | Lista de Opções | Flag de Tipo de Plantio |
Exemplo de requisição Postman: PATCH - Setor
