REST API de Monitoramento (versão 1)

Abaixo é apresentada a API REST disponível relacionada com usuários monitorados.

Caso qualquer requisição a API apresentada nesta página seja considerada como não monitorada conforme regras de inclusões e exclusões, será respondido com código de erro 403.

Caso o sistema de privacidade dos dados do usuário esteja ligado, qualquer requisição a API que tente criar um usuário com os campos abaixos preenchidos ou editar tais campos em um usuários existente que não consentiu com o termo de privacidade, será respondido com código de erro 409:
friendlyId, firstName, middleName, lastName, email e atributos customizados com a opção Identifica usuário habilitada.

Para melhor entender quando se utiliza cada operação apresentada nesta página, iniciaremos apresentando cenários de uso e em seguida as operações são apresentadas em detalhes.

Cenário de uso: monitoramento por sistema externo sem uso de identificador amigável

Neste cenário um sistema externo utiliza o monitoramento do LumisXP, sem utilização do campo de identificador amigável do usuário. Neste caso o sistema externo usará o identificador de rastreamento do usuário, possivelmente armazenando-o associado ao usuário do sistema, como forma de poder referenciar o mesmo usuário quando necessário.

Um uso básico neste cenário seria:

1. Um usuário inicia sua interação com o sistema externo. Se o sistema ainda não possui um identificador de rastreamento para este usuário, ele irá gerá-lo executando POST .../users. A chamada para esta operação irá retornar o identificador de rastreamento do usuário que o sistema externo deverá armazenar de forma que possa reutilizá-lo sempre que quiser referenciar este mesmo usuário.
2. Quando o sistema externo quiser armazenar informação sobre alguma ação feita pelo usuário, poderá utilizar a operação POST .../events/{id}/data, repassando como valor da propriedade lum_user.trackId o identificador de rastreamento do usuário. Isto fará com que campos que o evento possua correspondente a dados do usuários (lum_user.*) sejam preechidos com os dados correspondentes.
3. Quando o sistema externo quiser atualizar alguma informação sobre este usuário, poderá utilizar a operação PATCH .../users/{trackId}^[*].

Cenário de uso: monitoramento por sistema externo com uso de identificador amigável

Neste cenário um sistema externo utiliza o monitoramento do LumisXP, utiliza sua própria forma de identificar um usuário como identificador amigável no usuário do LumisXP.

Por exemplo, suponhamos que o sistema possui seus usuários cadastrados em um Active Directory, e utiliza como forma de identificar o usuário o seu login. Estes usuários podem ser importados para também existirem no LumisXP ou não. Caso sejam importados, neste exemplo a configuração de identificador amigável de usuários deve ser configurada para que corresponda ao login (assumindo que está no mesmo formato do login do sistema externo), para ser consistente com a forma que o sistema externo irá gerar esses identificadores.

Neste caso o sistema externo não precisa persistir de forma permanente o identificador de rastreamento do usuário, pois poderá recuperá-lo a partir do identificador amigável que foi definido pelo próprio sistema. Ele precisará manter o identificador de rastreamento do usuário em caso em que ainda não tem conhecimento de qual seu usuário está efetuando acesso (por exemplo, um website que permite acesso sem autenticação) e manter temporariamente no caso de usuário conhecido para evitar ter que chamar sempre a operação para recuperar o identificador de rastreamento a partir do identificador amigável (em ambos os casos, em uma aplicação web, é comum para isto armazenar o identificador de rastreamento^[*] em web storage, cookie ou sessão).

Um uso básico neste cenário seria:

1. Um usuário inicia sua interação com o sistema externo. Se o sistema ainda não possui um identificador de rastreamento para este usuário, ele irá gerá-lo executando o POST .../users, opcionalmente incluindo informações conhecidas sobre o usuário para serem armazenadas no monitoramento do LumisXP. Caso já se saiba o identificador amigável deste usuário (por exemplo, já foi autenticado), o identificador amigável deve ser passado nesta chamada para que seja utilizado o usuário correspondente.
2. Quando o sistema externo quiser armazenar informação sobre alguma ação feita pelo usuário, poderá utilizar a operação POST .../events/{id}/data, repassando como valor da propriedade lum_user.trackId o identificador de rastreamento do usuário. Isto fará com que campos que o evento possua correspondente a dados do usuários (lum_user.*) sejam preechidos com os dados correspondentes.
3. Quando o sistema externo quiser atualizar alguma informação sobre este usuário, poderá utilizar a operação PATCH .../users/{trackId}^[*].
4. Quando o usuário for reconhecido pelo sistema externo de forma que ele passe a saber o identificador amigável antes não conhecido (por exemplo, ao efetuar login), deve ser utilizada a operação POST .../users/{trackId}/identify^[*], que fará atualização dos usuários correspondentes se necessário e retornará o identificador de rastreamento do usuário que deve ser usado para referenciar o usuário com o identificador amigável especificado.

POST /lumis/api/rest/lumis/monitor/v1/users

Adiciona um usuário ou atualiza um usuário com um friendlyId especificado^[*].

Cabeçalhos de Requisição

Esta operação requer cabeçalhos na requisição compatíveis com:

Corpo da Requisição

