Penneo Sign Sandbox (Pré-visualização)

A Penneo transforma processos complexos numa experiência fluida e centrada no ser humano. Ao integrar assinaturas digitais em fluxos de trabalho automatizados, a nossa plataforma torna fácil validar quem aprovou que dados e quando, reduzindo os encargos administrativos e garantindo total conformidade e segurança. Este conector permite-lhe enviar documentos para assinatura.

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

Serviço	Class	Regions
Estúdio Copiloto	Premium	Todas as regiões Power Automate exceto as seguintes: - Governo dos EUA (CCG) - Governo dos EUA (GCC High) - China Cloud operado pela 21Vianet - Departamento de Defesa dos EUA (DoD)
Aplicações Lógicas	Standard	Todas as regiões do Logic Apps , exceto as seguintes: - Regiões Azure Government - Regiões Azure China - Departamento de Defesa dos EUA (DoD)
Power Apps	Premium	Todas as regiões Power Apps exceto as seguintes: - Governo dos EUA (CCG) - 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 (CCG) - Governo dos EUA (GCC High) - China Cloud operado pela 21Vianet - Departamento de Defesa dos EUA (DoD)

Contact
Nome	Apoio à Penneo
URL	https://www.support.penneo.com

Metadados do conector
Editora	Integração Penneo
origem	Swagger
Sítio Web	https://penneo.com
Política de privacidade	https://penneo.com/privacy-policy
Categorias	Productivity

Penneo Sign Sandbox

Pré-requisitos

Para usar este conector, vai precisar de uma conta Penneo Sandbox ativa.

Ações Suportadas

Criar um novo processo

Cria um novo processo em Penneo com os documentos e signatários especificados. O ficheiro de caso será criado em Penneo, e um UUID e um Hash de payload serão devolvidos que poderão ser usados para verificar o estado de criação através do endpoint de estado da fila.

Verificar o estado da tarefa

Recupera o estado atual de um ficheiro de caso fornecendo o UUID do trabalho e o Hash do payload. Este endpoint é usado para consultar o estado de conclusão de trabalho após submeter um pedido de criação de ficheiro de caso. O endpoint está limitado a 20 pedidos por minuto por combinação uuid-payloadHash.

Obtenha detalhes do processo

Recupera os detalhes de um processo específico da Penneo com base no ID do processo. Isto inclui os seus signatários, documentos e o estado atual.

Descarregar documento

Descarrega o conteúdo de um documento do Penneo como uma string codificada base64. Por defeito, a versão assinada do documento é devolvida; Use o signed parâmetro para obter a versão sem assinatura em vez disso. Se o seu processo incluir mais documentos, certifique-se de fazer um loop por cima de cada documento.

Obtenção de credenciais

O conector foi configurado para usar OAuth com Concessão de Código de Autorização. Os utilizadores terão de iniciar sessão com as suas credenciais habituais quando usarem o conector.

Introdução

Criação de um Processo

Prepare os Seus Documentos:
- Converta os seus documentos PDF para codificação base64
- Garantir que os documentos são ficheiros PDF válidos
Configurar os Signatários:
- Forneça o nome do signatário e o email (obrigatório)
- Opcionalmente, forneça o cargo, a língua, a ordem de assinatura, etc.
- Configure notificações de email e modelos personalizados de email, se necessário
Crie o Ficheiro do Caso:
- Use a ação "Criar um novo processo"
- Preencha os detalhes do processo:
  - Título
  - Documentos (PDFs codificados base64)
  - Signatários (com nomes e detalhes opcionais)
  - Definições opcionais (expiração, idioma, visibilidade, etc.)
Verifique o estado da criação do CaseFile:
- Depois de criar um ficheiro de caso, receberá um UUID e um payloadHash
- Use a ação "Verificar o estado do trabalho" para consultar a conclusão do trabalho
- Respeite o limite de taxa de 20 pedidos por minuto por combinação uuid-hash

