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 imagem abaixo, podemos ver com detalhes o fluxo geral, desde quando os dados saí do TOTVS Agro Bioenergia até chegar para Salesforce. O fluxo é divido em 3 etapas que serão detalhadas de acordo com decorrer do material, essas etapas são:
Resumidamente a integração segue o fluxo abaixo.
Após a explicação resumida acima, nas próximas seções iremos detalhas o papel de cada produto e suas funções a serem utilizadas.
O TOTVS Agro Connector Client é um aplicação On-premises, 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, conforme a imagem abaixo.
No Swagger, cadastramos a base de dados do produto, no caso TOTVS Agro Bioenergia.
Hoje, trabalhamos com 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, vinculamos 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 tebela 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.
Ele 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. |
Abaixo será exibidos as tabelas disponibilizadas para nós com base na API deles, ou seja o que devemos passar no body da requisição como JSON e exemplos de como estamos utilizando cada uma no postman:
Modelo à ser enviado: FAZENDA (Local de Producã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 Producã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 Producã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
