Guía de Migración de API V1 a V2

Esta guía te ayudará a migrar tu integración de la API V1 de Sheriff a la nueva versión V2. La migración es sencilla y no requiere cambios drásticos en tu código, principalmente actualizarás URLs y ajustarás algunos nombres de campos.

Cambios principales que afectan tu integración

Los cambios más importantes en V2 son:

URL base: /api/v1/ → /api/clients/v2/ (afecta todos los endpoints)
Endpoint de resumen: /helper/{rut}/summary → /helper/resumen?rut={rut}
Diario Oficial: Ya no es un endpoint separado, ahora está integrado en resumen
Nuevos endpoints: GET /helper/compliance/{rut}, GET /usage, GET /profiles
Cambios en rutas: Varios endpoints reorganizados (judicial, cobranzaLaboral, legal, etc.)

📋 Resumen de Cambios Principales

1. Cambio en la URL Base

Versión	URL Base	Ejemplo Completo
V1 (anterior)	`https://prod.api.thesheriff.cl/api/v1/`	`https://prod.api.thesheriff.cl/api/v1/helper/loadRut`
V2 (nueva)	`https://prod.api.thesheriff.cl/api/clients/v2/`	`https://prod.api.thesheriff.cl/api/clients/v2/helper/cargarRut`

Cambio: Se agrega /clients/ en la ruta y cambia de v1 a v2.

2. Consolidación de Información

En V2:

✅ Toda la información de la plataforma se obtiene a través de endpoints unificados:
- Resúmenes: Endpoint resumen que consolida toda la información en una sola llamada
- Detalle de ayudantes y submódulos: Endpoints organizados por categoría (judicial, cobranzaLaboral, legal, compliance, etc.)

3. Headers Requeridos (Sin Cambios)

Los headers de autenticación permanecen iguales:

-H 'Authorization: Bearer <TU_TOKEN>'
-H 'x-client-identifier: SheriffSecureClient-v1'
-H 'accept: application/json'

🔄 Tabla de Equivalencias de Endpoints

Endpoints de Plataforma (Carga y Consulta)

V1	V2	Cambios
`GET /helper/{rut}/summary`	`GET /helper/resumen?rut={rut}`	⚠️ Cambió el nombre y estructura: `summary` → `resumen`
`POST /helper/loadRut`	`POST /helper/cargarRut`	⚠️ Cambió la ruta: `/loadRut` → `/cargarRut`
`GET /helper/{rut}/getCivilCases`	`GET /helper/judicial/{rut}/civil`	⚠️ Cambió la ruta: `/getCivilCases` → `/judicial/{rut}/civil`
`GET /helper/{rut}/getLaboralCases`	`GET /helper/judicial/{rut}/laboral`	⚠️ Cambió la ruta: `/getLaboralCases` → `/judicial/{rut}/laboral`
`GET /helper/{rut}/getCobranzaCases`	`GET /helper/judicial/{rut}/cobranza`	⚠️ Cambió la ruta: `/getCobranzaCases` → `/judicial/{rut}/cobranza`
`GET /helper/{rut}/getMoraPrevisionalCases`	`GET /helper/cobranzaLaboral/{rut}/moraPrevisional`	⚠️ Cambió la ruta: `/getMoraPrevisionalCases` → `/cobranzaLaboral/{rut}/moraPrevisional`
`GET /helper/{rut}/getMultaLaboralCases`	`GET /helper/cobranzaLaboral/{rut}/multaLaboral`	⚠️ Cambió la ruta: `/getMultaLaboralCases` → `/cobranzaLaboral/{rut}/multaLaboral`
`GET /notification/creditScoring/{rut}/getByRut`	`GET /creditScore/{rut}`	⚠️ Cambió la ruta: `/notification/creditScoring/{rut}/getByRut` → `/creditScore/{rut}`
`GET /helper/{rut}/getOfficialDiary`	Integrado en `GET /helper/resumen?rut={rut}`	ℹ️ Ya no existe, ahora está en `data.legal.diarioOficial`
`GET /helper/{rut}/mallaSocietaria`	`GET /helper/legal/{rut}/mallaSocietaria`	⚠️ Cambió la ruta: `/helper/{rut}/mallaSocietaria` → `/helper/legal/{rut}/mallaSocietaria`

Endpoints de Compliance

V1	V2	Cambios
`POST /integration/compliance/loadProfile`	`POST /webhook/compliance/cargarPerfil`	⚠️ Cambió la ruta: `/integration/compliance/loadProfile` → `/webhook/compliance/cargarPerfil`
❌ No existía	`GET /helper/compliance/{rut}`	✨ NUEVO: Detalle de compliance

