Anexando documentos em registros específicos

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:

• o primeiro passo é enviar o arquivo para o servidor.
• o segundo passo salva o anexo e endereça ao respectivo registro.

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.

Parte 1: Envio do arquivo

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:

Endereço: https://api.sankhya.com.br/gateway/v1/mge/sessionUpload.mge
Com os seguintes parâmetros na URL:

• sessionkey=ANEXO_SISTEMA_ItemNota_2097_1
• fitem=S
• salvar=S
• useCache=N

Dentre esses atributos, o parâmetro mais importante é o sessionkey, que sempre varia. Este parâmetro deve ser enviado no seguinte formato:

ANEXO_SISTEMA: sempre fixo
nomeEntidade
pkRegistro

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

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.

Veja a seguir um exemplo prático desta requisição em formato curl:

curl --location 'https://api.sankhya.com.br/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"'

Nesta requsição, estamos enviando a imagem "foto_atualizada.jpg".

Parte 2: Salvar e Vincular anexo ao registro

Agora que o anexo foi enviado para o servidor, é hora de realizar o “vínculo” do mesmo com o respectivo registro desejado.

Veja os principais parâmetros variáveis desta requisição:

• Nome do serviço: AnexoSistemaSP.salvar
• pkEntity: chave primária da entidade. No caso de chave composta, separa com _
• keySession: utilizar exatamente a mesma utilizada no serviço anterior.
• nameEntity: nome da entidade
• description: descrição desejada para anexo (texto com até 20 caracteres).
• 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.

Os demais parâmetros contidos na requisição, devem permanecer sempre fixos, conforme exemplo a seguir.

A seguir um exemplo da requisição:
URL POST: https://api.sankhya.com.br/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":""
      }
   }
}