Open the menu

    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:

    Cabeçalho Valor
    Content-Type application/json
    Accept application/json

    Corpo da Requisição

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

    Propriedade Requerido Descrição Tipo
    friendlyId Não O identificador único amigável que será atribuído a este usuário. Se já existir um usuário com este identificador amigável, tal usuário será atualizado com as informações fornecidas por esta operação. Caso contrário um novo usuário será criado. string, até 255 caracteres.
    firstName Não Primeiro nome. string, até 100 caracteres.
    middleName Não Nome do meio. string, até 100 caracteres.
    lastName Não Último nome. string, até 100 caracteres.
    email Não Endereço de e-mail. string, até 255 caracteres.
    customAttributes Não Especifica valores a serem aplicados a atributos customizados. Para poder atribuir um valor a um atributo customizado, ele precisa ter sido previamente cadastrado em atributos de usuário nas configurações do portal ou na administração de atributos customizados no Modo de Customer Experience ligada ao projeto da requisição. O valor desta propriedade deve ser um objeto JSON que contém propriedades cujo nome é o identificador do atributo de usuário correspondente, e cujo valor é um valor único ou uma lista de valores a ser aplicado àquele atributo. O tipo do valor de cada elemento declarado no JSON deve corresponder ao tipo cadastrado para aquele atributo conforme a tabela abaixo:
    Tipo do atributoTipo no JSON
    booleanboolean
    double, longnumber
    keyword, string, text, urlstring
    datetimestring no formato ISO 8601 ou number com quantidade de milisegundos desde 1/1/1970 00:00 GMT. Se declarado em ISO 8601 sem fuso horário definido, será interpretado como no fuso horário padrão da JVM do LumisXP.
    		 object
    projectId Não O identificador do projeto. guid

    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.

    Propriedade Descrição Tipo Sempre Presente
    created Terá valor true se um novo usuário foi criado, ou false se um existente foi atualizado. boolean Sim
    lum_user.trackId O identificador de rastreamento do usuário criado ou atualizado. string Sim

    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:

    Cabeçalho Valor
    Content-Type application/merge-patch+json
    Accept application/json

    Parâmetros na URI

    Parâmetro Descrição
    {trackId} Identificador de rastreamento do usuário que será atualizado.

    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 o usuário com o identificador de rastreamento dado não possui identificador amigável 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 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 mas diferente do valor especificado, e se não existir um usuário com este identificador amigável, um novo usuário será criado com o identificador amigável 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, e se existir um usuário com este identificador amigável, 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:

    Cabeçalho Valor
    Content-Type application/json
    Accept application/json

    Parâmetros na URI

    Parâmetro Descrição
    {trackId} Identificador de rastreamento do usuário.

    Corpo da Requisição

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

    Propriedade Requerido Descrição Tipo
    friendlyId Sim Identificador amigável string, até 255 caracteres.

    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.

    Propriedade Descrição Tipo Sempre Presente
    lum_user.trackId O identificador de rastreamento do usuário. string Sim

    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"
	}
}

    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.