TECTAE - Classe protheus para integração com a plataforma TAE

Objetivo

Facilitar a integração entre produtos protheus com a plataforma TAE

Descrição

Classe criada especialmente para atender aos produtos do segmento de serviços, mas pode ser utilizada por qualquer produto protheus, com a versão mais atual do programa tectae.prw, disponibilizado na espedição de release do protheus, ou em pacotes de expedição contínua do módulo 28.

INSTANCIANDO A CLASSE

New

SINTAXE

 Local oTAE := TecTAE():New(<baseURL>)

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Default
baseURL	caractare	URL base, utilizada na integração		https://totvssign.staging.totvs.app

AUTENTICANDO

defUser

SINTAXE

  oTAE:defUser(<cUser>)

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Default
cUser	caractare	Define o usuário que será fará a autenticação na plataforma TAE	X

defPw

SINTAXE

  oTAE:defPw(<password>)

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Default
password	caractare	Define senha para autenticação na plataforma TAE	X

auth()

SINTAXE

  oTAE:auth()

EXEMPLO DE AUTENTICAÇÃO

EXEMPLO DE AUTENTICAÇÃO

//Cria uma instância de TECTAE e realiza a autenticação do objeto da integração
Static Function conTAE()
    Local cUser     := SUPERGETMV('MV_USRTAE') 
    Local cPsWrd    := SUPERGETMV('MV_PWTAE')
    Local cBaseUrl  := SUPERGETMV('MV_TAEBASE',,"https://totvssign.staging.totvs.app")
    Local oTAE      := TecTAE():New(cBaseUrl) 
    
//Definição de usuário e senha de autenticação do objeto
    oTAE:defUser(cUser)
    oTAE:defPw(cPsWrd)
    oTAE:auth() 

//Retorno do objeto autenticado
Return oTAE

REALIZANDO UPLOADO DE DOCUMENTOS

uploadFile

SINTAXE

  oTAE:uploadFile(<cFileContent>, <cFileName>, <envName>, <response>, <msgErr>, <endPoint>, <type>)

Parâmetros

Nome	Tipo	Descrição	Obrigatório	Default
cFileContent	base64	Conteúdo do arquivo	X
cFileName	caractere	Nome do arquivo	X
envName	caractere	Nome do envelope.	X
response	caractere	Resposta da requisição na plataforma TAE, obtido através de variável passada por referência.
msgErr	caractere	Retorno de mensagens de erro, obtido através de variável passada por referência
endPoint	caractere	Endpoint para upload de arquivos.		/documents/v1/envelopes/upload
type	caractere	Tipo do documento. Tipos aceitos: .pdf, .doc, .docx		.pdf

EXEMPLO DE UPLOAD DE ARQUIVO

Static Function uploadFileTAE()
	Local oTAE      := conTAE()
	Local oFile     := Nil
	Local cPathFile := ""
	Local cNomeFile := "Nome do arquivo"
	Local oRequest  := Nil
	Local cMsgErr   := ""
	Local nIdEnv	:= 0
	
	//Criando um arquivo de teste e retornando o caminho para cPathFile
 	cPathFile := genFileTeste(cNomeFile+".PDF")

	//Obtendo o arquivo de teste que será enviado 
	oFile := tecFOPEN(cFile) 
	
	lUpload := oTAE:uploadFile(oFile,cNomeFile+".PDF", "documento teste para integracao com o TAE", @oRequest, @cMsgErr)
	If lUpload
		//Código do envelope que deverá ser utilizado no método publicar
  		nIdEnv := oRequest:data
	EndIf
Return nIdEnv  

//Realiza leitura de um arquivo
Static Function tecFOPEN(cPath)
    Local cBuffer := ""
    Local cResult := ""
    Local nHandle := 0
    Local nBytes  := 0

	nHandle := FOPEN(cPath) 
	If nHandle > -1
		While (nBytes := FREAD(nHandle, @cBuffer, 524288)) > 0 
			cResult += cBuffer
		EndDo

		FCLOSE(nHandle)
	EndIf
Return cResult

