Passar para o conteúdo principal

API Assertiva Assinaturas

Escrito por Alex Bruno Machado

A API Assertiva Assinaturas permite criar, acompanhar e gerenciar processos de assinatura eletrônica de documentos. Por meio da API, é possível:

  • Enviar documentos para assinatura;

  • Cadastrar signatários;

  • Definir a ordem de assinatura;

  • Enviar links por e-mail ou SMS;

  • Consultar o status de envelopes;

  • Reenviar links de assinatura;

  • Cancelar envelopes;

  • Baixar documentos assinados;

  • Consultar e editar signatários;

  • Gerar relatórios de solicitações.

A integração deve ser realizada por uma equipe técnica. A documentação completa está disponível na https://integracao.assertivasolucoes.com.br/v3/portal

1. URL base

As requisições da API Assinaturas devem utilizar a seguinte URL base:

https://api.assertivasolucoes.com.br/autentica-assinaturas

Os endpoints são disponibilizados sob o caminho /v1.

Exemplo:

https://api.assertivasolucoes.com.br/autentica-assinaturas/v1/envelopes

2. Autenticação

Todos os endpoints da API Assinaturas exigem autenticação por meio de um token enviado no cabeçalho Authorization.

O token deve ser enviado no seguinte formato:

Authorization: Bearer SEU_TOKEN_DE_ACESSO

2.1 Obtenção do token

O token é gerado utilizando as credenciais da API:

  • Client ID

  • Secret

A geração deve utilizar o fluxo OAuth 2.0 client_credentials.

O procedimento detalhado está disponível no artigo Como gerar credenciais e token de acesso para as APIs da Assertiva.

2.2 Cabeçalhos recomendados

Para requisições JSON:

Cabeçalho

Valor

Authorization

Bearer SEU_TOKEN_DE_ACESSO

Content-Type

application/json

Accept

application/json

O token deve ser armazenado de forma segura. Nunca o exponha no código do front-end, em repositórios públicos ou em logs.

3. Fluxo de uma assinatura

O processo de assinatura normalmente segue estas etapas:

  1. Solicitar um link temporário para upload do documento.

  2. Fazer o upload do arquivo PDF utilizando o link recebido.

  3. Criar um envelope com o documento e os signatários.

  4. Enviar o link de assinatura aos signatários.

  5. Consultar o status do envelope.

  6. Aguardar a finalização das assinaturas.

  7. Obter os links temporários dos documentos assinados.

  8. Fazer o download dos documentos e, se necessário, do documento de auditoria.

4. Upload de documentos

Antes de criar o envelope, é necessário obter um link temporário para enviar o arquivo PDF.

4.1 Obter link temporário para upload

Método: GET

Endpoint:

/v1/documentos/obter-link-upload-temporario

URL completa:

https://api.assertivasolucoes.com.br/autentica-assinaturas/v1/documentos/obter-link-upload-temporario

Parâmetro

Parâmetro

Obrigatório

Descrição

quantidadeLinks

Não

Quantidade de links temporários desejada. Caso não seja informado, será gerado um link.

Exemplo

GET /v1/documentos/obter-link-upload-temporario?quantidadeLinks=1

Resposta esperada

A API retorna uma lista de links temporários. Cada link possui:

  • url: URL utilizada para upload;

  • chave: identificador do arquivo que será utilizado posteriormente na criação do envelope.

Exemplo:

{ "status": 200, "success": true, "data": { "links": [ { "url": "https://url-temporaria-de-upload", "chave": "00000000-0000-0000-0000-000000000000" } ] } }

4.2 Enviar o PDF

Após obter a URL temporária, faça o upload do arquivo utilizando:

  • Método: PUT

  • Content-Type: application/application-pdf

O arquivo deve ser enviado diretamente para a URL retornada pela API.

A URL de upload é temporária. Realize o envio imediatamente após sua obtenção.

A chave retornada deverá ser informada no campo chave ao criar o envelope.

5. Criar um envelope

Um envelope representa uma solicitação de assinatura. Ele pode conter um ou mais documentos e signatários.

5.1 Endpoint

Método: POST

Endpoint:

/v1/envelopes

URL completa:

https://api.assertivasolucoes.com.br/autentica-assinaturas/v1/envelopes

5.2 Estrutura da requisição

Campo

Obrigatório

Descrição

nome

Sim

Nome do envelope. Não é permitido criar mais de um envelope com o mesmo nome.

signatarios

Sim

Lista de pessoas que deverão assinar os documentos.

documentos

Sim

Lista de documentos que farão parte do envelope.

Limite de documentos

O tamanho total dos documentos enviados para o envelope deve ser de até 30 MB.

5.3 Estrutura do documento

Cada documento deve conter:

Campo

Obrigatório

Descrição

nome

Sim

