Documentación API

🔑 Autenticación

Antes de llamar a cualquier acción, se debe obtener un JWT token enviando las credenciales al endpoint de autenticación. El token luego se incluye en cada request como header Authorization: Bearer {token}.

POST

/onzecrm/token — Obtener token JWT

Autentica al comercio y devuelve un JWT Bearer token

▼

ℹ️ Este endpoint no requiere el header Authorization. Solo necesita el header api-key.

Headers requeridos

Header	Valor	Descripción
`api-key`	REQUERIDO	Clave de acceso de la aplicación registrada
`Content-Type`	`application/xml`	Formato del cuerpo

Campos del request

Campo	Tipo	Requerido	Descripción
`auth/user`	string	SÍ	Nombre de usuario del comercio
`auth/pass`	string	SÍ	Contraseña del comercio

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <auth>
    <user>mi_usuario</user>
    <pass>mi_contraseña</pass>
  </auth>
</MensajeFidelyGb>

Campos de la respuesta

Campo	Tipo	Descripción
`RespCode`	integer	0 = éxito \| 1 = error
`RespMsg`	string	Mensaje descriptivo
`auth/token`	string	JWT Bearer token para usar en requests siguientes
`auth/exp`	datetime	Fecha y hora de expiración del token

<?xml version="1.0" encoding="utf-8"?>
<RespuestaFidelyGb>
  <RespCode>0</RespCode>
  <RespMsg></RespMsg>
  <auth>
    <token>eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...</token>
    <exp>2026-03-19 10:00:00</exp>
  </auth>
</RespuestaFidelyGb>

// PHP — Obtener token y usar en una acción
$host   = 'https://api.ejemplo.com';
$apiKey = 'mi_api_key';

// 1. Autenticar
$ch = curl_init("$host/onzecrm/token");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "api-key: $apiKey",
        "Content-Type: application/xml"
    ],
    CURLOPT_POSTFIELDS => '<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb><auth><user>mi_usuario</user><pass>mi_clave</pass></auth></MensajeFidelyGb>',
]);
$resp  = curl_exec($ch);
curl_close($ch);

$xml   = simplexml_load_string($resp);
$token = (string) $xml->auth->token;

// 2. Usar el token
$ch = curl_init("$host/onzecrm/");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer $token",
        "api-key: $apiKey",
        "Content-Type: application/xml"
    ],
    CURLOPT_POSTFIELDS => '<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>300</CodAccion>
  <NroTarjeta>30123456</NroTarjeta>
</MensajeFidelyGb>',
]);
echo curl_exec($ch);
curl_close($ch);

# Python — requests
import requests
import xml.etree.ElementTree as ET

host    = "https://api.ejemplo.com"
api_key = "mi_api_key"

# 1. Autenticar
auth_xml = """<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <auth>
    <user>mi_usuario</user>
    <pass>mi_clave</pass>
  </auth>
</MensajeFidelyGb>"""

r = requests.post(
    f"{host}/onzecrm/token",
    data=auth_xml.encode("utf-8"),
    headers={"api-key": api_key, "Content-Type": "application/xml"}
)
token = ET.fromstring(r.text).find("auth/token").text

# 2. Usar el token
payload = """<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>300</CodAccion>
  <NroTarjeta>30123456</NroTarjeta>
</MensajeFidelyGb>"""

resp = requests.post(
    f"{host}/onzecrm/",
    data=payload.encode("utf-8"),
    headers={
        "Authorization": f"Bearer {token}",
        "api-key": api_key,
        "Content-Type": "application/xml"
    }
)
print(resp.text)

// C# — HttpClient
using System.Net.Http;
using System.Text;
using System.Xml.Linq;

var host   = "https://api.ejemplo.com";
var apiKey = "mi_api_key";
var client = new HttpClient();

// 1. Autenticar
var authXml = @"<?xml version=""1.0"" encoding=""utf-8""?>
<MensajeFidelyGb><auth><user>mi_usuario</user><pass>mi_clave</pass></auth></MensajeFidelyGb>";

var req = new HttpRequestMessage(HttpMethod.Post, $"{host}/onzecrm/token");
req.Headers.Add("api-key", apiKey);
req.Content = new StringContent(authXml, Encoding.UTF8, "application/xml");

var res   = await client.SendAsync(req);
var body  = await res.Content.ReadAsStringAsync();
var token = XDocument.Parse(body).Root.Element("auth").Element("token").Value;

// 2. Usar el token
var payload = @"<?xml version=""1.0"" encoding=""utf-8""?>
<MensajeFidelyGb>
  <CodAccion>300</CodAccion>
  <NroTarjeta>30123456</NroTarjeta>
</MensajeFidelyGb>";

var req2 = new HttpRequestMessage(HttpMethod.Post, $"{host}/onzecrm/");
req2.Headers.Add("Authorization", $"Bearer {token}");
req2.Headers.Add("api-key", apiKey);
req2.Content = new StringContent(payload, Encoding.UTF8, "application/xml");

Console.WriteLine(await (await client.SendAsync(req2)).Content.ReadAsStringAsync());

Headers para todas las demás peticiones

Header	Valor	Requerido
`Authorization`	`Bearer {token}`	SÍ
`api-key`	`{api_key}`	SÍ
`Content-Type`	`application/xml`	SÍ

📨 Estructura general de respuesta

Todas las respuestas de la API siguen el mismo envelope XML. El resultado real se determina leyendo RespCode, ya que la API siempre devuelve HTTP 200 independientemente del resultado del negocio.

<?xml version="1.0" encoding="utf-8"?>
<RespuestaFidelyGb>
  <RespCode>0</RespCode>   <!-- 0 = éxito | 1 = error -->
  <RespMsg>Mensaje descriptivo</RespMsg>
  <!-- Nodo específico según la acción: <Cliente>, <Venta>, <Movimiento>, etc. -->
</RespuestaFidelyGb>

⚠️ La API siempre responde con HTTP 200. Siempre verificar el valor de <RespCode> para determinar si la operación fue exitosa.

📋 Índice de acciones (CodAccion)

CodAccion	Descripción	Módulo
👤 Clientes
100 / 103	Alta de cliente	Clientes
110	Alta masiva de clientes (bulk import)	Clientes
101	Modificar cliente	Clientes
104	Actualizar suscripción/difusiones	Clientes
300	Consultar cliente	Clientes
301	Consultar movimientos del cliente	Clientes
302	Consultar novedades por rango de fechas	Clientes
🛒 Ventas
200	Nueva venta / acumulación de puntos	Ventas
201	Devolución / anulación parcial	Ventas
202	Cancelación de venta	Ventas
601	Actualizar número de comprobante	Ventas
⭐ Puntos
600	Ajuste manual de puntos (acreditar/descontar)	Puntos
🎟️ Cupones
700	Alta de cupón	Cupones
701	Modificar cupón	Cupones
702	Deshabilitar cupón	Cupones
703	Validar cupón y puntos (sin procesar)	Cupones
📦 Productos
500	Alta de producto	Productos
501	Modificar producto	Productos
502	Deshabilitar producto	Productos
503	Reactivar producto	Productos
504	Actualizar precios de producto	Productos
🏷️ Tags / Mensajería / Suscripciones
800	Asignación masiva de tags	Tags
801	Envío de plantilla de mensaje	Mensajería
802	Marcar mensaje como contestado	Mensajería
900	Crear suscripción	Suscripciones
901	Modificar suscripción	Suscripciones
902	Activar / Desactivar suscripción	Suscripciones
903	Eliminar suscripción	Suscripciones
📄 Integración por archivo
—	Envío de ventas, devoluciones y anulaciones en archivo CSV (multipart, sin XML)	Archivo

👤 Clientes

100 / 103

Alta de cliente

Registra un nuevo cliente en el programa de fidelidad. Si ya existe, ejecuta una actualización automática.

▼

ℹ️ CodAccion 100: usa el campo NroTarjeta como número de tarjeta. CodAccion 103: usa el DNI como número de tarjeta (ignora NroTarjeta). Si el cliente ya existe con el mismo DNI y comercio, se ejecuta automáticamente una actualización (101).

