Competidores y sus Valores (Stores)

Los competidores permiten asignar tiendas competidoras a tus puntos de venta (stores). Puedes marcar uno o más competidores y designar cuál es el competidor principal (marker).

Formato CSV (Archivos Planos)

El campo de valores de competidores es una cadena de texto compuesta que permite múltiples competidores.

Estructura Básica

{{Código del competidor}}:{{Valor booleano IsMarker}}

Componentes:

Código del competidor: Identificador único del competidor (ej: COMP0001)
IsMarker (opcional): true si es el competidor principal, false o ausente si no lo es

Ejemplos CSV

Ejemplo 1: Un solo competidor (sin marcar como principal)

CompetitorValues
COMP0001

Resultado:

Competidor: COMP0001
Es principal: false (por defecto)

Ejemplo 2: Un competidor marcado como principal

CompetitorValues
COMP0001;true

Resultado:

Competidor: COMP0001
Es principal: true

Ejemplo 3: Múltiples competidores con uno principal

CompetitorValues
COMP0001;true;COMP0002;false;COMP0003;false

Resultado:

Competidor: COMP0001 → Es principal: true
Competidor: COMP0002 → Es principal: false
Competidor: COMP0003 → Es principal: false

Archivo CSV Completo de Ejemplo

StoreCode|StoreName|CompetitorValues
STORE001|Tienda Centro|COMP0001;true
STORE002|Tienda Norte|COMP0001;true;COMP0002;false
STORE003|Tienda Sur|COMP0001;false;COMP0002;false;COMP0003;true

Interpretación:

STORE001: Tiene 1 competidor (COMP0001) que es el principal
STORE002: Tiene 2 competidores, COMP0001 es el principal
STORE003: Tiene 3 competidores, COMP0003 es el principal

Errores Comunes en CSV

❌ Incorrecto	✅ Correcto	Problema
`COMP0001 : true`	`COMP0001;true`	Espacios alrededor de `:`
`COMP0001;true;`	`COMP0001;true`	Termina con `;`
`COMP0001,COMP0002`	`COMP0001;COMP0002`	Usa `,` en lugar de `;`

Formato JSON (API REST)

En las APIs REST, los competidores se encuentran anidados dentro del array CompetitorValues.

Estructura Básica

"CompetitorValues": [
    {
        "Code": "COMP0001",
        "IsMarker": true
    }
]

Propiedades:

Code: Código del competidor
IsMarker: true si es el competidor principal, false si no

Ejemplos JSON

Ejemplo 1: Un solo competidor principal

{
    "StoreCode": "STORE001",
    "StoreName": "Tienda Centro",
    "CompetitorValues": [
        {
            "Code": "COMP0001",
            "IsMarker": true
        }
    ]
}

Ejemplo 2: Múltiples competidores

{
    "StoreCode": "STORE002",
    "StoreName": "Tienda Norte",
    "CompetitorValues": [
        {
            "Code": "COMP0001",
            "IsMarker": true
        },
        {
            "Code": "COMP0002",
            "IsMarker": false
        },
        {
            "Code": "COMP0003",
            "IsMarker": false
        }
    ]
}

Interpretación:

COMP0001 es el competidor principal
COMP0002 y COMP0003 son competidores secundarios

Request Completo de Ejemplo (POST)

POST /api/stores
Content-Type: application/json
Authorization: Bearer {token}

{
    "StoreCode": "STORE003",
    "StoreName": "Tienda Shopping Las Palmas",
    "Address": "Av. Principal 123",
    "City": "Buenos Aires",
    "CompetitorValues": [
        {
            "Code": "WALMART-001",
            "IsMarker": true
        },
        {
            "Code": "CARREFOUR-002",
            "IsMarker": false
        },
        {
            "Code": "DIA-003",
            "IsMarker": false
        }
    ]
}

Comparativa CSV vs JSON

Misma información en ambos formatos

CSV:

StoreCode|CompetitorValues
STORE001|COMP0001;true;COMP0002;false;COMP0003;false

JSON:

{
    "StoreCode": "STORE001",
    "CompetitorValues": [
        {
            "Code": "COMP0001",
            "IsMarker": true
        },
        {
            "Code": "COMP0002",
            "IsMarker": false
        },
        {
            "Code": "COMP0003",
            "IsMarker": false
        }
    ]
}

Casos de Uso

Retail: Asignar Competencia Local

Tienda ubicada en un centro comercial con 3 competidores cercanos:

{
    "StoreCode": "STORE-MALL-001",
    "StoreName": "Mi Tienda - Mall Center",
    "CompetitorValues": [
        {
            "Code": "ZARA-MALL",
            "IsMarker": true
        },
        {
            "Code": "HM-MALL",
            "IsMarker": false
        },
        {
            "Code": "UNIQLO-MALL",
            "IsMarker": false
        }
    ]
}

