> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://ayuda.clay.cl/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

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

# 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 <token>), 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.


|| Documentación interactiva completa (Swagger): [https://api.clay.cl/v2/reference](https://api.clay.cl/v2/reference)

---

## 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 | v2 |
| ---- |
| Header | `Token: <token>` | `Authorization: Bearer <token>` |
| Formato | Token directo | Bearer token (estándar HTTP) |

**v1 — NO usar:**

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

**v2 — Usar esto:**

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

| El token no cambia — solo la forma en que lo envías. Agrega la palabra `Bearer` antes del token y usa el header estándar `Authorization`.

---

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

| v1 | v2 | Método |
| ---- |
| `/v1/contabilidad/balance/` | `/v2/accounting/balance` | GET |
| `/v1/contabilidad/libro_diario/` | `/v2/accounting/daily-book` | GET |
| `/v1/contabilidad/eerr/` | `/v2/accounting/income-statement` | GET |
| `/v1/contabilidad/libro_mayor/` | `/v2/accounting/general-ledger` | GET |
| `/v1/contabilidad/plan_cuenta/` | `/v2/accounting/chart-of-accounts` | GET |

### 📄 Obligaciones

| v1 | v2 | Método |
| ---- |
| `/v1/obligaciones/dte/` | `/v2/obligations/dte` | GET |
| `/v1/obligaciones/honorarios/` | `/v2/obligations/honorarios` | GET |
| `/v1/obligaciones/pendientes/` | `/v2/obligations/pending` | GET |
| `/v1/obligaciones/facturas/` | `/v2/obligations/invoices` | GET |
| `/v1/obligaciones/cesiones/` | `/v2/obligations/cesiones` | GET |

### 🏦 Cuentas bancarias

| v1 | v2 | Método |
| ---- |
| `/v1/cuentas_bancarias/saldos/` | `/v2/bank-accounts/balances` | GET |
| `/v1/cuentas_bancarias/movimientos/` | `/v2/bank-accounts/movements` | GET |
| `/v1/cuentas_bancarias/matches/` | `/v2/bank-accounts/matches` | GET |
| `/v1/cuentas_bancarias/tarjetas/` | `/v2/bank-accounts/credit-cards` | GET |

### 🏢 Empresas

| v1 | v2 | Método |
| ---- |
| `/v1/empresas/` | `/v2/companies` | GET |
| `/v1/empresas/impuestos/` | `/v2/companies/taxes` | GET |
| `/v1/empresas/estado_avance/` | `/v2/companies/progress` | GET |

---

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

| v1 (antes) | v2 (ahora) | Contexto |
| ---- |
| `rut_empresa` | `company_rut` | Todos los endpoints |
| `fecha_desde` | `date_from` | Bancos y obligaciones |
| `fecha_hasta` | `date_to` | Bancos y obligaciones |
| `fecha_desde` | `accounting_date_from` | Contabilidad |
| `fecha_hasta` | `accounting_date_to` | Contabilidad |

### Filtros booleanos

| v1 (antes) | v2 (ahora) | Contexto |
| ---- |
| `recibida` | `is_received` | DTE, invoices |
| `con_match` | `has_match` | DTE, movimientos |
| `abono` | `is_deposit` | Movimientos bancarios |
| `pagada` | `is_paid` | DTE, movimientos |
| `rut_contraparte` | `counterpart_rut` | DTE, clientes |

||| ⚠️ **Ojo con las fechas de contabilidad:** Los endpoints `balance`, `daily-book` y `general-ledger` usan `accounting_date_from` / `accounting_date_to`, **no** `date_from` / `date_to`.

---

## 4. Campos de respuesta renombrados

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

| v1 (español) | v2 (inglés) | Contexto |
| ---- |
| `debe` | `debit` | Balance, libro diario, EERR, libro mayor |
| `haber` | `credit` | Balance, libro diario, EERR, libro mayor |
| `saldo` | `balance` | EERR, libro mayor |
| `activo` | `asset` | Balance |
| `pasivo` | `liability` | Balance |
| `listado` | `items` | Progress, paginación |
| `cantidad` | `count` | Progress |
| `monto` | `amount` | Progress |
| `numero_asiento` | `entry_number` | Libro diario, libro mayor |
| `usuario` | `user` | Progress |
| `matches_usuarios` | `matches_by_user` | Progress |

---

## 5. Ejemplos por endpoint

### Listar empresas — `GET /v2/companies`

**v1:**

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

**v2:**

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

---

### Balance contable — `GET /v2/accounting/balance`

||| ⚠️ Este endpoint usa `accounting_date_from` / `accounting_date_to`, NO `date_from` / `date_to`

**v1:**

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

**v2:**

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

---

### DTEs con filtros — `GET /v2/obligations/dte`

**v1:**

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

**v2:**

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

---

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

**v1:**

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

**v2:**

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

---

### Estado de avance — `GET /v2/companies/progress`

**v1:**

```python
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:**

```python
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`.

```python
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"]
```

| El loop termina solo cuando `has_more = False`. No necesitas saber el total de páginas de antemano.

---

## 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"]`

---

|| Documentación interactiva completa (Swagger): [https://api.clay.cl/v2/reference](https://api.clay.cl/v2/reference)