Nome do arquivo, normalmente com a extensão .pdf.

chave

Sim

Chave retornada no upload temporário do documento.

5.4 Estrutura do signatário

Cada signatário deve conter:

Campo

Obrigatório

Descrição

nome

Sim

Nome completo do signatário.

documento

Sim

CPF ou CNPJ do signatário.

email

Sim

E-mail do signatário.

celular

Condicional

Número do celular com DDD. Obrigatório quando a forma de envio for SMS.

perfilAssinatura

Sim

Papel do signatário no processo.

formaEnvio

Sim

Forma de envio do link: email ou sms.

prioridade

Sim

Ordem de envio e assinatura.

Regras dos documentos

  • CPF deve ser informado com 11 dígitos numéricos.

  • CNPJ pode conter até 14 caracteres alfanuméricos, conforme a documentação.

  • O celular deve ser informado somente com números.

  • Não é permitido mais de um signatário com o mesmo documento.

  • A prioridade define a ordem de envio dos links.

  • O celular é obrigatório quando formaEnvio for sms.

5.5 Perfis de assinatura

Os perfis disponíveis são:

  • contratada;

  • contratante;

  • testemunha;

  • exequente;

  • exequido;

  • locador;

  • locatario;

  • fiador.

5.6 Formas de envio

A API aceita duas formas de envio:

Valor

Descrição

email

O link de assinatura será enviado por e-mail.

sms

O link de assinatura será enviado por SMS.

5.7 Exemplo de criação de envelope

{ "nome": "Contrato de prestação de serviços", "signatarios": [ { "nome": "João da Silva", "documento": "12345678901", "celular": "11999999999", "email": "joao@exemplo.com.br", "perfilAssinatura": "contratante", "formaEnvio": "email", "prioridade": 1 }, { "nome": "Maria de Souza", "documento": "98765432100", "celular": "11988888888", "email": "maria@exemplo.com.br", "perfilAssinatura": "contratada", "formaEnvio": "email", "prioridade": 2 } ], "documentos": [ { "nome": "contrato.pdf", "chave": "00000000-0000-0000-0000-000000000000" } ] }

Resposta

Em caso de sucesso, a API retorna o identificador do envelope:

{ "status": 201, "success": true, "data": { "id": "00000000-0000-0000-0000-000000000000" } }

Armazene esse identificador, pois ele será utilizado nas consultas e operações posteriores.

6. Consultar um envelope

Permite consultar os dados detalhados de um envelope específico.

Método: GET

Endpoint:

/v1/envelopes/{envelope}

URL completa:

https://api.assertivasolucoes.com.br/autentica-assinaturas/v1/envelopes/{envelope}

Parâmetro

Parâmetro

Localização

Obrigatório

Descrição

envelope

Path

Sim

Identificador do envelope.

Informações retornadas

A resposta pode conter:

  • Nome do envelope;

  • Data de criação;

  • Status atual;

  • Mensagem do status;

  • Total de signatários;

  • Total de assinaturas realizadas;

  • Indicador de permissão para reenviar links;

  • Indicador de permissão para cancelar;

  • Lista de signatários;

  • Lista de documentos.

Status do envelope

Os status podem incluir:

  • emProcesso;

  • finalizado;

  • expirado;

  • cancelado.

7. Filtrar envelopes

Permite localizar envelopes de forma paginada utilizando diferentes filtros.

Método: GET

Endpoint:

/v1/envelopes/filtrar

Parâmetros

Parâmetro

Obrigatório

Descrição

envelope

Não

ID ou nome do envelope.

documento

Não

CPF ou CNPJ do signatário.

idUsuario

Não

ID do usuário ativo da empresa.

email

Não

E-mail do signatário.

criacaoInicio

Não

Data inicial de criação do envelope.

criacaoFim

Não

Data final de criação do envelope.

assinaturaInicio

Não

Data inicial da assinatura.

assinaturaFim

Não

Data final da assinatura.

status

Não

Status do envelope.

index

Sim

Índice da página.

size

Sim

Quantidade de registros por página.

Exemplo

GET /v1/envelopes/filtrar?status=finalizado&index=0&size=10

Estrutura da resposta

A resposta pode conter:

  • envelopes: lista de envelopes;

  • pages: quantidade total de páginas;

  • total: quantidade total de registros.

8. Contar envelopes por status

Retorna a quantidade total de envelopes agrupada por status.

Método: GET

Endpoint:

/v1/envelopes/contador-status

A resposta contém uma lista com:

  • Nome do status;

  • Identificador do status;

  • Quantidade de envelopes.

9. Reenviar link de assinatura

Permite reenviar o link de assinatura para os signatários autorizados por e-mail.

Método: PUT

Endpoint:

/v1/envelopes/{envelope}/reenviar-link

Parâmetro

Parâmetro

