Documentação

O Asaas não tem catálogo de produtos

O Asaas não tem catálogo de produtos: uma cobrança carrega um campo "description" de texto livre, digitado a cada emissão, e não existe um objeto de produto ou de preço ao qual a assinatura se prenda. Dois clientes do mesmo plano podem chegar com descrições diferentes, e nada no dado diz que se trata do mesmo plano. Por isso a segmentação por produto fica indisponível na conta inteira enquanto houver uma fonte Asaas, e não apenas nas assinaturas que vieram dela: um filtro que respondesse por metade da sua conta e ignorasse a outra metade pareceria completo sem ser, e isso é pior do que não ter filtro nenhum. O seu MRR, o seu churn e a sua receita não mudam de valor por causa disso; o que some das Métricas é a quebra por produto. Não há premissa a declarar aqui: o dado não existe do outro lado, e nenhuma leitura melhor o inventa.

O Asaas não registra trial em campo nenhum

A assinatura do Asaas não tem um único campo de trial: não existe "trialDays", "trialEndDate" nem equivalente, e mandar qualquer um deles na criação da assinatura é aceito com HTTP 200 e ignorado em silêncio (medido na conta de homologação). Não é uma lacuna que a gente contorne lendo melhor: para o Asaas, dar 7 dias grátis e emitir a primeira cobrança para daqui a 7 dias são a mesma operação, e é assim que a documentação oficial dele manda fazer trial. Nem o Asaas sabe dizer quem teve trial. Consequência: no Funil de vendas, Trials Iniciados fica em zero para esta fonte, e a Conversão de Trial não tem o que medir. O seu MRR não muda, porque uma assinatura sem cobrança confirmada já vale zero no nosso cálculo: o que se perde é o rótulo, não o dinheiro. Se você de fato dá um período gratuito antes da primeira cobrança, ele só passa a existir quando você declara a premissa em Configurações, nas Premissas de Cálculo.

Plano gratuito não é representável no Asaas

O Asaas recusa cobrança abaixo de R$ 5,00, e medimos isso nas quatro formas de pagamento: valor zero volta 400 (para ele, zero é o mesmo que não informar), um centavo volta 400 ("o valor mínimo é R$ 5,00") e R$ 100 com 100% de desconto também é recusado. Não é limitação da nossa leitura: um usuário do seu plano gratuito não tem assinatura nem cobrança no Asaas, ele existe só no seu banco de dados. Consequência: no Funil de vendas, Freemiums Iniciados fica em zero, a Conversão de Freemium não tem o que medir, e a sua base gratuita não aparece na contagem de Assinantes. O seu MRR não muda, porque usuário gratuito não traz receita recorrente, mas o topo do seu funil fica menor do que ele é na vida real. Não há premissa que resolva: não há o que ler, e nós não inventamos o que não foi gravado. Se você precisa medir o seu freemium, ele teria que ser declarado por outra fonte: a de Dados customizados aceita assinatura de valor zero.

O Asaas não tem histórico de eventos

Não existe no Asaas nada equivalente ao histórico de eventos da Stripe: não dá para listar o que aconteceu, ver a fila pendente nem pedir o reenvio de uma entrega. Se um evento se perde, não há a quem perguntar o que a gente perdeu. Consequência: o fato que ele carregava, um pagamento ou um cancelamento, ficaria de fora das suas métricas, e nada na tela denunciaria, porque não existe uma segunda lista para discordar da primeira. Como não dá para perguntar, a gente alarma: a tela de Fontes de Dados avisa quando o webhook foi apagado ou desativado, quando o Asaas pausou a fila de entrega depois de falhas repetidas (ele guarda os eventos pausados por 14 dias, então retomar dentro desse prazo não perde nada; passou disso, perdeu para sempre) e quando um evento chegou e não conseguimos guardá-lo. Desses avisos, só o último não some sozinho: os outros saem da tela quando a fonte volta a ficar sadia. Um evento perdido não volta, então, quando houve perda, a cura é reimportar a fonte, que relê a sua conta no Asaas e refaz o seu histórico a partir do que ele responde. Não há o que configurar nem o que declarar: o que se pede de você é atender o aviso quando ele aparecer.

O Asaas não avisa quando um cliente muda

