Documentação API

Endpoints

1-) Obter identificador para upload:

Este método retorna um identificador único (UUID) que deverá ser passado para solicitar o upload de um documento.

Requisição: GET https://www.assinebem.com.br/api/documento/get_identifier_to_upload

Parâmetros de entrada: Nenhum parâmetro é preciso, o sistema faz a autenticação pelo seu Token enviado pelo HEADER e gera um identificador randomicamente.

Retorno JSON:

{
    'identifier': 'UUID'
}
    

2-) Upload de documento:

Este método permite realizar o upload de um documento (arquivo) para assinatura, juntamente com as partes envolvidas.

** Obrigatório enviar o parâmetro URL_ARQUIVO ou ARQUIVO conforme descritos abaixo na tabela de parâmetros de entrada.

Requisição: POST https://www.assinebem.com.br/api/documento

Parâmetros de entrada:

Parâmetro	Obrigatório	Tipo	Descrição
id_identifier		UUID	Identificador do documento, gerado por get_identifier_to_upload
lista_partes		Array	Lista das partes envolvidas na assinatura separados por vírgula, vide estrutura < ParteEnvio >.
url_arquivo		String	URL com documento PDF
arquivo		Base64	Arquivo encodado em base64
identificacao_arquivo		String	Nome do arquivo, sem espaços ou caracteres especiais
sufixo_arquivo		String	Extensão do arquivo
quadro_assinaturas		int	Indica se terá um quadro de assinatura no comprovante da Assine Bem
id_centro_custo		int	ID único de centro de custo que deve ser vinculado ao documento

Retorno < DocumentoRetorno >:

Estrutura Json:

{
    "status_api": 999,
    "mensagem": "descricao da resposta",
    "documento": {
        "id_documento_status": 9,
        "descricao_documento_status": "status",
        "identificacao_arquivo": "identificacao",
        "nome_arquivo": "nome",
        "dt_criacao": dt_criacao,
        "id_externo": id_externo,
        "identificador_documento": identificador_documento,
        "nome_arquivo_assinado": "nome_arquivo_assinado",
        "quadro_assinaturas": "quadro_assinaturas",
        "hash_arquivo": "hash_arquivo",
        "lista_partes": Array
    }
}
    

2.1 -) Inserir parte em documento:

Este método permite adicionar uma nova parte em um documento existente.

** Obrigatório enviar o parâmetro URL_ARQUIVO ou ARQUIVO conforme descritos abaixo na tabela de parâmetros de entrada.

Requisição: POST https://www.assinebem.com.br/api/documento/parte/inserir

Parâmetros de entrada:

Parâmetro	Obrigatório	Tipo	Descrição
id_externo_documento		String	ID único do documento na plataforma, utilizado para consultas e alterações
parte		< ParteEnvio >	Dados da parte que deseja inserir

Retorno < DocumentoRetorno >:

Estrutura Json:

{
    "status_api": 999,
    "mensagem": "descricao da resposta",
    "documento": {
        "id_documento_status": 9,
        "descricao_documento_status": "status",
        "identificacao_arquivo": "identificacao",
        "nome_arquivo": "nome",
        "dt_criacao": dt_criacao,
        "id_externo": id_externo,
        "identificador_documento": identificador_documento,
        "nome_arquivo_assinado": "nome_arquivo_assinado",
        "quadro_assinaturas": "quadro_assinaturas",
        "hash_arquivo": "hash_arquivo",
        "lista_partes": Array
    }
}
    

3-) Consulta de documento:

Este método busca os dados do documento e retorna no formato Json.

Requisição: GET https://www.assinebem.com.br/api/documento

Parâmetros de entrada:

Parâmetro	Obrigatório	Tipo	Descrição
id_externo		String	ID único do documento na plataforma, utilizado para consultas e alterações

Retorno:

< DocumentoRetorno >

4-) Download de documento:

Este método retorna o binario do documento e informações do arquivo.

Requisição: GET https://www.assinebem.com.br/api/documento/download

Parâmetros de entrada:

Parâmetro	Obrigatório	Tipo	Descrição
id_externo		String	ID único do documento na plataforma, utilizado para consultas e alterações
assinado		String (valor:1)	Se parâmetro enviado, a API retornará a última versão do arquivo disponível com as assinaturas das partes e o comprovante da Assine Bem. Senão será retornado o arquivo original enviado para assinatura.