Endpoints de Uso y Administración (NUEVOS en V2)

V1	V2	Cambios
❌ No existía	`GET /usage`	✨ NUEVO: Consultar uso/consumo de la cuenta
❌ No existía	`GET /profiles`	✨ NUEVO: Listar todos los perfiles cargados

🔨 Ejemplos Prácticos de Migración

Ejemplo 1: Cargar un RUT

❌ V1 (Anterior)

curl -X 'POST' \
  'https://prod.api.thesheriff.cl/api/v1/helper/loadRut' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'x-client-identifier: SheriffSecureClient-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "rut": "12345678-9",
    "isMonitoring": false,
    "includeEquifax": false
  }'

✅ V2 (Nuevo)

curl -X 'POST' \
  'https://prod.api.thesheriff.cl/api/clients/v2/helper/cargarRut' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'x-client-identifier: SheriffSecureClient-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "rut": "12345678-9",
    "isMonitoring": false,
    "includeEquifax": false
  }'

Cambio: URL base (/api/v1/ → /api/clients/v2/) y nombre del endpoint (loadRut → cargarRut)

Ejemplo 2: Obtener Resumen de un RUT

❌ V1 (Anterior)

curl -X 'GET' \
  'https://prod.api.thesheriff.cl/api/v1/helper/12345678-9/summary' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'x-client-identifier: SheriffSecureClient-v1'

✅ V2 (Nuevo)

curl -X 'GET' \
  'https://prod.api.thesheriff.cl/api/clients/v2/helper/resumen?rut=12345678-9' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'x-client-identifier: SheriffSecureClient-v1'

Cambios:

URL base (/api/v1/ → /api/clients/v2/)
⚠️ Estructura del endpoint (helper/{rut}/summary → helper/resumen?rut={rut})

🔧 Checklist de Migración

Sigue estos pasos para migrar tu integración:

1. ✅ Actualizar URL Base

Cambiar https://prod.api.thesheriff.cl/api/v1/ por https://prod.api.thesheriff.cl/api/clients/v2/
Si usas QA, cambiar https://qa.api.thesheriff.cl/api/v1/ por https://qa.api.thesheriff.cl/api/clients/v2/

Ejemplo en código:

// ❌ Antes (V1)
const BASE_URL = 'https://prod.api.thesheriff.cl/api/v1/'

// ✅ Después (V2)
const BASE_URL = 'https://prod.api.thesheriff.cl/api/clients/v2/'

2. ✅ Actualizar Endpoint de Resumen

El endpoint cambió de estructura:

// ❌ V1
GET /helper/{rut}/summary

// ✅ V2
GET /helper/resumen?rut={rut}

3. ✅ Migrar Diario Oficial

El endpoint de Diario Oficial ya no existe de forma independiente:

// ❌ V1 - Endpoint independiente
GET /helper/{rut}/getOfficialDiary

// ✅ V2 - Integrado en resumen
GET /helper/resumen?rut={rut}
// Acceder: response.data.legal.diarioOficial.casos

4. ✅ Aprovechar Nuevos Endpoints

V2 incluye endpoints nuevos que no existían en V1:

// ✨ NUEVO en V2: Compliance detallado
GET / helper / compliance / { rut }

// ✨ NUEVO en V2: Consultar uso/consumo
GET / usage

// ✨ NUEVO en V2: Listar perfiles cargados
GET / profiles

5. ✅ Probar en QA

Antes de pasar a producción:

Probar todos los endpoints en ambiente QA: https://qa.api.thesheriff.cl/api/clients/v2/
Verificar que las respuestas son las esperadas
Validar que el parseo de datos funciona correctamente

6. ✅ Desplegar a Producción

Actualizar variables de entorno
Desplegar cambios
Monitorear logs por errores
Verificar funcionamiento correcto

📊 Comparación de Respuestas

Resumen

Las respuestas de resumen son muy similares entre V1 y V2, con algunas mejoras:

Estructura principal (igual en ambas versiones):

{
  "success": true,
  "data": {
    "rut": "12345678-9",
    "esPersonaJuridica": true,
    "fechaCarga": "13-06-2024",
    "identificacion": {...},
    "boletinComercial": {...},
    "judicial": {...},
    "cobranzaLaboral": {...},
    "legal": {...},
    "deudaBancaria": {...},
    "bienes": {...},
    "creditScoring": {...},
    "compliance": {...}
  }
}

Mejoras en V2:

