O que é o Asaas

O Asaas é uma plataforma brasileira de gestão financeira e cobranças voltada para pequenas e médias empresas. Ela permite criar clientes, gerar boletos, cobrar via Pix, cartão de crédito e realizar cobranças recorrentes (assinaturas) tudo via API REST, sem precisar de contrato com adquirente ou gateway separado.

O grande diferencial para desenvolvedores e a API bem documentada com ambiente sandbox gratuito, suporte a webhooks e um sistema de assinaturas nativo. Você cria a assinatura uma vez e o Asaas gera automaticamente as próximas cobranças no ciclo configurado.

Para projetos SaaS no Brasil, o Asaas é uma das escolhas mais populares justamente por dispensar integração com múltiplos serviços: uma única API cuida do cartão, boleto, Pix e da lógica de recorrência.

Como funciona a recorrência no Asaas

Quando você cria uma assinatura via POST /v3/subscriptions, o Asaas assume o controle do ciclo de cobrança. Ele gera automaticamente uma nova cobrança em cada ciclo (semanal, mensal, anual etc.) e dispara eventos de webhook para o seu backend a cada mudança de status.

O seu sistema não precisa se preocupar em criar cobranças manualmente. A responsabilidade do seu backend é reagir aos eventos: ativar o plano quando o pagamento é confirmado, suspender quando vencer, cancelar quando a assinatura for deletada.

Esse modelo é chamado de cobrança orientada a eventos. O Asaas é a fonte de verdade sobre o status financeiro; o seu sistema apenas ouve os webhooks e atualiza o banco de dados local conforme recebe os eventos.

Ciclos disponíveis e campos da assinatura

O campo cycle define com que frequência o Asaas gera novas cobranças. Os valores aceitos são:

  • WEEKLY: cobrança toda semana.
  • BIWEEKLY: a cada duas semanas.
  • MONTHLY: mensal - o mais comum para SaaS.
  • QUARTERLY: trimestral.
  • SEMIANNUALLY: semestral.
  • YEARLY: anual.

Além do cycle, os campos obrigatórios são: customer (ID do cliente no Asaas), billingType (CREDIT_CARD, BOLETO ou PIX), value (valor da cobrança) e nextDueDate (data da primeira cobrança).

Para cobranças no cartão de crédito, você também precisa enviar o objeto creditCard com os dados do cartão e creditCardHolderInfo com nome, email, CPF/CNPJ, CEP e telefone do titular.

Como criar uma assinatura: passo a passo

Antes de criar a assinatura, você precisa ter um customer cadastrado no Asaas. Faça um POST em /v3/customers com nome, email e CPF/CNPJ do cliente. O retorno traz o ID no formato cus_XXXXXXXXXXXX, que você usa na assinatura.

Com o customer em mãos, faca um POST em /v3/subscriptions. No header, inclua access_token com sua chave de API (ou a do ambiente sandbox para testes). No body, passe customer, billingType, value, nextDueDate, cycle e description. Para cartão de crédito, adicione os objetos creditCard e creditCardHolderInfo.

A resposta traz o ID da assinatura (sub_XXXXXXXXXXXX) e o status ACTIVE. O Asaas já agenda a próxima cobrança automaticamente. Salve o ID da assinatura no seu banco para conseguir associar os eventos de webhook a assinatura correta.

Configurando o webhook no Asaas

No painel do Asaas, va em Configurações > Integrações > Webhook e cadastre a URL do seu endpoint. O Asaas vai enviar um POST para essa URL sempre que um evento relevante acontecer. Configure também um token de autenticação que o Asaas vai incluir no header asaas-access-token de cada requisição - use isso para validar que a requisição veio realmente do Asaas.

Os eventos mais importantes para gerenciar assinaturas são:

  • PAYMENT_CONFIRMED: pagamento de cartão confirmado - ativar ou renovar o plano.
  • PAYMENT_RECEIVED: pagamento de boleto ou Pix recebido - mesmo efeito do CONFIRMED.
  • PAYMENT_OVERDUE: cobrança vencida - suspender acesso ou notificar o cliente.
  • PAYMENT_REFUNDED: estorno realizado - reverter ativação se necessário.
  • SUBSCRIPTION_DELETED: assinatura cancelada - cancelar acesso imediatamente.

Os eventos PAYMENT_CREATED e SUBSCRIPTION_CREATED são úteis para logs e auditoria, mas normalmente não mudam o status do plano no seu sistema.

Endpoint de webhook no .NET

No seu backend ASP.NET Core, crie um controller com rota /webhook/asaas decorado com [HttpPost]. A primeira coisa a fazer é validar o header asaas-access-token: se não bater com o token configurado, retorne 401. Nunca processe um webhook sem validar o token.

O payload do webhook traz um campo Event com o nome do evento e objetos Payment e/ou Subscription. Use um switch no Event para chamar o serviço correto. Para PAYMENT_CONFIRMED e PAYMENT_RECEIVED, ative ou renove o plano. Para PAYMENT_OVERDUE, suspenda ou notifique. Para SUBSCRIPTION_DELETED, cancele.

