Skip to main content

​
Descripción General

El endpoint de upsert crea inteligentemente una nueva entidad o actualiza una existente basándose en estrategias configurables de detección de duplicados. Maneja automáticamente conflictos y previene registros duplicados usando coincidencia exacta, coincidencia difusa o detección de similitud impulsada por IA.

​
Endpoint

PUT http://api.gu1.ai/entities/upsert

​
Autenticación

Requiere una clave API válida en el encabezado de autorización: 
Authorization: Bearer YOUR_API_KEY

​
Cuerpo de la Solicitud

​
entity
object
required
Los datos de la entidad (misma estructura que el endpoint de Crear Entidad)
​
options
object
Opciones de configuración para el comportamiento del upsert
​
options.conflictResolution
enum
Cómo manejar conflictos cuando se encuentra una entidad existente:
  • source_wins - Los nuevos datos sobrescriben los datos existentes
  • target_wins - Mantener los datos existentes, ignorar los nuevos datos
  • manual_review - Marcar para revisión manual sin actualizar
  • smart_merge (predeterminado) - Fusionar inteligentemente ambos conjuntos de datos
​
options.deduplicationStrategy
enum
Estrategia para detectar entidades duplicadas:
  • exact_match - Coincidir por externalId y taxId (sin distinción de mayúsculas)
  • fuzzy_match - Coincidencia de similitud en name y taxId (umbral del 80%)
  • ai_similarity - Detección de similitud semántica impulsada por IA
  • hybrid (recomendado) - Coincidencia exacta con alternativa difusa
​
options.createRelationships
boolean
default:"true"
Si se deben crear automáticamente relaciones entre entidades

​
Respuesta

​
success
boolean
Indica si la operación fue exitosa
​
action
string
La acción realizada: created o updated
​
entity
object
El estado final de la entidad después del upsert
​
previousEntity
object
El estado de la entidad antes de la actualización (null si fue recién creada)
​
confidence
number
Puntuación de confianza (0-1) para la coincidencia de detección de duplicados
​
reasoning
string
Explicación de por qué la entidad fue creada/actualizada
​
conflicts
array
Array de conflictos a nivel de campo detectados durante la fusión (si los hay)

​
Estrategias de Deduplicación

​
Coincidencia Exacta

Coincide entidades basándose en comparación exacta de campos (sin distinción de mayúsculas):
  • Campos: externalId, taxId
  • Caso de uso: Cuando tienes identificadores únicos confiables
  • Velocidad: La más rápida
  • Precisión: 100% para valores idénticos

​
Coincidencia Difusa

Usa distancia de Levenshtein para coincidencia de similitud:
  • Campos: name, taxId
  • Umbral: 80% de similitud
  • Caso de uso: Cuando se trabaja con errores tipográficos o variaciones
  • Velocidad: Moderada
  • Precisión: Alta para cadenas similares

​
Similitud IA

Detección de similitud semántica impulsada por IA:
  • Método: Embeddings vectoriales y similitud de coseno
  • Caso de uso: Coincidencia compleja de múltiples campos
  • Velocidad: Más lenta
  • Precisión: La más alta para entidades semánticamente similares

​
Híbrida (Recomendada)

Combina coincidencia exacta y difusa:
  • Principal: Coincidencia exacta en identificadores
  • Alternativa: Coincidencia difusa en nombres
  • Umbral de confianza: 80%
  • Caso de uso: Mejor equilibrio de velocidad y precisión

​
Estrategias de Resolución de Conflictos

​
smart_merge (Predeterminado)

Fusiona inteligentemente datos de ambas fuentes:
  • Prioridad: Datos más recientes para campos simples
  • Arrays: Fusiona y deduplica
  • Objetos: Fusión profunda con detección de conflictos
  • Valores vacíos: Preserva valores existentes no vacíos

​
source_wins

Los nuevos datos reemplazan completamente los existentes:
  • Caso de uso: Cuando los datos entrantes son autoritativos
  • Comportamiento: Todos los campos de la fuente
  • Riesgo: Puede perder datos existentes valiosos

​
target_wins

Mantiene los datos existentes, ignora los entrantes:
  • Caso de uso: Cuando los datos existentes son autoritativos
  • Comportamiento: No se realizan actualizaciones
  • Riesgo: Puede perder actualizaciones importantes

​
manual_review

Marca conflictos sin resolución automática:
  • Caso de uso: Datos de alto riesgo que requieren revisión humana
  • Comportamiento: Crea tarea de revisión
  • Resultado: Entidad marcada para resolución manual

​
Ejemplos

​
Upsert Simple (Comportamiento Predeterminado)

curl -X PUT http://api.gu1.ai/entities/upsert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": {
      "type": "person",
      "externalId": "customer_12345",
      "name": "María González",
      "countryCode": "AR",
      "taxId": "20-12345678-9",
      "entityData": {
        "person": {
          "firstName": "María",
          "lastName": "González",
          "dateOfBirth": "1985-03-15",
          "occupation": "Software Engineer",
          "income": 85000
        }
      }
    }
  }'

​
Upsert con Estrategia de Coincidencia Exacta

