Upsert de una entidad

Upsert

curl --request PUT \
  --url http://api.gu1.ai/entities/upsert \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entity": {},
  "options": {},
  "options.conflictResolution": {},
  "options.deduplicationStrategy": {},
  "options.createRelationships": true
}
'

import requests

url = "http://api.gu1.ai/entities/upsert"

payload = {
    "entity": {},
    "options": {},
    "options.conflictResolution": {},
    "options.deduplicationStrategy": {},
    "options.createRelationships": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    entity: {},
    options: {},
    'options.conflictResolution': {},
    'options.deduplicationStrategy': {},
    'options.createRelationships': true
  })
};

fetch('http://api.gu1.ai/entities/upsert', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/entities/upsert",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'entity' => [
        
    ],
    'options' => [
        
    ],
    'options.conflictResolution' => [
        
    ],
    'options.deduplicationStrategy' => [
        
    ],
    'options.createRelationships' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/entities/upsert"

	payload := strings.NewReader("{\n  \"entity\": {},\n  \"options\": {},\n  \"options.conflictResolution\": {},\n  \"options.deduplicationStrategy\": {},\n  \"options.createRelationships\": true\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("http://api.gu1.ai/entities/upsert")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"entity\": {},\n  \"options\": {},\n  \"options.conflictResolution\": {},\n  \"options.deduplicationStrategy\": {},\n  \"options.createRelationships\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities/upsert")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entity\": {},\n  \"options\": {},\n  \"options.conflictResolution\": {},\n  \"options.deduplicationStrategy\": {},\n  \"options.createRelationships\": true\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "action": "<string>",
  "entity": {},
  "previousEntity": {},
  "confidence": 123,
  "reasoning": "<string>",
  "conflicts": [
    {}
  ]
}

PUT

entities

upsert

Upsert

curl --request PUT \
  --url http://api.gu1.ai/entities/upsert \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entity": {},
  "options": {},
  "options.conflictResolution": {},
  "options.deduplicationStrategy": {},
  "options.createRelationships": true
}
'

import requests

url = "http://api.gu1.ai/entities/upsert"

payload = {
    "entity": {},
    "options": {},
    "options.conflictResolution": {},
    "options.deduplicationStrategy": {},
    "options.createRelationships": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    entity: {},
    options: {},
    'options.conflictResolution': {},
    'options.deduplicationStrategy': {},
    'options.createRelationships': true
  })
};

fetch('http://api.gu1.ai/entities/upsert', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/entities/upsert",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'entity' => [
        
    ],
    'options' => [
        
    ],
    'options.conflictResolution' => [
        
    ],
    'options.deduplicationStrategy' => [
        
    ],
    'options.createRelationships' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/entities/upsert"

	payload := strings.NewReader("{\n  \"entity\": {},\n  \"options\": {},\n  \"options.conflictResolution\": {},\n  \"options.deduplicationStrategy\": {},\n  \"options.createRelationships\": true\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("http://api.gu1.ai/entities/upsert")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"entity\": {},\n  \"options\": {},\n  \"options.conflictResolution\": {},\n  \"options.deduplicationStrategy\": {},\n  \"options.createRelationships\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities/upsert")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entity\": {},\n  \"options\": {},\n  \"options.conflictResolution\": {},\n  \"options.deduplicationStrategy\": {},\n  \"options.createRelationships\": true\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "action": "<string>",
  "entity": {},
  "previousEntity": {},
  "confidence": 123,
  "reasoning": "<string>",
  "conflicts": [
    {}
  ]
}

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

object

required

Los datos de la entidad (misma estructura que Crear entidad), incluyendo campos raíz opcionales como email, phone y nationality (ISO 3166-1 alfa-2 o etiqueta mapeable).

El esquema puede aceptar las mismas claves que crear (p. ej. monitoring, autoExecuteIntegrations). El upsert no ejecuta auto-enriquecimientos ni aplica monitoring. Usa POST /entities o POST /entities/automatic para el comportamiento de lista / Regtia op 1 durante el enriquecimiento.

object

Opciones de configuración para el comportamiento del upsert

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

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

boolean

default:"true"

Si se deben crear automáticamente relaciones entre entidades

Respuesta

boolean

Indica si la operación fue exitosa

string

La acción realizada: created o updated

object

El estado final de la entidad después del upsert

object

El estado de la entidad antes de la actualización (null si fue recién creada)

number

Puntuación de confianza (0-1) para la coincidencia de detección de duplicados

string

Explicación de por qué la entidad fue creada/actualizada

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
        }
      }
    }
  }'

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: '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
        }
      }
    }
  })
});

const result = await response.json();
console.log(`Action: ${result.action}`); // 'created' or 'updated'
console.log(`Confidence: ${result.confidence}`);

import requests

response = requests.put(
    'http://api.gu1.ai/entities/upsert',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        '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
                }
            }
        }
    }
)

result = response.json()
print(f"Action: {result['action']}")
print(f"Confidence: {result['confidence']}")

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"
    }
  }'

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: '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'
    }
  })
});

const result = await response.json();
if (result.action === 'updated') {
  console.log('Found and updated existing company');
  console.log('Conflicts:', result.conflicts);
}

