Documentación

Asaas no tiene catálogo de productos

Asaas no tiene catálogo de productos: un cobro lleva un campo "description" de texto libre, escrito en cada emisión, y no existe un objeto de producto ni de precio al que la suscripción se enganche. Dos clientes del mismo plan pueden llegar con descripciones distintas, y nada en el dato dice que son el mismo plan. Por eso la segmentación por producto queda no disponible en toda la cuenta mientras exista una fuente Asaas, y no solo en las suscripciones que vinieron de ella: un filtro que respondiera por la mitad de tu cuenta e ignorara la otra mitad parecería completo sin serlo, y eso es peor que no tener ningún filtro. Tu MRR, tu churn y tus ingresos no cambian de valor por esto; lo que desaparece de Métricas es el desglose por producto. No hay premisa que declarar aquí: el dato no existe del otro lado, y ninguna lectura más cuidadosa lo inventa.

Asaas no registra el trial en ningún campo

La suscripción de Asaas no tiene un solo campo de trial: no existe "trialDays", ni "trialEndDate", ni equivalente, y mandar cualquiera de ellos al crear la suscripción se acepta con HTTP 200 y se ignora en silencio (medido en la cuenta de homologación). No es un hueco que podamos sortear leyendo mejor: para Asaas, dar 7 días gratis y emitir el primer cobro dentro de 7 días son la misma operación, y así es como su propia documentación manda hacer un trial. Ni Asaas sabe decir quién tuvo trial. Consecuencia: en el Embudo de ventas, Trials Iniciados queda en cero para esta fuente, y la Conversión de Trial no tiene qué medir. Tu MRR no cambia, porque una suscripción sin cobro confirmado ya vale cero en nuestro cálculo: lo que se pierde es la etiqueta, no el dinero. Si de verdad das un período gratuito antes del primer cobro, este solo pasa a existir cuando declaras la premisa en Configuración, en Premisas de Cálculo.

Un plan gratuito no es representable en Asaas

Asaas rechaza cualquier cobro por debajo de R$ 5,00, y lo medimos en las cuatro formas de pago: valor cero devuelve 400 (para él, cero es lo mismo que no informar), un centavo devuelve 400 ("el valor mínimo es R$ 5,00") y R$ 100 con 100% de descuento también se rechaza. No es una limitación de nuestra lectura: un usuario de tu plan gratuito no tiene ni suscripción ni cobro en Asaas, existe solo en tu base de datos. Consecuencia: en el Embudo de ventas, Freemiums Iniciados queda en cero, la Conversión de Freemium no tiene qué medir, y tu base gratuita no aparece en el conteo de Suscriptores. Tu MRR no cambia, porque un usuario gratuito no trae ingreso recurrente, pero la parte alta de tu embudo se ve más pequeña de lo que es en la vida real. No hay premisa que lo resuelva: no hay nada que leer, y no inventamos lo que nunca se registró. Si necesitas medir tu freemium, tendría que declararse por otra fuente: la de Datos personalizados acepta suscripciones de valor cero.

Asaas no tiene historial de eventos

No existe en Asaas nada equivalente al historial de eventos de Stripe: no se puede listar lo que pasó, ver la cola pendiente ni pedir el reenvío de una entrega. Si un evento se pierde, no hay a quién preguntarle qué perdimos. Consecuencia: el hecho que llevaba, un pago o una cancelación, quedaría fuera de tus métricas, y nada en la pantalla lo delataría, porque no existe una segunda lista que discrepe de la primera. Como no podemos preguntar, alarmamos: la pantalla de Fuentes de Datos avisa cuando el webhook fue borrado o desactivado, cuando Asaas pausó la cola de entrega tras fallos repetidos (guarda los eventos pausados 14 días, así que retomar dentro de ese plazo no pierde nada; pasado ese plazo, se pierden para siempre) y cuando llegó un evento y no logramos guardarlo. De esos avisos, solo el último no desaparece solo: los demás salen de la pantalla cuando la fuente vuelve a estar sana. Un evento perdido no vuelve, así que cuando hubo pérdida, la cura es reimportar la fuente, que vuelve a leer tu cuenta de Asaas y rehace tu historial a partir de lo que él responde. No hay nada que configurar ni que declarar: lo que te pedimos es atender el aviso cuando aparezca.

Asaas no avisa cuando un cliente cambia

