Eventos APP

Endpoint para registro de usuários e eventos de aplicativos móveis.

📥 Collection Postman

URLs

Método	URL	Ação	Descrição
POST	`/api/v1/app/registeruser`	Cadastrar	Registra ID de dispositivo no FanID existente
POST	`/api/v1/app/event`	Cadastrar	Adiciona eventos usando User ID

Produção:

{connect-producao}/api/v1/app

Homologação:

{connect-homologacao}/api/v1/app

Autenticação

Todas as requisições requerem um token de acesso obtido no endpoint de Security. O token deve ser enviado no header AccessToken.

AccessToken: {seu_token}

Sobre a Autenticação

O token de acesso deve ser obtido através do endpoint de Security usando client_credentials. Consulte a seção Obter Token para mais detalhes.

1. Registrar Usuário do App

Associa um ID de dispositivo (userId) a um FanID existente, identificado por CPF ou Email.

Requisição

Endpoint: POST {connect-producao}/api/v1/app/registeruser

Headers:

AccessToken: {access_token}
Content-Type: application/json

Body - Identificação por Email

json

{
  "userId": "abc123def345",
  "document": "email@provider.net",
  "documentType": 4,
  "appName": "APPNAME",
  "appPlatform": "android"
}

Body - Identificação por CPF

json

{
  "userId": "abc123def345",
  "document": "22701153840",
  "documentType": 1,
  "appName": "APPNAME",
  "appPlatform": "android"
}

Campos do Body

Campo	Tipo	Obrigatório	Descrição
`userId`	string	Sim	ID único do dispositivo/usuário no app
`document`	string	Sim	CPF ou Email do usuário (sem formatação)
`documentType`	number	Sim	Tipo do documento (ver tabela abaixo)
`appName`	string	Sim	Nome do aplicativo
`appPlatform`	string	Sim	Plataforma: `android` ou `ios`

Tipos de Documento (documentType)

Código	Tipo	Exemplo
`1`	CPF	`22701153840` (sem pontos ou traços)
`4`	Email	`usuario@exemplo.com`

Resposta de Sucesso

Status: 201 Created

json

{
  "header": {
    "codigo": 1,
    "msg": "Usuário registrado com sucesso"
  }
}

Possíveis Erros

Código	Mensagem	Descrição
400	Documento inválido	CPF ou Email não encontrado
400	userId já registrado	O userId já está associado a outro usuário
401	Token inválido	Token de acesso inválido ou expirado

2. Registrar Eventos

Registra eventos de uso do aplicativo associados a um userId previamente registrado.

Requisição

Endpoint: POST {connect-producao}/api/v1/app/event

Headers:

AccessToken: {access_token}
Content-Type: application/json

Body

json

{
  "userId": "abc123def345",
  "eventName": "first_access",
  "eventValue": null,
  "eventDate": "2025-07-29T03:00:02.135Z",
  "appName": "APPNAME"
}

Campos do Body

Campo	Tipo	Obrigatório	Descrição
`userId`	string	Sim	ID único do dispositivo (registrado anteriormente)
`eventName`	string	Sim	Nome do evento
`eventValue`	string/null	Não	Valor associado ao evento
`eventDate`	datetime	Sim	Data/hora do evento (ISO 8601)
`appName`	string	Sim	Nome do aplicativo

Exemplos de Eventos

Primeiro Acesso

json

{
  "userId": "abc123def345",
  "eventName": "first_access",
  "eventValue": null,
  "eventDate": "2025-07-29T03:00:02.135Z",
  "appName": "APPNAME"
}

Acesso a uma Página/Rota

json

{
  "userId": "abc123def345",
  "eventName": "page_access",
  "eventValue": "/wallet",
  "eventDate": "2025-07-29T03:05:15.000Z",
  "appName": "APPNAME"
}

Compra no App

json

{
  "userId": "abc123def345",
  "eventName": "purchase",
  "eventValue": "{\"productId\": \"123\", \"value\": 99.90}",
  "eventDate": "2025-07-29T03:10:00.000Z",
  "appName": "APPNAME"
}

json

{
  "userId": "abc123def345",
  "eventName": "login",
  "eventValue": "biometric",
  "eventDate": "2025-07-29T03:00:00.000Z",
  "appName": "APPNAME"
}

Eventos Sugeridos

Evento	Descrição	eventValue
`first_access`	Primeiro acesso ao app	`null`
`login`	Login realizado	Método (biometric, password, etc)
`logout`	Logout realizado	`null`
`page_access`	Acesso a página/rota	Caminho da rota
`purchase`	Compra realizada	JSON com detalhes
`share`	Conteúdo compartilhado	Tipo de conteúdo
`notification_open`	Notificação aberta	ID da notificação