Campo	Tipo	Requerido	Validación	Descripción
`CodAccion`	integer	SÍ	100 ó 103	Código de la acción
`Cliente/DNI`	string	SÍ	Solo dígitos, mínimo 7	Documento de identidad
`Cliente/NroTarjeta`	string	NO	max:45	Nro. tarjeta fidelidad (solo CodAccion 100)
`Cliente/Nombre`	string	COND	max:100	Nombre (obligatorio según config. campaña)
`Cliente/Apellido`	string	COND	max:100	Apellido (obligatorio según config. campaña)
`Cliente/Sexo`	string	COND	M \| F	Sexo
`Cliente/FecNac`	string	COND	dd/mm/yyyy	Fecha de nacimiento
`Cliente/Email`	string	COND	email, max:100	Correo electrónico
`Cliente/Telefono`	string	COND	max:45	Teléfono
`Cliente/Direccion`	string	NO	max:100	Domicilio
`Cliente/CodPostal`	string	NO	max:10	Código postal
`Cliente/Localidad`	string	NO	max:100	Localidad
`Cliente/Provincia`	string	NO	max:100	Provincia
`Cliente/Categoria`	integer	SÍ	Debe pertenecer a la Campaña	ID de categoría del cliente
`Cliente/Campania`	integer	SÍ	Comercio debe estar adherido	ID de la campaña
`Cliente/RecibeDifusiones`	string	NO	S \| N \| 1 \| 0	Acepta comunicaciones
`Cliente/GrupoInteres`	integer	NO	—	ID de grupo de interés
`Cliente/Usuario`	string	NO	max:45	Usuario para login de cliente
`Cliente/Clave`	string	NO	max:45	Contraseña para login de cliente
`Cliente/CamposPersonalizados`	—	NO	—	Contenedor de campos personalizados de la campaña
`Cliente/CamposPersonalizados/{NombreTecnico}`	string	NO	—	Cada nodo hijo es el nombre técnico del campo personalizado configurado en la campaña. Puede repetirse para múltiples campos.
`tags`	string	NO	IDs separados por coma	Tags a asignar (ej: "1,4,7")

Campos personalizados: los nombres de los nodos dentro de <CamposPersonalizados> deben coincidir (sin distinguir mayúsculas) con el NombreTecnico de los campos configurados en la tabla campospersonalizados para la campaña indicada. El valor se guarda (o actualiza si ya existe) en clientes_campospersonalizados.

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>100</CodAccion>
  <Cliente>
    <DNI>30123456</DNI>
    <NroTarjeta>30123456</NroTarjeta>
    <Nombre>Juan</Nombre>
    <Apellido>Pérez</Apellido>
    <Sexo>M</Sexo>
    <FecNac>15/06/1985</FecNac>
    <Email>juan@email.com</Email>
    <Telefono>1155554444</Telefono>
    <Direccion>Av. Corrientes 1234</Direccion>
    <CodPostal>1043</CodPostal>
    <Localidad>Buenos Aires</Localidad>
    <Provincia>Buenos Aires</Provincia>
    <Categoria>5</Categoria>
    <Campania>12</Campania>
    <RecibeDifusiones>S</RecibeDifusiones>
    <GrupoInteres>3</GrupoInteres>
    <CamposPersonalizados>
      <nivel_vip>gold</nivel_vip>
      <sucursal_origen>Centro</sucursal_origen>
    </CamposPersonalizados>
  </Cliente>
  <tags>1,4,7</tags>
</MensajeFidelyGb>

Campo	Tipo	Descripción
`RespCode`	integer	0 = éxito \| 1 = error
`RespMsg`	string	Mensaje descriptivo
`Cliente/IDClienteFidely`	integer	ID interno asignado al cliente
`Cliente/NroTarjeta`	string	Número de tarjeta del cliente
`Cliente/GrupoInteres`	string	Nombre del grupo de interés asignado

<!-- Respuesta exitosa -->
<?xml version="1.0" encoding="utf-8"?>
<RespuestaFidelyGb>
  <RespCode>0</RespCode>
  <RespMsg>Cliente Fidelizado con éxito</RespMsg>
  <Cliente>
    <IDClienteFidely>4821</IDClienteFidely>
    <NroTarjeta>30123456</NroTarjeta>
    <GrupoInteres>Jóvenes</GrupoInteres>
  </Cliente>
</RespuestaFidelyGb>

<!-- Error: DNI inválido -->
<RespuestaFidelyGb>
  <RespCode>1</RespCode>
  <RespMsg>DNI Inválido</RespMsg>
  <Cliente>
    <IDClienteFidely>0</IDClienteFidely>
    <NroTarjeta>abc</NroTarjeta>
  </Cliente>
</RespuestaFidelyGb>

110

Alta masiva de clientes (bulk import)

Registra varios clientes en una sola petición. Procesa cada cliente como un alta individual (CodAccion 103) y devuelve un resumen agregado.

▼

ℹ️ El mensaje incluye uno o varios nodos <Cliente>. Cada cliente se procesa internamente como un alta CodAccion 103 (el DNI se usa como número de tarjeta). Si un cliente ya existe con el mismo DNI y comercio, se actualiza automáticamente. El proceso no se detiene ante errores: los clientes que fallan se omiten y se contabilizan en el resumen final.

Importante: la respuesta es un resumen agregado, no devuelve el IDClienteFidely de cada cliente. El detalle de los errores por cliente queda registrado en los logs del servidor (canal Bulk Cliente).

Campo	Tipo	Requerido	Validación	Descripción
`CodAccion`	integer	SÍ	110	Código de la acción
`Cliente`	nodo	SÍ	1..N nodos	Repetir un nodo `<Cliente>` por cada cliente a dar de alta
`Cliente/*`	—	COND	Igual que CodAccion 103	Cada nodo `<Cliente>` admite los mismos campos que el alta individual (DNI, Nombre, Apellido, Email, Categoria, Campania, etc.)

Los campos de cada <Cliente> son idénticos a los de CodAccion 100 / 103, incluyendo <CamposPersonalizados>. El DNI es obligatorio y se usa como número de tarjeta.

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>110</CodAccion>
  <Cliente>
    <DNI>30123456</DNI>
    <Nombre>Juan</Nombre>
    <Apellido>Pérez</Apellido>
    <Email>juan@email.com</Email>
    <Categoria>5</Categoria>
    <Campania>12</Campania>
  </Cliente>
  <Cliente>
    <DNI>27888777</DNI>
    <Nombre>Ana</Nombre>
    <Apellido>Gómez</Apellido>
    <Email>ana@email.com</Email>
    <Categoria>5</Categoria>
    <Campania>12</Campania>
  </Cliente>
</MensajeFidelyGb>

Campo	Tipo	Descripción
`RespCode`	integer	0 = todos los clientes se procesaron sin errores \| 1 = hubo uno o más errores
`RespMsg`	string	Resumen: cantidad de clientes procesados y, si los hubo, cantidad de errores

<!-- Todos procesados correctamente -->
<?xml version="1.0" encoding="utf-8"?>
<RespuestaFidelyGb>
  <RespCode>0</RespCode>
  <RespMsg>Se procesaron 2 clientes.</RespMsg>
</RespuestaFidelyGb>

<!-- Procesado parcial: algunos clientes fallaron -->
<RespuestaFidelyGb>
  <RespCode>1</RespCode>
  <RespMsg>Procesados 1. Errores: 1</RespMsg>
</RespuestaFidelyGb>

101

Modificar cliente

Actualiza los datos de un cliente existente identificado por IDClienteFidely.

▼

Campo	Tipo	Requerido	Descripción
`Cliente/IDClienteFidely`	integer	SÍ	ID del cliente a modificar
`Cliente/DNI`	string	SÍ	DNI (no puede duplicarse en otro cliente)
`Cliente/Campania`	integer	SÍ	ID de la campaña
`Cliente/Categoria`	integer	SÍ	ID de la categoría
`Cliente/(otros campos)`	—	COND	Mismos campos que CodAccion 100, según config. campaña
`Cliente/CamposPersonalizados`	—	NO	Contenedor de campos personalizados de la campaña
`Cliente/CamposPersonalizados/{NombreTecnico}`	string	NO	Cada nodo hijo es el nombre técnico del campo personalizado. Si ya existe un valor para el cliente, se sobreescribe.

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>101</CodAccion>
  <Cliente>
    <IDClienteFidely>4821</IDClienteFidely>
    <DNI>30123456</DNI>
    <Campania>12</Campania>
    <Categoria>5</Categoria>
    <Nombre>Juan Carlos</Nombre>
    <Apellido>Pérez</Apellido>
    <Email>juanc@email.com</Email>
    <Telefono>1166667777</Telefono>
    <CamposPersonalizados>
      <nivel_vip>platinum</nivel_vip>
    </CamposPersonalizados>
  </Cliente>
</MensajeFidelyGb>

<?xml version="1.0" encoding="utf-8"?>
<RespuestaFidelyGb>
  <RespCode>0</RespCode>
  <RespMsg>Cliente Fidelizado con éxito</RespMsg>
  <Cliente>
    <IDClienteFidely>4821</IDClienteFidely>
    <NroTarjeta>30123456</NroTarjeta>
    <GrupoInteres>Jóvenes</GrupoInteres>
  </Cliente>
</RespuestaFidelyGb>

104

Actualizar suscripción / difusiones