Nota: Pode verificar o que cada campo faz verificando https://penneo.readme.io/reference/createcasefile.

Recuperação de um Processo e dos seus Documentos

Obtenha os detalhes do processo:
- Use a ação "Obter detalhes do processo de processo" com o ID do processo
- A resposta inclui o estado do processo, os signatários e a lista de documentos (com os seus IDs de documentos)
Descarregue um documento:
- Use a ação "Descarregar documento" com o ID do documento obtido a partir dos detalhes do processo
- A resposta contém o conteúdo do documento como uma cadeia codificada base64, que pode decodificar para recuperar o ficheiro PDF

Problemas conhecidos e limitações

Limitação de Taxa: O endpoint Check job status está limitado a 20 pedidos por minuto por combinação uuid-hash. Implemente lógica de retentativa apropriada com retrocesso exponencial.
Processamento Assíncrono: A criação de ficheiros de caso é assíncrona. Deve usar o endpoint de estado do trabalho para verificar a conclusão em vez de esperar resultados imediatos.
Codificação Base64: Os documentos devem ser codificados em base64. Assegure a codificação correta para evitar falhas de pedido (pode usar a função base64 string na Power Platform para codificar os ficheiros PDF binários).
Ambiente Sandbox: Este conector está configurado para o ambiente sandbox Penneo (sandbox.penneo.com).
Tamanho do Documento: Documentos grandes podem demorar mais tempo a processar. 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

Limites de Limitação

Name	Chamadas	Período de Renovação
Chamadas de API por conexão	100	60 segundos

Ações

Criar um novo processo	Cria um novo processo em Penneo com os documentos e signatários especificados. O ficheiro de caso será criado de forma assíncrona, e serão devolvidos um UUID de trabalho e um payloadHash que podem ser usados para verificar o estado de criação através da ação Verificar o estado do trabalho. Pode configurar signatários, documentos, ordem de assinatura, notificações por email, controlo de acesso e várias outras definições de ficheiros de caso.
Descarregar documento	Descarrega o conteúdo de um documento da Penneo como uma cadeia codificada base64. Por defeito, a versão assinada do documento é devolvida.
Obtenha detalhes do processo	Recupera os detalhes de um processo específico da Penneo, incluindo os seus signatários, documentos e o estado atual. Estado dos processos: 0=novo, 1=pendente, 2=rejeitado, 3=eliminado, 4=assinado, 5=concluído, 6=falhado, 7=expirado, 8=anonimizado. Use o estado 5 (concluído) como gatilho para descarregar os documentos assinados.
Verificar o estado da tarefa	Recupera o estado atual de um trabalho assíncrono fornecendo o UUID do trabalho e o Hash do payload. Este endpoint é usado para consultar o estado de conclusão de trabalho após submeter um pedido de criação de ficheiro de caso. A ação está limitada a 20 pedidos por minuto por combinação uuid-payloadHash.

Criar um novo processo

ID da Operação:: CreateCaseFile

Cria um novo processo em Penneo com os documentos e signatários especificados. O ficheiro de caso será criado de forma assíncrona, e serão devolvidos um UUID de trabalho e um payloadHash que podem ser usados para verificar o estado de criação através da ação Verificar o estado do trabalho. Pode configurar signatários, documentos, ordem de assinatura, notificações por email, controlo de acesso e várias outras definições de ficheiros de caso.

Parâmetros

