# Carga histórica

Sube tu cartera actual con su historial de pagos sin mandar un solo mensaje por error.

La carga se hace en cuatro pasadas: clientes, cuotas, pagos y, si los tienes, créditos y conversaciones. Cada pasada se puede repetir sin duplicar nada.

## Antes de empezar

**Pausa las comunicaciones.** Una cuota vencida que entra a Makatea entra también al calendario de cobranza. En **Configuración → Comunicaciones automatizadas → Pausar** detienes todo envío de la organización mientras cargas. Reactívalas cuando hayas revisado la cartera en la app.

**Usa tus propios identificadores.** Manda `external_ref` en cada cliente y en cada cuota. Es único por organización y te deja buscar un registro con `?external_ref=` sin guardar los id de Makatea.

**Usa una `Idempotency-Key` por renglón.** Arma la llave con algo estable del renglón, por ejemplo `carga-CLI-1042`. Si la carga se corta y la vuelves a correr en menos de 24 horas, las llamadas repetidas devuelven la respuesta original en lugar de crear otro registro.

**Respeta el límite.** Son 600 llamadas por minuto por llave. Lee `X-RateLimit-Remaining` en cada respuesta y, si llega un `429`, espera los segundos de `Retry-After`.

## 1. Clientes

Por cada cliente de tu sistema llama `POST /v1/members`.

```sh
curl -s -X POST $MAKATEA_API/v1/members \
  -H "Authorization: Bearer $MAKATEA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: carga-CLI-1042" \
  -d '{
    "full_name": "Sofía Ramírez López",
    "phone_e164": "+5215512345678",
    "external_ref": "CLI-1042",
    "customer_since": "2023-04-15",
    "identity": { "lote": "14", "manzana": "3" }
  }'
```

Si contesta `409` porque el `external_ref` ya existe, el cliente ya está cargado. Recupera su id así.

```sh
curl -s "$MAKATEA_API/v1/members?external_ref=CLI-1042" -H "Authorization: Bearer $MAKATEA_KEY"
```

`customer_since` es la fecha en que se volvió tu cliente, no la de hoy. Dos clientes pueden compartir teléfono.

Si un cliente no debe recibir mensajes, mándalo con `do_not_contact: true` y su `do_not_contact_reason`.

## 2. Cuotas

Carga todas las cuotas, las pagadas y las abiertas, con su fecha de vencimiento original.

```sh
curl -s -X POST $MAKATEA_API/v1/billing-orders \
  -H "Authorization: Bearer $MAKATEA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: carga-CLI-1042-007" \
  -d '{
    "member_id": "6f1c…",
    "amount": 2400,
    "due_date": "2026-07-10",
    "period_label": "Mensualidad 7 de 60",
    "external_ref": "CLI-1042-007",
    "capital_portion": 1900,
    "interest_portion": 500
  }'
```

Si llevas capital e interés por cuota, mándalos aquí. Así el reporte de capital y utilidad sale bien desde el primer día.

## 3. Pagos con su fecha real

Por cada pago que ya recibiste llama `POST /v1/billing-orders/{id}/payments` con `paid_at` en el día en que entró el dinero.

```sh
curl -s -X POST $MAKATEA_API/v1/billing-orders/{id}/payments \
  -H "Authorization: Bearer $MAKATEA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: carga-pago-88121" \
  -d '{ "amount": 2400, "paid_at": "2026-07-09", "method": "transfer", "reference": "88121" }'
```

- Un abono parcial deja la cuota abierta con su saldo.
- Si el pago es mayor al saldo, `"excess": "credit"` aplica el sobrante a las siguientes cuotas y deja el resto como saldo a favor. Por omisión el excedente se rechaza con `422`.
- Los pagos con fecha anterior a tu alta cuentan como tu línea base en el Panel de recuperación.

## 4. Créditos y conversaciones (opcional)

**Créditos.** Si tus cuotas pertenecen a un préstamo, agrúpalas con `POST /v1/credits`. Manda el capital prestado, la fecha en que se prestó y las cuotas por su `external_ref`.

```json
{
  "member_id": "6f1c…",
  "external_ref": "CRED-2023-0415",
  "principal": 90000,
  "start_date": "2023-04-15",
  "periods": 60,
  "frequency": "monthly",
  "billing_order_external_refs": ["CLI-1042-001", "CLI-1042-002"]
}
```

**Conversaciones.** El historial de WhatsApp o correo que tuviste fuera de Makatea entra con `POST /v1/conversations/import`, hasta 20,000 renglones por llamada. Los mensajes importados no disparan respuestas, avisos ni webhooks. Prueba primero con `"dry_run": true`.

## 5. Revisa y reactiva

- `GET /v1/billing-orders?count=true` te da el total de cuotas cargadas.
- `GET /v1/stats` te da lo vencido, lo por vencer y lo cobrado con las mismas cifras del Panel.
- Revisa en la app qué cuotas quedaron vencidas antes de reactivar las comunicaciones.

## Sin programar

Para una carga de una sola vez no hace falta la API. En la app, el botón **Importar a la cartera** de la lista de clientes acepta CSV o la hoja de Excel de Makatea. Lo que entra por archivo no emite webhooks.