//Gerar documento de teste
Static Function genFileTeste(cNmFile)

    Local cFile             := ""
    Local cPathLocal        := GetSrvProfString("StartPath","") //'\system\'
    Local lAdjustToLegacy   := .T.    
    Local lDisableSetup     := .T.   
    Local lViewPDF          := .T.

    oPrint := FWMSPrinter():New(cNmFile/*cRelNome*/,IMP_PDF,lAdjustToLegacy,cPathLocal,lDisableSetup,,,,,,,lViewPDF)

    cFile := cPathLocal+cNmFile
    File2Printer( cFile, "PDF" )
    oPrint:cPathPDF:= cPathLocal

    oFont20 := TFont():New("Arial",9,20,.T.,.T.,5,.T.,5,.T.,.F.)

    oPrint:StartPage()
    nRow1 := 1

    oPrint:Line(nRow1+100,100,nRow1+0100,1400)
    
    oPrint:Say(nRow1+0080,100,"Arquivo para teste de integração com o TAE ",oFont20 ) 
    nRow1++
    
    oPrint:Preview()

    cFile := cPathLocal+cNmFile 

Return cFile

REALIZANDO PUBLICAÇÃO DE DOCUMENTOS

publicar

SINTAXE

  oTAE:publicar(<nIdEnv>,<aDest>,<aObserv>,<cPapel>,<cExpDate>,<cAssunto>,<cMsgTAE>,<cResponse>)

Parâmetros

Nome	Tipo	Descrição	Obrigatório
nIdEnv	numérico	Id do envelope, obtido ao utilizar o método uploadFile	x
aDest	array	Array com dados dos destinatários, com os dados nome, email, cpf para cada pessoa	x
aObserv	array	Array com os emails dos observadores.
cPapel	caractere	Papel dos assinantes, conforme cadastros da plataforma TAE. Exemplo: "como contratante"	x
cExpDate	caractere	Data de expiração do documento, no formato: 'yyyy-mm-dd'. A data deve ser maior que a data atual do sistema.	x
cAssunto	caractere	Assunto do documento que será assinado.
cMsgTAE	caractere	Mensagem que será enviado pelo TAE aos assinantes
cResponse	caractere	Resposta da api do TAE, passado via referência.

EXEMPLO DE PUBLICAÇÃO DE DOCUMENTO

static function publicarTAE(oTAE, nIdEnv)
    Local lRet      := .F.
    Local aDest     := {}
    Local aObserv   := {}
    //Data de expiração do documento > data atual
    Local cExpDate  := '2025-01-01'
    Local cPapel    := 'como contratante'
    Local cAssunto  := "Documento contrato xpto "
    Local cMsgTAE   := "Documento teste para ser assinado digitalmente."
    Local cResponse := ""
    
    aAdd(aDest,{"[email protected]","Assinante1","000.000.000-00"}) //Email, Nome, cpf (cpf válido)
    aAdd(aDest,{"[email protected]","Assinante2","000.000.000-02"}) //Email, Nome, cpf (cpf válido)

    aAdd(aObserv,'[email protected]')
    aAdd(aObserv,'[email protected]')

    lRet := oTAE:publicar(nIdEnv,aDest,aObserv,cPapel,cExpDate,cAssunto,cMsgTAE,@cResponse)

Return lRet

OBTENDO STATUS DE PUBLICAÇÃO

detailPub

SINTAXE

Local nStatus := oTAE:detailPub(<nEnvId>)

//0 = erro
//1 = pendente
//2 = finalizado
//5 = cancelado

Nome	Tipo	Descrição	Obrigatório	Default
nEnvId	numérico	Id do envelope, obtido ao utilizar o método uploadFile	x

CANCELAMENTO DE PUBLICAÇÃO

pubCancel

SINTAXE

oTAE:pubCancel(<nEnvId>)

Nome	Tipo	Descrição	Obrigatório	Default
nIdEnv	numérico	Id do envelope, obtido ao utilizar o método uploadFile	x

ASSUNTOS RELACIONADOS

Documentações das APIs TAE: https://totvs-sign.readme.io/reference/gettings-started
Documentação da plataforma TAE: TOTVS Assinatura Eletrônica

Árvore de páginas

TECTAE - Classe protheus para integração com a plataforma TAE

Objetivo

Descrição

INSTANCIANDO A CLASSE

AUTENTICANDO

REALIZANDO UPLOADO DE DOCUMENTOS

REALIZANDO PUBLICAÇÃO DE DOCUMENTOS

OBTENDO STATUS DE PUBLICAÇÃO

CANCELAMENTO DE PUBLICAÇÃO

ASSUNTOS RELACIONADOS