Penneo Sign Sandbox (versão prévia)

Penneo transforma processos complexos em uma experiência perfeita e centrada no ser humano. Ao integrar assinaturas digitais em fluxos de trabalho automatizados, nossa plataforma torna fácil validar quem aprovou quais dados e quando, reduzindo os encargos administrativos, garantindo total conformidade e segurança. Esse conector permite que você envie documentos para assinatura.

Esse conector está disponível nos seguintes produtos e regiões:

Service	Class	Regions
Copilot Studio	Premium	Todas as regiões Power Automate exceto as seguintes: – Governo dos EUA (GCC) – Governo dos EUA (GCC High) - China Cloud operado pela 21Vianet - Departamento de Defesa dos EUA (DoD)
Aplicativos Lógicos	Standard	Todas as regiões dos Aplicativos Lógicos , exceto as seguintes: – Azure Governamental regiões - Azure regiões da China - Departamento de Defesa dos EUA (DoD)
Power Apps	Premium	Todas as regiões Power Apps exceto as seguintes: – Governo dos EUA (GCC) – Governo dos EUA (GCC High) - China Cloud operado pela 21Vianet - Departamento de Defesa dos EUA (DoD)
Power Automate	Premium	Todas as regiões Power Automate exceto as seguintes: – Governo dos EUA (GCC) – Governo dos EUA (GCC High) - China Cloud operado pela 21Vianet - Departamento de Defesa dos EUA (DoD)

Contact
Nome	Suporte do Penneo
URL	https://www.support.penneo.com

Metadados do conector
Publicador	Integração do Penneo
fonte	Swagger
Site	https://penneo.com
Política de privacidade	https://penneo.com/privacy-policy
Categories	Produtividade

Penneo Sign Sandbox

Pré-requisitos

Para usar esse conector, você precisará de uma conta ativa da Área Restrita do Penneo.

Ações com Suporte

Criar um novo arquivo de caso

Cria um novo arquivo de caso no Penneo com os documentos e signatários especificados. O arquivo de caso será criado no Penneo, e um UUID e um payloadHash serão retornados que podem ser usados para verificar o status de criação por meio do ponto de extremidade de status da fila.

Verificar o status do trabalho

Recupera o status atual de um arquivo de caso fornecendo o trabalho UUID e payloadHash. Esse ponto de extremidade é usado para sondar o status de conclusão do trabalho depois de enviar uma solicitação de criação de arquivo de caso. O ponto de extremidade é limitado a 20 solicitações por minuto por combinação uuid-payloadHash.

Obter detalhes do arquivo de caso

Recupera os detalhes de um arquivo de caso específico do Penneo com base na ID do arquivo de caso. Isso inclui seus signatários, documentos e status atual.

Baixar documento

Baixa o conteúdo de um documento do Penneo como uma cadeia de caracteres codificada em base64. Por padrão, a versão assinada do documento é retornada; use o signed parâmetro para obter a versão sem sinal. Se o arquivo de caso incluir mais documentos, certifique-se de fazer loop sobre cada documento.

Obtendo credenciais

O conector foi configurado para usar o OAuth com concessão de código de autorização. Os usuários terão que fazer logon com suas credenciais regulares quando usarem o conector.

Introdução

Criando um arquivo de caso

Preparar seus documentos:
- Converter seus documentos PDF em codificação base64
- Verifique se os documentos são arquivos PDF válidos
Configurar signatários:
- Fornecer o nome e o email do signatário (obrigatório)
- Opcionalmente, forneça função, idioma, ordem de assinatura etc.
- Configurar notificações por email e modelos de email personalizados, se necessário
Crie o arquivo de caso:
- Usar a ação "Criar um novo arquivo de caso"
- Preencha os detalhes do arquivo de caso:
  - Title
  - Documentos (PDFs codificados em base64)
  - Signatários (com nomes e detalhes opcionais)
  - Configurações opcionais (expiração, idioma, visibilidade etc.)
