Introdução

Bem vindo à documentação da API de integração do TOTVS Assinatura Eletrônica. Aqui nós descrevemos como integrar ao TOTVS Assinatura Eletrônica.

🚧

Pré-requisitos

Provisionar uma empresa no ambiente de homologação, basta enviar os dados abaixo para o email: [email protected]

Assunto: Provisionar empresa no ambiente de homologação para iniciar integração

Dados:
Nome da empresa:
CNPJ:
Nome do solicitante:
Email do solicitante:

Ao provisionar o ambiente o usuário acima receberá um e-mail com o acesso de administrador na plataforma:
https://totvssign.staging.totvs.app/webapptotvssign/#/auth

O ambiente de homologação é liberado por um período de 60 dias, mediante a solicitação do cliente. Caso seja necessário um prazo maior para algum teste ou homologação, basta solicitar a prorrogação pelo e-mail mencionado acima.

Obs: No ambiente de homologação são testadas diariamente novas funcionalidades e correções pelo time de desenvolvimento do TAE. Devido a isso, o ambiente pode ficar instável / lento / indisponível sem aviso prévio.

🚧

Cadastro de ApplicationId para integrações que irão implementar assinaturas de documentos dentro do software integrador, utilizando autenticação por envio de código por email (sem cadastro).

Para utilizar as rotas relacionadas à autenticação por envio de código (Assinatura sem cadastro) é necessário cadastrar o seu produto/sistema para que seja gerado um ApplicationId que será informado no Header das rotas abaixo:

API: IdentityIntegration
POST: /v1/verification-code/send
POST: /v1/verification-code/validate

API: SignIntegration
POST: /v3/assinaturas/sem-cadastro
POST: /v2/assinaturas/rejeitar-sem-cadastro

Para solicitar o cadastro envie um e-mail para: [email protected]
Assunto: Cadastrar Integração para uso de Assinatura sem cadastro (Gerar ApplicationId)

Dados:
Integração nativa TOTVS? [ ] Sim ou [ ] Não
Qual sistema integrador?
CNPJ da empresa provisionada no TAE:
Ambiente: [ ] Homologação-Staging ou [ ] Produção

📘

Como fazer a virada de chave de Homologação para Produção

Após realizar o desenvolvimento e homologação, pasta alterar o link das apis para apontar para o ambiente de produção.

URL BASE HOMOLOGAÇÂO:
https://totvssign.staging.totvs.app

URL BASE PRODUÇÃO:
https://totvssign.totvs.app

Reforçando que, obviamente as bases de dados são diferentes. Então os dados/documentos gerados durante os testes não serão encontrados no ambiente produtivo.

Para provisionar um trial em ambiente produtivo basta o responsável pela empresa, preencher o formulário de criação de conta de empresa no link: https://www.totvs.com/assinatura-eletronica/
O provisionamento é feito automaticamente.

📘

Fluxo base do sistema:

1- Autenticação na API IdentityIntegration gerando Token JWT/JWE
2- Upload de documentos na API Documents, necessário enviar o Token JWT/JWE
3- Criação da publicação no SignIntegration, necessário informar o ID do documento retornado pelo documents e o Token JWT/JWE.
4- Listagem de publicações e downloads no Documents, necessário informar o ID do documento e o Token JWT/JWE.

No link abaixo, temos exemplos de jornadas e fluxos de integrações (diagramas)

https://totvs-sign.readme.io/reference/jornadas

Segue abaixo resumo das principais rotas utilizadas no sistema

👍

IdentityIntegration (Gestão de usuários e autenticação)

Listar empresas provisionadas pelo domínio do e-mail do usuário a ser cadastrado:
GET /api/companies/list

Registrar usuário:
POST /api/users/register

Login (gerar token jwt/jwe):
POST /v2/auth/login

Swagger:
https://totvssign.staging.totvs.app/identityintegration/swagger/index.html

👍

Sign (Envio de envelope e assinaturas): (autenticação necessária com token jwt/jwe)

Enviar envelope
POST /v2/publicacoes

obs:
¹ Ao criar a publicação, os destinatários vão receber um e-mail para se cadastrar na plataforma. E assim visualizar e assinar o documento.
² Ao criar uma publicação é possível incluir a assinatura do autor automaticamente.
³ Ao criar uma publicação é possível definir opções para a publicação: solicitar assinatura manuscrita, definir data de expiração, personalizar assunto e mensagem do e-mail a ser enviado.

Adicionar destinatários em uma publicação já enviada:
POST /v2/publicacoes/destinatario-list

Remover destinatários em uma publicação já enviada:
DELETE /v2/publicacoes/destinatario

Reenviar e-mails para destinatários pendentes:
POST /v2/Publicacoes/reenvia-email-pendentes

Assinar eletronicamente/testemunhar um documento via integração:
POST /v2/assinaturas

Rejeitar um documento via integração:
POST /v2/assinaturas/rejeitar

Swagger:
https://totvssign.staging.totvs.app/signintegration/swagger/index.html?urls.primaryName=V2

👍

Documents (Listagem de publicações e Download): (autenticação necessária com token jwt/jwe)

Upload de arquivos
POST: /v1/envelopes/upload

obs: ¹ A rota aceita uma lista de arquivos (.doc, .docx ou .pdf). Caso envie mais de um na requisição eles serão unidos em um único arquivo.

Listar todas as publicações que o usuário realizou ou participa (com possibilidade de usar filtros):
POST /v4/publicacoes/pesquisas

Obter informações de uma publicação específica :
GET /v2/publicacoes/{id}

Download por tipo:
GET /v1/publicacoes/{id}/download

obs: :
¹ Tipos de download:
[Documento Original] = 1 ,
[Assinado (documento original com manifesto de assinaturas)] = 2,
[Assinado Digital (Documento com assinaturas com certificado digital)] = 3,
[Baixar todos (Zip com todos)] = 4.

Swagger:
https://totvssign.staging.totvs.app/documents/swagger/index.html

📘

Outros recursos

Confira os outros recursos disponíveis na lateral esquerda. Caso queira sugerir um novo recurso utilize a central colaborativa TOTVS:

https://centraldeatendimento.totvs.com/hc/pt-br/articles/360039467434-Central-Colaborativa-Como-Acessar

Segmento CROSS -> Assinatura Eletronica