5-) Download do documento binário:

Este método retorna o binário do documento.

Requisição: GET https://www.assinebem.com.br/api/documento/download_arquivo

Parâmetros de entrada:

Parâmetro	Obrigatório	Tipo	Descrição
id_externo		String	ID único do documento na plataforma, utilizado para consultas e alterações

Retorno:

Binário do arquivo com RESPONSE type: "application/pdf".

6-) Invalidar documento:

Este método invalida o documento na plataforma e não permite futuras assinaturas.

Requisição: POST https://www.assinebem.com.br/api/documento/invalidar

Parâmetros de entrada:

Parâmetro	Obrigatório	Tipo	Descrição
id_externo		String	ID único do documento na plataforma, utilizado para consultas e alterações

Estrutura Json:

{
    'status_api': 999,
    'mensagem': 'descrição da resposta'
}
    

7-) Consulta de parte:

Este método busca os dados da parte e retorna no formato Json.

Requisição: GET https://www.assinebem.com.br/api/parte

Parâmetros de entrada:

Parâmetro	Obrigatório	Tipo	Descrição
id_externo		String	ID único do documento na plataforma, utilizado para consultas e alterações

Retorno:

< ParteRetorno >

8-) Consulta status da parte:

Este método busca o status da parte e retorna no formato Json

Requisição: GET https://www.assinebem.com.br/api/parte/status

Parâmetros de entrada:

Parâmetro	Obrigatório	Tipo	Descrição
id_externo		String	ID único do documento na plataforma, utilizado para consultas e alterações

Estrutura Json:

{
    'status_api': 999,
    'mensagem': 'descrição da resposta',
    'id_externo': 'ID',
    'id_status': 'ID',
    'descricao': 'descrição do status em texto'
}
    

9-) Atualiza dados da parte:

Este método atualiza os dados básicos da parte dependendo das restrições.

Requisição: POST https://www.assinebem.com.br/api/parte/atualizar

Parâmetros de entrada:

Parâmetro	Obrigatório	Tipo	Descrição
id_externo		String	ID único do documento na plataforma, utilizado para consultas e alterações
rg		String	Representando RG da parte. Se não for passado, não será atualizado.
cpf		String	Representando CPF (sem pontuação) da parte. Se não for passado, não será atualizado.
ddd		int	Int representando os dois dígitos do DDD. Se não for passado, não será atualizado.
telefone		int	Int representando o número de celular da parte. (8 ou 9 dígitos) Se não for passado, não será atualizado.
id_tipo_telefone		int	Int representando o tipo de telefone.

** Somente será permitido atualizar se status da parte for 'Não validado' ou 'Dados inválidos'.

** Somente será atualizado se os valores passados forem diferentes dos atuais.

** O ddd/telefone só será atualizado se passar os dois valores em conjunto.

Estrutura Json:

{
    'status_api': 999,
    'mensagem': 'descrição da resposta',
    'parte': 
}
    

10-) Notificar parte com novo acesso:

Esse método notifica a parte via E-mail e SMS com novo acesso para assinar documentos pendentes.

Requisição: POST https://www.assinebem.com.br/api/parte/novo_acesso

Parâmetros de entrada:

Parâmetro	Obrigatório	Tipo	Descrição
id_externo		String	ID único do documento na plataforma, utilizado para consultas e alterações

Estrutura Json:

{
    'sucesso': 0 // ou 1
}
    

Descrição retorno:

ID	Descrição
1	Se parte foi notificada com sucesso.
0	Se parte não foi notificada.

11-) Consulta status da assinatura da parte em um documento:

Este método busca o status da parte e retorna em forma de JSON.

Requisição: GET https://www.assinebem.com.br/api/documento/assinatura/status

Parâmetros de entrada:

Parâmetro	Obrigatório	Tipo	Descrição
id_externo		String	ID único do documento na plataforma, utilizado para consultas e alterações
id_externo_documento		String	ID único do documento na plataforma, utilizado para consultas e alterações

Estrutura Json:

{
    'id_externo_parte': 'ID',
    'id_externo_documento': 'ID',
    'identificador_assinatura': ''
}
    

Descrição retorno:

ID	Descrição
identificador_assinatura	UUID único da assinatura, se vier preenchido significa que a parte assinou.