Verificar o status de criação do CaseFile:
- Depois de criar um arquivo de caso, você receberá uma UUID e payloadHash
- Use a ação "Verificar status do trabalho" para sondar a conclusão do trabalho
- Respeitar o limite de taxa de 20 solicitações por minuto por combinação uuid-hash

Observação: você pode verificar o que cada campo faz verificando https://penneo.readme.io/reference/createcasefile.

Recuperando um arquivo de caso e seus documentos

Obtenha os detalhes do arquivo de caso:
- Use a ação "Obter detalhes do arquivo de caso" com a ID do arquivo de caso
- A resposta inclui o status do arquivo de caso, os signatários e a lista de documentos (com suas IDs de documento)
Baixe um documento:
- Use a ação "Baixar documento" com a ID do documento obtida dos detalhes do arquivo de caso
- A resposta contém o conteúdo do documento como uma cadeia de caracteres codificada em base64, que você pode decodificar para recuperar o arquivo PDF

Problemas e limitações conhecidos

Limitação de taxa: o ponto de extremidade verificar o status do trabalho é limitado a 20 solicitações por minuto por combinação uuid-hash. Implemente a lógica de repetição apropriada com retirada exponencial.
Processamento assíncrono: a criação de arquivo de caso é assíncrona. Você deve usar o ponto de extremidade de status do trabalho para verificar a conclusão em vez de esperar resultados imediatos.
Codificação base64: os documentos devem ser codificados em base64. Verifique a codificação adequada para evitar falhas de solicitação (você pode usar a função de cadeia de caracteres base64 no Power Platform para codificar os arquivos PDF binários).
Ambiente de área restrita: esse conector está configurado para o ambiente de área restrita do Penneo (sandbox.penneo.com).
Tamanho do documento: documentos grandes podem levar mais tempo para serem processados. Considere os limites de tamanho do documento ao codificar para base64.

Instruções de implantação

Execute os seguintes comandos e siga os prompts:

paconn create --api-def apiDefinition.swagger.json --api-prop apiProperties.json --icon icon.png --script script.csx

Limitações

Nome	Chamadas	Período de renovação
Chamadas à API por conexão	100	60 segundos

Ações

Baixar documento	Baixa o conteúdo de um documento do Penneo como uma cadeia de caracteres codificada em base64. Por padrão, a versão assinada do documento é retornada.
Criar um novo arquivo de caso	Cria um novo arquivo de caso no Penneo com os documentos e signatários especificados. O arquivo de caso será criado de forma assíncrona, e um UUID do trabalho e um payloadHash serão retornados que podem ser usados para verificar o status de criação por meio da ação Verificar status do trabalho. Você pode configurar signatários, documentos, ordem de assinatura, notificações por email, controle de acesso e várias outras configurações de arquivo de caso.
Obter detalhes do arquivo de caso	Recupera os detalhes de um arquivo de caso específico da Penneo, incluindo seus signatários, documentos e status atual. Status do arquivo de caso: 0=new, 1=pending, 2=rejected, 3=deleted, 4=signed, 5=completed, 6=failed, 7=expired, 8=anonymized. Use o status 5 (concluído) como gatilho para baixar os documentos assinados.
Verificar o status do trabalho	Recupera o status atual de um trabalho assíncrono fornecendo o trabalho UUID e payloadHash. Esse ponto de extremidade é usado para sondar o status de conclusão do trabalho depois de enviar uma solicitação de criação de arquivo de caso. A ação é limitada a 20 solicitações por minuto por combinação uuid-payloadHash.

Baixar documento

ID da operação:: DownloadDocument

Baixa o conteúdo de um documento do Penneo como uma cadeia de caracteres codificada em base64. Por padrão, a versão assinada do documento é retornada.

Parâmetros

Nome	Chave	Obrigatório	Tipo	Description
ID do documento	documentId	True	integer	A ID do documento a ser baixado. Recupere as documentIds com a ação "Obter detalhes do arquivo de caso".
Assinado	signed		boolean	Obtenha o documento assinado ou não assinado. Por padrão, o documento assinado será retornado se o documento tiver sido assinado.

Retornos

Corpo: DocumentContent

Criar um novo arquivo de caso

ID da operação:: CreateCaseFile

