Documentação API
Estruturas de Dados
<DocumentoRetorno>
Estrutura do Documento retorno pela API.
Estrutura JSON:
{"id_documento_status": "null", "descricao_documento_status": "null", "identificacao_arquivo": "null", "dt_criacao": "null", "id_externo": "null", "identificador_documento": "null", "hash_arquivo": "null", "quadro_assinaturas": "null", "quantidade_paginas": "null", "dt_limite_assinatura": "null", "lista_partes": "Array<ParteRetorno></ParteRetorno>"}
<ParteEnvio>
Estrutura para criar um registro de Parte na API.
Parâmetros de entrada:
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| Pessoa | Pessoa |
Estrutura básica de uma Pessoa, utilizar uma das seguintes: < PessoaCPF > < PessoaOutroDocumento > ou < PessoaId > |
|
| id_validacao_bloco | Int | Vide tabela validacoes_blocos. | |
| id_tipo_telefone | Int | Vide tabela telefones_tipos. | |
| identificacao_parte | String | Identificar a função da parte no documento. Ex.: Locador, Locatário, Estagiário, Empresa concedente, etc. | |
| id_referencia | String | Identificação da parte no sistema de origem dos dados. | |
| acoes | Array | Array com as ações da parte no documento. Parâmetro opcional, o padrão é sempre ASSINAR e VISUALIZAR. Vide tabela parte_acoes. | |
| ordem_assinatura | Int | Indicar ordem de assinaturas, assina do menor para o maior, o padrão é sempre 0, ou seja, assina primeiro. | |
| notificar | Int | Indica se Parte deve ser notificada. O parâmetro não é obrigatório e o default é 1, ou seja, sempre é notificado. Caso não queira que seja notificado, é necessário enviar como 0. | |
| pessoa_preenche_dados | Int | Define que a parte deve preencher os dados pela Assine Bem antes de realizar Assinatura, portanto não é necessário enviar os dados obrigatórios como CPF, RG. Para utilizar esta opção, o valor deste parâmetro deve ser 1 e o produto estar configurado e disponível para a sua conta. | |
| validar_campos | Int | Se a parte assina um modelo e o solicitante deseja validar os campos preenchidos antes de efetivar a assinatura, o valor deve ser 1. | |
| validar_anexos | Int | Se a parte assina um modelo e possui anexos no processo de assinatura, e o solicitante deseja validar os anexos enviados, o valor deve ser 1. | |
| anexos | Array<ParteAnexo> | Lista de estrutura ParteAnexo para configurar anexos que devem se enviados pela parte antes de realizar a assinatura no documento. | |
| redirecionamentos | Array<ParteRedirecionamento> | Estrutura ParteRedirecionamento para configurar redirecionamentos da parte durante processo de assinatura digital. Essa estrutura depende de um produto extra que necessita liberação da equipe da Assine Bem para utilização. | |
| confirmacoes | Array | Array com IDs de confirmações que devem ser feitas pela parte antes da assinatura no documento. Vide tabela tipos_confirmacoes. | |
| envia_email | Int |
Indica se Parte deve ser notificado via E-mail se tiver e-mail preenchido. O padrão é 1, ou seja, sempre notifica. |
|
| envia_sms | Int |
Indica se Parte deve ser notificado via SMS se os dados de telefone estiverem preenchidos. O padrão é 0, ou seja, não notifica. |
|
| envia_whatsapp | Int |
Indica se Parte deve ser notificado via WhatsApp se os dados de telefone estiverem preenchidos. O padrão é 0, ou seja, não notifica. |
|
| pode_delegar | Int |
Indica se Parte pode delegar sua assinatura para outra Parte fora do processo quando for assinar. O Padrão é 0, ou seja, não pode. |
|
| pode_substituir | Int |
Indica se Parte pode ser substituida pelo solicitante por outra Parte fora do processo. O Padrão é 0, ou seja, não pode. |
|
| idioma | String | String do idioma do acesso da Parte. Parâmetro opcional, o padrão é sempre Português do Brasil. Vide tabela idiomas. |
Estrutura JSON:
{"id_validacao_bloco": 999, "identificacao_parte": "", "id_referencia": "aaa111", "email": "usuario@dominio.com.br", "ddi": 55, "ddd": 99, "telefone": 11112222, "id_tipo_telefone": 2, "acoes": "Array <Tabela: parte_acoes>, // opcional", "ordem_assinatura": "99, // opcional", "notificar": "0, // opcional", "pessoa_preenche_dados": "0, // opcional", "validar_campos": "0, // opcional", "validar_anexos": "0, // opcional", "anexos": "Array <ParteAnexo></ParteAnexo> // opcional", "redirecionamentos": "Array <ParteRedirecionamento></ParteRedirecionamento> // opcional", "confirmacoes": "Array <Integer></Integer> // opcional", "envia_email": "1", "envia_sms": "0", "envia_whatsapp": "0", "idioma": "portugues"}
<PessoaCPF>
Estrutura para criar uma nova Parte utilizando CPF como documento principal de identificação.
Parâmetros de entrada:
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| nome | String | Nome completo da parte. | |
| nome_social | String | Nome social da parte. | |
| cpf | Int | Número completo do CPF sem pontuação. | |
| rg | String |
Estrutura JSON:
{"nome": "Fulano de tal", "cpf": "99999999999", "rg": ""}
<PessoaOutroDocumento>
Estrutura para criar uma nova Parte utilizando outro documento que não seja o CPF como documento principal de identificação.
Parâmetros de entrada:
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| nome | String | Nome completo da parte. | |
| nome_social | String | Nome social da parte. | |
| id_tipo_documento | Int | Inteiro para identificar que deseja identificar a parte por outro processo que não seja o CPF, para isso, o valor desse parâmetro deve ser 2. | |
| descricao_documento | String |
String com a descrição para a parte sobre qual documento está sendo utilizado para identificação. Exemplo: Passaporte, código interno e etc. |
|
| documento | String |
String com o valor do documento para cada parte. Exemplo: número do passaporte da pessoa ou código interno pré-combinado com a parte. |
Estrutura JSON:
{"nome": "Fulano de tal", "id_tipo_documento": 2, "descricao_documento": "Passaporte", "documento": "999AAA"}
<PessoaId>
Estrutura para utilizar uma Parte que já existe a partir do id_externo.
Parâmetros de entrada:
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| id_externo | String | ID que foi retornado ao criar a parte |
Estrutura JSON:
{"id_externo": "ID"}
<ParteRetorno>
Estrutura da Parte retornado pela API.
Estrutura JSON:
{"id_referencia": "", "id_externo": "ID", "id_status_pessoa_parte": "", "descricao_parte_status": "", "identificacao_parte": "", "dt_ult_notificado": "DD/MM/YYYY HH:MI:SS", "dt_criacao": "DD/MM/YYYY HH:MI:SS", "pessoa": {"nome": "null", "rg": "null", "cpf": "null", "id_tipo_documento": "null", "descricao_documento": "null", "documento": "null", "pessoa_preenche_dados": "null", "lista_emails": "Array <PessoaEmail></PessoaEmail>", "lista_telefones": "Array <PessoaTelefone></PessoaTelefone>"}, "parte_url": "<ParteUrlRetorno></ParteUrlRetorno> //(Opcional)"}
<PessoaEmail>
Estrutura de E-mail da Parte retornado pela API.
Estrutura JSON:
{"email": "null", "descricao_status_email": "null", "data_criacao": "DD/MM/YYYY HH:MI:SS"}
<PessoaTelefone>
Estrutura de Telefone da Parte retornado pela API.
Estrutura JSON:
{"ddd": "null", "telefone": "null", "id_pessoa_tipo_telefone": "null", "descricao_status_telefone": "null", "descricao_tipo_telefone": "null", "data_criacao": "DD/MM/YYYY HH:MI:SS"}
<ParteUrlRetorno>
Estrutura de Url da Parte retornado pela API.
Parâmetros de saída:
| Parâmetro | Sempre retorna? | Tipo | Descrição |
|---|---|---|---|
| url | String | URL completa para acesso ao sistema pelo assinante. | |
| assinatura | String | Opcional com valor 0 ou 1. Se a URL for de assinatura, este parâmetro retorna 1. | |
| validacao | String | Opcional com valor 0 ou 1. Se a URL for de validação, este parâmetro retorna 1. | |
| token | String | Token UUID para acesso ao sistema com expiração. | |
| dt_expiracao_token | String | Data de expiração do Token quando for URL de acesso para assinatura. |
Estrutura JSON:
{"url": "null", "token": "null", "assinatura": "null", "validacao": "null", "dt_expiracao_token": "DD/MM/YYYY HH:MI:SS"}
<ParteAnexo>
Estrutura para configurar anexos que devem ser enviados pela parte durante processo de assinatura.
Parâmetros de entrada:
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| identificacao | String | Identificacao simples do anexo. Exemplo: comprovante-de-residencia | |
| label | String |
Texto que aparecerá para o usuário explicando o que deve ser enviado.
Exemplo: Envie seu comprovante de residência. |
|
| obrigatorio | Int |
Se o anexo deve ser enviado obrigatoriamente, o parâmetro deve ser 1. O padrão é 0, ou seja, não obrigatorio. |
|
| posicao | String | Vide tabela anexos_posicao. | |
| limite_arquivos | Int |
Quantidade de arquivos que podem ser enviados por anexo. O limite padrão é 3 e o teto é 10. |
Estrutura JSON:
{"identificacao": "STRING", "label": "STRING", "obrigatorio": "Int", "posicao": "Int", "limite_arquivos": "Int"}
<ParteRedirecionamento>
Estrutura para configurar redirecionamento da parte durante processo de assinatura.
Parâmetros de entrada:
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| tipo | String | Vide tabela tipos_redirecionamentos. | |
| url | String |
URL para onde a parte será redirecionada. A URL deve ser com protocolo https e estar liberada na whitelist da Assine Bem. Para isso, é preciso enviar a solicitação de adicionar a URL para a equipe comercial. |
|
| parametros | JSON | String JSON key-value pair com os parâmetros que devem ser enviados juntos com a URL durante o redirecionamento. |
Estrutura JSON:
{"tipo": "STRING", "url": "STRING", "parametros": "JSON KEY-VALUE PAIR"}
<DocumentoParteAtualiza>
Estrutura para atualizar um registro de Parte no Documento.
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 e alterações | |
| identificacao_parte | String |
Identificar a função da parte no documento. Ex.: Locador, Locatário, Estagiário, Empresa concedente, etc. |
|
| id_validacao_bloco | Int | Vide tabela validacoes_blocos. | |
| ordem_assinatura | Int | Indica ordem de assinaturas, assina do menor para o maior, o padrão é sempre 0, ou seja, assina primeiro. | |
| pode_delegar | Int |
Indica se Parte pode delegar sua assinatura para outra Parte fora do processo quando for assinar. O Padrão é 0, ou seja, não pode. |
|
| pode_substituir | Int |
Indica se Parte pode ser substituida pelo solicitante por outra Parte fora do processo. O Padrão é 0, ou seja, não pode. |
|
| acoes | Array<String> |
Indica ações da Parte no Documento. Vide tabela parte_acoes. O padrão do sistema é configurar para Visualizar e Assinar. |
|
| notificacoes | Array<String> |
Indica como a Assine Bem notificará a Parte no Documento. Vide tabela parte_notificacoes. |
|
| redirecionamentos | Array<ParteRedirecionamento> |
Estrutura ParteRedirecionamento para configurar redirecionamentos da parte durante processo de assinatura digital. Essa estrutura depende de um produto extra que necessita liberação da equipe da Assine Bem para utilização. |
|
| idioma | String | String do idioma do acesso da Parte. Parâmetro opcional, o padrão é sempre Português do Brasil. Vide tabela idiomas. |
Estrutura JSON:
{"id_externo_documento": null, "id_externo_parte": null, "identificacao_parte": null, "id_validacao_bloco": null, "ordem_assinatura": null, "pode_delegar": null, "pode_substituir": null, "acoes": null, "notificacoes": null, "redirecionamentos": null, "idioma": null}
<DocumentoParteRetorno>
Estrutura da Parte no Documento retornado pela API.
Estrutura JSON:
{"id_externo_slot": null, "identificacao_parte": null, "id_validacao_bloco": null, "ordem_assinatura": 0, "pode_delegar": 0, "pode_substituir": 0, "acoes": [], "notificacoes": [], "id_externo": null, "dt_criacao": null, "id_status_pessoa_parte": null, "descricao_parte_status": null, "dt_ult_notificado": null, "pessoa": {"nome": null, "nome_social": null, "rg": null, "cpf": null, "id_tipo_documento": null, "id_referencia": null, "id_tipo_usuario_referencia": null, "id_lingua": null, "emails": {"email": null, "id_pessoa_status_email": null, "data_criacao": null, "data_atualizacao_status": null, "descricao_status_email": null}, "telefones": {"ddi": 55, "ddd": null, "telefone": null, "id_pessoa_tipo_telefone": null, "id_pessoa_status_telefone": null, "dt_criacao": null, "dt_atualizacao_status": null, "descricao_status_telefone": null, "descricao_tipo_telefone": null}, "lista_emails": [{"email": null, "id_pessoa_status_email": null, "data_criacao": null, "data_atualizacao_status": null, "descricao_status_email": null}], "lista_telefones": [{"ddi": 55, "ddd": null, "telefone": null, "id_pessoa_tipo_telefone": null, "id_pessoa_status_telefone": null, "dt_criacao": null, "dt_atualizacao_status": null, "descricao_status_telefone": null, "descricao_tipo_telefone": null}]}, "validacoes": [], "parte_url": {"url": null, "token": null, "dt_expiracao_token": "", "assinatura": 0, "validacao": 0}, "validado": 0, "em_analise": 0, "anexos": [{"id_api": null, "identificacao": null, "label": null, "obrigatorio": 0, "posicao": null, "limite_arquivos": null, "id_referencia": null}]}
<AssinaturaParte>
Estrutura de Assinatura da Parte retornado pela API.
Estrutura JSON:
{"dt_criado": "DD/MM/YYYY HH:MI:SS", "dt_visualizado": "DD/MM/YYYY HH:MI:SS", "dt_assinado": "DD/MM/YYYY HH:MI:SS", "id_externo": "ID da parte", "identificador_assinatura": "Identificador \u00fanico da assinatura da parte no documento"}
<ModeloParte>
Estrutura da Parte no Modelo retornado pela API.
Estrutura JSON:
{"id_modelo_parte": "ID_INTEIRO", "identificacao_parte": "STRING", "anexos": "INTEIRO // opcional(quantidade de anexos que devem ser enviados pela parte no modelo)"}
<ModeloParteEnvio>
Estrutura de Parte para adicionar no Modelo.
Parâmetros de entrada:
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| id_modelo_parte | Int | ID da parte configurada no modelo, usa-se esse ID como referência para vincular a parte a ser cadastrada (vide) na parte referência do modelo. | |
| ParteEnvio | <ParteEnvio> | Estrutura ParteEnvio com dados para adicionar no modelo. | |
| campos | Array<ModeloCampoEnvio> |
Lista com os campos ({chave: valor}) que devem ser pré-preenchidos para a parte. ** Esse parâmetro deve estar aninhado dentro do ParteEnvio como uma nova chave da estrutura. |
Estrutura JSON:
{"id_modelo_parte": "ID_INTEIRO", "id_validacao_bloco": 999, "identificacao_parte": "", "id_referencia": "aaa111", "email": "usuario@dominio.com.br", "ddi": 55, "ddd": 99, "telefone": 11112222, "id_tipo_telefone": 2, "acoes": "Array <Tabela: parte_acoes>, // opcional", "ordem_assinatura": "99, // opcional", "notificar": "0, // opcional", "pessoa_preenche_dados": "0, // opcional", "validar_campos": "0, // opcional", "validar_anexos": "0, // opcional", "anexos": "Array <ParteAnexo></ParteAnexo> // opcional", "redirecionamentos": "Array <ParteRedirecionamento></ParteRedirecionamento> // opcional", "confirmacoes": "Array <Integer></Integer> // opcional", "envia_email": "1", "envia_sms": "0", "envia_whatsapp": "0", "idioma": "portugues", "campos": [{"$ID_CAMPO": "$VALOR_CAMPO"}]}
<ModeloCampo>
Estrutura de um Campo no Modelo.
Parâmetros de saída:
| Parâmetro | Sempre retorna? | Tipo | Descrição |
|---|---|---|---|
| nome_campo | String | Formatada sem acento, caractere especial ou espaço e etc. Os espaços são substituídos como '-'. | |
| id_tipo_campo | Int | Vide tabela modelo_tipos_campos. |
Estrutura JSON:
{"id_campo": "ID_INTEIRO", "nome_campo": "STRING", "label_campo": "STRING", "preenchimento_obrigatorio": "INT", "id_tipo_campo": "INT", "descricao_tipo_campo": "STRING", "opcoes": "Array <ModeloCampoOpcoes></ModeloCampoOpcoes> // (opcional)"}
<ModeloCampoEnvio>
Estrutura para preencher um Campo no Modelo.
Parâmetros de entrada:
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| $ID_CAMPO | Int |
Retornado pela consulta do campo (vide |
|
| $VALOR_CAMPO | String|Int | Valor preenchido do campo para gerar documento a partir do modelo. (pode ser nulo se o campo não for obrigatório e não desejar preencher nada). |
Estrutura JSON:
{"$ID_CAMPO": "$VALOR_CAMPO"}
<ModeloCampoOpcoes>
Estrutura com opções de um campo no Modelo.
Estrutura JSON:
{"id_opcao": "ID_INTEIRO", "opcao": "STRING"}
<ModeloRetorno>
Estrutura do Modelo retorno pela API.
Parâmetros de saída:
| Parâmetro | Sempre retorna? | Tipo | Descrição |
|---|---|---|---|
| partes | Array | Lista de partes do modelo que devem ser preenchidas para solicitar a assinatura digital. | |
| campos_avulsos | Array | Campos que o modelo espera que sejam preenchidos para gerar o documento a partir do modelo e solicitar a assinatura. |
Estrutura JSON:
{"modelo": {"dt_criacao": "DD/MM/AAAA HH:MI:SS", "dt_alteracao": "DD/MM/AAAA HH:MI:SS", "nome": "STRING", "id_externo": "ID_INTEIRO", "partes": "Array <ModeloParte> </ModeloParte> // (opcional)", "campos_avulsos": "Array <ModeloCampo> </ModeloCampo> // (opcional)"}}
<AnexoRetorno>
Estrutura de Anexo da Parte retornado pela API.
Parâmetros de saída:
| Parâmetro | Sempre retorna? | Tipo | Descrição |
|---|---|---|---|
| envio_obrigatorio | Int |
Este parâmetro identifica se o envio do anexo é ou não obrigatório. Retorno 1 se obrigatório, 0 se não obrigatório. |
|
| enviado | Int |
Este parâmetro identifica se o anexo foi enviado. Retorno 1 se foi enviado, 0 se não foi enviado. |
|
| status | Int | Este parâmetro identifica o status do anexo enviado. Pode ser 1 (Pendente) ou 2 (Aprovado) ou 3 (Inválido) ou 4 (Não enviado). | |
| id_download | Int | Este parâmetro só é retornado se (enviado = 1) e utiliza-o para fazer download do anexo no Endpoint "documento/anexos/download". |
Estrutura JSON:
{"$id_externo_parte": [{"identificacao_anexo": "STRING", "envio_obrigatorio": "INTEIRO", "enviado": "INTEIRO", "status": "INTEIRO", "descricao_status": "STRING", "dt_enviado": "DD/MM/AAAA HH:MI:SS", "id_download": "INTEIRO // Opcional"}]}