Uma regra crítica: sempre retorne HTTP 200, mesmo que você ignore o evento. Se o Asaas não receber 200, ele retenta o webhook até 5 vezes com intervalos crescentes. Retornar 500 ou 4xx faz o Asaas re-enviar o mesmo evento múltiplas vezes, o que pode causar ativações ou cancelamentos duplicados.

DTOs e lógica de ativação

Para deserializar o payload do webhook, crie uma classe AsaasWebhookDto com as propriedades Event (string), Payment (AsaasPaymentDto nullable) e Subscription (AsaasSubscriptionDto nullable). O AsaasPaymentDto precisa de pelo menos: Id, Customer, Subscription (ID da assinatura), Status, Value, DueDate e PaymentDate.

Na lógica de ativação, busque a assinatura no seu banco usando o AsaasSubscriptionId (o campo Subscription do payload). Atualize o status para Active, registre a data do último pagamento e calcule a próxima renovação com base no ciclo. Para planos mensais, use DueDate.AddMonths(1).

Um ponto importante: idempotência. O mesmo evento pode chegar mais de uma vez (falha de rede, timeout, retry do Asaas). Sempre verifique se o payment.Id já foi processado antes de ativar ou renovar. Salve os IDs de pagamentos já processados em uma tabela de controle e ignore eventos duplicados.

Comparação com alternativas

As principais alternativas ao Asaas para recorrência no Brasil são o Stripe (internacional, excelente API mas cobra em USD), o PagSeguro (nacional, API mais complexa) e o Iugu (similar ao Asaas, também brasileiro).

O Stripe tem a melhor API do mercado e documentação impecável, mas trabalhar com conversão USD/BRL e tributação pode complicar para produtos vendidos exclusivamente no Brasil. O Iugu é muito similar ao Asaas em features e taxa.

O Asaas se destaca pela facilidade de abertura de conta, sandbox gratuito sem burocracia e pelo suporte a Pix nativo, o que é essencial para o mercado brasileiro. Para SaaS com clientes brasileiros que preferem Pix ou boleto, o Asaas é a escolha mais prática.

Pontos positivos e limitações

Os pontos fortes do Asaas para recorrência são claros: API bem documentada, sandbox gratuito, suporte a Pix/boleto/cartão no mesmo contrato, webhooks confiáveis e um painel completo para acompanhar assinaturas sem precisar de ferramentas externas.

As limitações existem e vale conhecer. A taxa por transação pode ser maior do que gateways puros dependendo do volume. O suporte técnico via chat não é instantâneo fora do horário comercial. E a personalização das emails de cobrança enviadas ao cliente é limitada.

Um ponto de atenção para devs: o Asaas não garante a ordem de entrega dos webhooks. Um PAYMENT_CONFIRMED pode chegar antes de um PAYMENT_CREATED para a mesma cobrança. Projete o seu sistema para ser tolerante a eventos fora de ordem.

Casos de uso reais

O Asaas com recorrência é usado em vários tipos de produto SaaS brasileiro:

  • Plataformas de cursos: cobram mensalmente e liberam acesso ao conteúdo após PAYMENT_CONFIRMED.
  • Ferramentas B2B: planos mensais/anuais com suspensão automática em PAYMENT_OVERDUE.
  • Aplicativos de gestão: trial gratuito que converte para plano pago na primeira cobrança confirmada.
  • Clubes de assinatura: cobrança recorrente com envio de produto físico vinculado ao evento de pagamento.

Dicas e boas práticas

Use sempre o ambiente sandbox do Asaas durante o desenvolvimento. O sandbox tem URL própria (sandbox.asaas.com) e tokens separados. Nunca use credenciais de produção no código de desenvolvimento.

Implemente uma tabela de idempotency keys (payment_id processados) para evitar ativações duplicadas. Guarde o payment.Id de cada evento PAYMENT_CONFIRMED ou PAYMENT_RECEIVED já processado e ignore se receber o mesmo ID novamente.

Configure um retry com backoff no seu serviço de ativação para lidar com falhas temporárias de banco de dados sem lançar exceção para o Asaas. Erros internos devem ser tratados antes de retornar 200 - use try/catch e log de erros, mas sempre retorne 200 para o Asaas. Use filas (RabbitMQ, Azure Service Bus) se precisar de maior confiabilidade na entrega.

Vale a pena usar o Asaas para recorrência?

Para produtos SaaS com clientes brasileiros, sim. O Asaas resolve em uma única integração o que antes exigia contrato com adquirente, gateway e lógica de recorrência manual. A API é estável, o sandbox funciona bem e o suporte a Pix e boleto é nativo.

Se você está construindo um SaaS com planos mensais e precisa começar rápido, o fluxo descrito neste post (criar assinatura + endpoint de webhook) é tudo que você precisa para ter recorrência funcionando em produção em poucas horas.

O próximo passo é criar o cliente no Asaas, subir o endpoint de webhook em produção com HTTPS (obrigatório), configurar o webhook no painel e testar com o simulador de eventos que o próprio Asaas oferece no sandbox.