✨ Mejor documentación de campos
✨ Estructura más consistente
✨ Nuevos campos agregados en compliance
✨ Mejor manejo de valores null

⚠️ Puntos Importantes

1. Integración con Diario Oficial

El endpoint de Diario Oficial fue integrado en resumen en V2. Esto se hizo para:

✅ Simplificar la API
✅ Reducir el número de llamadas necesarias
✅ Consolidar información en endpoints más completos
✅ Mejorar el rendimiento

Recomendación: Usa resumen para obtener toda la información en una sola llamada.

2. Compatibilidad hacia atrás

❌ No hay compatibilidad hacia atrás entre V1 y V2
⚠️ V1 seguirá funcionando por un periodo de transición
✅ Se recomienda migrar lo antes posible a V2

3. Nuevas funcionalidades en V2

V2 incluye mejoras que no existían en V1:

🆕 Endpoint de Compliance detallado (/compliance/{rut})
🆕 Mejor estructura de datos en respuestas
🆕 Documentación mejorada con glosario completo
🆕 Endpoints de administración (getUsage, getProfiles)
🆕 Webhooks mejorados con más eventos

🆘 Ayuda y Soporte

Recursos Disponibles

📖 Documentación Completa V2
📚 Glosario de Términos - Referencia de todos los valores posibles
❓ Preguntas Frecuentes
🔐 Guía de Autenticación

¿Necesitas Ayuda?

Si tienes dudas durante la migración:

Consulta la documentación: La mayoría de dudas están resueltas en los docs
Revisa el glosario: Para entender valores y campos específicos
Contacta a tu account manager: Para dudas comerciales o de integración específica
Soporte técnico: Para problemas técnicos o bugs

📝 Ejemplo de Código Completo

JavaScript/Node.js

// Configuración
const BASE_URL = 'https://prod.api.thesheriff.cl/api/clients/v2/'
const TOKEN = 'tu-token-aqui'

const headers = {
  Authorization: `Bearer ${TOKEN}`,
  'x-client-identifier': 'SheriffSecureClient-v1',
  'Content-Type': 'application/json',
}

// 1. Cargar un RUT
async function cargarRut(rut, isMonitoring = false, includeEquifax = false) {
  const response = await fetch(`${BASE_URL}helper/cargarRut`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ rut, isMonitoring, includeEquifax }),
  })
  return response.json()
}

// 2. Obtener resumen completo
async function obtenerResumen(rut) {
  const response = await fetch(`${BASE_URL}helper/resumen?rut=${rut}`, {
    method: 'GET',
    headers,
  })
  return response.json()
}

// 3. Obtener casos civiles
async function obtenerCasosCiviles(rut) {
  const response = await fetch(`${BASE_URL}helper/judicial/${rut}/civil`, {
    method: 'GET',
    headers,
  })
  return response.json()
}

// 4. Obtener credit scoring
async function obtenerCreditScoring(rut) {
  const response = await fetch(`${BASE_URL}creditScore/${rut}`, {
    method: 'GET',
    headers,
  })
  return response.json()
}

// 5. Obtener compliance detallado
async function obtenerCompliance(rut) {
  const response = await fetch(`${BASE_URL}helper/compliance/${rut}`, {
    method: 'GET',
    headers,
  })
  return response.json()
}

// Uso
;(async () => {
  const rut = '12345678-9'

  // Cargar RUT
  await cargarRut(rut, false, false)
  console.log('RUT cargado exitosamente')

  // Obtener toda la información
  const resumen = await obtenerResumen(rut)
  console.log('Razón Social:', resumen.data.identificacion.razonSocial)
  console.log('Riesgo:', resumen.data.compliance.riesgo)

  // Obtener casos civiles
  const casosCiviles = await obtenerCasosCiviles(rut)
  console.log('Casos civiles:', casosCiviles.data.length)
})()

Python

import requests

# Configuración
BASE_URL = 'https://prod.api.thesheriff.cl/api/clients/v2/'
TOKEN = 'tu-token-aqui'

headers = {
    'Authorization': f'Bearer {TOKEN}',
    'x-client-identifier': 'SheriffSecureClient-v1',
    'Content-Type': 'application/json'
}

# 1. Cargar un RUT
def cargar_rut(rut, is_monitoring=False, include_equifax=False):
    url = f'{BASE_URL}helper/cargarRut'
    data = {
        'rut': rut,
        'isMonitoring': is_monitoring,
        'includeEquifax': include_equifax
    }
    response = requests.post(url, headers=headers, json=data)
    return response.json()

