ID Batch V2

Endpoint para procesar registros de usuarios en lote (FanID) y sus datos relacionados.

📥 Collection Postman

URLs

Método	URL	Acción	Descripción
POST	`/api/v2/IF_ID_Batch`	Registrar	Procesa registros de usuarios en lote y sus datos

Producción:

{connect-produccion}/api/v2/IF_ID_Batch

Homologación:

{connect-homologacion}/api/v2/IF_ID_Batch

Autenticación

Todas las solicitudes requieren un token de acceso obtenido en el endpoint de Security. El token debe enviarse en el header AccessToken.

AccessToken: {su_token}

Procesar Registros en Lote

Solicitud

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

Headers:

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

Estructura del Body

Estructura Principal

json

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

Campo	Tipo	Obligatorio	Descripción
`systemId`	number	Sí	ID del sistema de origen (será informado por Fanbase)
`data`	array	Sí	Array de objetos con datos de usuarios

Campos del Objeto `data` (Datos Personales)

json

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

Campo	Tipo	Obligatorio	Descripción
`identity`	number	Sí	Mantener siempre 0 para integración
`name1`	string	Sí	Nombre completo
`gender`	string	No	Género: `M` / `F` / `O` / `null`
`socialName`	string	No	Apodo/Nombre social
`birthday`	number	Sí	Día de nacimiento (01-31)
`birthMonth`	number	Sí	Mes de nacimiento (01-12)
`birthYear`	number	Sí	Año de nacimiento (4 dígitos)
`nationalityIso3`	string	No	Nacionalidad, formato ISO3 (ej: BRA)

Campos del Array `numbers` (Documentos)

json

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

Campo	Tipo	Obligatorio	Descripción
`numberType`	number	Sí	Tipo de documento (ver tabla abajo)
`number`	string	Sí	Número del documento (sin formato)
`verified`	number	No	Verificado: `0` (no) o `1` (sí)

Tipos de Documento (numberType)

Código	Tipo
`1`	CPF
`3`	Teléfono
`4`	Email

Campos del Array `sysValues` (Valores del Sistema)

Datos relevantes que no tienen relación directa con el registro (ej: Número de carnet, Código de Socio).

json

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

Campo	Tipo	Obligatorio	Descripción
`key`	string	Sí	Clave identificadora
`value`	string	Sí	Valor asociado

Campos del Objeto `addresses` (Dirección)

json

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

Campo	Tipo	Obligatorio	Descripción
`addressType`	number	Sí	Tipo: `1` (Principal), `2` (Alternativo)
`add1`	string	Sí	Calle/Dirección
`add2`	string	No	Complemento
`number`	number	No	Número de la casa
`add3`	string	Sí	Barrio
`zip`	string	Sí	Código postal
`city`	string	Sí	Ciudad
`state`	string	Sí	Estado (2 dígitos: SP/DF/RJ/etc)
`iso3`	string	Sí	País, formato ISO3 (ej: BRA)

Campos del Array `transactions` (Transacciones) - Opcional