Name	Chave	Obrigatório	Tipo	Descrição
título	title	True	string	O título do processo.
sendAt	sendAt		integer	Carimbo temporal em que o processo deve ser enviado. Nulo = imediatamente
name	name	True	string	Nome do signatário
função	role		string	Papel para quem assina. Permitidos: letras, números, espaços, vírgula, sublinhado, hífen. Deve começar com uma letra/número e não pode terminar com um espaço.
e-mail	email		email	Email do signatário. A Penneo tratará de todas as comunicações
failUrl	failUrl		uri	URL de redirecionamento após falha
linguagem	language		string	Língua gestual
emailTexto	emailText		string	Texto personalizado para o email de pedido de assinatura. Se não for fornecido, o modelo da empresa é predefinido.
signOrder	signOrder		integer	A ordem de assinatura. 0 significa sem ordem imposta.
successUrl	successUrl		uri	URL de redirecionar após sucesso
emailAssunto	emailSubject		string	Assunto do email de pedido de assinatura. Se não for fornecido, o modelo da empresa é predefinido.
reminderIntervalo	reminderInterval		integer	Dias antes de ser enviado o lembrete
lembreteEmailTexto	reminderEmailText		string	Texto personalizado para o email de lembrete. Se não for fornecido, o modelo da empresa é predefinido.
completadoTexto de Email	completedEmailText		string	Texto personalizado para o email completo. Se não for fornecido, o modelo da empresa é predefinido.
recordaçãoEmailAssunto	reminderEmailSubject		string	Sujeito do email de lembrete. Se não for fornecido, o modelo da empresa é predefinido.
completadoAssunto do Email	completedEmailSubject		string	Assunto do email completo. Se não for fornecido, o modelo da empresa é predefinido.
enableInsecureSigning	enableInsecureSigning		boolean	Se for verdade, o signatário pode usar assinaturas táteis (desenho, texto, upload de imagem)
insecureSigningMethods	insecureSigningMethods		array of string	Permitiam métodos de assinatura inseguros. Por defeito a configuração da empresa se estiver vazia.
Métodos de Assinatura Segura	secureSigningMethods		array of string	Permitiam métodos de assinatura eletrónica segura. Anula as definições do ficheiro do caso e do cliente quando definidas.
Vatin.	vatin		string	Número de identificação do IVA da empresa do signatário
ssnType	ssnType		string	Tipo de SSN/telemóvel. Exemplo de 'dk:cpr', 'se:pin', 'no:nin', 'be:nrn', 'fi:pic' ou 'sms'. Por defeito, é 'legado'
activeAt	activeAt		integer	Carimbo temporal de ativação
expireAt	expireAt		integer	Carimbo temporal de expiração
Controlo de Acesso	accessControl		boolean	Se ativado, o SSN/VATIN/telefone é validado antes do acesso
emailFormato	emailFormat		string	Define o formato do email
em Nome deDe	onBehalfOf		string	A empresa/organização por quem este signatário assina em nome
storeAsContact	storeAsContact		boolean	Se for verdade, o signatário será armazenado como contacto em Penneo
NúmeroDeSegurança SocialPlain	socialSecurityNumberPlain		string	O número de SSN ou telefone do signatário (recomenda-se o formato E.164)
expireAt	expireAt		integer	Marca a data de expiração do processo do processo. Se não for fornecida, aplicam-se os incumprimentos
linguagem	language		string	A linguagem do ficheiro de caso será aplicada a todos os signatários que não tenham um conjunto de linguagem
PDF	pdf	True	string	PDF codificado em Base64
assinavel	signable		boolean	O True cria um documento assinável. Falso, o documento é adicionado como anexo e não pode ser assinado.
roles	roles		array of string	Os papéis de signatário autorizados a assinar este documento. Por defeito, todos os signatários se estiverem vazios.
título	title	True	string	O título do documento
documentOrder	documentOrder		integer	A ordem de assinatura do documento. Ordem padrão fornecida.
metadados	metaData		string	Metadados do documento, pesquisáveis em Penneo
sensitiveData	sensitiveData		boolean	Se for verdade, os signatários devem validar a sua identidade antes de aceder aos documentos. Desativa anexos de e-mail para documentos assinados.
signOnMeeting	signOnMeeting		boolean	Especifica se os documentos devem ser assinados durante uma reunião.
Modo de visibilidade	visibilityMode		integer	0 = Os signatários veem todos os documentos. 1 = Os signatários veem apenas os documentos que precisam de assinar.
disableEmailAnexos	disableEmailAttachments		boolean	Desativa anexos de e-mail para documentos assinados nos emails de finalização. Anulado se sensitiveData for verdadeiro.
disableNotificationsOwner	disableNotificationsOwner		boolean	Se for verdade, o proprietário do processo não receberá notificações para o processo.
folderId	folderId		integer	O ID da pasta onde queres colocar o teu ficheiro de caso
metadados	metaData		string	Metadados do processo, pesquisáveis em Penneo
referenciar	reference		string	A referência do processo será apresentada na aplicação web Penneo
name	name	True	string	Nome do destinatário
e-mail	email	True	email	E-mail do destinatário

