Fluxo de bloqueio de assinatura por divergência de split

Trate bloqueios de assinatura por divergência de Split

Uma assinatura pode ser bloqueada quando o valor configurado para o Split de Pagamentos ultrapassa o valor líquido disponível na cobrança.

Durante o bloqueio, novas cobranças deixam de ser geradas até que a divergência seja corrigida ou o prazo de regularização expire.

Quando o bloqueio ocorre

O Asaas verifica a compatibilidade do Split quando:

uma nova cobrança da assinatura é criada;
uma cobrança pertencente à assinatura é processada;
o valor líquido disponível fica inferior ao valor destinado aos participantes do Split.

Quando a divergência é identificada:

a assinatura é bloqueada;
o Split é temporariamente desabilitado;
novas cobranças deixam de ser geradas;
o evento SUBSCRIPTION_SPLIT_DIVERGENCE_BLOCK é enviado.

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Detectar divergência de Split"] --> B["Bloquear a assinatura"]
    B --> C["Enviar Webhook"]
    C --> D{"Corrigido em até 2 dias úteis?"}

    D --> DSim(("Sim"))
    D --> DNao(("Não"))

    DSim --> E["Desbloquear a assinatura"]
    E --> F["Retomar cobranças com Split"]

    DNao --> G["Expirar o bloqueio"]
    G --> H["Desabilitar o Split"]
    H --> I["Retomar cobranças sem Split"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px
    classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px,font-size:17px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px,font-size:16px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px,font-size:16px

    class A inicio
    class D decisao
    class B,C,E,G,H validacao
    class F sucesso
    class I analise

    class DSim respostaSim
    class DNao respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 3 stroke:#22C55E,stroke-width:4px
    linkStyle 4 stroke:#EF4444,stroke-width:4px

1. Identifique o bloqueio

Acompanhe os eventos de assinatura por Webhook.

Quando ocorrer uma divergência, sua aplicação receberá:

SUBSCRIPTION_SPLIT_DIVERGENCE_BLOCK

Utilize subscription.id para identificar a assinatura afetada.

A propriedade additionalInfo contém informações complementares sobre o bloqueio.

Consulte os Eventos para assinaturas.

👍
Recomendado
Utilize Webhooks como mecanismo principal para identificar o bloqueio.
Evite polling para verificar continuamente o estado da assinatura. Consulte a API apenas quando precisar recuperar ou confirmar o estado atual do recurso.

2. Corrija a divergência

A regularização pode ser feita ajustando:

o valor da assinatura; ou
a configuração de Split da assinatura.

O ajuste deve ocorrer em até 2 dias úteis.

Para atualizar a assinatura, utilize:

PUT /v3/subscriptions/{id}

Ao alterar o Split, envie a nova configuração em split.

Consulte o endpoint Atualizar assinatura existente.

⚠️
Atenção
Ao atualizar uma assinatura, não envie split como null ou [] se quiser manter a configuração. Esses valores desabilitam o Split.
Alterar o Split da assinatura também não modifica cobranças já geradas.

Se precisar corrigir o Split de uma cobrança já existente, atualize essa cobrança separadamente.

Consulte Split em assinaturas.

3. Aguarde o desbloqueio

Quando a divergência é corrigida dentro do prazo, o Asaas desbloqueia automaticamente a assinatura.

Após o desbloqueio:

novas cobranças voltam a ser geradas;
o Split permanece configurado;
os valores atualizados são utilizados nas próximas cobranças.

Não considere o fluxo normalizado apenas após enviar a atualização. Aguarde a confirmação do estado da assinatura por Webhook ou consulte pontualmente o recurso quando necessário.

Se o prazo expirar

Se a divergência não for corrigida em até 2 dias úteis:

o bloqueio é encerrado;
o Split permanece desabilitado;
novas cobranças voltam a ser geradas sem Split.

Nesse cenário, o Asaas envia:

SUBSCRIPTION_SPLIT_DIVERGENCE_BLOCK_FINISHED

Esse evento indica que o período de bloqueio terminou e que a recorrência foi retomada sem a configuração de Split anterior.

Como tratar os eventos

Durante esse fluxo, considere principalmente:

Evento	Tratamento
`SUBSCRIPTION_SPLIT_DIVERGENCE_BLOCK`	Identifique a assinatura, interrompa processos que dependam das próximas cobranças e inicie a regularização
`SUBSCRIPTION_SPLIT_DIVERGENCE_BLOCK_FINISHED`	Atualize sua aplicação para refletir que o bloqueio terminou e o Split foi removido

Processe os eventos de forma idempotente utilizando o id do Webhook.

Para conhecer o payload completo e os demais eventos de assinatura, consulte Eventos para assinaturas.

Próximos passos

Updated 6 days ago

Did this page help you?