# 2. Obtener resumen completo
def obtener_resumen(rut):
    url = f'{BASE_URL}helper/resumen?rut={rut}'
    response = requests.get(url, headers=headers)
    return response.json()

# 3. Obtener casos civiles
def obtener_casos_civiles(rut):
    url = f'{BASE_URL}helper/judicial/{rut}/civil'
    response = requests.get(url, headers=headers)
    return response.json()

# 4. Obtener credit scoring
def obtener_credit_scoring(rut):
    url = f'{BASE_URL}creditScore/{rut}'
    response = requests.get(url, headers=headers)
    return response.json()

# 5. Obtener compliance detallado
def obtener_compliance(rut):
    url = f'{BASE_URL}helper/compliance/{rut}'
    response = requests.get(url, headers=headers)
    return response.json()

# Uso
if __name__ == '__main__':
    rut = '12345678-9'

    # Cargar RUT
    cargar_rut(rut, is_monitoring=False, include_equifax=False)
    print('RUT cargado exitosamente')

    # Obtener toda la información
    resumen = obtener_resumen(rut)
    print(f"Razón Social: {resumen['data']['identificacion']['razonSocial']}")
    print(f"Riesgo: {resumen['data']['compliance']['riesgo']}")

    # Obtener casos civiles
    casos_civiles = obtener_casos_civiles(rut)
    print(f"Casos civiles: {len(casos_civiles['data'])}")

✨ Conclusión

La migración de V1 a V2 es sencilla y principalmente involucra:

✅ Actualizar la URL base en tu código
✅ Ajustar el parseo de respuestas si es necesario
✅ Aprovechar nuevas funcionalidades de V2

¿Listo para migrar?

Sigue el checklist paso a paso y estarás usando V2 en poco tiempo. Si tienes dudas, consulta la documentación completa o contacta a soporte.

📋 Resumen de Cambios Principales​

1. Cambio en la URL Base​

2. Consolidación de Información​

3. Headers Requeridos (Sin Cambios)​

🔄 Tabla de Equivalencias de Endpoints​

Endpoints de Plataforma (Carga y Consulta)​

Endpoints de Compliance​

Endpoints de Uso y Administración (NUEVOS en V2)​

🔨 Ejemplos Prácticos de Migración​

Ejemplo 1: Cargar un RUT​

❌ V1 (Anterior)​

✅ V2 (Nuevo)​

Ejemplo 2: Obtener Resumen de un RUT​

❌ V1 (Anterior)​

✅ V2 (Nuevo)​

🔧 Checklist de Migración​

1. ✅ Actualizar URL Base​

2. ✅ Actualizar Endpoint de Resumen​

3. ✅ Migrar Diario Oficial​

4. ✅ Aprovechar Nuevos Endpoints​

5. ✅ Probar en QA​

6. ✅ Desplegar a Producción​

📊 Comparación de Respuestas​

Resumen​

⚠️ Puntos Importantes​

1. Integración con Diario Oficial​

2. Compatibilidad hacia atrás​

3. Nuevas funcionalidades en V2​

🆘 Ayuda y Soporte​

Recursos Disponibles​

¿Necesitas Ayuda?​

📝 Ejemplo de Código Completo​

JavaScript/Node.js​

Python​

✨ Conclusión​

📋 Resumen de Cambios Principales

1. Cambio en la URL Base

2. Consolidación de Información

3. Headers Requeridos (Sin Cambios)

🔄 Tabla de Equivalencias de Endpoints

Endpoints de Plataforma (Carga y Consulta)

Endpoints de Compliance

Endpoints de Uso y Administración (NUEVOS en V2)

🔨 Ejemplos Prácticos de Migración

Ejemplo 1: Cargar un RUT

❌ V1 (Anterior)

✅ V2 (Nuevo)

Ejemplo 2: Obtener Resumen de un RUT

❌ V1 (Anterior)

✅ V2 (Nuevo)

🔧 Checklist de Migración

1. ✅ Actualizar URL Base

2. ✅ Actualizar Endpoint de Resumen

3. ✅ Migrar Diario Oficial

4. ✅ Aprovechar Nuevos Endpoints

5. ✅ Probar en QA

6. ✅ Desplegar a Producción

📊 Comparación de Respuestas

Resumen

⚠️ Puntos Importantes

1. Integración con Diario Oficial

2. Compatibilidad hacia atrás

3. Nuevas funcionalidades en V2

🆘 Ayuda y Soporte

Recursos Disponibles

¿Necesitas Ayuda?

📝 Ejemplo de Código Completo

JavaScript/Node.js

Python

✨ Conclusión