Asaas no tiene webhook de cliente: los cuatro eventos "CUSTOMER_*" se rechazan con HTTP 400 al crear el webhook, mientras que otros 24 se aceptan (los medimos uno por uno). Un cliente NUEVO igual llega hasta nosotros de forma indirecta, porque el evento de su suscripción o de su cobro nos manda a buscarlo. Lo que no llega es el CAMBIO de quien ya está aquí: corregir el nombre, el correo o el documento en el registro de Asaas no genera ningún evento, y el dato nuevo solo aparece cuando reimportas la fuente. Ninguna métrica cambia por esto: el MRR, el churn y el conteo de Suscriptores no dependen del nombre de nadie, y lo que queda viejo es la etiqueta que lees en Clientes. Reverificar cada cliente en cada cobro lo arreglaría, y no lo hacemos: gastaría la cuota de API de tu cuenta para corregir un dato que no mueve ningún número. No hay nada que declarar.

El trial solo existe si lo declaras

Como Asaas no distingue "siete días gratis" de "primer cobro dentro de siete días", el trial solo existe si DECLARAS que tu operación lo tiene, en Configuración, en Premisas de Cálculo. Sin declararlo, ningún cliente cuenta como trial: sería una suposición, y una suposición se convierte en un número en tu pantalla. Al declararlo, el intervalo entre la creación de la suscripción y el primer cobro pasa a leerse como período de prueba, y la duración sale del propio dato, no de un número que tú escribes (por eso la pregunta es sí o no, y no "cuántos días"). El efecto colateral se dice de frente: si también aplazas el primer cobro por otro motivo, una negociación o un acuerdo puntual, esas suscripciones entran como trial y tus métricas de trial sobreestiman. La premisa viene desactivada, mueve solo el Embudo de ventas y nunca el MRR, y activarla o desactivarla recalcula tu historial al instante.

El churn se fecha al final del último período pagado

La suscripción borrada en Asaas no dice cuándo se borró: quedan "dateCreated" y "nextDueDate", no existe "deletedDate", "canceledDate" ni "endDate", y no hay historial de eventos de donde pescar la fecha. Sellar el instante en que nuestro barrido vio que la suscripción desapareció sería peor que no tener fecha: el día de tu churn dependería de cuándo corrió nuestro robot, y reprocesar el historial movería el gráfico de ayer. Así que cambiamos la pregunta: "¿cuándo canceló?" Asaas no lo sabe, pero "¿hasta cuándo pagó?" está registrado en cada cobro liquidado, y se queda ahí para siempre. El intervalo de MRR de una suscripción Asaas es la unión de sus períodos pagados, y el churn se fecha al final del último. En la práctica: quien pagó hasta el 10 de marzo y no renovó aparece como churn el 10 de marzo, y no el día en que borraste la suscripción en el panel, así que el Churn de Clientes y el Churn de MRR siguen la fecha del dato, no la de tu clic. No hay nada que declarar: es la lectura más fiel que el dato de Asaas permite.

El ciclo quincenal (BIWEEKLY) se trata como 14 días

Asaas tiene un ciclo llamado "BIWEEKLY" y su documentación solo lo llama "quinzenal", una palabra ambigua: en portugués suele significar 15 días (24 cobros al año), en inglés biweekly significa 14 (26 al año). Lo medimos creando una suscripción real en la cuenta de homologación: los cobros salieron el 14/07, el 28/07 y el 11/08, es decir, 14 días. Entonces el MRR de una suscripción quincenal es su importe por 26, dividido entre 12. Suponer 15 días daría cerca de un 8% menos de MRR en cada suscripción de ese ciclo, y el error no aparecería en ninguna parte. Si no usas el ciclo quincenal, esta premisa no toca ningún número tuyo, y no hay nada que declarar.

El cliente eliminado se recupera por sus cobros

El cliente eliminado desaparece de los listados de Asaas: "/v3/customers" no tiene "includeDeleted", así que ni un barrido completo de tu base lo encuentra. Pero sigue respondiendo por id (un GET directo devuelve HTTP 200), y sus suscripciones y cobros siguen citando ese id. Eso es exactamente lo que usamos: cuando una suscripción o un cobro apunta a un cliente que el listado no trajo, buscamos a ese cliente por id y lo traemos de vuelta. Sin esa recuperación tu historial perdería gente: en la cuenta Asaas real en la que medimos, 124 clientes, el 28% de la base histórica, existen solo por ella. Consecuencia: el conteo de Suscriptores, el Churn de Clientes, el ARPA y el LTV también cuentan a quien ya eliminaste de Asaas, que es lo correcto para un historial, porque su pasado ocurrió. No hay nada que declarar.