Clase opcional para agregar datos de transacciones (compras de e-commerce, tiendas, 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	Obligatorio	Descripción
`date`	datetime	Sí	Fecha de la transacción (ISO 8601)
`type`	number	Sí	Tipo de transacción
`productType`	number	Sí	Tipo de producto
`productDesc`	string	Sí	Descripción del producto
`productExternalCode`	string	Sí	Código del producto en el sistema de origen
`qty`	number	Sí	Cantidad
`value`	number	Sí	Valor unitario
`channel`	string	Sí	Canal de venta (ej: Nombre de la tienda)
`externalCode`	string	Sí	Código de la transacción en el sistema de origen
`deliveryMode`	string	No	Modo de entrega
`priceType`	string	No	Tipo de precio
`cupon`	string	No	Código de cupón de descuento
`paymentMode`	string	Sí	Modo de pago (Tarjeta de crédito, Pix, etc)
`complement`	string	No	Código del ítem en el pedido (ej: item:1, item:2)
`discount`	string	No	Motivo del descuento
`discountValue`	number	No	Valor del descuento

Campos del Array `memberships` (Planes de Socio) - Opcional

Clase opcional para agregar datos de planes de socio.

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	Obligatorio	Descripción
`externalId`	string	Sí	Código del contrato en el sistema de origen
`status`	string	Sí	Estado: Activo/Inactivo/Moroso/etc
`data`	datetime	Sí	Fecha de contratación
`cancelamento`	datetime	No	Fecha de cancelación (si fue cancelado)
`codigoCliente`	string	Sí	CPF o Email del cliente
`plano`	string	Sí	Nombre del plan
`planoCode`	string	No	Código del plan en el sistema de origen
`complemento`	string	No	Otras informaciones del contrato
`parcelas`	number	No	Número de cuotas pagadas
`validade`	datetime	No	Fecha de validez (cuando no hay renovación automática)
`origem`	string	No	Canal de origen de la contratación
`ativacao`	datetime	No	Fecha de activación (inicio de vigencia)
`tipoVigencia`	string	No	Tipo de vigencia: Anual, Mensual
`formaPagamento`	string	No	Modo de pago (Tarjeta de crédito, Pix, etc)

Dependientes/Invitados (`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	Obligatorio	Descripción
`guestFanbaseId`	number	No	ID Fanbase existente (si se conoce)
`externalId`	string	No	Código del dependiente en el sistema de origen
`cpf`	string	No	CPF del dependiente
`email`	string	No	Email del dependiente
`celular`	string	No	Celular del dependiente
`name1`	string	No	Nombre completo
`gender`	string	No	Género: M/F/O/null
`socialName`	string	No	Apodo
`birthday`	number	No	Día de nacimiento (01-31)
`birthMonth`	number	No	Mes de nacimiento (01-12)
`birthYear`	number	No	Año de nacimiento (4 dígitos)

Atributos del Membership (`attributes`)

json

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

Campo	Tipo	Obligatorio	Descripción
`type`	string	Sí	Tipo del atributo (ej: Card)
`name`	string	No	Nombre de identificación (ej: Carnet)
`value`	string	Sí	Valor del atributo
`note`	string	No	Campo libre para anotaciones
`externalCode`	string	No	Código interno del atributo

Campos del Array `optins` (Opt-ins)

Información de opt-ins (LGPD/GDPR) concedidos por el fan en los sistemas legados.

json

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

Campo	Tipo	Obligatorio	Descripción
`optinCode`	string	Sí	Código del opt-in (ej: USOPRIVACIDAD)
`optinDesc`	string	Sí	Descripción del opt-in
`optinDate`	datetime	Sí	Fecha y hora de aceptación
`optinCancelDate`	datetime	No	Fecha y hora de cancelación

Campos del Array `attributes` (Atributos del Usuario)

Atributos personalizados del fan para visualización customizada en Fanbox.

Atención

Es necesario solicitar internamente la configuración de los atributos antes de usar.

json

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

Campo	Tipo	Obligatorio	Descripción
`key`	string	Sí	Clave de identificación del atributo
`value`	string	Sí	Valor del atributo

Campos de Contraseña (Creación de Cuenta SSO)

Creación de Cuenta SSO

Si envía el campo pwd o pwdhash, el sistema creará automáticamente una cuenta en el SSO (Single Sign-On) para el usuario. Esto permite que el usuario inicie sesión en la plataforma usando sus credenciales.

Campo	Tipo	Obligatorio	Descripción
`pwd`	string	No	Contraseña en texto plano para creación de cuenta
`pwdhash`	string	No	Contraseña encriptada para creación de cuenta

Importante

Use pwd para enviar contraseña en texto plano (el sistema hará el hash)
Use pwdhash si ya tiene la contraseña en formato hash
Nunca envíe ambos - elija uno u otro
Si ninguno es enviado, el usuario será creado sin cuenta de login

Ejemplo Completo - Registro Simple

json

{
  "systemId": 0,
  "data": [
    {
      "data": {
        "identity": 0,
        "name1": "Juan García",
        "gender": "M",
        "socialName": "Juan",
        "birthday": 15,
        "birthMonth": 8,
        "birthYear": 1990,
        "nationalityIso3": "BRA"
      },
      "numbers": [
        {
          "numberType": 1,
          "number": "12345678900",
          "verified": 1
        },
        {
          "numberType": 4,
          "number": "juan@ejemplo.com",
          "verified": 1
        }
      ],
      "sysValues": [
        {
          "key": "CODIGO_SOCIO",
          "value": "SOC-123456"
        }
      ],
      "addresses": {
        "addressType": 1,
        "add1": "Calle Ejemplo",
        "add2": "Depto 101",
        "number": 123,
        "add3": "Centro",
        "zip": "01234567",
        "city": "São Paulo",
        "state": "SP",
        "iso3": "BRA"
      }
    }
  ]
}

Ejemplo Completo - Registro con Plan de Socio y Cuenta SSO

json

{
  "systemId": 0,
  "data": [
    {
      "data": {
        "identity": 0,
        "name1": "María Santos",
        "gender": "F",
        "birthday": 20,
        "birthMonth": 3,
        "birthYear": 1985,
        "nationalityIso3": "BRA"
      },
      "numbers": [
        {
          "numberType": 1,
          "number": "98765432100",
          "verified": 1
        },
        {
          "numberType": 4,
          "number": "maria@ejemplo.com",
          "verified": 1
        }
      ],
      "addresses": {
        "addressType": 1,
        "add1": "Av. Principal",
        "number": 500,
        "add3": "Jardín América",
        "zip": "04567890",
        "city": "São Paulo",
        "state": "SP",
        "iso3": "BRA"
      },
      "memberships": [
        {
          "externalId": "CONTRATO-2025-001",
          "status": "Activo",
          "data": "2025-01-15T10:00:00.000Z",
          "codigoCliente": "98765432100",
          "plano": "Plan 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": "Tarjeta de Crédito"
        }
      ],
      "optins": [
        {
          "optinCode": "NEWSLETTER",
          "optinDesc": "Acepto recibir newsletters",
          "optinDate": "2025-01-15T10:00:00.000Z"
        },
        {
          "optinCode": "SMS",
          "optinDesc": "Acepto recibir SMS promocionales",
          "optinDate": "2025-01-15T10:00:00.000Z"
        }
      ],
      "pwd": "contraseña123"
    }
  ]
}

Respuesta de Éxito

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": "juan@ejemplo.com",
        "alternativeNumber": null,
        "messageError": null,
        "account": {
          "success": true,
          "login": "12345678900",
          "messageError": null
        }
      }
    ]
  }
}

Campos de la Respuesta

Resume

Campo	Tipo	Descripción
`total`	number	Total de usuarios procesados
`success`	number	Total procesados con éxito
`fail`	number	Total con error
`status`	string	Estado general: `SUCCESS`, `PARTIAL_SUCCESS` o `FAILURE`

Items

Campo	Tipo	Descripción
`userId`	number	ID del usuario creado (0 si no fue creado)
`success`	boolean	Éxito en el procesamiento
`cpf`	string	CPF del usuario
`email`	string	Email del usuario
`alternativeNumber`	string/null	Código alternativo
`messageError`	string/null	Mensaje de error
`account`	object	Detalles de la cuenta SSO creada

Account (cuando `pwd` o `pwdhash` es enviado)

Campo	Tipo	Descripción
`success`	boolean	Si la cuenta SSO fue creada con éxito
`login`	string	Login de la cuenta (generalmente CPF)
`messageError`	string/null	Mensaje de error en la creación de la cuenta

Ejemplo de Implementación

javascript

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

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

  return await response.json();
}

const datos = {
  systemId: 0,
  data: [
    {
      data: {
        identity: 0,
        name1: "Juan García",
        birthday: 15,
        birthMonth: 8,
        birthYear: 1990
      },
      numbers: [
        { numberType: 1, number: "12345678900", verified: 1 },
        { numberType: 4, number: "juan@ejemplo.com", verified: 1 }
      ],
      pwd: "contraseña123"
    }
  ]
};

procesarRegistrosLote(datos, accessToken)
  .then(result => console.log(result))
  .catch(error => console.error(error));

Tablas Auxiliares

Para campos como iso3 (país) y nationalityIso3 (nacionalidad), consulte la página de Tablas Auxiliares con la lista completa de códigos ISO3 de países.

ID Batch V2 ​

URLs ​

Autenticación ​

Procesar Registros en Lote ​

Solicitud ​

Estructura del Body ​

Estructura Principal ​

Campos del Objeto data (Datos Personales) ​

Campos del Array numbers (Documentos) ​

Tipos de Documento (numberType) ​

Campos del Array sysValues (Valores del Sistema) ​

Campos del Objeto addresses (Dirección) ​

Campos del Array transactions (Transacciones) - Opcional ​

Campos del Array memberships (Planes de Socio) - Opcional ​

Dependientes/Invitados (guests) ​

Atributos del Membership (attributes) ​

Campos del Array optins (Opt-ins) ​

Campos del Array attributes (Atributos del Usuario) ​

Campos de Contraseña (Creación de Cuenta SSO) ​

Ejemplo Completo - Registro Simple ​

Ejemplo Completo - Registro con Plan de Socio y Cuenta SSO ​

Respuesta de Éxito ​

Campos de la Respuesta ​

Resume ​

Items ​

Account (cuando pwd o pwdhash es enviado) ​

Ejemplo de Implementación ​

Tablas Auxiliares ​

ID Batch V2

URLs

Autenticación

Procesar Registros en Lote

Solicitud

Estructura del Body

Estructura Principal

Campos del Objeto `data` (Datos Personales)

Campos del Array `numbers` (Documentos)

Tipos de Documento (numberType)

Campos del Array `sysValues` (Valores del Sistema)

Campos del Objeto `addresses` (Dirección)

Campos del Array `transactions` (Transacciones) - Opcional

Campos del Array `memberships` (Planes de Socio) - Opcional

Dependientes/Invitados (`guests`)

Atributos del Membership (`attributes`)

Campos del Array `optins` (Opt-ins)

Campos del Array `attributes` (Atributos del Usuario)

Campos de Contraseña (Creación de Cuenta SSO)

Ejemplo Completo - Registro Simple

Ejemplo Completo - Registro con Plan de Socio y Cuenta SSO

Respuesta de Éxito

Campos de la Respuesta

Resume

Items

Account (cuando `pwd` o `pwdhash` es enviado)

Ejemplo de Implementación

Tablas Auxiliares