Este serviço permite gerenciar destinatários do processo de assinatura, em andamento, que possuem ação de Receber Cópia, permitindo incluir, editar e/ou excluir um ou mais destinatários que receberão cópia dos documentos ao término das assinaturas. 

Requisição

Orientações

Quando campo requerido estiver como “Sim” = Sempre requerido
Quando campo requerido estiver como “Não” = Informação Opcional
Quando campo requerido estiver como “Talvez” = Em alguns casos ele será requerido. Para saber estes casos, consultar a descrição do tópico, conforme o número de referência da linha na tabela.

Exemplo de Body Request

[
  {
    "acao": 1,
    "nome": "João da Silva",
    "email": "joao.silva@example.com",
    "telefone": ""
  },
  {
    "acao": 2,
    "idProcessoDestinatario": "11111111-2222-3333-4444-555555555555",
    "nome": "João da Silva Junior",
    "email": "",
    "telefone": "+5511999999999"
  },
  {
    "acao": 3,
    "idProcessoDestinatario": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
]

Validações

Validações gerais

1. Para autenticar na API da ArqSign, o usuário deve informar a AppKey da conta que está gerenciando os destinatários do processo.
2. Somente conta com status Ativo pode gerenciar destinatários do processo via integração ArqSign.
3. O plano de assinatura vigente deve possuir a permissão “10.1 Usar Integração ArqSign.
4. Somente é permitido gerenciar destinatários com ação de Receber Cópia de processos com status “Aguardando” ou “Em processo”.
5. Para incluir ou alterar destinatário com forma de envio por WhatsApp (telefone) a conta precisa possuir saldo de WhatsApp.

Validações específicas

acao

Descrição: Parâmetro obrigatório informando ação a ser executada para o destinatário, permitindo os valores 1 = Incluir, 2 = Alterar ou 3 =Excluir.

Quando for enviado o valor 1 no parâmetro acao significa que o sistema irá incluir um novo destinatário com ação de receber cópia no processo de assinaturas.

Quando for enviado o valor 2 no parâmetro acao significa que o sistema irá alterar os dados do destinatário com ação de receber cópia no processo de assinaturas.

Quando for enviado o valor 3 no parâmetro acao significa que o sistema irá excluir os dados do destinatário com ação de receber cópia no processo de assinaturas.

Validação:

a. Somente é permitido valores iguais a 1, 2 ou 3.

   Mensagem: O parâmetro acao permite somente valores 1, 2 ou 3.

IdProcessoDestinatário

Descrição: Parâmetro informando o id do destinatário com ação de receber cópia que será alterado ou excluído conforme valor informado no parâmetro acao.

O sistema desconsidera este parâmetro quando no campo acao for enviado valor 1 (Incluir).

Validações:

a. Quando no campo acao for enviado valor 2 (Alterar) ou 3 (Excluir) é necessário informar o id do destinatário.

    Mensagem: O parâmetro idProcessoDestinatário é obrigatório quando o parâmetro acao for igual a 2 ou 3.

b. O sistema verifica se o id destinatário pertence ao Id do Processo informado na URL.

    Mensagem: Processo inválido.

c. O sistema verifica se o Id do destinatário possui tipo de ação Receber uma cópia.

    Mensagem: Destinatário com tipo de ação diferente de receber uma cópia.

d. O sistema verifica se o Id do destinatário já foi informado.

    Mensagem: Destinatário duplicado.

e. O sistema verifica se o Id do destinatário possui tipo de ação diferente de Receber uma cópia.

    Mensagem: Destinatário Inválido.

nome

Descrição: Parâmetro informando o nome do destinatário com ação de receber cópia que será alterado ou incluído conforme valor informado no parâmetro acao.

O sistema desconsidera este parâmetro quando no campo acao for enviado valor 3 (Excluir).

Este parâmetro é opcional quando for enviado valor 2 no parâmetro “acao”.

Validações:

a. Quando no campo acao for enviado valor 1 (Incluir) é necessário informar o nome do destinatário.

    Mensagem: O parâmetro nome é obrigatório quando o parâmetro acao for igual a 1.

email

Descrição: Parâmetro informando o e-mail do destinatário com ação de receber cópia que será alterado ou incluído conforme valor informado no parâmetro acao.

O sistema desconsidera este parâmetro quando no campo acao for enviado valor 3 (Excluir).

Validações:

a. O sistema verifica se o formato de e-mail é válido.

    Mensagem: email inválido.

b. Para ação de inclusão ou alteração é necessário informar email ou telefone.

    Mensagem: O parâmetro email ou telefone é obrigatório.

c. O sistema verifica se o email ou telefone já existe para outro destinatário.

   Mensagem: Já existe destinatário com o e-mail ou telefone informado.

telefone

Descrição: Parâmetro informando o telefone do destinatário com ação de receber cópia que será alterado ou incluído conforme valor informado no parâmetro acao.

O sistema desconsidera este parâmetro quando no campo acao for enviado valor 3 (Excluir).

Validações:

a. Para ação de inclusão ou alteração é necessário informar email ou telefone.

    Mensagem: O parâmetro email ou telefone é obrigatório.

b. Verifica se o formato de telefone é válido

    Mensagem: telefone inválido.

c. O sistema verifica se o email ou telefone já existe para outro destinatário.

    Mensagem: Já existe destinatário com o e-mail ou telefone informado.

d. O sistema valida o saldo de WhatsApp ao incluir ou alterar destinatário para envio por WhatsApp.

    Mensagem: A conta não possui créditos de WhatsApp.

Retorno validações

Erro: 400 – Bad Request

Este erro é retornado quando não for possível interpretar a requisição e/ou o servidor tenta processar a solicitação, mas algum parâmetro da solicitação não é válido, por exemplo, um recurso formatado incorretamente ou uma tentativa de requisição com dados faltantes. As informações sobre a solicitação são fornecidas no corpo da resposta e incluem um código de erro e uma mensagem de erro.

a. Item obrigatório: Esta mensagem é exibida no singular ou plural quando um ou mais itens obrigatórios não tiver sido enviado na chamada da API.

   Mensagem: O(s) item(ns) listado(s) é(são) obrigatório(s): “nome dos itens separados por vírgula”.

b. Formato incorreto: Esta mensagem é exibida no singular ou plural quando um ou mais itens estiverem sido enviados com formato incorreto.

    Mensagem: O(s) item(ns) listado(s) está(ão) com o formato incorreto: “nome dos itens separados por vírgula”.

c. Ids inexistente: Esta mensagem é exibida no singular ou plural quando um ou mais Id enviado não existir.

    Mensagem: O(s) id(s) listado(s) não existe(m): “nome dos itens que são Ids de tabela, separados por vírgula”.

d. Algum parâmetro está incorreto ou é inexistente: Esta mensagem é exibida quando a chamada é feita com algum parâmetro escrito errado ou quando é enviado uma informação que não existe no método.

   Mensagem: Algum parâmetro está incorreto ou é inexistente.

Erro: 401 – Unauthorized

Este erro é retornado quando a chave de autenticação da API ArqSign está incorreta ou não foi informada corretamente.

Erro: 404 – Not Found

Este erro é retornado quando o recurso solicitado ou o endpoint não foi localizado.

Erro: 500 – Server Error

Este erro é retornado quando:

• Ocorre um erro interno no servidor,
• Ocorre uma falha na plataforma ArqSign,
• Formato do JSON incorreto.

Retorno de sucesso

Status 200 – Success

• Para destinatários incluídos ou alterados com sucesso, o serviço retorna a lista dos destinatários efetivamente incluídos/alterados.
• Para destinatários excluídos, não há retorno de itens específicos.

Retorno – Exemplo Body

[
{
    "idProcessoDestinatario": "guid",
    "nome": "string",
    "email": "string",
    "telefone": "string"
}
]