12-) Consulta de assinaturas pendentes:

Este método busca todas as partes com assinatura pendente de documentos ainda não assinados.

Requisição: POST https://www.assinebem.com.br/api/documento/assinatura/pendentes

Parâmetros de entrada:

Parâmetro	Obrigatório	Tipo	Descrição
offset		int	Offset da busca de assinaturas pendentes, pois é retornado 50 registros por vez.

Estrutura Json:

{
    'offset_ini': 'Índice inicial do offset',
    'offset_fim': 'Índice final do offset',
    'total': 'Total de assinaturas pendentes.',
    'total_retornado': 'Total de registros retornados',
    'assinaturas_pendentes': Array<{
        'id_externo_parte': 'ID único',
        'id_externo_documento': 'ID único',
        'documento': < DocumentoRetorno >,
        'parte': < ParteRetorno >
    }>
}
    

13-) Consulta modelos configurados para o cliente:

Este método busca todos os modelos configurados para cliente e retorna lista em JSON.

Requisição: GET https://www.assinebem.com.br/api/modelo/obter_modelos.

Parâmetros de entrada:

Nenhum parâmetro é preciso, o sistema faz a autenticação pelo seu Token enviado pelo HEADER e retorna lista de modelos configurados para sua conta.

Estrutura Json:

{
    'status_api': 999,
    'mensagem': 'descricao da resposta',
    'modelos': [{
        'dt_alteracao': 'DD/MM/AAAA HH:MI:SS',
        'nome': 'STRING',
        'id_externo': 'ID_INTEIRO',
        'dt_criacao': 'DD/MM/AAAA HH:MI:SS'
    }]
}
    

14-) Consulta dados de um modelo:

Este método busca os dados do modelo e retorna no formato JSON.

Requisição: GET https://www.assinebem.com.br/api/modelo/obter_modelos

Parâmetros de entrada:

Parâmetro	Obrigatório	Tipo	Descrição
id_externo		int	ID único do modelo na plataforma, utilizado para consultas.

Estrutura Json:

{
    'status_api': 999,
    'mensagem': 'descricao da resposta',
    < ModeloRetorno >
}
    

15-) Upload de modelo:

Este método permite solicitar assinatura de modelo, juntamente com as partes envolvidas.

Requisição: POST https://www.assinebem.com.br/api/modelo

Parâmetros de entrada:

Parâmetro	Obrigatório	Tipo	Descrição
id_externo		int	ID único do modelo na plataforma, utilizado para consultas.
lista_partes		Array	Lista das partes envolvidas na assinatura separados por vírgula, vide estrutura < ParteEnvio >.
lista_campos		Array	Lista com campos do modelo que devem ser preenchidos separados por vírgula, vide formato abaixo. Se modelo não tiver campos configurados para preenchimento, não é preciso enviar esse parâmetro.
identificacao_arquivo		String	Nome do arquivo, sem espaços ou caracteres especiais.
quadro_assinaturas		String	Indica se terá um quadro de assinatura no comprovante da Assine Bem.
id_centro_custo		int	ID único de centro de custo que deve ser vinculado ao documento

Retorno:

16-) Consulta anexos de um documento:

Este método busca os anexos configurados para os assinantes do documento.

É possível buscar os anexos configurados para o documento ou somente de uma parte no documento ao passar o parâmetro não obrigatório "id_externo_parte".

Requisição: GET https://www.assinebem.com.br/api/documento/anexos

Parâmetros de entrada:

Parâmetro	Obrigatório	Tipo	Descrição
id_externo		String	ID único do documento na plataforma, utilizado para consultas.
id_externo_parte		String	ID único da parte na plataforma, utilizado para consultas.

Estrutura Json:

{
    'status_api': 999,
    'mensagem': 'descricao da resposta',
    'documento': {
        'id_externo': None
        'identificador_documento': None
        'identificacao_arquivo': None
    },
    'anexos': < AnexoRetorno >
}
    

17-) Download do anexo binário:

Este método retorna o binário do arquivo anexo.

Requisição: GET https://www.assinebem.com.br/api/documento/anexos/download

Parâmetros de entrada:

Parâmetro	Obrigatório	Tipo	Descrição
id_externo		String	ID único do documento na plataforma, utilizado para consultas e alterações
id_download		int	ID único do para fazer download do anexo, retornado ao consultar os anexos no documento vide (< AnexoRetorno >)