Cria um novo arquivo de caso no Penneo com os documentos e signatários especificados. O arquivo de caso será criado de forma assíncrona, e um UUID do trabalho e um payloadHash serão retornados que podem ser usados para verificar o status de criação por meio da ação Verificar status do trabalho. Você pode configurar signatários, documentos, ordem de assinatura, notificações por email, controle de acesso e várias outras configurações de arquivo de caso.

Parâmetros

Nome	Chave	Obrigatório	Tipo	Description
title	title	True	string	O título do arquivo de caso.
sendAt	sendAt		integer	Carimbo de data/hora em que o arquivo de caso deve ser enviado. Nulo = imediatamente
name	name	True	string	Nome do signatário
função	role		string	Função para o signatário. Permitido: letras, números, espaços, vírgula, sublinhado, hífen. Deve começar com uma letra/número e não deve terminar com um espaço.
email	email		email	Email do signatário. Penneo lidará com todas as comunicações
failUrl	failUrl		uri	URL de redirecionamento após falha
linguagem	language		string	Idioma do signatário
emailText	emailText		string	Texto personalizado para o email de solicitação de assinatura. O padrão será o modelo da empresa, se não for fornecido.
signOrder	signOrder		integer	A ordem de assinatura. 0 significa nenhuma ordem imposta.
successUrl	successUrl		uri	URL de redirecionamento após o sucesso
emailSubject	emailSubject		string	Assunto do email de solicitação de assinatura. O padrão será o modelo da empresa, se não for fornecido.
reminderInterval	reminderInterval		integer	Dias antes do lembrete ser enviado
reminderEmailText	reminderEmailText		string	Texto personalizado para o email de lembrete. O padrão será o modelo da empresa, se não for fornecido.
completedEmailText	completedEmailText		string	Texto personalizado para o email concluído. O padrão será o modelo da empresa, se não for fornecido.
reminderEmailSubject	reminderEmailSubject		string	Assunto do email de lembrete. O padrão será o modelo da empresa, se não for fornecido.
completedEmailSubject	completedEmailSubject		string	Assunto do email concluído. O padrão será o modelo da empresa, se não for fornecido.
enableInsecureSigning	enableInsecureSigning		boolean	Se for true, o signatário poderá usar assinaturas de toque (desenho, texto, upload de imagem)
insecureSigningMethods	insecureSigningMethods		array of string	Métodos de assinatura inseguros permitidos. O padrão será a configuração da empresa se estiver vazia.
secureSigningMethods	secureSigningMethods		array of string	Os métodos de assinatura eletrônica seguros permitidos. Substitui o arquivo de caso e as configurações do cliente quando definido.
vatin	vatin		string	Número de identificação de IVA da empresa do signatário
ssnType	ssnType		string	Tipo de SSN/mobile. Exemplo 'dk:cpr', 'se:pin', 'no:nin', 'be:nrn', 'fi:pic' ou 'sms'. Padrão para 'herdado'
activeAt	activeAt		integer	Carimbo de data/hora de ativação
expireAt	expireAt		integer	Carimbo de data/hora de expiração
de controle de acesso	accessControl		boolean	Se habilitado, SSN/VATIN/phone será validado antes do acesso
emailFormat	emailFormat		string	Define o formato de email
onBehalfOf	onBehalfOf		string	A empresa/organização da qual esse signatário assina em nome
storeAsContact	storeAsContact		boolean	Se for true, o signatário será armazenado como contato no Penneo
socialSecurityNumberPlain	socialSecurityNumberPlain		string	O SSN do signatário ou o número de telefone (formato E.164 recomendado)
expireAt	expireAt		integer	Carimbo de data/hora quando o arquivo de caso expirar. Se não for fornecido, os padrões serão aplicados
linguagem	language		string	O idioma do arquivo de caso será aplicado a cada signatário que não tenha um conjunto de idiomas
Pdf	pdf	True	string	PDF codificado em Base64
conectável	signable		boolean	True cria um documento que pode ser assinado. False, o documento é adicionado como um anexo e não pode ser assinado.
funções	roles		array of string	Funções de signatário com permissão para assinar este documento. O padrão é todos os signatários, se estiverem vazios.
title	title	True	string	O título do documento
documentOrder	documentOrder		integer	A ordem de assinatura do documento. Padrões para a ordem fornecida.
metadados	metaData		string	Metadados do documento, pesquisáveis em Penneo
sensitiveData	sensitiveData		boolean	Se for true, os signatários deverão validar sua identidade antes de acessar documentos. Desabilita anexos de email para documentos assinados.
signOnMeeting	signOnMeeting		boolean	Especifica se os documentos devem ser assinados durante uma reunião.
visibilityMode	visibilityMode		integer	0 = Os signatários veem todos os documentos. 1 = Os signatários veem apenas os documentos que precisam assinar.
disableEmailAttachments	disableEmailAttachments		boolean	Desabilita anexos de email para documentos assinados em emails de finalização. Substituído se sensitiveData for true.
disableNotificationsOwner	disableNotificationsOwner		boolean	Se o proprietário do arquivo de caso verdadeiro não receber notificações para o arquivo de caso.
folderId	folderId		integer	A ID da pasta em que você deseja colocar o arquivo de caso
metadados	metaData		string	Metadados do arquivo de caso, pesquisáveis no Penneo
referência	reference		string	A referência do arquivo de caso será mostrada no aplicativo Web Penneo
name	name	True	string	Nome do destinatário
email	email	True	email	Email do destinatário