curl -X PUT http://api.gu1.ai/entities/upsert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": {
      "type": "company",
      "externalId": "company_789",
      "name": "Tech Solutions S.A.",
      "countryCode": "BR",
      "taxId": "12.345.678/0001-90",
      "entityData": {
        "company": {
          "legalName": "Tech Solutions Sociedade Anônima",
          "revenue": 7500000
        }
      }
    },
    "options": {
      "deduplicationStrategy": "exact_match",
      "conflictResolution": "smart_merge"
    }
  }'

​
Upsert con Coincidencia Difusa

curl -X PUT http://api.gu1.ai/entities/upsert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": {
      "type": "person",
      "externalId": "customer_new_123",
      "name": "Maria Gonzales",
      "countryCode": "AR",
      "taxId": "20-12345678-9",
      "entityData": {
        "person": {
          "firstName": "Maria",
          "lastName": "Gonzales"
        }
      }
    },
    "options": {
      "deduplicationStrategy": "fuzzy_match",
      "conflictResolution": "smart_merge"
    }
  }'

​
Estrategia Híbrida (Recomendada)

curl -X PUT http://api.gu1.ai/entities/upsert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": {
      "type": "company",
      "externalId": "comp_456",
      "name": "TechSolutions SA",
      "countryCode": "BR",
      "taxId": "12.345.678/0001-90",
      "entityData": {
        "company": {
          "employeeCount": 100
        }
      }
    },
    "options": {
      "deduplicationStrategy": "hybrid"
    }
  }'

​
Ejemplos de Respuesta

​
Nueva Entidad Creada

{
  "success": true,
  "action": "created",
  "entity": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "customer_12345",
    "type": "person",
    "name": "María González",
    ...
  },
  "previousEntity": null,
  "confidence": 1.0,
  "reasoning": "No existing entity found matching criteria. Created new entity.",
  "conflicts": []
}

​
Entidad Existente Actualizada

{
  "success": true,
  "action": "updated",
  "entity": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "customer_12345",
    "type": "person",
    "name": "María González",
    "entityData": {
      "person": {
        "income": 95000
      }
    },
    ...
  },
  "previousEntity": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "entityData": {
      "person": {
        "income": 85000
      }
    },
    ...
  },
  "confidence": 1.0,
  "reasoning": "Exact match found on externalId. Updated existing entity with smart merge.",
  "conflicts": [
    {
      "field": "entityData.person.income",
      "oldValue": 85000,
      "newValue": 95000,
      "resolution": "source_wins"
    }
  ]
}

​
Casos de Uso

​
Importación de Datos desde Sistema Externo

// Importar datos de clientes desde CRM, evitando duplicados
async function importCustomer(crmData) {
  const response = await fetch('http://api.gu1.ai/entities/upsert', {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      entity: {
        type: 'person',
        externalId: crmData.customerId,
        name: crmData.fullName,
        countryCode: crmData.country,
        taxId: crmData.taxId,
        entityData: {
          person: {
            firstName: crmData.firstName,
            lastName: crmData.lastName,
            income: crmData.annualIncome
          }
        },
        attributes: {
          source: 'crm_import',
          importDate: new Date().toISOString()
        }
      },
      options: {
        deduplicationStrategy: 'hybrid',
        conflictResolution: 'smart_merge'
      }
    })
  });

  return response.json();
}

​
Enriquecimiento Progresivo de Datos

def enrich_entity_data(external_id, new_data):
    """Agregar progresivamente datos a la entidad a medida que estén disponibles"""
    response = requests.put(
        'http://api.gu1.ai/entities/upsert',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        json={
            'entity': {
                'type': 'person',
                'externalId': external_id,
                'name': new_data.get('name'),
                'countryCode': new_data.get('country'),
                'entityData': new_data.get('details', {}),
                'attributes': new_data.get('attributes', {})
            },
            'options': {
                'deduplicationStrategy': 'exact_match',
                'conflictResolution': 'smart_merge'  # Fusionar nuevo con existente
            }
        }
    )

    result = response.json()
    if result['action'] == 'updated':
        print(f"Enriched existing entity with new data")
    return result

​
Mejores Prácticas

  1. Elegir la Estrategia Correcta:
    • exact_match para datos limpios y estructurados con IDs confiables
    • fuzzy_match para datos ingresados por usuarios con posibles errores tipográficos
    • hybrid para la mayoría de escenarios de producción
  2. Manejar Conflictos con Elegancia:
    • Usar smart_merge para resolución automática
    • Usar manual_review para datos financieros críticos
    • Verificar el array conflicts en la respuesta para cambios importantes
  3. Monitorear Puntuaciones de Confianza:
    • Puntuaciones inferiores a 0.7 pueden indicar coincidencias débiles
    • Registrar actualizaciones de baja confianza para revisión
    • Considerar umbral de revisión manual
  4. Gestión de Relaciones:
    • Establecer createRelationships: true para vincular automáticamente entidades relacionadas
    • Útil para relaciones transacción-cliente, empresa-persona

​
Respuestas de Error

​
400 Bad Request

{
  "error": "Invalid tax ID format for country"
}

​
400 Campos Requeridos Faltantes

{
  "error": "Missing required fields",
  "missingFields": ["legalName"],
  "requiredFields": ["legalName", "industry"]
}

​
500 Internal Server Error

{
  "error": "Failed to upsert entity"
}

​
Próximos Pasos