Regras de negócio

Utilizando a API é possível realizar a inclusão, ou atualização, de dados no SankhyaOm. Para isso, utilizamos o serviço \"DatasetSP.save\". O mesmo serviço é utilizado para ambos os casos, o que vai indicar se é inclusão ou atualização é o envio da chave primária do registro ou não, ou seja, ao enviar a chave primária indica a necessidade de atualização, e caso a chave primária não seja enviada, a API entende que é necessário fazer a inclusão do registro.

Exemplo de uso

• URL Gateway Produção: https://api.sankhya.com.br/
• URL Gateway Sandbox: https://api.sandbox.sankhya.com.br/

URL de chamada: https://[URL_GATEWAY]/gateway/v1/mge/service.sbr?serviceName=DatasetSP.save&outputType=json

Vejamos agora a estrutura base da requisição para incluir e atualizar dados via API:

{
   "serviceName":"DatasetSP.save",
   "requestBody":{
      "entityName":"NomeDaEntidade",
      "standAlone":false,
      "fields":[ "CAMPO_1",
        "CAMPO_2",
        "CAMPO_N"
      ],
      "records":[
         {
            "pk":{  // deve ser enviado apenas para situação de atualização
               "NOME_PK":"VALOR_PK"
            },
            "values":{
               "0": "VALOR_1",
               "1": "VALOR_2",
               "2": "VALOR_N"
            }
         }
      ]
   }
}

Esta estrutura é padrão, e permite fazer inclusão, e atualização, em qualquer entidade existente no SankhyaOm. Para isso, basta indicar a Entidade (entityName), os campos (fields) e os respectivos valores (records).
Veremos a seguir 2 exemplos práticos de inclusão e atualização de registros.

Como fazer a inclusão de dados?

Agora que temos a estrutura base da requisição para incluir e atualizar dados via API, vamos apresentar um exemplo de inclusão utilizando registros com PK simples e com PK composta. Veja a seguir a inclusão de um Parceiro e seu contato.

Exemplo para incluir parceiro:

{
   "serviceName":"DatasetSP.save",
   "requestBody":{
      "entityName":"Parceiro",
      "standAlone":false,
      "fields":[
         "CODPARC",
         "NOMEPARC",
         "ATIVO",
         "TIPPESSOA",
         "CODCID",
         "CODREG",
         "CLASSIFICMS",
         "ComplementoParc.SUGTIPNEGENTR",
         "ComplementoParc.SUGTIPNEGSAID"
      ],
      "records":[
         {
            "values":{
               "1":"NOME DO PARCEIRO BEM AQUI",
               "2":"S",
               "3":"F",
               "4":"1",
               "5":"0",
               "6":"C",
               "7":"13",
               "8":"13"
            }
         }
      ]
   }
}

Retorno:

{
    "serviceName": "DatasetSP.save",
    "status": "1",
    "pendingPrinting": "false",
    "transactionId": "EAE26797DAF8A192B2FFF990097337A7",
    "responseBody": {
        "total": "1",
        "result": [
            [
                "4454",
                "NOME DO PARCEIRO BEM AQUI",
                "S",
                "F",
                "1",
                "0",
                "C",
                "13",
                "13"
            ]
        ]
    }
}

No retorno, a primeira linha da requisição indica o Código atribuído a este parceiro (neste exemplo 4454).
Agora, vamos fazer a inclusão de múltiplos registros utilizando PK do parceiro como chave de ligação para registros de detalhe. O json a seguir inclui dois contatos para o parceiro na entidade Contato que possui PK composta (CODPARC, CODCONTATO). Segue json para incluir os contatos para o parceiro recém incluído:

Exemplo para incluir os contatos do parceiro:

{
   "serviceName":"DatasetSP.save",
   "requestBody":{
      "entityName":"Contato",
      "standAlone":false,
      "fields":[
         "CODCONTATO",
         "ATIVO",
         "NOMECONTATO",
         "EMAIL",
         "CELULAR"
      ],
      "records":[
         {
            "foreignKey":{
               "CODPARC":"4454"
            },
            "values":{
               "1":"S",
               "2":"Nome do Contato 1",
               "4":"33  999998888"
            }
         },
         {
            "foreignKey":{
               "CODPARC":"4454"
            },
            "values":{
               "1":"S",
               "2":"Nome do Contato 2",
               "4":"33  999998888"
            }
         }
      ]
   }
}

Retorno:

{
    "serviceName": "DatasetSP.save",
    "status": "1",
    "pendingPrinting": "false",
    "transactionId": "A0B2291C8ED35C5DD22E42B36B98BE97",
    "responseBody": {
        "total": "2",
        "result": [
            [
                "1",
                "S",
                "NOME DO CONTATO 1",
                "",
                "33  999998888"
            ],
            [
                "2",
                "S",
                "NOME DO CONTATO 2",
                "",
                "33  999998888"
            ]
        ]
    }
}

Dessa forma, com uma requisição conseguimos realizar múltiplas inclusões. Note que incluirmos o contato código 1 e 2 para o parceiro 4454.\n
Vale ressaltar que não é necessário enviar todos os dados (records) indicados na seção de campos (fields). O exemplo acima indica 5 campos, mas envia apenas 3 informações para realizar a inclusão do parceiro.

Como fazer alterações em dados?

Agora que vimos como incluir registros, vamos fazer algumas atualizações nos cadastros incluídos recentemente. Vamos atualizar o nome do parceiro e adicionar e-mails aos contatos que foram vinculados ao parceiro.
Para realizar uma atualização de cadastro, basta indicar a PK forte do registro desejado. Vejamos a seguir o json para atualizar o cadastro do parceiro 4454:

{
   "serviceName":"DatasetSP.save",
   "requestBody": {
      "entityName":"Parceiro",
      "standAlone":false,
      "fields": [
         "CODPARC",
         "NOMEPARC",
         "ATIVO",
         "TIPPESSOA"
      ],
      "records":[
         {
            "pk": {
               "CODPARC":"4454"
            },
            "values": {
               "1":"JOSE DA SILVA XAVIER"
            }
         }
      ]
   }
}

Retorno:

{
    "serviceName": "DatasetSP.save",
    "status": "1",
    "pendingPrinting": "false",
    "transactionId": "E5526480FF334FF05DC6118028A60AE0",
    "responseBody": {
        "total": "1",
        "result": [
            [
                "4454",
                "JOSE DA SILVA XAVIER",
                "S",
                "F"
            ]
        ]
    }
}

Agora vamos atualizar o cadastro dos dois contatos, adicionando e-mails aos mesmos. Segue json para realizar a requisição:

{
   "serviceName":"DatasetSP.save",
   "requestBody":{
      "entityName":"Contato",
      "standAlone":false,
      "fields":[
         "CODCONTATO",
         "ATIVO",
         "NOMECONTATO",
         "EMAIL",
         "CELULAR"
      ],
      "records":[
         {
            "pk":{
               "CODPARC":"4454",
               "CODCONTATO":"1"
            },
            "values":{
               "3":"[email protected]"
            }
         },
         {
            "pk":{
               "CODPARC":"4454",
               "CODCONTATO":"2"
            },
            "values":{
               "3":"[email protected]"
            }
         }
      ]
   }
}

Retorno:

{
    "serviceName": "DatasetSP.save",
    "status": "1",
    "pendingPrinting": "false",
    "transactionId": "42C865B17822AC52F3F58DFEA7394BE5",
    "responseBody": {
        "total": "2",
        "result": [
            [
                "1",
                "S",
                "NOME DO CONTATO 1",
                "[email protected]",
                "33  999998888"
            ],
            [
                "2",
                "S",
                "NOME DO CONTATO 2",
                "[email protected]",
                "33  999998888"
            ]
        ]
    }
}