Retornos

Corpo: JobResponse

Obter detalhes do arquivo de caso

ID da operação:: GetCaseFileDetails

Recupera os detalhes de um arquivo de caso específico da Penneo, incluindo seus signatários, documentos e status atual. Status do arquivo de caso: 0=new, 1=pending, 2=rejected, 3=deleted, 4=signed, 5=completed, 6=failed, 7=expired, 8=anonymized. Use o status 5 (concluído) como gatilho para baixar os documentos assinados.

Parâmetros

Nome	Chave	Obrigatório	Tipo	Description
ID do arquivo de caso	caseFileId	True	integer	A ID do arquivo de caso a ser recuperado. Recupere a ID do arquivo de caso com a ação "Verificar status do trabalho".

Retornos

Detalhes de um arquivo de caso recuperado do arquivo seguro penneo.

Corpo: CaseFileDetails

Verificar o status do trabalho

ID da operação:: CheckJobStatus

Recupera o status atual de um trabalho assíncrono fornecendo o trabalho UUID e payloadHash. Esse ponto de extremidade é usado para sondar o status de conclusão do trabalho depois de enviar uma solicitação de criação de arquivo de caso. A ação é limitada a 20 solicitações por minuto por combinação uuid-payloadHash.

Parâmetros

Nome	Chave	Obrigatório	Tipo	Description
uuid	uuid	True	uuid	A UUID do trabalho a ser verificado. Isso é retornado quando o trabalho é criado.
payloadHash	payloadHash	True	string	O hash SHA-256 do conteúdo. Isso é retornado quando o trabalho é criado e é usado para verificar a autenticidade da solicitação.

Retornos

Corpo: QueueJob

Definições

JobResponse

Nome	Caminho	Tipo	Description
jobs	jobs	array of Job	Matriz de trabalhos criados (normalmente contém um trabalho)
status	status	string	Status da solicitação de criação de trabalho
mensagem	message	string	Mensagem legível por humanos sobre a criação do trabalho

Trabalho

Nome	Caminho	Tipo	Description
uuid	uuid	uuid	Identificador exclusivo para o trabalho que pode ser usado para verificar o status
uuid	payload.uuid	uuid	UUID do arquivo de caso criado
bundleUuid	payload.bundleUuid	uuid	UUID do pacote que contém o arquivo de caso
etlVersionUuid	payload.etlVersionUuid	uuid	UUID da versão ETL usada para processamento
organizationUuid	payload.organizationUuid	uuid	UUID da organização que possui esse arquivo de caso
customData	payload.customData	object	Metadados adicionais e contexto para o trabalho
createdAt	createdAt	date-time	Carimbo de data/hora ISO 8601 quando o trabalho foi criado
payloadHash	payloadHash	string	Hash SHA-256 do conteúdo, usado para verificação ao verificar o status do trabalho

