Crear cuenta
PlataformaIndustriasPreciosSeguridadFAQEmpleo

Cambios de la API

Cada entrada lleva el día en que el cambio llegó a producción. Lo que no está desplegado no aparece aquí.

· Sincronización como ERP, pausa de la cobranza, cuotas que se generan y llaves de prueba

Makatea-API-Version: 2026-09-27

Tu sistema ya puede decir «así está el cliente hoy» sin preguntar si existe, cargar 500 registros en una llamada, pausar la cobranza de un cliente, generar el calendario de un crédito y probar todo sin que salga un solo mensaje.

Sincronizar como ERP

  • PUT /v1/members/by-ref/{external_ref}, PUT /v1/billing-orders/by-ref/{external_ref} y PUT /v1/credits/by-ref/{external_ref} crean o actualizan por tu identificador: 201 si lo crea, 200 si lo actualiza o si ya estaba igual. El encabezado Makatea-Upsert-Result dice cuál.
  • POST /v1/members/batch, /v1/billing-orders/batch y /v1/payments/batch reciben hasta 500 filas. Nunca fallan completos: cada fila trae su resultado con su índice y su código de error.
  • Mandar el mismo lote dos veces deja todo igual. dry_run: true dice qué pasaría sin escribir nada.
  • Los lotes no disparan webhooks ni le mandan mensajes a tus clientes. En pagos, notify_members: true manda las confirmaciones.

Control de la cobranza

  • POST /v1/members/{id}/pause con until y reason detiene la cobranza automática hasta esa fecha. POST /v1/members/{id}/resume la reanuda antes.
  • POST /v1/flows/{id}/members y DELETE /v1/flows/{id}/members/{member_id} inscriben o sacan a un cliente de un flujo de lista.
  • Eventos nuevos: member.paused, member.resumed y message.classified (el cliente escribió con una intención reconocida, como pagar o reagendar).

Cuotas

  • POST /v1/credits acepta schedule y genera las cuotas: semanales, quincenales o mensuales, con la suma exacta al centavo. La última cuota absorbe el redondeo.
  • Con capital y total, cada cuota trae su desglose de capital e interés.
  • POST /v1/billing-orders/{id}/split divide una cuota en partes que suman exactamente su saldo.

Liga de pago

  • POST /v1/billing-orders/{id}/payment-link acepta send_via (whatsapp, sms o email) para mandarla al cliente, y expires_at para su vigencia.
  • El evento payment_link.opened avisa cuando el cliente abre la liga.
  • GET y PUT /v1/settings/branding muestran u ocultan «Cobrado con Makatea» en los correos de cobranza y en la página de pago.

Versiones, errores y cupo

  • Cada respuesta dice qué versión aplicó en Makatea-Version. Puedes pedir otra con ese mismo encabezado. Las llaves que ya tenías siguen en 2026-09-23.
  • Desde 2026-09-27, un campo que la operación no conoce en el cuerpo contesta 422 unknown_field.
  • Cada endpoint de webhook conserva la versión con que se creó.
  • Cada operación de la referencia lista sus códigos de error.
  • Encabezados RateLimit-Policy y RateLimit. Una petición rechazada con 429 ya no gasta cupo.

Llaves de prueba

  • Las llaves mk_test_ trabajan sobre una copia de tu organización. Todo funciona igual, pero ningún mensaje sale y no se cobra dinero real.
  • Cada respuesta dice Makatea-Livemode: false cuando usas una llave de prueba.

Corrección

  • POST /v1/messages ya no le escribe a un cliente marcado como «no contactar»: contesta 409 do_not_contact.

· Llaves de API, idempotencia, webhooks firmados y cartera de crédito

Makatea-API-Version: 2026-09-23

La API deja de depender de la sesión de un usuario y gana todo lo que necesita una integración de cobranza.

Autenticación

  • Llaves mk_live_ que el dueño o un administrador crea en Configuración → Desarrolladores.
  • Cada llave tiene permisos read o write, puede expirar y se revoca al momento.
  • La llave viaja en Authorization: Bearer o en X-API-Key. Sin llave válida la respuesta es 401. Sin el permiso es 403 insufficient_scope.

Forma de las respuestas

  • El éxito siempre viene en {"data": …} y el error siempre en {"error": {"code", "message", "request_id"}}.
  • Cada respuesta trae X-Request-Id y Makatea-API-Version: 2026-09-23.
  • Un parámetro que no existe contesta 400 unknown_parameter con la lista de los permitidos.
  • Límite de 600 llamadas por minuto por llave, con X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset y Retry-After.

Idempotencia

  • Idempotency-Key en todo POST, PUT, PATCH y DELETE. La misma llave con el mismo cuerpo devuelve la respuesta original durante 24 horas.
  • La misma llave con otro cuerpo es 422 idempotency_key_reused.

Paginación y sincronización

  • Un solo cursor en todas las listas: pagination.next_cursor y has_more. offset sigue funcionando.
  • updated_since en clientes, cuotas y pagos ordena por fecha de cambio para sincronizar desde un punto.

Webhooks

  • 13 eventos, de member.created a message.received, entregados desde una cola.
  • Firma Makatea-Signature: t=…,v1=… con HMAC-SHA256 sobre el cuerpo completo.
  • 8 intentos durante 3 días. Consulta de eventos y entregas, y reintento manual con POST /v1/webhook-deliveries/{id}/retry.

Pagos y cartera

  • Pagos parciales con fecha real (paid_at) y regla para el excedente.
  • Libro de pagos con GET /v1/payments. La anulación (POST /v1/payments/{id}/void) queda como renglón negativo.
  • Condonación, cargos moratorios y saldo a favor por cliente.
  • PATCH /v1/billing-orders/{id} mueve una cuota de fecha o de cliente y reprograma sus recordatorios.
  • Créditos con capital e interés por cuota (/v1/credits) y regla de aplicación de pagos configurable.
  • Liga de pago con la cuenta de pagos de la organización: POST /v1/billing-orders/{id}/payment-link.

Promesas, mensajes y documentos

  • Promesas de pago por cliente. Pausan la cobranza hasta su fecha y emiten promise.kept o promise.broken.
  • POST /v1/messages manda un texto o una plantilla por la línea de la organización.
  • Conversación de cada cliente e importación del historial con POST /v1/conversations/import.
  • Documentos adjuntos por cliente, de hasta 15 MB.

Operación

  • GET /v1/status contesta sin llave.
  • El spec OpenAPI se genera de la misma tabla de rutas que atiende las llamadas.