O Asaas não tem webhook de cliente: os quatro eventos "CUSTOMER_*" são recusados com HTTP 400 na criação do webhook, enquanto outros 24 são aceitos (medimos um por um). Um cliente NOVO ainda chega até nós de carona, porque o evento da assinatura ou da cobrança dele nos manda buscá-lo. O que não chega é a MUDANÇA de quem já está aqui: corrigir o nome, o e-mail ou o documento no cadastro do Asaas não gera evento nenhum, e o dado novo só aparece quando você reimporta a fonte. Nenhuma métrica muda com isso: o MRR, o churn e a contagem de Assinantes não dependem do nome de ninguém, e o que fica velho é o rótulo que você lê em Clientes. Reconferir todo cliente a cada cobrança consertaria isso, e nós não fazemos: gastaria a cota de API da sua conta para corrigir um dado que não muda número. Não há o que declarar.

O trial só existe se você declarar

Como o Asaas não distingue "sete dias grátis" de "primeira cobrança daqui a sete dias", o trial só existe se você DECLARAR que a sua operação tem trial, em Configurações, nas Premissas de Cálculo. Sem declarar, nenhum cliente é contado como trial: seria um chute, e um chute vira número na sua tela. Declarando, o intervalo entre a criação da assinatura e a primeira cobrança passa a ser lido como período de teste, e a duração sai do próprio dado, não de um número que você digita (por isso a pergunta é sim ou não, e não "quantos dias"). O efeito colateral fica dito na cara: se você também adia a primeira cobrança por outro motivo, uma negociação ou um acordo pontual, essas assinaturas entram como trial e as suas métricas de trial superestimam. A premissa vem desligada, mexe só no Funil de vendas e nunca no MRR, e ligá-la ou desligá-la recalcula o seu histórico na hora.

O churn é datado no fim do último período pago

A assinatura apagada no Asaas não diz quando foi apagada: sobram "dateCreated" e "nextDueDate", não existe "deletedDate", "canceledDate" nem "endDate", e não há histórico de eventos de onde pescar a data. Carimbar o instante em que a nossa varredura viu a assinatura sumir seria pior do que não ter data: o dia do seu churn passaria a depender de quando o nosso robô rodou, e reprocessar o histórico moveria o gráfico de ontem. Então trocamos a pergunta: "quando cancelou?" o Asaas não sabe, mas "até quando pagou?" está registrado em cada cobrança quitada, e fica lá para sempre. O intervalo de MRR de uma assinatura Asaas é a união dos períodos pagos, e o churn é datado no fim do último deles. Na prática: quem pagou até 10 de março e não renovou aparece como churn em 10 de março, e não no dia em que você apagou a assinatura no painel, então o Churn de Clientes e o Churn de MRR seguem a data do dado, não a do seu clique. Não há o que declarar: é a leitura mais fiel que o dado do Asaas permite.

O ciclo quinzenal (BIWEEKLY) é tratado como 14 dias

O Asaas tem um ciclo chamado "BIWEEKLY" e a documentação dele só diz "quinzenal", uma palavra ambígua: em português ela costuma significar 15 dias (24 cobranças por ano), em inglês significa 14 (26 por ano). Medimos criando uma assinatura de verdade na conta de homologação: as cobranças saíram em 14/07, 28/07 e 11/08, ou seja, 14 dias. Então o MRR de uma assinatura quinzenal é o valor dela vezes 26, dividido por 12. Chutar 15 dias daria cerca de 8% a menos de MRR em cada assinatura desse ciclo, e o erro não apareceria em lugar nenhum. Se você não usa o ciclo quinzenal, esta premissa não toca em número nenhum seu, e não há o que declarar.

O cliente apagado é recuperado pelas cobranças dele

O cliente apagado some da listagem do Asaas: "/v3/customers" não tem "includeDeleted", então nem uma varredura completa da sua base o encontra. Mas ele continua respondendo por id (um GET direto devolve HTTP 200), e as assinaturas e as cobranças dele continuam citando esse id. Nós usamos exatamente isso: quando uma assinatura ou uma cobrança aponta para um cliente que a listagem não trouxe, buscamos aquele cliente pelo id e o trazemos de volta. Sem essa recuperação o seu histórico perderia gente: na conta Asaas real em que medimos, 124 clientes, 28% da base histórica, só existem por causa dela. Consequência: a contagem de Assinantes, o Churn de Clientes, o ARPA e o LTV também contam quem você já apagou do Asaas, que é o certo para um histórico, porque o passado dele aconteceu. Não há o que declarar.