Devoluções

Body: JobResponse

Descarregar documento

ID da Operação:: DownloadDocument

Descarrega o conteúdo de um documento da Penneo como uma cadeia codificada base64. Por defeito, a versão assinada do documento é devolvida.

Parâmetros

Name	Chave	Obrigatório	Tipo	Descrição
ID do documento	documentId	True	integer	O ID do documento para descarregar. Recupere os documentIds com a ação "Obter detalhes do processo do processo".
Assinatura	signed		boolean	Obtenha o documento assinado ou não assinado. Por defeito, o documento assinado é devolvido se já tiver sido assinado.

Devoluções

Body: DocumentContent

Obtenha detalhes do processo

ID da Operação:: GetCaseFileDetails

Recupera os detalhes de um processo específico da Penneo, incluindo os seus signatários, documentos e o estado atual. Estado dos processos: 0=novo, 1=pendente, 2=rejeitado, 3=eliminado, 4=assinado, 5=concluído, 6=falhado, 7=expirado, 8=anonimizado. Use o estado 5 (concluído) como gatilho para descarregar os documentos assinados.

Parâmetros

Name	Chave	Obrigatório	Tipo	Descrição
ID do Processo	caseFileId	True	integer	O ID do processo a recuperar. Recupere o ID do processo com a ação "Verificar o estado do trabalho".

Devoluções

Detalhes de um processo recuperado do arquivo seguro da Penneo.

Body: CaseFileDetails

Verificar o estado da tarefa

ID da Operação:: CheckJobStatus

Recupera o estado atual de um trabalho assíncrono fornecendo o UUID do trabalho e o Hash do payload. Este endpoint é usado para consultar o estado de conclusão de trabalho após submeter um pedido de criação de ficheiro de caso. A ação está limitada a 20 pedidos por minuto por combinação uuid-payloadHash.

Parâmetros

Name	Chave	Obrigatório	Tipo	Descrição
uuid	uuid	True	uuid	O UUID do trabalho para verificar. Este é devolvido quando o emprego é criado.
payloadHash	payloadHash	True	string	O hash SHA-256 da carga útil. Este é devolvido quando o trabalho é criado e é usado para verificar a autenticidade do pedido.

Devoluções

Body: QueueJob

Definições

JobResponse

Name	Caminho	Tipo	Descrição
jobs	jobs	array of Job	Array de empregos criados (normalmente contém um trabalho)
estado	status	string	Estado do pedido de criação de emprego
mensagem	message	string	Mensagem legível para humanos sobre a criação de emprego

Job

Name	Caminho	Tipo	Descrição
uuid	uuid	uuid	Identificador único para o trabalho que pode ser usado para verificar o estado
uuid	payload.uuid	uuid	UUID do ficheiro de caso criado
bundleUuid	payload.bundleUuid	uuid	UUID do fibrado que contém o ficheiro de caso
etlVersionUuid	payload.etlVersionUuid	uuid	UUID da versão ETL usada para processamento
organizationUuid	payload.organizationUuid	uuid	UUID da organização que detém este processo
customData	payload.customData	object	Metadados adicionais e contexto para o trabalho
createdAt	createdAt	date-time	Carimbo temporal ISO 8601 quando o trabalho foi criado
payloadHash	payloadHash	string	SHA-256 hash da carga útil, usado para verificação ao verificar o estado do trabalho