Dica

Use o campo eventValue para armazenar dados adicionais do evento. Para dados complexos, use JSON string.

Resposta de Sucesso

Status: 201 Created

json

{
  "header": {
    "codigo": 1,
    "msg": "Evento registrado com sucesso"
  }
}

Possíveis Erros

Código	Mensagem	Descrição
400	userId não encontrado	O userId não foi registrado anteriormente
401	Token inválido	Token de acesso inválido ou expirado

Exemplo de Implementação Completa

javascript

class FanbaseAppEvents {
  constructor(accessToken, connectUrl, appName) {
    this.accessToken = accessToken;
    this.connectUrl = connectUrl;
    this.appName = appName;
  }

  async registrarUsuario(userId, document, documentType, platform) {
    const response = await fetch(`${this.connectUrl}/api/v1/app/registeruser`, {
      method: 'POST',
      headers: {
        'AccessToken': this.accessToken,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        userId,
        document,
        documentType,
        appName: this.appName,
        appPlatform: platform
      })
    });

    if (!response.ok) {
      throw new Error(`Erro ${response.status}: ${response.statusText}`);
    }

    return await response.json();
  }

  async registrarEvento(userId, eventName, eventValue = null) {
    const response = await fetch(`${this.connectUrl}/api/v1/app/event`, {
      method: 'POST',
      headers: {
        'AccessToken': this.accessToken,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        userId,
        eventName,
        eventValue: typeof eventValue === 'object' ? JSON.stringify(eventValue) : eventValue,
        eventDate: new Date().toISOString(),
        appName: this.appName
      })
    });

    if (!response.ok) {
      throw new Error(`Erro ${response.status}: ${response.statusText}`);
    }

    return await response.json();
  }
}

// Exemplo de uso
const fanbase = new FanbaseAppEvents(
  accessToken,
  '{connect-producao}',
  'MeuApp'
);

// Registrar usuário por email
await fanbase.registrarUsuario(
  'device-123456',
  'usuario@exemplo.com',
  4, // Email
  'android'
);

// Registrar evento de primeiro acesso
await fanbase.registrarEvento('device-123456', 'first_access');

// Registrar acesso a uma página
await fanbase.registrarEvento('device-123456', 'page_access', '/home');

// Registrar compra
await fanbase.registrarEvento('device-123456', 'purchase', {
  productId: '123',
  value: 99.90,
  quantity: 1
});

Fluxo Recomendado

mermaid

sequenceDiagram
    participant App
    participant Fanbase
    
    App->>Fanbase: 1. Obter Token (Security)
    Fanbase-->>App: access_token
    
    App->>Fanbase: 2. Registrar Usuário
    Note right of App: userId + CPF/Email
    Fanbase-->>App: Sucesso
    
    loop A cada evento
        App->>Fanbase: 3. Registrar Evento
        Fanbase-->>App: Sucesso
    end

Obter Token - Autenticar com Security usando client_credentials
Registrar Usuário - Associar userId do dispositivo ao FanID (uma vez)
Registrar Eventos - Enviar eventos de uso conforme acontecem no app

Eventos APP ​

URLs ​

Autenticação ​

1. Registrar Usuário do App ​

Requisição ​

Body - Identificação por Email ​

Body - Identificação por CPF ​

Campos do Body ​

Tipos de Documento (documentType) ​

Resposta de Sucesso ​

Possíveis Erros ​

2. Registrar Eventos ​

Requisição ​

Body ​

Campos do Body ​

Exemplos de Eventos ​

Primeiro Acesso ​

Acesso a uma Página/Rota ​

Compra no App ​

Login no App ​

Eventos Sugeridos ​

Resposta de Sucesso ​

Possíveis Erros ​

Exemplo de Implementação Completa ​

Fluxo Recomendado ​

Eventos APP

URLs

Autenticação

1. Registrar Usuário do App

Requisição

Body - Identificação por Email

Body - Identificação por CPF

Campos do Body

Tipos de Documento (documentType)

Resposta de Sucesso

Possíveis Erros

2. Registrar Eventos

Requisição

Body

Campos do Body

Exemplos de Eventos

Primeiro Acesso

Acesso a uma Página/Rota

Compra no App

Login no App

Eventos Sugeridos

Resposta de Sucesso

Possíveis Erros

Exemplo de Implementação Completa

Fluxo Recomendado