O Asaas não tem chave só de leitura

Toda chave de API do Asaas é full-access, e não há como pedir menos: a especificação da API não tem "scope", "permission" nem "readOnly", e o corpo de criação de chave aceita só "name" e "expirationDate". Isso é diferente da Stripe, onde pedimos uma chave restrita que, por construção, não consegue mover dinheiro: a chave que você colar aqui emite cobrança, transfere dinheiro para fora da conta e apaga cliente. O que fazemos com ela é leitura, e uma única escrita: registrar o nosso próprio webhook. O cliente HTTP que o import, o dreno e a varredura recebem só sabe fazer GET, e o caminho que escreve está trancado no recurso "/webhooks" por uma guarda travada por teste. Ainda assim o risco é seu, e você tem o direito de saber antes de colar: pode revogar a chave quando quiser no painel do Asaas, ou criá-la já com data de expiração (quando ela expirar, a sincronização para e a tela de Fontes de Dados avisa). Isto não muda número nenhum seu: é risco, não métrica.

A cota de API do Asaas é sua, não nossa

O Asaas limita 25.000 requisições a cada 12 horas por CONTA, e essa cota é compartilhada com o uso que você mesmo faz dela: o seu site, o seu ERP e o seu checkout gastam do mesmo bolso que a nossa leitura. Se a nossa varredura fosse a gota que estoura a cota, as chamadas da SUA operação passariam a falhar, e isso é inaceitável: uma métrica errada é ruim, travar o seu caixa não é negociável. Por isso cada passe tem um teto declarado de 2.000 chamadas, cerca de 8% da cota de 12 horas, e usa 6 chamadas simultâneas embora o Asaas aceite 50; quando o teto é atingido, a varredura para, diz que parou e continua no passe seguinte, sem perder nada. E paramos na primeira recusa por excesso, sem insistir: o Asaas não devolve nenhum cabeçalho de limite de uso (procuramos em cerca de 55 requisições e não veio um), então não temos como distinguir um limite de rajada do estouro da sua cota, e na dúvida a sua operação vem primeiro. Quando isso acontece, a tela de Fontes de Dados acende o alarme. Não há o que declarar nem o que configurar.

Nesta fonte, quem informa os dados é você

Nas outras fontes há um gateway do outro lado, e o que ele registrou é a referência contra a qual tudo é conferido. Aqui não há: as assinaturas, os clientes e os pagamentos desta fonte são exatamente os que você declarou, pela tela, pela planilha ou pela API. Consequência: o que você declara é a verdade, e é sobre ela que cada número desta conta é calculado. Uma assinatura que você esqueceu de declarar não aparece em lugar nenhum, e nada a denuncia, porque não existe uma segunda cópia para discordar da primeira. Pelo mesmo motivo, esta fonte guarda a ÚNICA cópia destes dados: não há de onde reimportar, remover a fonte apaga o que você declarou e refaz as suas métricas sem isso, e é por isso que a tela pede um backup antes. Não há premissa a declarar aqui: é a natureza da fonte, e vale igual para quem declara três assinaturas e para quem declara três mil.

A planilha assume um valor único por assinatura

Uma linha de planilha tem UM valor; uma assinatura tem uma HISTÓRIA de valores. Não existe coluna que diga "custou R$ 99 até março e R$ 149 depois", então a planilha só sabe afirmar uma coisa: esta assinatura sempre valeu isto. É o que assumimos ao subir o arquivo, e o valor da coluna "amount" passa a valer desde a data de início da assinatura. Consequência: se o preço mudou no meio do caminho, o MRR dos meses passados sai com o preço de hoje, e o upgrade some do mês em que ele aconteceu (nas Métricas não haverá expansão nem contração ali, e o gráfico sobe como se sempre tivesse sido assim). Subir a planilha de novo com o preço novo não corrige nada em silêncio: a subida inteira é recusada, porque reescrever um valor já declarado muda o MRR de meses que já fecharam, e isso é uma errata, que você precisa confirmar. O que fazer: informe as faixas de valor da assinatura, na tela ou pela API, uma faixa por preço com a data em que ele passou a valer, e aí cada mês usa o preço daquele mês e o upgrade aparece como expansão no dia em que aconteceu.