Localização

Obrigatório

Descrição

envelope

Path

Sim

Identificador do envelope.

Essa operação deve ser realizada somente quando o envelope permitir o reenvio de links.

10. Cancelar um envelope

Cancela um envelope e seus signatários.

Método: PUT

Endpoint:

/v1/envelopes/{envelope}/cancelar

Parâmetro

Parâmetro

Localização

Obrigatório

Descrição

envelope

Path

Sim

Identificador do envelope.

O cancelamento depende do status atual do envelope e das permissões disponíveis.

11. Links de assinatura dos signatários

11.1 Obter link de assinatura

Permite obter o link de assinatura de um signatário.

Método: GET

Endpoint:

/v1/signatarios/{signatario}/obter-link

Parâmetro

Parâmetro

Localização

Obrigatório

Descrição

signatario

Path

Sim

Identificador do signatário.

Resposta

{ "status": 200, "success": true, "data": { "url": "https://link-de-assinatura" } }

11.2 Reenviar link do signatário

Permite reenviar o link individual de assinatura conforme a forma de envio cadastrada.

Método: PUT

Endpoint:

/v1/signatarios/{signatario}/reenviar-link

12. Consultar perfis de assinatura

Retorna os perfis de assinatura disponíveis para utilização no cadastro de signatários.

Método: GET

Endpoint:

/v1/signatarios/perfis-acesso

A resposta contém:

  • chave: identificador do perfil;

  • valor: descrição do perfil.

13. Consultar signatários

Permite localizar signatários já cadastrados pelo nome.

Método: GET

Endpoint:

/v1/signatarios

Parâmetro

Parâmetro

Obrigatório

Descrição

nome

Sim

Nome utilizado na busca. Deve conter pelo menos três caracteres.

14. Editar um signatário

Permite atualizar os dados de um signatário que ainda não tenha finalizado o processo de assinatura.

Não é permitido editar um signatário cujo status seja finalizado.

Método: PUT

Endpoint:

/v1/signatarios/{signatarioId}

Campos obrigatórios

  • nome;

  • documento;

  • email;

  • perfilAssinatura;

  • formaEnvio.

Exemplo

{ "nome": "João da Silva", "documento": "12345678901", "celular": "11999999999", "email": "novoemail@exemplo.com.br", "perfilAssinatura": "contratante", "formaEnvio": "email" }

15. Documentos assinados

15.1 Obter links dos documentos assinados

Retorna links temporários para download dos documentos relacionados ao envelope.

Método: GET

Endpoint:

/v1/envelopes/{envelope}/links-documentos-assinados

Parâmetros

Parâmetro

Localização

Obrigatório

Descrição

envelope

Path

Sim

Identificador do envelope.

auditoria

Query

Não

Define se o documento de auditoria deverá ser incluído.

A resposta retorna uma lista de links temporários para os documentos assinados e, quando solicitado, para o documento de auditoria.

Os links devem ser utilizados dentro do período de validade informado pela API.

15.2 Obter link de um documento específico

Permite obter o link de um documento individual.

Método: GET

Endpoint:

/v1/envelopes/{envelope}/documentos/{documento}/link-download

Parâmetros

Parâmetro

Localização

Obrigatório

Descrição

envelope

Path

Sim

Identificador do envelope.

documento

Path

Sim

Identificador do documento.

Quando o envelope estiver finalizado, o link retornará o documento assinado. Caso o processo ainda esteja em andamento, poderá ser retornado o documento original.

16. Relatórios

A API permite gerar relatórios de solicitações e consultar o status de processamento.

16.1 Listar tipos de relatório

Método: GET

Endpoint:

/v1/relatorios/tipos

Atualmente, a documentação disponibiliza o tipo de relatório:

  • solicitacoes: relatório de solicitações.

16.2 Listar status de relatório

Método: GET

Endpoint:

/v1/relatorios/status

A resposta retorna os status disponíveis, como:

  • Identificador;

  • Tag;

  • Nome do status.

16.3 Criar uma solicitação de relatório

A geração do relatório ocorre em segundo plano.

Método: POST

Endpoint:

/v1/relatorios

Campos obrigatórios

Campo

Descrição

tipo

Tipo do relatório, como solicitacoes.

dataInicial

Data inicial no formato yyyy-MM-dd.

dataFinal

Data final no formato yyyy-MM-dd.

Exemplo

{ "tipo": "solicitacoes", "dataInicial": "2023-01-01", "dataFinal": "2023-03-31" }

Resposta

A API retorna o identificador do relatório:

{ "status": 201, "success": true, "data": { "id": "00000000-0000-0000-0000-000000000000" } }

16.4 Filtrar relatórios

Método: GET

Endpoint:

/v1/relatorios/filtrar

Parâmetros

Parâmetro

Obrigatório