CSV equivalente:

StoreCode|CompetitorValues
STORE-MALL-001|ZARA-MALL;true;HM-MALL;false;UNIQLO-MALL;false

Supermercados: Competencia Directa

{
    "StoreCode": "SUPER-NORTE-01",
    "StoreName": "Supermercado Norte",
    "CompetitorValues": [
        {
            "Code": "CARREFOUR-NORTE",
            "IsMarker": true
        },
        {
            "Code": "DIA-NORTE",
            "IsMarker": false
        }
    ]
}

CSV equivalente:

SUPER-NORTE-01|CARREFOUR-NORTE;true;DIA-NORTE;false

Reglas de Negocio

Competidor Principal (IsMarker = true)

Recomendaciones

✅ Solo un competidor principal por tienda (aunque el sistema permite múltiples)
✅ El competidor principal debe ser el más relevante estratégicamente
✅ Puedes tener hasta N competidores secundarios (sin límite técnico)
✅ Los competidores deben estar previamente registrados en el sistema

Validación Pre-Envío

Checklist antes de enviar

Los códigos de competidores existen en el sistema Prisma
Solo hay un competidor con IsMarker: true por tienda (recomendado)
No hay espacios alrededor de : (CSV)
Se usa ; como separador (CSV)
No termina con ; (CSV)
El JSON está bien formado (API)

Solución de Problemas

Error: “Competitor not found”

Causa: El código del competidor no existe en Prisma

Solución:

Verifica que el competidor esté creado en el sistema
Revisa que el código sea exactamente el mismo (case-sensitive)
Solicita la lista de competidores disponibles

Error: “Invalid boolean value”

Causa CSV: El valor booleano no es true o false

Solución:

❌ COMP0001;yes
❌ COMP0001;1
✅ COMP0001;true
✅ COMP0001;false

Advertencia: “Multiple markers detected”

Causa: Hay más de un competidor con IsMarker: true

Solución: Revisa tu lógica de negocio. Generalmente, solo debe haber un competidor principal.

// ⚠️ Poco común pero válido
"CompetitorValues": [
    {
        "Code": "COMP0001",
        "IsMarker": true  // Principal
    },
    {
        "Code": "COMP0002",
        "IsMarker": true  // ¿También principal?
    }
]

// ✅ Recomendado
"CompetitorValues": [
    {
        "Code": "COMP0001",
        "IsMarker": true  // Principal
    },
    {
        "Code": "COMP0002",
        "IsMarker": false  // Secundario
    }
]

Ejemplos de Código

Python: Generar formato CSV

def format_competitors_csv(competitors):
    """
    Genera string de competidores en formato CSV
    competitors: lista de tuplas (code, is_marker)
    """
    parts = []
    for code, is_marker in competitors:
        if is_marker:
            parts.append(f"{code};true")
        else:
            parts.append(code)
    return ";".join(parts)

# Uso
competitors = [
    ("COMP0001", True),   # Principal
    ("COMP0002", False),  # Secundario
    ("COMP0003", False)   # Secundario
]

result = format_competitors_csv(competitors)
print(result)
# Output: COMP0001;true;COMP0002;COMP0003

Python: Generar formato JSON

def format_competitors_json(competitors):
    """
    Genera array de competidores en formato JSON
    competitors: lista de tuplas (code, is_marker)
    """
    return [
        {"Code": code, "IsMarker": is_marker}
        for code, is_marker in competitors
    ]

# Uso
competitors = [
    ("WALMART-001", True),
    ("CARREFOUR-002", False)
]

import json
result = format_competitors_json(competitors)
print(json.dumps(result, indent=2))

Output:

[
  {
    "Code": "WALMART-001",
    "IsMarker": true
  },
  {
    "Code": "CARREFOUR-002",
    "IsMarker": false
  }
]

Actualizar Competidores

Reemplazar completamente

Cuando envías una actualización, reemplazas completamente la lista de competidores:

// Estado actual
"CompetitorValues": [
    {"Code": "COMP0001", "IsMarker": true}
]

// Envías actualización
"CompetitorValues": [
    {"Code": "COMP0002", "IsMarker": true},
    {"Code": "COMP0003", "IsMarker": false}
]

// Resultado: COMP0001 fue removido, se agregaron COMP0002 y COMP0003

Recursos Relacionados

Etiquetas y sus Valores - Formato similar para etiquetas
Códigos y sus Valores - Formato similar para códigos
Formatos de Archivos - Especificaciones generales
Autenticación API REST - Cómo autenticarte en la API

Soporte

¿Necesitas ayuda con los competidores?

📧 Contacta al equipo de soporte
🔍 Solicita la lista de competidores disponibles
📋 Envía ejemplos para validación
🏪 Consulta sobre estrategias de asignación de competidores