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.

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

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.

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.

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.

{
  "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.