Asaas no tiene clave de solo lectura

Toda clave de API de Asaas es de acceso total, y no hay forma de pedir menos: la especificación de la API no tiene "scope", ni "permission", ni "readOnly", y el cuerpo de creación de clave acepta solo "name" y "expirationDate". Esto es distinto de Stripe, donde pedimos una clave restringida que, por construcción, no puede mover dinero: la clave que pegues aquí emite cobros, transfiere dinero fuera de la cuenta y elimina clientes. Lo que hacemos con ella es leer, y una sola escritura: registrar nuestro propio webhook. El cliente HTTP que reciben la importación, el drenaje y el barrido solo sabe hacer GET, y el camino que escribe está bloqueado en el recurso "/webhooks" por una guarda que un test mantiene en pie. Aun así el riesgo es tuyo, y tienes derecho a saberlo antes de pegarla: puedes revocarla cuando quieras en el panel de Asaas, o crearla ya con fecha de vencimiento (cuando venza, la sincronización se detiene y la pantalla de Fuentes de Datos te avisa). Nada de esto cambia ningún número tuyo: es riesgo, no métrica.

La cuota de API de Asaas es tuya, no nuestra

Asaas limita 25.000 peticiones cada 12 horas por CUENTA, y esa cuota es compartida con el uso que tú mismo haces de ella: tu sitio, tu ERP y tu checkout gastan del mismo bolsillo que nuestra lectura. Si nuestro barrido fuera la gota que revienta la cuota, las llamadas de TU operación empezarían a fallar, y eso es inaceptable: una métrica equivocada es mala, trabar tu caja no es negociable. Por eso cada pase tiene un tope declarado de 2.000 llamadas, cerca del 8% de la cuota de 12 horas, y usa 6 llamadas simultáneas aunque Asaas acepte 50; cuando se alcanza el tope, el barrido para, dice que paró y continúa en el pase siguiente, sin perder nada. Y paramos en el primer rechazo por exceso, sin insistir: Asaas no devuelve ninguna cabecera de límite de uso (buscamos en unas 55 peticiones y no vino ni una), así que no podemos distinguir un límite de ráfaga del agotamiento de tu cuota, y en la duda tu operación va primero. Cuando eso pasa, la pantalla de Fuentes de Datos enciende la alarma. No hay nada que declarar ni que configurar.

En esta fuente, quien informa los datos eres tú

En las otras fuentes hay una pasarela del otro lado, y lo que ella registró es la referencia contra la que todo se verifica. Aquí no la hay: las suscripciones, los clientes y los pagos de esta fuente son exactamente los que tú declaraste, por la pantalla, por planilla o por la API. Consecuencia: lo que declaras es la verdad, y sobre ella se calcula cada número de esta cuenta. Una suscripción que olvidaste declarar no aparece en ninguna parte, y nada la delata, porque no existe una segunda copia que discrepe de la primera. Por el mismo motivo, esta fuente guarda la ÚNICA copia de estos datos: no hay de dónde reimportarlos, eliminar la fuente borra lo que declaraste y rehace tus métricas sin eso, y por eso la pantalla te pide una copia de seguridad antes. No hay premisa que declarar aquí: es la naturaleza de la fuente, y vale igual para quien declara tres suscripciones y para quien declara tres mil.

La planilla asume un único importe por suscripción

Una fila de planilla lleva UN importe; una suscripción lleva una HISTORIA de importes. No existe columna que diga "costó R$ 99 hasta marzo y R$ 149 después", así que la planilla solo sabe afirmar una cosa: esta suscripción siempre valió esto. Es lo que asumimos al subir el archivo, y el importe de la columna "amount" pasa a valer desde la fecha de inicio de la suscripción. Consecuencia: si el precio cambió por el camino, el MRR de los meses pasados sale con el precio de hoy, y el upgrade desaparece del mes en que ocurrió (en Métricas no habrá expansión ni contracción ahí, y el gráfico sube como si siempre hubiera sido así). Subir la planilla de nuevo con el precio nuevo no lo corrige en silencio: la subida entera se rechaza, porque reescribir un importe ya declarado cambia el MRR de meses que ya cerraron, y eso es una fe de erratas, que tienes que confirmar. Qué hacer: declara los tramos de importe de la suscripción, en la pantalla o por la API, un tramo por precio con la fecha en que empezó a valer, y así cada mes usa el precio de ese mes y el upgrade aparece como expansión el día en que ocurrió.