Modifica la preferencia del cliente para recibir comunicaciones y difusiones.

▼

Campo	Tipo	Requerido	Descripción
`NroTarjeta`	string	SÍ	Número de tarjeta del cliente
`RecibeDifusiones`	string	SÍ	S \| SI \| 1 = suscripto / N \| NO \| 0 = no suscripto

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>104</CodAccion>
  <NroTarjeta>30123456</NroTarjeta>
  <RecibeDifusiones>S</RecibeDifusiones>
</MensajeFidelyGb>

<?xml version="1.0" encoding="utf-8"?>
<RespuestaFidelyGb>
  <RespCode>0</RespCode>
  <RespMsg>Suscripcion de Cliente modificada con éxito</RespMsg>
  <Cliente>
    <IDClienteFidely>4821</IDClienteFidely>
    <Campania>12</Campania>
    <Categoria>5</Categoria>
    <RecibeDifusiones>S</RecibeDifusiones>
  </Cliente>
</RespuestaFidelyGb>

300

Consultar cliente

Devuelve los datos completos de un cliente, incluyendo saldo de puntos y categoría.

▼

Campo	Tipo	Requerido	Descripción
`NroTarjeta`	string	SÍ	Número de tarjeta del cliente

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>300</CodAccion>
  <NroTarjeta>30123456</NroTarjeta>
</MensajeFidelyGb>

Campo	Tipo	Descripción
`Cliente/IDClienteFidely`	integer	ID interno del cliente
`Cliente/Campania`	integer	ID de campaña asociada
`Cliente/Categoria`	integer	ID de categoría
`Cliente/Nombre`	string	Nombre
`Cliente/Apellido`	string	Apellido
`Cliente/FecNac`	string	Fecha de nacimiento (dd/mm/yyyy)
`Cliente/Dni`	string	Documento de identidad
`Cliente/Telefono`	string	Teléfono
`Cliente/Direccion`	string	Domicilio
`Cliente/Email`	string	Correo electrónico
`Cliente/Sexo`	string	M \| F
`Cliente/CodPostal`	string	Código postal
`Cliente/Puntos`	integer	Saldo actual de puntos
`Cliente/RecibeDifusiones`	string	S \| N
`Cliente/GrupoInteres`	integer	ID del grupo de interés
`Cliente/ValorPunto`	decimal	Valor monetario de un punto
`Cliente/Tags/Tag`	string	Título de cada tag asignado al cliente (nodo repetitivo, puede no aparecer si no tiene tags)
`Cliente/Cupones/Cupon`	string	Código de cada cupón disponible para el cliente (nodo repetitivo, puede no aparecer si no tiene cupones)
`Cliente/RedefinicionPunto/PorcentualCompra`	decimal	Porcentaje sobre el importe de compra
`Cliente/RedefinicionPunto/PorcentualPunto`	decimal	Porcentaje sobre puntos acumulados

<?xml version="1.0" encoding="utf-8"?>
<RespuestaFidelyGb>
  <RespCode>0</RespCode>
  <RespMsg>Cliente Ok</RespMsg>
  <Cliente>
    <IDClienteFidely>4821</IDClienteFidely>
    <Campania>12</Campania>
    <Categoria>5</Categoria>
    <Nombre>Juan Carlos</Nombre>
    <Apellido>Pérez</Apellido>
    <FecNac>15/06/1985</FecNac>
    <Dni>30123456</Dni>
    <Telefono>1166667777</Telefono>
    <Direccion>Av. Corrientes 1234</Direccion>
    <Email>juanc@email.com</Email>
    <Sexo>M</Sexo>
    <CodPostal>1043</CodPostal>
    <Puntos>1500</Puntos>
    <RecibeDifusiones>S</RecibeDifusiones>
    <GrupoInteres>3</GrupoInteres>
    <ValorPunto>0.5000</ValorPunto>
    <Tags>
      <Tag>VIP</Tag>
      <Tag>Cumpleaños</Tag>
    </Tags>
    <Cupones>
      <Cupon>VERANO25</Cupon>
    </Cupones>
    <RedefinicionPunto>
      <PorcentualCompra>0,00</PorcentualCompra>
      <PorcentualPunto>0,00</PorcentualPunto>
    </RedefinicionPunto>
  </Cliente>
</RespuestaFidelyGb>

301

Consultar movimientos del cliente

Devuelve el resumen estadístico de compras y puntos acumulados en los últimos 1 y 3 meses.

▼

Campo	Tipo	Requerido	Descripción
`DNI`	string	SÍ	DNI o número de tarjeta del cliente

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>301</CodAccion>
  <DNI>30123456</DNI>
</MensajeFidelyGb>

Campo	Tipo	Descripción
`Cliente/IDClienteFidely`	integer	ID del cliente
`Cliente/Categoria`	string	Nombre de la categoría
`Cliente/SaldoPuntos`	integer	Saldo actual de puntos
`Cliente/PesosAhorroUltimoMes`	decimal	Importe ahorrado en el último mes
`Cliente/PesosAhorro3Meses`	decimal	Importe ahorrado en los últimos 3 meses
`Cliente/PuntosUltimoMes`	integer	Puntos acumulados en el último mes
`Cliente/Puntos3Meses`	integer	Puntos acumulados en los últimos 3 meses
`Cliente/MovimientosUltimoMes`	integer	Cantidad de compras en el último mes
`Cliente/Movimientos3Meses`	integer	Cantidad de compras en los últimos 3 meses

<?xml version="1.0" encoding="utf-8"?>
<RespuestaFidelyGb>
  <RespCode>0</RespCode>
  <RespMsg>Cliente Ok</RespMsg>
  <Cliente>
    <IDClienteFidely>4821</IDClienteFidely>
    <Categoria>Gold</Categoria>
    <SaldoPuntos>1500</SaldoPuntos>
    <PesosAhorroUltimoMes>2500.00</PesosAhorroUltimoMes>
    <PesosAhorro3Meses>7800.00</PesosAhorro3Meses>
    <PuntosUltimoMes>250</PuntosUltimoMes>
    <Puntos3Meses>780</Puntos3Meses>
    <MovimientosUltimoMes>3</MovimientosUltimoMes>
    <Movimientos3Meses>9</Movimientos3Meses>
  </Cliente>
</RespuestaFidelyGb>

302

Consultar novedades

Devuelve los clientes que tuvieron altas o modificaciones en un rango de fechas.

▼

Campo	Tipo	Requerido	Descripción
`FechaDesde`	string	SÍ	Fecha inicio del rango. Formato `dd/mm/yyyy HH:mm:ss` (la hora es obligatoria)
`FechaHasta`	string	SÍ	Fecha fin del rango. Formato `dd/mm/yyyy HH:mm:ss` (la hora es obligatoria)

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>302</CodAccion>
  <FechaDesde>01/03/2026 00:00:00</FechaDesde>
  <FechaHasta>18/03/2026 23:59:59</FechaHasta>
</MensajeFidelyGb>

<?xml version="1.0" encoding="utf-8"?>
<RespuestaFidelyGb>
  <RespCode>0</RespCode>
  <RespMsg>OK</RespMsg>
  <Novedades>
    <Cliente>
      <IDClienteFidely>4821</IDClienteFidely>
      <Categoria>5</Categoria>
      <NroTarjeta>30123456</NroTarjeta>
      <Nombre>Juan Carlos</Nombre>
      <Apellido>Pérez</Apellido>
      <FecNac>15/06/1985</FecNac>
      <Dni>30123456</Dni>
      <Telefono>1166667777</Telefono>
      <Direccion>Av. Corrientes 1234</Direccion>
      <Email>juanc@email.com</Email>
      <Sexo>M</Sexo>
      <CodPostal>1043</CodPostal>
      <Localidad>Buenos Aires</Localidad>
      <Provincia>Buenos Aires</Provincia>
      <Sucursal>0</Sucursal>
      <IdGrupoInteres>3</IdGrupoInteres>
      <GrupoInteres>Jóvenes</GrupoInteres>
      <Codigo>GRP01</Codigo>
      <Tags>VIP,Cumpleaños</Tags>
    </Cliente>
    <!-- más registros... -->
  </Novedades>
</RespuestaFidelyGb>

<!-- Sin novedades -->
<RespuestaFidelyGb>
  <RespCode>1</RespCode>
  <RespMsg>No hay novedades</RespMsg>
  <Novedades></Novedades>
</RespuestaFidelyGb>

🛒 Ventas

200

Nueva venta

Registra una compra, acredita puntos y aplica cupones o canje de puntos si corresponde.

▼

