ID Batch V2

Endpoint para processar cadastros em lote de usuários (FanID) e seus dados relacionados.

📥 Collection Postman

URLs

Método	URL	Ação	Descrição
POST	`/api/v2/IF_ID_Batch`	Cadastrar	Processa cadastros em lote de usuários e seus dados

Produção:

{connect-producao}/api/v2/IF_ID_Batch

Homologação:

{connect-homologacao}/api/v2/IF_ID_Batch

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}

Processar Cadastros em Lote

Requisição

Endpoint: POST {connect-producao}/api/v2/IF_ID_Batch

Headers:

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

Estrutura do Body

Estrutura Principal

json

{
  "systemId": 0,
  "data": [
    {
      "data": { ... },
      "numbers": [ ... ],
      "sysValues": [ ... ],
      "addresses": { ... },
      "transactions": [ ... ],
      "memberships": [ ... ],
      "optins": [ ... ],
      "attributes": [ ... ],
      "pwd": "string",
      "pwdhash": "string"
    }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`systemId`	number	Sim	ID do sistema de origem (será informado pela Fanbase)
`data`	array	Sim	Array de objetos com dados dos usuários

Campos do Objeto `data` (Dados Pessoais)

json

{
  "data": {
    "identity": 0,
    "name1": "string",
    "gender": "string",
    "socialName": "string",
    "birthday": 0,
    "birthMonth": 0,
    "birthYear": 0,
    "nationalityIso3": "string"
  }
}

Campo	Tipo	Obrigatório	Descrição
`identity`	number	Sim	Manter sempre 0 para integração
`name1`	string	Sim	Nome completo
`gender`	string	Não	Gênero: `M` / `F` / `O` / `null`
`socialName`	string	Não	Apelido/Nome social
`birthday`	number	Sim	Dia do nascimento (01-31)
`birthMonth`	number	Sim	Mês do nascimento (01-12)
`birthYear`	number	Sim	Ano do nascimento (4 dígitos)
`nationalityIso3`	string	Não	Nacionalidade, formato ISO3 (ex: BRA)

Campos do Array `numbers` (Documentos)

json

{
  "numbers": [
    {
      "numberType": 0,
      "number": "string",
      "verified": 0
    }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`numberType`	number	Sim	Tipo do documento (ver tabela abaixo)
`number`	string	Sim	Número do documento (sem formatação)
`verified`	number	Não	Verificado: `0` (não) ou `1` (sim)

Tipos de Documento (numberType)

Código	Tipo
`1`	CPF
`3`	Telefone
`4`	Email

Campos do Array `sysValues` (Valores do Sistema)

Dados relevantes que não possuem ligação direta com o cadastro (ex: Número de carteirinha, Código de Sócio).

json

{
  "sysValues": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`key`	string	Sim	Chave identificadora
`value`	string	Sim	Valor associado

Campos do Objeto `addresses` (Endereço)

json

{
  "addresses": {
    "addressType": 0,
    "add1": "string",
    "add2": "string",
    "number": 0,
    "add3": "string",
    "zip": "string",
    "city": "string",
    "state": "string",
    "iso3": "string"
  }
}

Campo	Tipo	Obrigatório	Descrição
`addressType`	number	Sim	Tipo: `1` (Principal), `2` (Alternativo)
`add1`	string	Sim	Rua/Logradouro
`add2`	string	Não	Complemento
`number`	number	Não	Número da casa
`add3`	string	Sim	Bairro
`zip`	string	Sim	CEP
`city`	string	Sim	Cidade
`state`	string	Sim	Estado (2 dígitos: SP/DF/RJ/etc)
`iso3`	string	Sim	País, formato ISO3 (ex: BRA)

Campos do Array `transactions` (Transações) - Opcional

Classe opcional para adicionar dados de transações (compras de e-commerce, lojas, etc).

json

{
  "transactions": [
    {
      "date": "2025-09-20T18:41:31.219Z",
      "type": 0,
      "productType": 0,
      "productDesc": "string",
      "productExternalCode": "string",
      "qty": 0,
      "value": 0,
      "channel": "string",
      "externalCode": "string",
      "deliveryMode": "string",
      "priceType": "string",
      "cupon": "string",
      "paymentMode": "string",
      "complement": "string",
      "discount": "string",
      "discountValue": 0
    }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`date`	datetime	Sim	Data da transação (ISO 8601)
`type`	number	Sim	Tipo da transação
`productType`	number	Sim	Tipo de produto
`productDesc`	string	Sim	Descrição do produto
`productExternalCode`	string	Sim	Código do produto no sistema de origem
`qty`	number	Sim	Quantidade
`value`	number	Sim	Valor unitário
`channel`	string	Sim	Canal de venda (ex: Nome da loja)
`externalCode`	string	Sim	Código da transação no sistema de origem
`deliveryMode`	string	Não	Modo de entrega
`priceType`	string	Não	Tipo de preço
`cupon`	string	Não	Código do cupom de desconto
`paymentMode`	string	Sim	Modo de pagamento (Cartão de crédito, Pix, etc)
`complement`	string	Não	Código do item no pedido (ex: item:1, item:2)
`discount`	string	Não	Motivo do desconto
`discountValue`	number	Não	Valor do desconto

Campos do Array `memberships` (Planos de Sócio) - Opcional

Classe opcional para adicionar dados de planos de sócio.

json

{
  "memberships": [
    {
      "externalId": "string",
      "status": "string",
      "data": "2025-09-20T18:41:31.219Z",
      "cancelamento": "2025-09-20T18:41:31.219Z",
      "codigoCliente": "string",
      "plano": "string",
      "planoCode": "string",
      "complemento": "string",
      "parcelas": 0,
      "validade": "2025-09-20T18:41:31.219Z",
      "origem": "string",
      "ativacao": "2025-09-20T18:41:31.219Z",
      "tipoVigencia": "string",
      "formaPagamento": "string",
      "guests": [ ... ],
      "attributes": [ ... ]
    }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`externalId`	string	Sim	Código do contrato no sistema de origem
`status`	string	Sim	Status: Ativo/Inativo/Inadimplente/etc
`data`	datetime	Sim	Data da contratação
`cancelamento`	datetime	Não	Data de cancelamento (se cancelado)
`codigoCliente`	string	Sim	CPF ou Email do cliente
`plano`	string	Sim	Nome do plano
`planoCode`	string	Não	Código do plano no sistema de origem
`complemento`	string	Não	Outras informações do contrato
`parcelas`	number	Não	Número de parcelas pagas
`validade`	datetime	Não	Data de validade (quando não há renovação automática)
`origem`	string	Não	Canal de origem da contratação
`ativacao`	datetime	Não	Data de ativação (início da vigência)
`tipoVigencia`	string	Não	Tipo de vigência: Anual, Mensal
`formaPagamento`	string	Não	Modo de pagamento (Cartão de crédito, Pix, etc)

Dependentes/Convidados (`guests`)

json

{
  "guests": [
    {
      "guestFanbaseId": 0,
      "externalId": "string",
      "cpf": "string",
      "email": "string",
      "celular": "string",
      "name1": "string",
      "gender": "string",
      "socialName": "string",
      "birthday": 0,
      "birthMonth": 0,
      "birthYear": 0
    }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`guestFanbaseId`	number	Não	ID Fanbase existente (se conhecido)
`externalId`	string	Não	Código do dependente no sistema de origem
`cpf`	string	Não	CPF do dependente
`email`	string	Não	Email do dependente
`celular`	string	Não	Celular do dependente
`name1`	string	Não	Nome completo
`gender`	string	Não	Gênero: M/F/O/null
`socialName`	string	Não	Apelido
`birthday`	number	Não	Dia do nascimento (01-31)
`birthMonth`	number	Não	Mês do nascimento (01-12)
`birthYear`	number	Não	Ano do nascimento (4 dígitos)

Atributos do Membership (`attributes`)

json

{
  "attributes": [
    {
      "type": "string",
      "name": "string",
      "value": "string",
      "note": "string",
      "externalCode": "string"
    }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	Tipo do atributo (ex: Card)
`name`	string	Não	Nome de identificação (ex: Carteirinha)
`value`	string	Sim	Valor do atributo
`note`	string	Não	Campo livre para anotações
`externalCode`	string	Não	Código interno do atributo

Campos do Array `optins` (Opt-ins)

Informações de opt-ins (LGPD) concedidos pelo fã nos sistemas legados.

json

{
  "optins": [
    {
      "optinCode": "string",
      "optinDesc": "string",
      "optinDate": "2025-09-20T18:41:31.219Z",
      "optinCancelDate": "2025-09-20T18:41:31.219Z"
    }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`optinCode`	string	Sim	Código do opt-in (ex: USOPRIVACIDADE)
`optinDesc`	string	Sim	Descrição do opt-in
`optinDate`	datetime	Sim	Data e hora do aceite
`optinCancelDate`	datetime	Não	Data e hora de cancelamento

Campos do Array `attributes` (Atributos do Usuário)

Atributos personalizados do fã para exibição customizada no Fanbox.

Atenção

É necessário solicitar internamente a configuração dos atributos antes de usar.

json

{
  "attributes": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`key`	string	Sim	Chave de identificação do atributo
`value`	string	Sim	Valor do atributo

Campos de Senha (Criação de Conta SSO)

Criação de Conta SSO

Se você enviar o campo pwd ou pwdhash, o sistema irá criar automaticamente uma conta no SSO (Single Sign-On) para o usuário. Isso permite que o usuário faça login na plataforma usando suas credenciais.

Campo	Tipo	Obrigatório	Descrição
`pwd`	string	Não	Senha em texto plano para criação de conta
`pwdhash`	string	Não	Senha criptografada para criação de conta

Importante

Use pwd para enviar senha em texto plano (o sistema fará o hash)
Use pwdhash se já possui a senha em formato hash
Nunca envie ambos - escolha um ou outro
Se nenhum for enviado, o usuário será criado sem conta de login

Exemplo Completo - Cadastro Simples

json

{
  "systemId": 0,
  "data": [
    {
      "data": {
        "identity": 0,
        "name1": "João da Silva",
        "gender": "M",
        "socialName": "João",
        "birthday": 15,
        "birthMonth": 8,
        "birthYear": 1990,
        "nationalityIso3": "BRA"
      },
      "numbers": [
        {
          "numberType": 1,
          "number": "12345678900",
          "verified": 1
        },
        {
          "numberType": 4,
          "number": "joao@exemplo.com",
          "verified": 1
        }
      ],
      "sysValues": [
        {
          "key": "CODIGO_SOCIO",
          "value": "SOC-123456"
        }
      ],
      "addresses": {
        "addressType": 1,
        "add1": "Rua Exemplo",
        "add2": "Apto 101",
        "number": 123,
        "add3": "Centro",
        "zip": "01234567",
        "city": "São Paulo",
        "state": "SP",
        "iso3": "BRA"
      }
    }
  ]
}

Exemplo Completo - Cadastro com Plano de Sócio e Conta SSO

json

{
  "systemId": 0,
  "data": [
    {
      "data": {
        "identity": 0,
        "name1": "Maria Santos",
        "gender": "F",
        "birthday": 20,
        "birthMonth": 3,
        "birthYear": 1985,
        "nationalityIso3": "BRA"
      },
      "numbers": [
        {
          "numberType": 1,
          "number": "98765432100",
          "verified": 1
        },
        {
          "numberType": 4,
          "number": "maria@exemplo.com",
          "verified": 1
        }
      ],
      "addresses": {
        "addressType": 1,
        "add1": "Av. Principal",
        "number": 500,
        "add3": "Jardim América",
        "zip": "04567890",
        "city": "São Paulo",
        "state": "SP",
        "iso3": "BRA"
      },
      "memberships": [
        {
          "externalId": "CONTRATO-2025-001",
          "status": "Ativo",
          "data": "2025-01-15T10:00:00.000Z",
          "codigoCliente": "98765432100",
          "plano": "Plano Premium Anual",
          "planoCode": "PREMIUM-ANUAL",
          "parcelas": 12,
          "validade": "2026-01-15T10:00:00.000Z",
          "origem": "Website",
          "ativacao": "2025-01-15T10:00:00.000Z",
          "tipoVigencia": "Anual",
          "formaPagamento": "Cartão de Crédito"
        }
      ],
      "optins": [
        {
          "optinCode": "NEWSLETTER",
          "optinDesc": "Aceito receber newsletters",
          "optinDate": "2025-01-15T10:00:00.000Z"
        },
        {
          "optinCode": "SMS",
          "optinDesc": "Aceito receber SMS promocionais",
          "optinDate": "2025-01-15T10:00:00.000Z"
        }
      ],
      "pwd": "senha123"
    }
  ]
}

Resposta de Sucesso

Status: 200 OK

json

{
  "header": {
    "codigo": 1,
    "msg": "Ok"
  },
  "data": {
    "resume": {
      "total": 1,
      "success": 1,
      "fail": 0,
      "status": "SUCCESS"
    },
    "items": [
      {
        "userId": 6011883,
        "success": true,
        "cpf": "12345678900",
        "email": "joao@exemplo.com",
        "alternativeNumber": null,
        "messageError": null,
        "account": {
          "success": true,
          "login": "12345678900",
          "messageError": null
        }
      }
    ]
  }
}

Campos da Resposta

Resume

Campo	Tipo	Descrição
`total`	number	Total de usuários processados
`success`	number	Total processados com sucesso
`fail`	number	Total com erro
`status`	string	Status geral: `SUCCESS`, `PARTIAL_SUCCESS` ou `FAILURE`

Items

Campo	Tipo	Descrição
`userId`	number	ID do usuário criado (0 se não criado)
`success`	boolean	Sucesso no processamento
`cpf`	string	CPF do usuário
`email`	string	Email do usuário
`alternativeNumber`	string/null	Código alternativo
`messageError`	string/null	Mensagem de erro
`account`	object	Detalhes da conta SSO criada

Account (quando `pwd` ou `pwdhash` for enviado)

Campo	Tipo	Descrição
`success`	boolean	Se a conta SSO foi criada com sucesso
`login`	string	Login da conta (geralmente CPF)
`messageError`	string/null	Mensagem de erro na criação da conta

Exemplo de Implementação

javascript

async function processarCadastrosLote(dados, accessToken) {
  const response = await fetch('{connect-producao}/api/v2/IF_ID_Batch', {
    method: 'POST',
    headers: {
      'AccessToken': accessToken,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(dados)
  });

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

  return await response.json();
}

const dados = {
  systemId: 0,
  data: [
    {
      data: {
        identity: 0,
        name1: "João da Silva",
        birthday: 15,
        birthMonth: 8,
        birthYear: 1990
      },
      numbers: [
        { numberType: 1, number: "12345678900", verified: 1 },
        { numberType: 4, number: "joao@exemplo.com", verified: 1 }
      ],
      pwd: "senha123"
    }
  ]
};

processarCadastrosLote(dados, accessToken)
  .then(result => console.log(result))
  .catch(error => console.error(error));

Tabelas Auxiliares

Para campos como iso3 (país) e nationalityIso3 (nacionalidade), consulte a página de Tabelas Auxiliares com a lista completa de códigos ISO3 de países.

ID Batch V2 ​

URLs ​

Autenticação ​

Processar Cadastros em Lote ​

Requisição ​

Estrutura do Body ​

Estrutura Principal ​

Campos do Objeto data (Dados Pessoais) ​

Campos do Array numbers (Documentos) ​

Tipos de Documento (numberType) ​

Campos do Array sysValues (Valores do Sistema) ​

Campos do Objeto addresses (Endereço) ​

Campos do Array transactions (Transações) - Opcional ​

Campos do Array memberships (Planos de Sócio) - Opcional ​

Dependentes/Convidados (guests) ​

Atributos do Membership (attributes) ​

Campos do Array optins (Opt-ins) ​

Campos do Array attributes (Atributos do Usuário) ​

Campos de Senha (Criação de Conta SSO) ​

Exemplo Completo - Cadastro Simples ​

Exemplo Completo - Cadastro com Plano de Sócio e Conta SSO ​

Resposta de Sucesso ​

Campos da Resposta ​

Resume ​

Items ​

Account (quando pwd ou pwdhash for enviado) ​

Exemplo de Implementação ​

Tabelas Auxiliares ​

ID Batch V2

URLs

Autenticação

Processar Cadastros em Lote

Requisição

Estrutura do Body

Estrutura Principal

Campos do Objeto `data` (Dados Pessoais)

Campos do Array `numbers` (Documentos)

Tipos de Documento (numberType)

Campos do Array `sysValues` (Valores do Sistema)

Campos do Objeto `addresses` (Endereço)

Campos do Array `transactions` (Transações) - Opcional

Campos do Array `memberships` (Planos de Sócio) - Opcional

Dependentes/Convidados (`guests`)

Atributos do Membership (`attributes`)

Campos do Array `optins` (Opt-ins)

Campos do Array `attributes` (Atributos do Usuário)

Campos de Senha (Criação de Conta SSO)

Exemplo Completo - Cadastro Simples

Exemplo Completo - Cadastro com Plano de Sócio e Conta SSO

Resposta de Sucesso

Campos da Resposta

Resume

Items

Account (quando `pwd` ou `pwdhash` for enviado)

Exemplo de Implementação

Tabelas Auxiliares