O corpo da requisição deve ser um objeto JSON com as propriedades listadas abaixo:

Resposta de Sucesso

Quando a operação é bem sucedida, a resposta conterá um objeto JSON informação sobre a ação executada e o identificador do usuário criado ou atualizado.

Resposta de Erro

Esta operação responde como erro o objeto JSON padrão de erro.

Exemplo de Requisição

POST /lumis/api/rest/lumis/monitor/v1/users HTTP/1.1
Accept: application/json
Content-Type: application/json
(... outros cabeçalhos ...)

{
	"friendlyId": "11111111111",
	"firstName": "John",
	"middleName": "Doe",
	"lastName": "Smith",
	"email": "jds@example.com",
	"customAttributes":
	{
		"active": false,
		"classes": 5,
		"company": "Acme",
		"memberSince": "1980-12-02T05:23:26-03:00",
		"phone": ["(00)1234-5678","(11)98765-4321"]
	}
}

Exemplo de Resposta de Sucesso

{
	"created": false,
	"lum_user":
	{ 
		"trackId": "d4JdixacSOUHzGuStMaUaOAjE8VF42WI"
	}
}

PATCH /lumis/api/rest/lumis/monitor/v1/users/{trackId}

Atualiza dados de um usuário^[*].

Cabeçalhos de Requisição

Esta operação requer cabeçalhos na requisição compatíveis com:

Parâmetros na URI

Corpo da Requisição

O corpo da requisição deve ser um objeto JSON contendo as propriedades do usuário a serem alteradas. As propriedades aceitas neste objeto são as mesmas descritas no método POST acima, exceto friendlyId, que não é permitido ser declarado nesta operação.

Resposta de Sucesso

A resposta desta operação em caso de sucesso será o corpo vazio e código de resposta 204.

Resposta de Erro

Esta operação responde como erro o objeto JSON padrão de erro.

Exemplo de Requisição

Neste exemplo será atualizado o valor de email e será apagado o atributo customizado company, caso exista.

PATCH /lumis/api/rest/lumis/monitor/v1/users/d4JdixacSOUHzGuStMaUaOAjE8VF42WI HTTP/1.1
Content-Type: application/merge-patch+json
Accept: application/json
(... outros cabeçalhos ...)

{
	"email": "my_new_email@example.com",
	"customAttributes":
	{
		"company": null
	}
}

POST /lumis/api/rest/lumis/monitor/v1/users/{trackId}/identify

Identifica um usuário com um identificador amigável^[*], retornando o identificador de rastreamento do usuário resultante com tal identificador amigável.

Se na sessão atual houver um usuário autenticado e seu identificador amigável não corresponder ao trackId ou friendlyId especificado, esta operação não fará nada e responderá com código de erro HTTP 409.

Se o usuário com o identificador de rastreamento dado não possui identificador amigável nem login e não existe usuário com identificador amigável igual ao valor especificado, este usuário passará a ter o identificador amigável especificado e seu identificador de rastreamento será retornado.

Se o usuário com o identificador de rastreamento dado não possui identificador amigável nem login mas já existe usuário com identificador amigável igual ao valor especificado, ambos usuários serão mesclados em um único usuário e o seu identificador de rastreamento será retornado.

Se o usuário com o identificador de rastreamento dado já possui identificador amigável igual ao valor especificado, nenhuma alteração será feita e o seu identificador de rastreamento será retornado.

Se o usuário com o identificador de rastreamento dado já possui identificador amigável diferente do valor especificado ou possui login mas não possui identificador amigável:

• se não existir um usuário com o identificador amigável dado, um novo usuário será criado com o identificador amigável e o seu identificador de rastreamento será retornado.
• se existir um usuário com o identificador amigável dado, será retornado o identificador de rastreamento deste usuário já existente.

Cabeçalhos de Requisição

Esta operação requer cabeçalhos na requisição compatíveis com:

Parâmetros na URI

Corpo da Requisição

O corpo da requisição deve ser um objeto JSON com as propriedades listadas abaixo:

Resposta de Sucesso

Quando a operação é bem sucedida, a resposta conterá um objeto JSON com o identificador de rastreamento do usuário que possui o identificador amigável especificado.

Resposta de Erro

Esta operação responde como erro o objeto JSON padrão de erro.

Exemplo de Requisição

POST /lumis/api/rest/lumis/monitor/v1/users/d4JdixacSOUHzGuStMaUaOAjE8VF42WI/identify HTTP/1.1
Content-Type: application/json
Accept: application/json
(... outros cabeçalhos ...)

{
	"friendlyId": "111111111111"
}

Exemplo de Resposta de Sucesso

{
	"lum_user":
	{
		"trackId": "d4JdixacSOUHzGuStMaUaOAjE8VF42WI"
	}
}

Observação sobre a privacidade do usuário

Para usuários que não possuam login, para ser possível armazenar primeiro nome (firstName), nome do meio (middleName), último nome (lastName), e-mail (email), identificador amigável (friendlyId) ou algum atributo customizado que tenha a flag Identifica usuário ligada, o usuário atualmente rastreado deve, necessariamente, ter consentido com ao menos um termo de privacidade no ambiente.