Guía de Migración: API v1 → v2

Esta guía explica todos los cambios necesarios para migrar tu integración desde la API v1 a la nueva API v2 de Clay.
La nueva versión trae mejoras significativas que te facilitarán el trabajo:
✅ Más datos por request — pasamos de 200 a 500 ítems por consulta
✅ Endpoints más rápidos — menor latencia en las respuestas para que tus procesos corran mejor.
✅ Más endpoints disponibles — ahora puedes crear asientos contables, gestionar conexiones, crear DTEs, notas de venta, órdenes de compra, webhooks, y más. Todo desde la API.
✅Autenticación estándar — pasamos a Bearer token (Authorization: Bearer ), el estándar de la industria.
✅ Paginación mejorada — los nuevos campos has_more y next_offset hacen más simple y seguro iterar sobre resultados grandes.
✅ Parámetros en inglés y más descriptivos — por ejemplo, rut_empresa → company_rut, fecha_desde → date_from.

1. Autenticación

El único cambio en autenticación es el formato del header HTTP. El token es el mismo, solo cambia cómo lo envías.

v1 — NO usar:

headers = {"Token": "mi-token-abc123"}

v2 — Usar esto:

headers = {"Authorization": "Bearer mi-token-abc123"}

2. Cambios en endpoints

Todos los endpoints cambian de paths en español a inglés:

https://api.clay.cl/v1/ruta_en_español/ → https://api.clay.cl/v2/route-in-english

📊 Contabilidad

📄 Obligaciones

🏦 Cuentas bancarias

🏢 Empresas

3. Parámetros renombrados

La lógica no cambia. Solo los nombres de los parámetros que envías en el request.

Identificadores y fechas

Filtros booleanos

4. Campos de respuesta renombrados

Lo que antes recibías en español, ahora viene en inglés. Los valores son exactamente los mismos.

5. Ejemplos por endpoint

Listar empresas — GET /v2/companies

v1:

requests.get(
    "https://api.clay.cl/v1/empresas/",
    headers={"Token": TOKEN}
)
# resp["data"]

v2:

requests.get(
    "https://api.clay.cl/v2/companies",
    headers={"Authorization": f"Bearer {TOKEN}"}
)
# resp["data"]["items"]

Balance contable — GET /v2/accounting/balance

v1:

params={
    "rut_empresa": rut,
    "fecha_desde": "2025-01-01",
    "fecha_hasta": "2025-12-31"
}

v2:

params={
    "company_rut": rut,
    "accounting_date_from": "2025-01-01",
    "accounting_date_to": "2025-12-31"
}

DTEs con filtros — GET /v2/obligations/dte

v1:

params={
    "rut_empresa": rut,
    "fecha_desde": "2025-01-01",
    "recibida": True,
    "con_match": False
}

v2:

params={
    "company_rut": rut,
    "date_from": "2025-01-01",
    "is_received": True,
    "has_match": False
}

Movimientos bancarios — GET /v2/bank-accounts/movements

v1:

params={
    "rut_empresa": rut,
    "fecha_desde": "2025-01-01",
    "abono": True,
    "limit": 100
}

v2:

params={
    "company_rut": rut,
    "date_from": "2025-01-01",
    "is_deposit": True,
    "limit": 100
}

Estado de avance — GET /v2/companies/progress

v1:

params={
    "rut": rut,
    "fecha_desde": "2025-01-01",
    "fecha_hasta": "2025-12-31",
    "info": "total_movimientos,matches_usuarios"
}
# data["total_movimientos"]["cantidad"]
# data["matches_usuarios"]["listado"]

v2:

params={
    "company_rut": rut,
    "date_from": "2025-01-01",
    "date_to": "2025-12-31",
    "info": "total_movements,matches_by_user"
}
# data["total_movements"]["count"]
# data["matches_by_user"]["items"]

Paginación automática — Nuevo en v2

En v2 puedes iterar todos los resultados con un loop simple usando has_more y next_offset.

items = []
offset = 0

while True:
    resp = requests.get(url, params={..., "offset": offset})
    data = resp.json()["data"]
    items.extend(data["items"])
    if not data["pagination"]["has_more"]:
        break
    offset = data["pagination"]["next_offset"]

6. Checklist de migración

Antes de pasar a producción, verifica que hayas hecho cada uno de estos cambios:

• Cambiar header de Token: <token> a Authorization: Bearer <token>
• Actualizar todas las URLs de /v1/ a /v2/ con paths en inglés
• Reemplazar rut_empresa por company_rut en todos los requests
• Contabilidad: cambiar fecha_desde/hasta a accounting_date_from/to
• Bancos y obligaciones: cambiar fecha_desde/hasta a date_from/to
• Filtros booleanos: recibida → is_received, abono → is_deposit, con_match → has_match
• Campos de respuesta: debe/haber → debit/credit, listado → items, cantidad → count
• Paginación: usar data["pagination"]["has_more"] y data["pagination"]["next_offset"]

Actualizado el: 22/06/2026