QueueJob

Nome	Caminho	Tipo	Description
tipo	type	string	O tipo do trabalho de fila (por exemplo, 'casefile_creation')
uuid	uuid	uuid	Identificador exclusivo para o trabalho
Resultado	result	object	O resultado da execução do trabalho de fila, retornado como JSON quando o trabalho é concluído. Contém o resultado e quaisquer dados relevantes.
jobStatus	jobStatus	string	Status atual do trabalho. Valores possíveis 'pendentes' (aguardando para serem processados), 'processamento' (atualmente sendo executado), 'concluído' (concluído com êxito), 'falha' (falha na execução), 'aborted_duplicated' (anulado devido à duplicação)
conteúdo	payload	object	O conteúdo original enviado com o trabalho, armazenado como JSON. Contém os dados e metadados do arquivo de caso.
Tentativas	retries	integer	O número de vezes que o trabalho foi repetido após uma falha
createdAt	createdAt	date-time	A data e a hora em que o trabalho de fila foi criado
updatedAt	updatedAt	date-time	A data e a hora em que o trabalho da fila foi atualizado pela última vez
maxRetries	maxRetries	integer	O número máximo de tentativas permitidas para este trabalho antes de ser marcado como com falha
payloadHash	payloadHash	string	Hash SHA-256 do conteúdo, usado para fins de verificação e segurança
errorMessage	errorMessage	string	Mensagem de erro que descreve por que o trabalho falhou, se aplicável. Só está presente quando jobStatus está 'com falha'.

CcRecipient

Nome	Caminho	Tipo	Description
name	name	string	Nome do destinatário
email	email	email	Email do destinatário

CaseFileDetails

Detalhes de um arquivo de caso recuperado do arquivo seguro penneo.

Nome	Caminho	Tipo	Description
userId	userId	integer	ID do usuário que possui o arquivo de caso.
customerId	customerId	integer	ID do cliente à qual o arquivo de caso pertence.
Signatários	signers	array of SignerDetails	Lista de signatários no arquivo de caso.
ID	id	integer	A ID do arquivo de caso.
title	title	string	O título do arquivo de caso.
status	status	integer	O status do arquivo de caso.
Documentos	documents	array of DocumentDetails	Lista de documentos no arquivo de caso.
expireAt	expireAt	integer	Carimbo de data/hora UNIX quando o arquivo de caso expira.
ccRecipients	ccRecipients	array of CcRecipient	Lista de destinatários CC que recebem uma cópia dos documentos assinados.
criado	created	integer	Carimbo de data/hora UNIX quando o arquivo de caso foi criado.
ativada	activated	integer	Carimbo de data/hora UNIX quando o arquivo de caso foi ativado.
atualizado	updated	integer	Carimbo de data/hora UNIX quando o arquivo de caso foi atualizado pela última vez.
concluído	completed	integer	Carimbo de data/hora UNIX quando o arquivo de caso foi concluído.

SignerDetails

Um signatário em um arquivo de caso.

Nome	Caminho	Tipo	Description
name	name	string	Nome do signatário.
ID	id	integer	A ID do signatário.
signingRequest	signingRequest	SigningRequestDetails	A solicitação de assinatura associada a um signatário.

SigningRequestDetails

A solicitação de assinatura associada a um signatário.

Nome	Caminho	Tipo	Description
ID	id	integer	A ID da solicitação de assinatura.
email	email	string	Email do signatário.
status	status	integer	O status da solicitação de assinatura.

DocumentDetails

Um documento em um arquivo de caso.

Nome	Caminho	Tipo	Description
ID	id	integer	A ID do documento. Use isso para baixar o documento com a ação "Baixar documento".
status	status	integer	O status do documento.
conectável	signable	boolean	True se o documento estiver com sinal.

Documentcontent

Nome	Caminho	Tipo	Description
Conteúdo do Documento	content	byte	Conteúdo codificado em Base64 do documento.