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/#/authO 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/validateAPI: SignIntegration
POST: /v3/assinaturas/sem-cadastro
POST: /v2/assinaturas/rejeitar-sem-cadastroPara 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.appURL BASE PRODUÇÃO:
https://totvssign.totvs.appReforç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/listRegistrar usuário:
POST /api/users/registerLogin (gerar token jwt/jwe):
POST /v2/auth/loginSwagger:
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/publicacoesobs:
¹ 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-listRemover destinatários em uma publicação já enviada:
DELETE /v2/publicacoes/destinatarioReenviar e-mails para destinatários pendentes:
POST /v2/Publicacoes/reenvia-email-pendentesAssinar eletronicamente/testemunhar um documento via integração:
POST /v2/assinaturasRejeitar um documento via integração:
POST /v2/assinaturas/rejeitarSwagger:
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/uploadobs: ¹ 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/pesquisasObter informações de uma publicação específica :
GET /v2/publicacoes/{id}Download por tipo:
GET /v1/publicacoes/{id}/downloadobs: :
¹ 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