Campo	Tipo	Requerido	Descripción
`Venta/NroTarjeta`	string	SÍ	Tarjeta o DNI del cliente (max:45)
`Venta/ImporteTotal`	decimal	SÍ	Importe total de la compra
`Venta/PuntosCanjeados`	integer	NO	Puntos que el cliente desea canjear en esta compra. El valor del punto se toma de la categoría del cliente.
`Venta/IdComprobante`	string	NO	Identificador alternativo del comprobante
`Venta/NroComprobante`	string	SÍ	Número de ticket/factura (max:45)
`Venta/FechaComprobante`	string	NO	Fecha del comprobante
`Venta/CodigoCupon`	string	NO	Código alfanumérico del cupón a aplicar
`Venta/IdCupon`	integer	NO	ID numérico del cupón (alternativa a CodigoCupon)
`Venta/ImporteAcos`	decimal	NO	Importe ACOS (costo). Cuando la campaña define `CalcularPuntosSobre = 'C'` se resta al `ImporteTotal` para calcular los puntos a acreditar.
`Venta/Operador`	string	NO	Identificador o nombre del operador/vendedor que registra la venta. Se persiste en el movimiento.
`Venta/ObraSocial`	string	NO	Obra social asociada a la venta. Se persiste en el movimiento y se reutiliza al procesar devoluciones.
`Venta/Productos`	—	NO	Tag repetitivo, uno por línea de producto
`Venta/Productos/IdProducto`	string	NO	Código del producto
`Venta/Productos/Cantidad`	decimal	NO	Cantidad de unidades
`Venta/Productos/Precio`	decimal	NO	Precio unitario

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>200</CodAccion>
  <Venta>
    <NroTarjeta>30123456</NroTarjeta>
    <ImporteTotal>1500.00</ImporteTotal>
    <PuntosCanjeados>100</PuntosCanjeados>
    <IdComprobante>TKT-2026-0001</IdComprobante>
    <NroComprobante>FC-0001-00000123</NroComprobante>
    <FechaComprobante>18/03/2026</FechaComprobante>
    <ImporteAcos>600.00</ImporteAcos>
    <Operador>VEND015</Operador>
    <ObraSocial>OSDE</ObraSocial>
    <Productos>
      <IdProducto>PROD001</IdProducto>
      <Cantidad>2</Cantidad>
      <Precio>750.00</Precio>
    </Productos>
    <Productos>
      <IdProducto>PROD002</IdProducto>
      <Cantidad>1</Cantidad>
      <Precio>0.00</Precio>
    </Productos>
  </Venta>
</MensajeFidelyGb>

Campo	Tipo	Descripción
`Venta/IdMovimiento`	integer	ID del movimiento generado
`Venta/PuntosDescontados`	integer	Puntos descontados por canje
`Venta/PuntosAcreditados`	integer	Puntos acreditados por la compra
`Venta/TotalPuntosCliente`	integer	Saldo total de puntos del cliente post-venta
`Venta/IdCupon`	integer	ID del cupón aplicado (0 si no hubo)
`Venta/DescuentoCupon`	decimal	Monto de descuento aplicado por el cupón

<?xml version="1.0" encoding="utf-8"?>
<RespuestaFidelyGb>
  <RespCode>0</RespCode>
  <RespMsg>Venta Fidelizada con éxito</RespMsg>
  <Venta>
    <IdMovimiento>98765</IdMovimiento>
    <PuntosDescontados>100</PuntosDescontados>
    <PuntosAcreditados>150</PuntosAcreditados>
    <TotalPuntosCliente>1550</TotalPuntosCliente>
    <IdCupon>45</IdCupon>
    <DescuentoCupon>375.00</DescuentoCupon>
  </Venta>
</RespuestaFidelyGb>

201

Devolución / Anulación parcial

Registra una devolución de mercadería. Revierte puntos acreditados si corresponde.

▼

ℹ️ Misma estructura de request y response que CodAccion 200. Cambia solo el valor de CodAccion. El nodo <Productos> es repetitivo e incluye IdProducto, Cantidad y Precio. Admite además <Venta><PuntosDevueltos> (entero): puntos a reacreditar al cliente por la devolución.

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>201</CodAccion>
  <Venta>
    <NroTarjeta>30123456</NroTarjeta>
    <ImporteTotal>500.00</ImporteTotal>
    <NroComprobante>NC-0001-00000010</NroComprobante>
    <Productos>
      <IdProducto>PROD001</IdProducto>
      <Cantidad>1</Cantidad>
      <Precio>500.00</Precio>
    </Productos>
  </Venta>
</MensajeFidelyGb>

202

Cancelación de venta

Cancela/anula completamente una venta. No requiere validación de los campos de venta.

▼

⚠️ CodAccion 202 cancela el movimiento identificado por IdMovimiento. No se utiliza NroTarjeta en esta acción.

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>202</CodAccion>
  <Venta>
    <IdMovimiento>98765</IdMovimiento>
  </Venta>
</MensajeFidelyGb>

601

Actualizar número de comprobante

Reemplaza el número de comprobante de un movimiento ya registrado.

▼

Campo	Tipo	Requerido	Descripción
`IdMovimiento`	integer	SÍ	ID del movimiento a actualizar
`NroComprobante`	string	SÍ	Nuevo número de comprobante (max:45)

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>601</CodAccion>
  <IdMovimiento>98765</IdMovimiento>
  <NroComprobante>FC-0001-00000124</NroComprobante>
</MensajeFidelyGb>

<?xml version="1.0" encoding="utf-8"?>
<RespuestaFidelyGb>
  <RespCode>0</RespCode>
  <RespMsg>Número de Comprobante actualizado con éxito</RespMsg>
</RespuestaFidelyGb>

⭐ Puntos

600

Ajuste manual de puntos

Acredita o descuenta puntos a un cliente sin asociarlos a una venta. Útil para bonificaciones, correcciones o canjes manuales.

▼

ℹ️ Enviar Puntos con valor positivo para acreditar, negativo para descontar.

Campo	Tipo	Requerido	Validación	Descripción
`Movimiento/NroTarjeta`	string	SÍ	max:45	Tarjeta o DNI del cliente
`Movimiento/Puntos`	integer	SÍ	entero, puede ser negativo	Puntos a acreditar (+) o descontar (-)
`Movimiento/Motivo`	string	SÍ	max:255	Descripción del motivo del ajuste

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>600</CodAccion>
  <Movimiento>
    <NroTarjeta>30123456</NroTarjeta>
    <Puntos>200</Puntos>  <!-- negativo para descontar: -50 -->
    <Motivo>Bonificación especial por cumpleaños</Motivo>
  </Movimiento>
</MensajeFidelyGb>

Campo	Tipo	Descripción
`Movimiento/IdMovimiento`	integer	ID del ajuste generado
`Movimiento/PuntosDescontados`	integer	Puntos descontados (si fue negativo)
`Movimiento/PuntosAcreditados`	integer	Puntos acreditados (si fue positivo)
`Movimiento/TotalPuntosCliente`	integer	Saldo total del cliente post-ajuste

<?xml version="1.0" encoding="utf-8"?>
<RespuestaFidelyGb>
  <RespCode>0</RespCode>
  <RespMsg>Puntos acreditados con éxito</RespMsg>
  <Movimiento>
    <IdMovimiento>98766</IdMovimiento>
    <PuntosDescontados>0</PuntosDescontados>
    <PuntosAcreditados>200</PuntosAcreditados>
    <TotalPuntosCliente>1750</TotalPuntosCliente>
  </Movimiento>
</RespuestaFidelyGb>

🎟️ Cupones

700

Alta de cupón

Crea un nuevo cupón de descuento o beneficio para una campaña.

▼

Campo	Tipo	Requerido	Validación	Descripción
`Cupon/Codigo`	string	SÍ	max:50	Código único del cupón
`Cupon/TipoBeneficio`	string	SÍ	PORCENTAJE \| MONTO_FIJO \| PUNTOS	Tipo de beneficio que otorga el cupón
`Cupon/ValorBeneficio`	decimal	SÍ	min: 0.01	Valor del beneficio (% o monto fijo)
`Cupon/FechaDesde`	string	SÍ	—	Inicio de vigencia
`Cupon/FechaHasta`	string	SÍ	—	Fin de vigencia
`Cupon/IdCampania`	integer	SÍ	—	ID de la campaña asociada
`Cupon/Descripcion`	string	NO	—	Descripción del beneficio
`Cupon/UsosMaximos`	integer	NO	—	Límite total de usos del cupón (0 = sin límite)
`Cupon/UsosMaximosPorCliente`	integer	NO	—	Límite de usos por cliente (0 = sin límite)
`Cupon/IdCliente`	integer	NO	debe existir	Restringe el cupón a un cliente específico
`Cupon/Condiciones`	—	NO	—	Contenedor opcional de restricciones de aplicabilidad. Admite los sub-nodos `Clasificadores`, `Productos`, `Marcas` y `Segmentos` (ver acción 703 para la lógica de evaluación).

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>700</CodAccion>
  <Cupon>
    <Codigo>VERANO25</Codigo>
    <TipoBeneficio>PORCENTAJE</TipoBeneficio>
    <ValorBeneficio>25.00</ValorBeneficio>
    <FechaDesde>01/03/2026</FechaDesde>
    <FechaHasta>31/03/2026</FechaHasta>
    <IdCampania>12</IdCampania>
  </Cupon>
