Incluir e Alterar Dados
<h1>Regras de negócio</h1> 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.<br /><br /> <h3>Exemplo de uso</h3> <ul> <li>URL Gateway Produção: https://api.sankhya.com.br/</li> <li>URL Gateway Sandbox: https://api.sandbox.sankhya.com.br/</li> </ul> <b>URL de chamada</b>: https://[URL_GATEWAY]/gateway/v1/mge/service.sbr?serviceName=DatasetSP.save&outputType=json<br /><br /> <b>Vejamos agora a estrutura base da requisição para incluir e atualizar dados via API:</b>{
"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"
}
}
]
}
}
<br /> 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).<br /> Veremos a seguir 2 exemplos práticos de inclusão e atualização de registros. <br /><br /><br />
<h2>Como fazer a inclusão de dados?</h2> 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.<br /><br /> <b>Exemplo para incluir parceiro:</b>{
"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"
}
}
]
}
}
<b>Retorno:</b>
{
"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"
]
]
}
}
<br />No retorno, a primeira linha da requisição indica o Código atribuído a este parceiro (neste exemplo 4454).<br /> 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:<br /><br /> <b>Exemplo para incluir os contatos do parceiro:</b>
{
"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"
}
}
]
}
}
<b>Retorno:</b><br/>
{
"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"
]
]
}
}
<br />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<br />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.<br /><br />
<h2>Como fazer alterações em dados?</h2> 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.<br /> 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:<br />{
"serviceName":"DatasetSP.save",
"requestBody": {
"entityName":"Parceiro",
"standAlone":false,
"fields": [
"CODPARC",
"NOMEPARC",
"ATIVO",
"TIPPESSOA"
],
"records":[
{
"pk": {
"CODPARC":"4454"
},
"values": {
"1":"JOSE DA SILVA XAVIER"
}
}
]
}
}
<b>Retorno:</b><br />
{
"serviceName": "DatasetSP.save",
"status": "1",
"pendingPrinting": "false",
"transactionId": "E5526480FF334FF05DC6118028A60AE0",
"responseBody": {
"total": "1",
"result": [
[
"4454",
"JOSE DA SILVA XAVIER",
"S",
"F"
]
]
}
}
<br />Agora vamos atualizar o cadastro dos dois contatos, adicionando e-mails aos mesmos. Segue json para realizar a requisição:<br />
{
"serviceName":"DatasetSP.save",
"requestBody":{
"entityName":"Contato",
"standAlone":false,
"fields":[
"CODCONTATO",
"ATIVO",
"NOMECONTATO",
"EMAIL",
"CELULAR"
],
"records":[
{
"pk":{
"CODPARC":"4454",
"CODCONTATO":"1"
},
"values":{
"3":"financeiro@empresa.com.br"
}
},
{
"pk":{
"CODPARC":"4454",
"CODCONTATO":"2"
},
"values":{
"3":"comercial@empresa.com.br"
}
}
]
}
}
<b>Retorno:</b><br />
{
"serviceName": "DatasetSP.save",
"status": "1",
"pendingPrinting": "false",
"transactionId": "42C865B17822AC52F3F58DFEA7394BE5",
"responseBody": {
"total": "2",
"result": [
[
"1",
"S",
"NOME DO CONTATO 1",
"financeiro@empresa.com.br",
"33 999998888"
],
[
"2",
"S",
"NOME DO CONTATO 2",
"comercial@empresa.com.br",
"33 999998888"
]
]
}
}
Response
Cadastro efetuado com sucesso