Retorno:

Binário do arquivo com RESPONSE type: "application/png | jpg | jpeg | pdf".

18-) Aprovar anexo:

Este método aprova o anexo enviado pelo assinante que muda o status de pendente para aprovado.

Com isso, o anexo fica disponível para download e é anexado a versão final do arquivo assinado.

Requisição: POST https://www.assinebem.com.br/api/documento/anexos/aprovado

Parâmetros de entrada:

Parâmetro	Obrigatório	Tipo	Descrição
id_externo		String	ID único do documento na plataforma, utilizado para consultas e alterações
id_externo_parte		String	ID único da parte na plataforma, utilizado para consultas.
id_download		int	ID único do anexo, retornado ao consultar os anexos no documento vide (< AnexoRetorno >)

Retorno se sucesso:

{
    'status_api': 200,
    'mensagem': 'descricao da resposta'
}
    

19-) Invalidar anexo:

Este método invalida o anexo enviado pelo assinante que muda o status de pendente para inválido.

Com isso, se o parâmetro 'reenviar' for passado, a plataforma enviará uma notificação para assinante refazer o envio do anexo invalidado.

Requisição: POST https://www.assinebem.com.br/api/documento/anexos/invalidar

Parâmetros de entrada:

Parâmetro	Obrigatório	Tipo	Descrição
id_externo		String	ID único do documento na plataforma, utilizado para consultas e alterações
id_externo_parte		String	ID único da parte na plataforma, utilizado para consultas.
id_download		int	ID único do anexo, retornado ao consultar os anexos no documento vide (< AnexoRetorno >)
reenviar		int	Inteiro para definir se o assinante deverá ou não reenviar o anexo invalidado. Valores: 1 (para reenviar) ou 2 (para não reenviar).

Retorno se sucesso:

{
    'status_api': 200,
    'mensagem': 'descricao da resposta',
    'reenviado': 'INTEIRO'
}
    

Se anexo reenviado para o assinante, o parâmetro de retorno 'reenviado' é igual a 1 senão é 0

20-) Busca centro de custos:

Busca centros de custo configurados da empresa.

Requisição: GET https://www.assinebem.com.br/api/documento/centro_custo

Parâmetros de entrada: Nenhum parâmetro é preciso, o sistema faz a autenticação pelo seu Token enviado pelo HEADER.

Retorno JSON:

{
    'status_api': 200,
    'mensagem': 'descricao da resposta',
    'centros_custo': Array<{
        'id_centro_custo': 'INTEIRO'
        'descricao': 'STRING'
    }>
}
    

21 -) Busca URL do assinante:

Busca URL do assinante para assinatura ou validação dependendo do Assinante X Documento.

Requisição: GET https://www.assinebem.com.br/api/documento/parte/url

Podem ser retornadas duas URLs, uma para assinatura ou para validação

Para assinatura, é retornada somente se o assinante tiver com assinatura pendente do documento passado como parâmetro ou algum outro. Ou se o status do assinante for 'válido'.

Para validação, é retornada se não tiver documento pendente ou estiver com status diferente de 'válido'.

Parâmetros de entrada:

Parâmetro	Obrigatório	Tipo	Descrição
id_externo_documento		String	ID único do documento na plataforma, utilizado para consultas e alterações
id_externo_parte		String	ID único da parte na plataforma, utilizado para consultas.

Retorno JSON:

{
    'status_api': 200,
    'mensagem': 'descricao da resposta',
    'url': 'STRING (URL ABSOLUTA)',
    'assinatura': 'INTEIRO', // 0 ou 1
    'validacao': 'INTEIRO',  // 0 ou 1
    'token': 'STRING (UUID)', // OPCIONAL
    'dt_expiracao_token': 'STRING (dd/mm/yyyy hh:mi:ss)', // OPCIONAL
    'id_externo_documento': 'ID único',
    'id_externo_parte': 'ID único'
}
    

Se URL retornada for para assinatura: - parâmetro 'assinatura' é igual a 1 senão é 0. - parâmetro 'token' é igual um UUID para acesso ao sistema de assinatura com expiração. - parâmetro 'dt_expiracao_token' é uma STRING em formato de Data e Hora com expiração do token retornado.

Se URL retornada for para validação: - parâmetro 'validacao' é igual a 1 senão é 0.