</MensajeFidelyGb>

<?xml version="1.0" encoding="utf-8"?>
<RespuestaFidelyGb>
  <RespCode>0</RespCode>
  <RespMsg>Cupón creado con éxito</RespMsg>
  <Cupon>
    <IdCupon>45</IdCupon>
    <Codigo>VERANO25</Codigo>
  </Cupon>
</RespuestaFidelyGb>

701

Modificar cupón

Actualiza los datos de un cupón existente. Se identifica por IdCupon o Codigo.

▼

Campo	Tipo	Requerido	Descripción
`Cupon/IdCupon`	integer	SÍ (o Codigo)	ID del cupón a modificar
`Cupon/Codigo`	string	SÍ (o IdCupon)	Código del cupón (alternativa a IdCupon)
`Cupon/(otros campos)`	—	NO	Campos a actualizar. Solo se modifican los que se envían. Admite: `Descripcion`, `TipoBeneficio`, `ValorBeneficio`, `FechaDesde`, `FechaHasta`, `UsosMaximos`, `UsosMaximosPorCliente`, `IdCliente`, `Activo` (S \| N) y `Condiciones` (reemplaza las existentes).

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>701</CodAccion>
  <Cupon>
    <IdCupon>45</IdCupon>
    <ValorBeneficio>30.00</ValorBeneficio>
    <FechaHasta>30/04/2026</FechaHasta>
  </Cupon>
</MensajeFidelyGb>

Response XML

<?xml version="1.0" encoding="utf-8"?>
<RespuestaFidelyGb>
  <RespCode>0</RespCode>
  <RespMsg>Cupón modificado con éxito</RespMsg>
  <Cupon>
    <IdCupon>45</IdCupon>
    <Codigo>VERANO25</Codigo>
  </Cupon>
</RespuestaFidelyGb>

702

Deshabilitar cupón

Desactiva un cupón, impidiendo su uso en futuras transacciones.

▼

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>702</CodAccion>
  <Cupon>
    <IdCupon>45</IdCupon>
    <!-- Alternativa: <Codigo>VERANO25</Codigo> -->
  </Cupon>
</MensajeFidelyGb>

Response XML

<?xml version="1.0" encoding="utf-8"?>
<RespuestaFidelyGb>
  <RespCode>0</RespCode>
  <RespMsg>Cupón deshabilitado con éxito</RespMsg>
  <Cupon>
    <IdCupon>45</IdCupon>
    <Codigo>VERANO25</Codigo>
  </Cupon>
</RespuestaFidelyGb>

703

Validar cupón y puntos

Consulta si un cupón y/o puntos son válidos para una transacción sin procesarla. Ideal para mostrar el descuento antes de confirmar la compra.

▼

Campo	Tipo	Requerido	Descripción
`Venta/NroTarjeta`	string	SÍ	Tarjeta o DNI del cliente
`Venta/ImporteTotal`	decimal	SÍ	Importe total de la compra a validar
`Venta/ImporteAcos`	decimal	NO	Importe ACOS (costo). Cuando la campaña tiene `CalcularPuntosSobre = 'C'`, se resta al `ImporteTotal` antes de validar los puntos a canjear.
`Venta/CodigoCupon`	string	NO	Código de cupón a validar
`Venta/PuntosCanjeados`	integer	NO	Puntos a canjear a validar
`Venta/Productos`	—	NO	Tag repetitivo, uno por línea de producto. Requerido si el cupón tiene restricciones por producto, marca, segmento o clasificador.
`Venta/Productos/IdProducto`	string	NO	Código externo del producto (mismo formato que en CodAccion 200). Se resuelve internamente al ID Fidely para evaluar las condiciones del cupón.
`Venta/Productos/Cantidad`	integer	NO	Cantidad de unidades
`Venta/Productos/Precio`	decimal	NO	Precio unitario del producto

Validación de cupón contra productos: si el cupón tiene condiciones de aplicabilidad configuradas, el sistema evalúa cada producto enviado contra esas condiciones en el siguiente orden de prioridad:

Productos específicos — se verifica si el IdProducto está en la lista cupones_productos del cupón.
Marca — si no aplica por producto, se verifica si la marca del producto (idMarca) está en cupones_marcas.
Segmento — si no aplica por marca, se verifica si el producto pertenece a algún segmento configurado en cupones_segmentos.
Clasificador — si no aplica por segmento, se verifica si el producto tiene algún clasificador coincidente en cupones_clasificadores.

Si el cupón no tiene ninguna condición configurada, aplica sobre el importe total sin importar los productos enviados. Si tiene condiciones pero no se envían productos, el cupón se rechaza. ProductosAplicables en la respuesta indica la suma de unidades que efectivamente aplican, e ImporteTotal se recalcula sobre el importe de esos productos.

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>703</CodAccion>
  <Venta>
    <NroTarjeta>30123456</NroTarjeta>
    <ImporteTotal>1500.00</ImporteTotal>
    <ImporteAcos>600.00</ImporteAcos>
    <CodigoCupon>VERANO25</CodigoCupon>
    <PuntosCanjeados>100</PuntosCanjeados>
    <Productos>
      <IdProducto>1042</IdProducto>
      <Cantidad>2</Cantidad>
      <Precio>500.00</Precio>
    </Productos>
    <Productos>
      <IdProducto>2078</IdProducto>
      <Cantidad>1</Cantidad>
      <Precio>500.00</Precio>
    </Productos>
  </Venta>
</MensajeFidelyGb>

Campo	Tipo	Descripción
`Validacion/ClienteValido`	string	S = cliente activo y válido \| N = inválido
`Validacion/CuponValido`	string	S = cupón válido \| N = inválido o no aplica
`Validacion/CuponMensaje`	string	Mensaje descriptivo sobre el cupón
`Validacion/CuponDescripcion`	string	Descripción del beneficio del cupón
`Validacion/CuponTipoBeneficio`	string	PORCENTAJE \| MONTO_FIJO \| PUNTOS
`Validacion/CuponValorBeneficio`	decimal	Valor configurado del beneficio
`Validacion/DescuentoCupon`	decimal	Monto de descuento calculado sobre ImporteTotal
`Validacion/PuntosCanjeadosValidos`	integer	Puntos aprobados para canje
`Validacion/PuntosCanjeadosSolicitados`	integer	Puntos solicitados para canje
`Validacion/PuntosMensaje`	string	Mensaje sobre la validación de puntos
`Validacion/SaldoPuntosCliente`	integer	Saldo actual de puntos del cliente
`Validacion/ValorCanjePunto`	decimal	Valor monetario de cada punto
`Validacion/ProductosAplicables`	integer	Suma de unidades de productos que cumplen las condiciones del cupón (por producto específico, marca, segmento o clasificador). 0 si el cupón no tiene restricciones de producto o si ningún producto aplica.

<?xml version="1.0" encoding="utf-8"?>
<RespuestaFidelyGb>
  <RespCode>0</RespCode>
  <RespMsg></RespMsg>
  <Validacion>
    <ClienteValido>S</ClienteValido>
    <CuponValido>S</CuponValido>
    <CuponMensaje>Cupón válido</CuponMensaje>
    <CuponDescripcion>25% de descuento en toda la compra</CuponDescripcion>
    <CuponTipoBeneficio>PORCENTAJE</CuponTipoBeneficio>
    <CuponValorBeneficio>25.00</CuponValorBeneficio>
    <DescuentoCupon>375.00</DescuentoCupon>
    <PuntosCanjeadosValidos>100</PuntosCanjeadosValidos>
    <PuntosCanjeadosSolicitados>100</PuntosCanjeadosSolicitados>
    <PuntosMensaje>Puntos válidos para canje</PuntosMensaje>
    <SaldoPuntosCliente>1500</SaldoPuntosCliente>
    <ValorCanjePunto>0.50</ValorCanjePunto>
    <ProductosAplicables>0</ProductosAplicables>
  </Validacion>
</RespuestaFidelyGb>

📦 Productos

ℹ️ Los CodAccion 500 a 504 comparten la misma estructura de request. Para enviar varios productos se repite el nodo <Productos> (uno por producto), no se anidan nodos <Producto> dentro de un único <Productos>.

500 501

Alta (500) y Modificar producto (501)

