Introdução

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

🚧

Pré-requisitos

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

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

Dados:
Nome da empresa:
CNPJ (SEM PONTOS/TRAÇOS):
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.

Importante!!

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 verificação de código (sem cadastro).

Para utilizar as rotas relacionadas à autenticação por verificação de código (Assinatura sem cadastro) é necessário cadastrar o seu produto/sistema para que seja gerado um ApplicationId, que deverá 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, basta 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 JWE;
2- Upload de documentos na API Documents, necessário enviar o Token gerado;
3- Criação da publicação na API Documents, necessário informar o ID do documento retornado no processo anterior e o Token JWE.
4- Listagem de publicações e downloads na API Documents, necessário informar o ID do documento e o Token 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 jwe):
POST /v2/auth/login

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

👍

Documents (Publicação de documentos e download)

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.

Publicar documento
POST: /v1/publicacoes

Obs:
¹ Ao criar a publicação, os participantes serão notificados de acordo com a definição do autor.
² É 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, dentre outras.

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

👍

SignIntegration (Assinatura de documentos e seus participantes)

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

Remover destinatários de 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

📘

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