Descrição

index

Sim

Índice da página.

size

Sim

Quantidade de registros por página.

A resposta pode conter:

  • ID do relatório;

  • Data de extração;

  • Filtros utilizados;

  • Status;

  • Tipo do relatório;

  • Total de páginas;

  • Total de registros.

16.5 Gerar link para download do relatório

Método: GET

Endpoint:

/v1/relatorios/{id}/gerar-link

Parâmetro

Parâmetro

Localização

Obrigatório

Descrição

id

Path

Sim

Identificador do relatório.

O endpoint retorna uma URL temporária para download do arquivo. De acordo com a documentação, essa URL permanece válida por 60 segundos.

17. Formato das respostas

As respostas de sucesso seguem uma estrutura semelhante a:

{ "status": 200, "success": true, "data": {} }

Campos

Campo

Descrição

status

Código HTTP da operação.

success

Indica se a operação foi realizada com sucesso.

data

Dados retornados pela API.

Em respostas de erro, podem ser retornados:

  • status;

  • success;

  • messages: lista de mensagens de erro.

18. Códigos de resposta

A API pode retornar os seguintes códigos:

Código

Significado

Tratamento recomendado

200

Operação realizada com sucesso.

Processar os dados retornados.

201

Recurso criado com sucesso.

Armazenar o ID retornado.

400

Dados ou campos inválidos.

Validar o corpo e os parâmetros da requisição.

401

Usuário não autenticado.

Verificar o token e as credenciais utilizadas.

403

Acesso não autorizado.

Confirmar as permissões da aplicação.

408

Tempo limite de resposta excedido.

Repetir a operação após validar a disponibilidade do serviço.

500

Erro interno do servidor.

Tentar novamente e acionar o suporte se persistir.

503

Serviço indisponível.

Aguardar e realizar nova tentativa.

504

Gateway sem resposta dentro do prazo.

Repetir a requisição posteriormente.

19. Boas práticas de integração

  • Armazene o token de acesso em local seguro.

  • Nunca exponha o Secret ou o token no front-end.

  • Utilize HTTPS em todas as comunicações.

  • Armazene os IDs de envelopes, documentos, signatários e relatórios.

  • Controle a duplicidade de envelopes e signatários.

  • Não crie envelopes com nomes repetidos.

  • Valide CPF, CNPJ, e-mail e celular antes do envio.

  • Envie o celular quando a forma de envio for sms.

  • Controle a prioridade dos signatários.

  • Consulte o status do envelope antes de tentar cancelá-lo ou reenviar links.

  • Não tente editar signatários que já finalizaram a assinatura.

  • Faça o download dos arquivos utilizando imediatamente as URLs temporárias.

  • Não registre documentos, tokens ou dados pessoais completos nos logs.

  • Implemente tratamento específico para erros de autenticação, permissão, indisponibilidade e timeout.

  • Proteja os documentos assinados conforme as políticas internas de segurança e privacidade.

20. Resumo dos principais endpoints

Funcionalidade

Método

Endpoint

Obter link temporário de upload

GET

/v1/documentos/obter-link-upload-temporario

Criar envelope

POST

/v1/envelopes

Filtrar envelopes

GET

/v1/envelopes/filtrar

Contar envelopes por status

GET

/v1/envelopes/contador-status

Consultar envelope

GET

/v1/envelopes/{envelope}

Cancelar envelope

PUT

/v1/envelopes/{envelope}/cancelar

Reenviar links do envelope

PUT

/v1/envelopes/{envelope}/reenviar-link

Obter documentos assinados

GET

/v1/envelopes/{envelope}/links-documentos-assinados

Obter link de documento

GET

/v1/envelopes/{envelope}/documentos/{documento}/link-download

Listar perfis de assinatura

GET

/v1/signatarios/perfis-acesso

Filtrar signatários

GET

/v1/signatarios

Obter link do signatário

GET

/v1/signatarios/{signatario}/obter-link

Reenviar link do signatário

PUT

/v1/signatarios/{signatario}/reenviar-link

Editar signatário

PUT

/v1/signatarios/{signatarioId}

Listar tipos de relatório

GET

/v1/relatorios/tipos

Listar status de relatório

GET

/v1/relatorios/status

Criar relatório

POST

/v1/relatorios

Filtrar relatórios

GET

/v1/relatorios/filtrar

Gerar link de download do relatório

GET

/v1/relatorios/{id}/gerar-link

21. Suporte

Para consultar os exemplos completos de requisição, os modelos de resposta e as regras de cada endpoint, acesse a https://integracao.assertivasolucoes.com.br/v3/portal

Em caso de dúvidas sobre a integração, entre em contato com o suporte da Assertiva pelo e-mail:

atendimento@assertivasolucoes.com.br

Respondeu à sua pergunta?