Registra uno o más productos nuevos (500) o actualiza sus datos (501).

▼

Campo	Tipo	Requerido	Descripción
`IdRed`	integer	NO	Ignorado: la red se deriva automáticamente del comercio autenticado (token). Enviarlo no tiene efecto.
`Productos/IdProducto`	string	SÍ	Código único del producto
`Productos/Producto`	string	NO	Nombre / descripción del producto
`Productos/Marca`	integer	NO	ID de la marca del producto
`Productos/Costo`	decimal	NO	Precio de costo
`Productos/Precio`	decimal	NO	Precio de venta al público
`Productos/Clasificadores`	—	NO	Tag repetitivo, uno por clasificador asignado
`Clasificadores/IdTipoClasificador`	integer	NO	1=Laboratorio, 2=Rubro, 3=Subrubro, 4=Droga, 5=Accion
`Clasificadores/IdClasificador`	integer	NO	Identificador de la entidad clasificadora
`Clasificadores/Nombre`	string	NO	Nombre del clasificador

<!-- Producto único con clasificadores -->
<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>500</CodAccion>
  <IdRed>1</IdRed>
  <Productos>
    <IdProducto>PROD001</IdProducto>
    <Producto>Zapatillas Running XR</Producto>
    <Marca>7</Marca>
    <Costo>8000.00</Costo>
    <Precio>12999.00</Precio>
    <Clasificadores>
      <IdTipoClasificador>2</IdTipoClasificador>
      <IdClasificador>15</IdClasificador>
      <Nombre>Calzado</Nombre>
    </Clasificadores>
    <Clasificadores>
      <IdTipoClasificador>3</IdTipoClasificador>
      <IdClasificador>42</IdClasificador>
      <Nombre>Running</Nombre>
    </Clasificadores>
  </Productos>
</MensajeFidelyGb>

<!-- Múltiples productos: se REPITE el nodo <Productos>, uno por producto -->
<MensajeFidelyGb>
  <CodAccion>500</CodAccion>
  <Productos>
    <IdProducto>PROD001</IdProducto>
    <Producto>Zapatillas Running XR</Producto>
    <Costo>8000.00</Costo>
    <Precio>12999.00</Precio>
    <Clasificadores>
      <IdTipoClasificador>2</IdTipoClasificador>
      <IdClasificador>15</IdClasificador>
      <Nombre>Calzado</Nombre>
    </Clasificadores>
  </Productos>
  <Productos>
    <IdProducto>PROD002</IdProducto>
    <Producto>Remera Deportiva</Producto>
    <Costo>2500.00</Costo>
    <Precio>4500.00</Precio>
  </Productos>
</MensajeFidelyGb>

<?xml version="1.0" encoding="utf-8"?>
<RespuestaFidelyGb>
  <RespCode>0</RespCode>
  <RespMsg>Productos fidelizados con éxito</RespMsg>
</RespuestaFidelyGb>

502 503 504

Deshabilitar (502) / Reactivar (503) / Actualizar precios (504)

Gestión del estado y precios de uno o más productos. Misma estructura que CodAccion 500.

▼

ℹ️ Misma estructura de request que CodAccion 500/501. Solo cambia el valor de CodAccion.

<!-- Deshabilitar producto -->
<MensajeFidelyGb>
  <CodAccion>502</CodAccion>
  <Productos>
    <IdProducto>PROD001</IdProducto>
  </Productos>
</MensajeFidelyGb>

<!-- Actualizar precio -->
<MensajeFidelyGb>
  <CodAccion>504</CodAccion>
  <Productos>
    <IdProducto>PROD001</IdProducto>
    <Precio>14500.00</Precio>
  </Productos>
</MensajeFidelyGb>

🏷️ Tags

800

Asignación masiva de tags

Asigna uno o más tags a múltiples clientes en forma asíncrona (procesado en cola).

▼

⚠️ El procesamiento es asíncrono. La respuesta confirma que la tarea fue encolada, no que fue completada.

Campo	Tipo	Requerido	Descripción
`IdCampania`	integer	SÍ	ID de la campaña
`IdAnalisis`	integer	NO	ID de análisis asociado
`Tags`	string	NO	IDs de tags separados por coma (ej: "1,4,7")
`Clientes`	string	SÍ	IDs de clientes separados por coma (ej: "4821,4822")

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>800</CodAccion>
  <IdCampania>12</IdCampania>
  <IdAnalisis>5</IdAnalisis>
  <Tags>1,4,7</Tags>
  <Clientes>4821,4822,4823</Clientes>
</MensajeFidelyGb>

{
  "success": true,
  "message": "Asignación masiva iniciada"
}

💬 Mensajería

801

Envío de plantilla de mensaje (vía CodAccion)

Envía un mensaje de plantilla (WhatsApp u otro canal) a un destinatario desde el endpoint principal.

▼

Campo	Tipo	Requerido	Descripción
`Telefono`	string	SÍ	Número de teléfono destino con código de país (ej: 5491155554444)
`IdCampania`	integer	SÍ	ID de la campaña
`NombreTemplate`	string	SÍ	Nombre de la plantilla configurada
`Dni`	string	NO	DNI del cliente destinatario. Si se envía y no hay `Parametros`, se usa para resolver el nombre del cliente (`{{1}}`).
`Parametros/Parametro`	string, repetible	NO	Textos del body en orden (`{{1}}`, `{{2}}`, ...). Si el nodo está presente, no se mezcla con el nombre resuelto por DNI. Un parámetro vacío responde error.
`Link`	string	NO	URL completa o sufijo del botón URL (índice 0). Si la plantilla de Meta tiene una base fija, enviar solo el sufijo que exige la plantilla aprobada.

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>801</CodAccion>
  <Telefono>5491155554444</Telefono>
  <IdCampania>12</IdCampania>
  <NombreTemplate>bienvenida_cliente</NombreTemplate>
  <Dni>30123456</Dni>
  <Parametros>
    <Parametro>María</Parametro>
    <Parametro>18452</Parametro>
  </Parametros>
  <Link>https://mi-comercio.com/promo?id=123</Link>
</MensajeFidelyGb>

<?xml version="1.0" encoding="utf-8"?>
<RespuestaFidelyGb>
  <RespCode>0</RespCode>
  <RespMsg>Mensaje enviado exitosamente</RespMsg>
</RespuestaFidelyGb>

802

Marcar mensaje como contestado

Actualiza el estado "contestado" de la difusión y/o alerta asociadas a un teléfono dentro de una campaña.

▼

Campo	Tipo	Requerido	Descripción
`NroTelefono`	string	SÍ	Teléfono del cliente cuyo mensaje se marca
`Campania`	integer	SÍ	ID de la campaña
`Contestado`	string	NO	S \| N. Estado a asignar. Por defecto `N` si se omite.

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>802</CodAccion>
  <NroTelefono>5491155554444</NroTelefono>
  <Campania>12</Campania>
  <Contestado>S</Contestado>
</MensajeFidelyGb>

Campo	Tipo	Descripción
`Resultado/Success`	boolean	true si se realizó alguna actualización
`Resultado/Difusion/Actualizada`	boolean	true si se actualizó la difusión asociada
`Resultado/Difusion/Id`	integer	ID de la difusión actualizada
`Resultado/Alerta/Actualizada`	boolean	true si se actualizó la alerta asociada
`Resultado/Alerta/Id`	integer	ID de la alerta actualizada

<?xml version="1.0" encoding="utf-8"?>
<RespuestaFidelyGb>
  <RespCode>0</RespCode>
  <RespMsg>Estado actualizado con éxito</RespMsg>
  <Resultado>
    <Success>true</Success>
    <Difusion>
      <Actualizada>true</Actualizada>
      <Id>3344</Id>
    </Difusion>
    <Alerta>
      <Actualizada>false</Actualizada>
      <Id>0</Id>
    </Alerta>
  </Resultado>
</RespuestaFidelyGb>

🔔 Suscripciones

Gestión de suscripciones periódicas asociadas a clientes. Permiten configurar cobros o acciones recurrentes en un día específico del mes.

900

Crear suscripción

Crea una nueva suscripción periódica para un cliente.

▼