QueueJob

Name	Caminho	Tipo	Descrição
tipo	type	string	O tipo do trabalho de fila (por exemplo, 'casefile_creation')
uuid	uuid	uuid	Identificador único para o cargo
result	result	object	O resultado da execução do trabalho na fila é devolvido como JSON quando o trabalho é concluído. Contém o resultado e quaisquer dados relevantes.
situação do emprego	jobStatus	string	Situação atual do trabalho. Valores possíveis 'pendentes' (à espera de serem processados), 'processing' (atualmente em execução), 'completado' (concluído com sucesso), 'failed' (execução falhada), 'aborted_duplicated' (abortado devido a duplicação)
payload	payload	object	A carga útil original submetida com o trabalho, armazenada como JSON. Contém os dados e metadados do ficheiro do caso.
tentativas	retries	integer	O número de vezes que o trabalho foi tentado novamente após um fracasso
createdAt	createdAt	date-time	A data e hora em que o trabalho de fila foi criado
atualizadoem	updatedAt	date-time	A data e hora em que o trabalho da fila foi atualizado pela última vez
maxRetries	maxRetries	integer	O número máximo de tentativas permitido para esta tarefa antes de ser marcada como falhada
payloadHash	payloadHash	string	SHA-256 hash da carga útil, usado para verificação e segurança
errorMessage	errorMessage	string	Mensagem de erro a descrever porque é que o trabalho falhou, se aplicável. Só está presente quando o estado do emprego está 'falhado'.

CcRecipient

Name	Caminho	Tipo	Descrição
name	name	string	Nome do destinatário
e-mail	email	email	E-mail do destinatário

CaseFileDetails

Detalhes de um processo recuperado do arquivo seguro da Penneo.

Name	Caminho	Tipo	Descrição
userId	userId	integer	ID do utilizador que detém o processo de processo.
ID do cliente	customerId	integer	ID do cliente a quem pertence o processo.
signatários	signers	array of SignerDetails	Lista de signatários no processo.
id	id	integer	O ID do processo.
título	title	string	O título do processo.
estado	status	integer	O estado do processo.
Documentação	documents	array of DocumentDetails	Lista de documentos no processo.
expireAt	expireAt	integer	Carimbo temporal do UNIX quando o ficheiro do caso expira.
ccDestinatários	ccRecipients	array of CcRecipient	Lista de beneficiários de CC que recebem uma cópia dos documentos assinados.
criado	created	integer	Carimbo temporal do UNIX quando o ficheiro de caso foi criado.
ativado	activated	integer	Carimbo temporal UNIX quando o ficheiro de caso foi ativado.
atualizado	updated	integer	Carimbo temporal do UNIX quando o ficheiro do caso foi atualizado pela última vez.
concluída	completed	integer	Carimbo temporal UNIX quando o ficheiro de caso estava concluído.

SignerDetails

Um signatário num processo.

Name	Caminho	Tipo	Descrição
name	name	string	Nome do signatário.
id	id	integer	O ID do signatário.
assinaturaPedido	signingRequest	SigningRequestDetails	O pedido de assinatura associado a um signatário.

Pedidos de assinaturaDetalhes

O pedido de assinatura associado a um signatário.

Name	Caminho	Tipo	Descrição
id	id	integer	O ID do pedido de assinatura.
e-mail	email	string	Email do signatário.
estado	status	integer	O estado do pedido de assinatura.

DocumentDetalhes

Um documento num processo de processo.

Name	Caminho	Tipo	Descrição
id	id	integer	O ID do documento. Use isto para descarregar o documento com a ação "Download document".
estado	status	integer	O estado do documento.
assinavel	signable	boolean	É verdade se o documento for assinável.

DocumentContent

Name	Caminho	Tipo	Descrição
Conteúdo do documento	content	byte	Base64 codificava o conteúdo do documento.