Contatos e identificadores

Um contato é uma pessoa da agenda da organização: nome, e-mail, identificador, telefone e uma descrição. Na tela de criação de documentos, o Signer sugere os contatos para preencher os participantes. Esta página mostra como gerenciar os contatos e os identificadores de um usuário pela API.

Contatos

Todas as rotas começam com /api/organization/contacts. Sem o parâmetro organizationId na query string, a organização é a da chave de API.

Operação	Rota
Listar e pesquisar	GET /api/organization/contacts?q=maria&limit=20&offset=0
Criar	POST /api/organization/contacts
Consultar	GET /api/organization/contacts/{contactId}
Alterar	PUT /api/organization/contacts/{contactId}
Excluir	DELETE /api/organization/contacts/{contactId}
Criar em lote	POST /api/organization/contacts/batch/create
Excluir em lote	POST /api/organization/contacts/batch/delete

O parâmetro q pesquisa o começo do nome ou do sobrenome, o começo do e-mail, do telefone e do identificador, e as palavras da descrição. A listagem devolve os contatos em items e o total em totalCount.

O corpo de criação e de alteração tem estes campos:

POST /api/organization/contacts
{
  "name": "Maria Souza",
  "emailAddress": "maria.souza@mailinator.com",
  "identifier": "81976153069",
  "identifierType": "Cpf",
  "phone": "+55 11 91234-5678",
  "description": "Diretora financeira"
}

Os campos name e emailAddress são obrigatórios. O campo identifierType é obrigatório quando a instância aceita mais de um tipo de identificador. Os tipos estão em O participante (user).

Criar e excluir em lote

Para criar vários contatos de uma vez, envie a lista em contacts com type igual a Contacts:

POST /api/organization/contacts/batch/create
{
  "type": "Contacts",
  "contacts": [
    { "name": "Maria Souza", "emailAddress": "maria.souza@mailinator.com" },
    { "name": "João Lima", "emailAddress": "joao.lima@mailinator.com" }
  ]
}

Para criar os contatos a partir de um arquivo CSV:

1. Faça o upload do arquivo com POST /api/uploads, como no passo 1 da criação de documentos.
2. Envie o ID do upload em uploadId, com type igual a Csv.

O CSV tem as colunas name, email, identifier e description, sem diferenciar maiúsculas de minúsculas. Se o upload não existe, a API responde com o erro UploadNotFound. A resposta das duas formas é a lista dos contatos criados.

Para excluir vários contatos, envie a lista dos IDs no corpo:

POST /api/organization/contacts/batch/delete
[ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "9b2c1e4d-8f3a-4c6b-a1d2-0e5f7a8b9c10" ]

Quem pode gerenciar os contatos

Os administradores e gerentes da organização podem ver, criar, alterar e excluir contatos. Os operadores e os usuários básicos só podem ver e usar os contatos, a não ser que a instância permita que eles também os gerenciem (configuração General:AllowBasicAndOperatorUsersToManageContacts, em Configurações do Signer).

Rotas da interface web

A interface web usa duas rotas que não estão na referência da API (Swagger):

• As rotas terminadas em /personal (por exemplo GET /api/organization/contacts/personal) fazem o mesmo que as rotas sem o sufixo. A interface usa essas rotas para a conta pessoal do usuário.
• GET /api/organization/contacts/participant-search?q=maria pesquisa, sem repetir pessoas, os usuários da organização, os contatos (includeContacts=true) e os usuários de fora da organização (includeExternalUsers=true). A instância pode desligar as duas últimas buscas na seção AdvancedSearch das Configurações do Signer. Cada item informa a origem em origin: Contact, OrganizationUser ou ExternalOrganizationUser.

Identificadores de um usuário

Quando a instância permite vários identificadores por usuário, um usuário pode ter, por exemplo, um CPF e um passaporte. Veja Identificação de participantes. Estas rotas não estão na referência da API (Swagger).

Operação	Rota
Listar	GET /api/users/{userId}/identifiers
Adicionar	POST /api/users/{userId}/identifiers
Alterar o valor	PUT /api/users/{userId}/identifiers/{identifierId}
Excluir	DELETE /api/users/{userId}/identifiers/{identifierId}

Um usuário que entrou no Signer gerencia os próprios identificadores com as mesmas rotas sem /users/{userId}, por exemplo GET /api/identifiers. Essas rotas não aceitam chave de API. Para gerenciar os identificadores de outro usuário, a chave precisa do papel de administrador do sistema, como a chave de API de administração.

Cada identificador tem type e value. A resposta também traz id e isGrant, que indica o identificador sincronizado com o Grant ID:

POST /api/users/4d961566-9b03-450c-b144-930e0294bac2/identifiers
{
  "type": "Passport",
  "value": "AB123456"
}

Cada usuário tem no máximo um identificador de cada tipo. O PUT altera só o valor: para mudar o tipo, exclua o identificador e adicione outro. Erros comuns:

Código	Quando
InvalidIdentifierValue	O valor não é válido para o tipo, por exemplo um CPF com dígito verificador errado.
IdentifierAlreadyBeingUsedCode	O usuário já tem um identificador desse tipo.
IdentifierNotFound	O identifierId não pertence ao usuário.
CannotDeleteGrantIdentifier	O identificador é do tipo padrão da instância e é sincronizado com o Grant ID.