Campo	Tipo	Requerido	Validación	Descripción
`Suscripcion/Cliente`	integer	SÍ	—	IDClienteFidely del cliente
`Suscripcion/Dia`	integer	SÍ	1–31	Día del mes para la suscripción
`Suscripcion/Activo`	boolean	NO	true \| false \| 1 \| 0	Estado inicial. Por defecto `true` si se omite.
`Suscripcion/Notas`	string	NO	—	Notas libres de la suscripción
`Suscripcion/TipoAlerta`	integer	NO	—	ID del tipo de alerta. Si se omite se guarda `0`; conviene enviarlo siempre.
`Suscripcion/Productos`	—	NO	—	Nodo repetitivo, uno por producto asociado a la suscripción
`Suscripcion/Productos/IdProducto`	string	NO	—	Código del producto
`Suscripcion/Productos/Cantidad`	integer	NO	—	Cantidad (por defecto 1)

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>900</CodAccion>
  <Suscripcion>
    <Cliente>4821</Cliente>
    <Dia>15</Dia>
    <Activo>true</Activo>
    <Notas>Entrega mensual</Notas>
    <TipoAlerta>1</TipoAlerta>
    <Productos>
      <IdProducto>PROD001</IdProducto>
      <Cantidad>2</Cantidad>
    </Productos>
  </Suscripcion>
</MensajeFidelyGb>

<?xml version="1.0" encoding="utf-8"?>
<RespuestaFidelyGb>
  <RespCode>0</RespCode>
  <RespMsg>Suscripción creada exitosamente</RespMsg>
  <Suscripcion>
    <IdSuscripcion>123</IdSuscripcion>
  </Suscripcion>
</RespuestaFidelyGb>

901

Modificar suscripción

Actualiza el día u otros datos de una suscripción existente.

▼

Campo	Tipo	Requerido	Descripción
`Suscripcion/IdSuscripcion`	integer	SÍ	ID de la suscripción a modificar
`Suscripcion/Cliente`	integer	SÍ	IDClienteFidely del cliente
`Suscripcion/Dia`	integer	NO	Nuevo día del mes (1–31). Solo se actualiza si se envía.
`Suscripcion/Activo`	boolean	NO	Estado. Solo se actualiza si se envía.
`Suscripcion/Notas`	string	NO	Notas. Solo se actualizan si se envían.
`Suscripcion/TipoAlerta`	integer	COND	ID del tipo de alerta. Atención: siempre se aplica; si se omite, la suscripción queda con `0`. Conviene reenviarlo siempre.
`Suscripcion/Productos`	—	NO	Si se envía, reemplaza todos los productos de la suscripción (mismos sub-nodos que en 900).

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>901</CodAccion>
  <Suscripcion>
    <IdSuscripcion>123</IdSuscripcion>
    <Cliente>4821</Cliente>
    <Dia>20</Dia>
  </Suscripcion>
</MensajeFidelyGb>

902

Activar / Desactivar suscripción

Establece el estado activo/inactivo de una suscripción según el valor enviado en Activo.

▼

⚠️ No es un toggle automático: el estado se fija al valor recibido en <Activo>. Si se omite, se interpreta como false (desactivar).

Campo	Tipo	Requerido	Descripción
`Suscripcion/IdSuscripcion`	integer	SÍ	ID de la suscripción
`Suscripcion/Activo`	boolean	SÍ	true \| false \| 1 \| 0. Estado a establecer.

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>902</CodAccion>
  <Suscripcion>
    <IdSuscripcion>123</IdSuscripcion>
    <Activo>false</Activo>
  </Suscripcion>
</MensajeFidelyGb>

903

Eliminar suscripción

Elimina una suscripción de forma permanente.

▼

<?xml version="1.0" encoding="utf-8"?>
<MensajeFidelyGb>
  <CodAccion>903</CodAccion>
  <Suscripcion>
    <IdSuscripcion>123</IdSuscripcion>
  </Suscripcion>
</MensajeFidelyGb>

<?xml version="1.0" encoding="utf-8"?>
<RespuestaFidelyGb>
  <RespCode>0</RespCode>
  <RespMsg>Suscripción eliminada exitosamente</RespMsg>
</RespuestaFidelyGb>

📄 Integración por archivo (CSV)

ℹ️ Alternativa a las acciones de venta (200 / 201 / 202) para sistemas que no pueden llamar al servicio en cada venta: el sistema de facturación genera un archivo con las ventas, devoluciones y anulaciones del período y lo envía a WIBI (por ejemplo, con una tarea programada cada hora o al cierre de caja). WIBI lo procesa en segundo plano: identifica o da de alta al cliente, calcula los puntos con las reglas de la campaña y registra el movimiento en la sucursal que corresponde. Cualquier sistema de facturación puede generarlo con el formato descripto más abajo.

POST

Envío del archivo — /onzecrm/ProcessFileMov/UploadFileExternal

Recibe el archivo CSV como multipart/form-data, autenticado con usuario y clave del comercio. No usa XML ni token JWT.

▼

⚠️ Autenticación distinta al resto del servicio: este método no lleva api-key ni Authorization: Bearer. Se autentica con pUser / pPass, el usuario y la clave del comercio que WIBI configura como comercio de autenticación de la campaña.

URL	`POST {host}/onzecrm/ProcessFileMov/UploadFileExternal`
Content-Type	`multipart/form-data`
Límites	10 MB y 50.000 filas por archivo · 30 envíos por minuto
Procesamiento	Asincrónico. La respuesta sólo confirma la recepción; el archivo se procesa en el minuto siguiente.

Campo	Tipo	Requerido	Validación	Descripción
`file`	archivo	SÍ	.csv o .txt · text/csv o text/plain · máx. 10 MB	Archivo con el formato descripto en Formato del archivo
`pUser`	string	SÍ	—	Usuario del comercio de autenticación
`pPass`	string	SÍ	—	Clave del comercio de autenticación

POST /onzecrm/ProcessFileMov/UploadFileExternal HTTP/1.1
Host: {host}
Content-Type: multipart/form-data; boundary=----wibi

------wibi
Content-Disposition: form-data; name="pUser"

USUARIO_COMERCIO
------wibi
Content-Disposition: form-data; name="pPass"

CLAVE_COMERCIO
------wibi
Content-Disposition: form-data; name="file"; filename="ventas_20261021.csv"
Content-Type: text/csv

1001,21/10/2026 10:15:00,F,Venta,,Sucursal Centro, ... (ver formato)
------wibi--

Siempre HTTP 200 con un JSON. El campo error indica el resultado.

error	Descripción
`"0"`	Archivo recibido. `data` trae el nombre, la ruta y la fecha de recepción.
`"01"`	Usuario o clave incorrecta.
`"02"`	Falta el archivo, extensión o tipo no permitido, o excede el tamaño.
`"03"`	Error al guardar el archivo. Reintentar.

// Recibido
{
  "error": "0",
  "data": {
    "id": 0,
    "name": "ventas_20261021.csv",
    "path": "uploads/5b0c2f1e-....csv",
    "id_user": 14253,
    "id_file_version": 1,
    "date_add": "/Date(1792607400000)/",
    "date_process": "/Date(-2208988800000)/",
    "process": false,
    "process_error": false,
    "process_log": ""
  }
}

// Error de autenticación
{ "error": "01", "mensaje": "Usuario o clave incorrecta" }

// Archivo inválido
{ "error": "02", "message": "Extensión de archivo no permitida" }

El mensaje de error llega en mensaje o en message según el caso: leer ambos. El resultado del procesamiento (ventas aplicadas, omitidas o con error) se consulta en WIBI, en el panel de uploads de la campaña.

// PHP — Enviar el archivo de ventas
$host = 'https://apiv2.wibi.com.ar';

$ch = curl_init("$host/onzecrm/ProcessFileMov/UploadFileExternal");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_TIMEOUT        => 60,
    CURLOPT_POSTFIELDS     => [
        'pUser' => 'USUARIO_COMERCIO',
        'pPass' => 'CLAVE_COMERCIO',
        'file'  => new CURLFile('ventas_20261021.csv', 'text/csv', 'ventas_20261021.csv'),
    ],
]);
$resp = json_decode(curl_exec($ch), true);
curl_close($ch);

if (($resp['error'] ?? '') !== '0') {
    // No recibido: registrar y reintentar más tarde
    error_log('WIBI: ' . ($resp['mensaje'] ?? $resp['message'] ?? 'sin respuesta'));
}

# Python — Enviar el archivo de ventas
import requests

host = "https://apiv2.wibi.com.ar"

with open("ventas_20261021.csv", "rb") as f:
    r = requests.post(
        f"{host}/onzecrm/ProcessFileMov/UploadFileExternal",
        data={"pUser": "USUARIO_COMERCIO", "pPass": "CLAVE_COMERCIO"},
        files={"file": ("ventas_20261021.csv", f, "text/csv")},
        timeout=60,
    )

resp = r.json()
if resp.get("error") != "0":
    # No recibido: registrar y reintentar más tarde
    raise RuntimeError(resp.get("mensaje") or resp.get("message"))

// C# (.NET) — Enviar el archivo de ventas
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text.Json;

var host = "https://apiv2.wibi.com.ar";
using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
using var form = new MultipartFormDataContent();
form.Add(new StringContent("USUARIO_COMERCIO"), "pUser");
form.Add(new StringContent("CLAVE_COMERCIO"), "pPass");