import requests

response = requests.put(
    'http://api.gu1.ai/entities/upsert',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        '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'
        }
    }
)

result = response.json()
if result['action'] == 'updated':
    print("Found and updated existing company")
    print(f"Conflicts: {result['conflicts']}")

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"
    }
  }'

// Coincidirá "Maria Gonzales" con "María González" existente
// debido al umbral de similitud superior al 80%

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: 'customer_new_123',
      name: 'Maria Gonzales', // Ligera variación en la ortografía
      countryCode: 'AR',
      taxId: '20-12345678-9',
      entityData: {
        person: {
          firstName: 'Maria',
          lastName: 'Gonzales'
        }
      }
    },
    options: {
      deduplicationStrategy: 'fuzzy_match',
      conflictResolution: 'smart_merge'
    }
  })
});

const result = await response.json();
console.log(`Matched with confidence: ${result.confidence}`);
console.log(`Reasoning: ${result.reasoning}`);

import requests

# Coincidirá "Maria Gonzales" con "María González" existente
response = requests.put(
    'http://api.gu1.ai/entities/upsert',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'entity': {
            'type': 'person',
            'externalId': 'customer_new_123',
            'name': 'Maria Gonzales',  # Ligera variación
            'countryCode': 'AR',
            'taxId': '20-12345678-9',
            'entityData': {
                'person': {
                    'firstName': 'Maria',
                    'lastName': 'Gonzales'
                }
            }
        },
        'options': {
            'deduplicationStrategy': 'fuzzy_match',
            'conflictResolution': 'smart_merge'
        }
    }
)

result = response.json()
print(f"Matched with confidence: {result['confidence']}")
print(f"Reasoning: {result['reasoning']}")

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"
    }
  }'

// Intenta coincidencia exacta primero, recurre a difusa si es necesario
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: 'company',
      externalId: 'comp_456',
      name: 'TechSolutions SA', // Variación de "Tech Solutions S.A."
      countryCode: 'BR',
      taxId: '12.345.678/0001-90', // Coincidencia exacta en ID fiscal
      entityData: {
        company: {
          employeeCount: 100
        }
      }
    },
    options: {
      deduplicationStrategy: 'hybrid' // Lo mejor de ambos mundos
    }
  })
});

const result = await response.json();
// Coincidirá en taxId (exacta) o name (difusa)
console.log(`Strategy used: ${result.reasoning}`);

import requests

# Híbrida: intenta coincidencia exacta primero, difusa como alternativa
response = requests.put(
    'http://api.gu1.ai/entities/upsert',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'entity': {
            'type': 'company',
            'externalId': 'comp_456',
            'name': 'TechSolutions SA',
            'countryCode': 'BR',
            'taxId': '12.345.678/0001-90',
            'entityData': {
                'company': {
                    'employeeCount': 100
                }
            }
        },
        'options': {
            'deduplicationStrategy': 'hybrid'
        }
    }
)

result = response.json()
print(f"Strategy used: {result['reasoning']}")

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

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
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
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
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

Upsert en Lote - Procesar múltiples entidades a la vez
Listar Entidades - Consultar entidades insertadas
Actualizar Entidad - Realizar actualizaciones específicas
Obtener Entidad - Recuperar detalles completos de la entidad

​Descripción General

​Endpoint

​Autenticación

​Cuerpo de la Solicitud

​Respuesta

​Estrategias de Deduplicación

​Coincidencia Exacta

​Coincidencia Difusa

​Similitud IA

​Híbrida (Recomendada)

​Estrategias de Resolución de Conflictos

​smart_merge (Predeterminado)

​source_wins

​target_wins

​manual_review

​Ejemplos

​Upsert Simple (Comportamiento Predeterminado)

​Upsert con Estrategia de Coincidencia Exacta

​Upsert con Coincidencia Difusa

​Estrategia Híbrida (Recomendada)

​Ejemplos de Respuesta

​Nueva Entidad Creada

​Entidad Existente Actualizada

​Casos de Uso

​Importación de Datos desde Sistema Externo

​Enriquecimiento Progresivo de Datos

​Mejores Prácticas

​Respuestas de Error

​400 Bad Request

​400 Campos Requeridos Faltantes

​500 Internal Server Error

​Próximos Pasos

Descripción General

Endpoint

Autenticación

Cuerpo de la Solicitud

Respuesta

Estrategias de Deduplicación

Coincidencia Exacta

Coincidencia Difusa

Similitud IA

Híbrida (Recomendada)

Estrategias de Resolución de Conflictos

smart_merge (Predeterminado)

source_wins

target_wins

manual_review

Ejemplos

Upsert Simple (Comportamiento Predeterminado)

Upsert con Estrategia de Coincidencia Exacta

Upsert con Coincidencia Difusa

Estrategia Híbrida (Recomendada)

Ejemplos de Respuesta

Nueva Entidad Creada

Entidad Existente Actualizada

Casos de Uso

Importación de Datos desde Sistema Externo

Enriquecimiento Progresivo de Datos

Mejores Prácticas

Respuestas de Error

400 Bad Request

400 Campos Requeridos Faltantes

500 Internal Server Error

Próximos Pasos