Anexar Arquivos

<h1>Anexando documentos em registros específicos</h1> A maioria das entidades do sistema permite anexar documentos em suas respectivas telas (ex.: cadastro de parceiros, cadastro de produtos, item da nota, contratos, etc.). O objetivo deste tutorial é apresentar como isso pode ser feito via API. O processo é realizado em duas etapas: <ul> <li>o primeiro passo é enviar o arquivo para o servidor.</li> <li>o segundo passo salva o anexo e endereça ao respectivo registro.</li> </ul> Para ilustrar, apresentamos a seguir as duas requisições, detalhando o objetivo e impacto de cada ação, bem como o papel de cada atributo utilizado nas requisições. <br /><br /> <h2>Observação Importante</h2> Este serviço de anexos é destinado para envio de anexos para entidades que utilizam o componente padrão de anexos (componente do "clipe") na interface do SankhyaOm. Entidades que não exibem o ícone de clipe na tela - como, por exemplo, o Cabeçalho de Nota, Ordem de Serviço - não são compatíveis com este mecanismo de anexos destacado aqui. <br /><br /> <h2>Parte 1: Envio do arquivo</h2> A requisição basicamente faz um POST de um formulário do tipo multipart, enviando o documento utilizando uma sessionKey que será utilizada posteriormente, no serviço de endereçamento do anexo ao registro desejado. Seguem os principais atributos dessa requisição:<br /> <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/sessionUpload.mge<br /> Com os seguintes parâmetros na URL: <ul> <li>sessionkey=ANEXO_SISTEMA_ItemNota_2097_1</li> <li>fitem=S</li> <li>salvar=S</li> <li>useCache=N</li> </ul> Dentre esses atributos, o parâmetro mais importante é o sessionkey, que sempre varia. Este parâmetro deve ser enviado no seguinte formato:<br /><br /> ANEXO_SISTEMA: sempre fixo<br /> nomeEntidade<br /> pkRegistro<br /> <br /> No exemplo acima, a entidade é ItemNota e a PK do item nota (que é composto) é NUNOTA 2097 e SEQUENCIA 1. Com isso temos: ANEXO_SISTEMA_ItemNota_2097_1<br /><br /> Em seguida, é necessário preparar o "formulário", onde o tipo (Content-Type) deve ser "multipart/form-data" com uma variável chamada "arquivo" contendo o endereço do anexo a ser enviado.<br /><br /> Veja a seguir um exemplo prático desta requisição em formato curl:<br /><br />

curl --location 'https://[URL_GATEWAY]/gateway/v1/mge/sessionUpload.mge?sessionkey=ANEXO_SISTEMA_ItemNota_2097_1&fitem=S&salvar=S&useCache=N' \
--header 'appkey: APPKEY_DA_SUA_APLICACAO_BEM_AQUI' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer BEAR_TOKEN_VALIDO_BEM_AQUI' \
--header 'Accept: text/html' \
--header 'Content-Type: multipart/form-data' \
--form 'arquivo=@"MtBz0s5kk/foto_atualizada.jpg"'

<br /> Nesta requsição, estamos enviando a imagem "foto_atualizada.jpg". <br /><br /> <h2>Parte 2: Salvar e Vincular anexo ao registro</h2> Agora que o anexo foi enviado para o servidor, é hora de realizar o “vínculo” do mesmo com o respectivo registro desejado.<br /> Veja os principais parâmetros variáveis desta requisição:<br />

<ul> <li>Nome do serviço: AnexoSistemaSP.salvar</li> <li>pkEntity: chave primária da entidade. No caso de chave composta, separa com _</li> <li>keySession: utilizar exatamente a mesma utilizada no serviço anterior.</li> <li>nameEntity: nome da entidade</li> <li>description: descrição desejada para anexo (texto com até 20 caracteres).</li> <li>nameAttach: nome para o anexo. Sugestão de enviar o mesmo nome que o documento tem, ao utilizar o serviço de enviar o anexo.</li> </ul> Os demais parâmetros contidos na requisição, devem permanecer sempre fixos, conforme exemplo a seguir. <br /><br /> A seguir um exemplo da requisição:<br /> URL POST: https://[URL_GATEWAY]/gateway/v1/mge/service.sbr?serviceName=AnexoSistemaSP.salvar&outputType=json

{
   "serviceName":"AnexoSistemaSP.salvar",
   "requestBody":{
      "params":{
         "pkEntity":"2097_1",
         "keySession":"ANEXO_SISTEMA_ItemNota_2097_1",
         "nameEntity":"ItemNota",
         "description":"Foto Atualizada 1",
         "keyAttach":"",
         "typeAcess":"ALL",
         "typeApres":"GLO",
         "nuAttach":"",
         "nameAttach":"foto_atualizada.jpg",
         "fileSelect":1,
         "oldFile":""
      }
   }
}