var archivo = new ByteArrayContent(File.ReadAllBytes("ventas_20261021.csv"));
archivo.Headers.ContentType = new MediaTypeHeaderValue("text/csv");
form.Add(archivo, "file", "ventas_20261021.csv");

var resp = await http.PostAsync($"{host}/onzecrm/ProcessFileMov/UploadFileExternal", form);
using var json = JsonDocument.Parse(await resp.Content.ReadAsStringAsync());
if (json.RootElement.GetProperty("error").GetString() != "0")
{
    // No recibido: registrar y reintentar más tarde
}

curl -X POST "https://apiv2.wibi.com.ar/onzecrm/ProcessFileMov/UploadFileExternal" \
  -F "pUser=USUARIO_COMERCIO" \
  -F "pPass=CLAVE_COMERCIO" \
  -F "file=@ventas_20261021.csv;type=text/csv"

CSV

Formato del archivo

31 columnas separadas por coma (más una opcional para la tarjeta física), sin encabezado, una línea por renglón de producto.

▼

Codificación	UTF-8
Separador	Coma (`,`). Los textos con coma van entre comillas dobles.
Encabezado	No lleva. Las 31 columnas van siempre, en este orden, aunque estén vacías. La columna 32 (`NroTarjeta`) es obligatoria sólo en campañas con tarjeta física; en campañas con tarjeta virtual los archivos de 31 columnas se procesan igual.
Agrupación	Una venta con varios productos ocupa varias líneas con el mismo `IdTransaccion`. Los datos de cabecera y del cliente se toman de la primera.
Fechas	`dd/mm/aaaa`, `dd/mm/aaaa hh:mm:ss`, `aaaa-mm-dd` o `aaaa-mm-dd hh:mm:ss`
Importes	Punto (`1250.50`) o coma (`1250,50`) decimal; también `1.250,50`.

#	Campo	Tipo	Requerido	Descripción
1	`IdTransaccion`	entero	SÍ	Número positivo, único por comprobante. Agrupa los renglones y evita duplicados si el archivo se reenvía.
2	`FechaTransaccion`	fecha	RECOM	Fecha y hora de la venta. Vacía = fecha de proceso.
3	`Anulada`	string	NO	`T`, `SI`, `TRUE` o `1` = el comprobante es una anulación.
4	`TipoOperacion`	string	RECOM	Se reconoce por texto: anulación (anula), devolución / nota de crédito (devuelve puntos), puntos por alta / redención de puntos (eventos sin productos, se omiten). Otro valor = venta.
5	`IdTransaccionAnulada`	entero	COND	En anulaciones y devoluciones: `IdTransaccion` de la venta original.
6	`NombreSucursal`	string	SÍ	Debe estar en el mapa de sucursales de la campaña (lo configura WIBI). Sin mapear, la venta queda con error.
7	`NombreVendedor`	string	NO	Se guarda como operador.
8	`NombrePromocion`	string	NO	Informativo.
9	`NombreProducto`	string	RECOM	Descripción; se usa para el alta del producto.
10	`CodigoBarra`	numérico	SÍ	EAN / UPC, sólo dígitos. Un renglón sin código numérico se descarta.
11	`Categoria`	string	NO	Rubro; se usa en promociones e informes.
12	`Marca`	string	NO	Informativo.
13	`Cantidad`	decimal	SÍ	Mayor a 0 (en devoluciones puede venir negativa).
14	`PrecioVenta`	decimal	SÍ	Precio unitario con impuestos.
15	`MontoDescuento`	decimal	NO	Descuento por unidad; se resta del precio unitario.
16	`PorcentajeDescuento`	decimal	NO	Informativo.
17	`Puntos`	decimal	NO	Informativo: los puntos los calcula WIBI con las reglas de la campaña.
18	`PuntosVendedor`	decimal	NO	Informativo.
19	`NombreCanje`	string	NO	Informativo.
20	`NombreCliente`	string	RECOM	Nombre, para el alta del cliente.
21	`ApellidoCliente`	string	RECOM	Apellido.
22	`FechaNacimiento`	fecha	NO	Mismos formatos de fecha.
23	`Sexo`	string	NO	`M` / `F` (también masculino / femenino).
24	`NumeroDocumento`	string	COND	Documento del cliente: se toman sólo los dígitos, hasta 10. Obligatorio para dar de alta un cliente nuevo (todo cliente WIBI tiene documento). Sin `NroTarjeta` identifica al cliente y es su número de tarjeta en WIBI. Con tarjeta física puede omitirse si el cliente ya existe con esa tarjeta; si la tarjeta no tiene cliente y no hay documento, la venta queda con error.
25	`Email`	string	RECOM	Para comunicaciones.
26	`Telefono`	string	RECOM	Para WhatsApp y recordatorios.
27	`Provincia`	string	NO	Domicilio.
28	`Localidad`	string	NO	Domicilio.
29	`Calle`	string	NO	Domicilio.
30	`Numero`	string	NO	Domicilio.
31	`CodigoPostal`	string	NO	Domicilio.
32	`NroTarjeta`	numérico	COND	Número de la tarjeta física del programa (hasta 45 dígitos; se ignoran espacios y guiones). Obligatorio si la campaña usa tarjeta física: sin él la venta se omite. En campañas con tarjeta virtual es opcional. Si viene, identifica al cliente: se busca por tarjeta y, si no existe, por documento (y se le asigna la tarjeta); un cliente nuevo se da de alta con esa tarjeta. Una tarjeta con letras deja la venta omitida.

RECOM = recomendado: sin él la venta se procesa igual, con menos datos. COND = obligatorio sólo en ese caso.

Ejemplo

Una venta de dos productos (1001), la anulación de la venta 987 y una venta de un cliente que ya tiene su tarjeta física, identificado sólo por la columna 32 (1003):

1001,21/10/2026 10:15:00,F,Venta,,Sucursal Centro,Juan Pérez,,Ibuprofeno 400 mg x 20,7790001000012,Medicamentos,Genfar,1,3500.00,0,0,0,0,,Ana,Gómez,15/03/1985,F,30123456,ana@mail.com,1155550000,Buenos Aires,CABA,Corrientes,1234,1043
1001,21/10/2026 10:15:00,F,Venta,,Sucursal Centro,Juan Pérez,,Protector solar FPS 50 200 ml,7790002000029,Dermocosmética,Isdin,2,12000.00,600.00,5,0,0,,Ana,Gómez,15/03/1985,F,30123456,ana@mail.com,1155550000,Buenos Aires,CABA,Corrientes,1234,1043
1002,21/10/2026 11:40:00,T,Anulación,987,Sucursal Centro,Juan Pérez,,,,,,0,0,0,0,0,0,,Ana,Gómez,,F,30123456,,,,,,,
1003,21/10/2026 12:05:00,F,Venta,,Sucursal Centro,Juan Pérez,,Ibuprofeno 400 mg x 20,7790001000012,Medicamentos,Genfar,1,3500.00,0,0,0,0,,Luis,Ramírez,,M,,luis@mail.com,5512345678,,,,,,6000123456789

Reglas de proceso

Reenvíos	Cada `IdTransaccion` se procesa una sola vez: reenviar un archivo no duplica puntos.
Clientes	Si el documento no existe en la campaña, se da de alta con los datos del archivo.
Productos	Si el código de barras no existe, se da de alta.
Anulación	Revierte los puntos de la venta original, que tiene que haberse enviado antes.
Devolución	Descuenta puntos según el importe devuelto.
Sucursal excluida	Si WIBI marca una sucursal como “no sincronizar”, sus ventas se omiten sin error.

⚠️ Clientes fuera de Argentina: del documento se conservan sólo los dígitos (hasta 10). Identificadores alfanuméricos como CURP o RFC (México) no sirven: quedarían reducidos a los dígitos de la fecha de nacimiento y se mezclarían clientes distintos. Si el programa usa tarjeta física, enviarla en la columna 32 (NroTarjeta) y en NumeroDocumento un número propio del cliente (por ejemplo, el celular a 10 dígitos), necesario para el alta de clientes nuevos. Los códigos de producto también tienen que ser numéricos (EAN / UPC).

Documentación API — WIBI CRM

🔑 Autenticación

Headers requeridos

Campos del request

Campos de la respuesta

Headers para todas las demás peticiones

📨 Estructura general de respuesta

📋 Índice de acciones (CodAccion)

👤 Clientes

🛒 Ventas

⭐ Puntos

🎟️ Cupones

Response XML

Response XML

📦 Productos

🏷️ Tags

💬 Mensajería

🔔 Suscripciones

📄 Integración por archivo (CSV)

Ejemplo

Reglas de proceso