Integração iugu para cobrança recorrente

Na iugu, a integração trabalha com faturas e outros recursos financeiros documentados. O sistema imobiliário precisa relacionar cada fatura ao contrato, à competência e à categoria corretos. Nome e e-mail do pagador não substituem essa referência.

A fatura deve corresponder a uma obrigação identificada

A criação de fatura admite configurações de meios de pagamento, vencimento e itens, conforme a API e a conta. A documentação também prevê vínculo com assinatura e regras de prioridade para o meio de pagamento. Esses detalhes precisam ser respeitados pela integração, não escondidos atrás de um botão genérico. ^{[IUGU_INVOICE]}

Escolha quem gera a recorrência

Uma carteira pode utilizar recursos de assinatura do provedor ou uma agenda própria que emite faturas. O ponto crítico é evitar que ambos gerem a mesma obrigação. Defina uma responsabilidade de emissão e preserve o vínculo entre agenda, competência e fatura.

Se o contrato for atualizado, determine quais períodos ainda podem ser alterados. A mudança de uma regra futura não deve reescrever faturas já pagas. Encerrar a recorrência também não elimina valores anteriores pendentes. ^[IUGU_SUBS]

Exemplo de controle mensal

A locação tem aluguel de R$ 2.100,00 com vencimento no dia 12. Janeiro possui uma fatura externa registrada. Ao repetir o processamento mensal, a integração deve localizar a referência existente ou reconhecer a emissão concluída, em vez de criar outra fatura para janeiro.

Quando um valor variável for adicionado, como encargo conferido daquele mês, preserve a composição. Não altere o plano inteiro para refletir uma despesa pontual que só deveria aparecer uma vez.

Estados exigem interpretação fiel

O provedor distingue situações de fatura, inclusive estados que não equivalem a quitação integral. A integração deve mapear esses estados de modo consistente e manter em revisão diferenças ou pagamentos parciais, em vez de reduzir tudo a “pago” ou “não pago”. ^{[IUGU_STATUS]}

Da mesma forma, expiração de acesso e vencimento da obrigação não são necessariamente o mesmo evento. A comunicação ao cliente precisa orientar o próximo passo sem criar uma cobrança nova indevidamente.

Conexão própria e comunicação

O administrador deve autorizar sua conta e proteger o token correspondente. E-mails do provedor e e-mails do SaaS precisam ser coordenados para não gerar mensagens contraditórias ou em excesso. O Resend, previsto para as comunicações da eencia, não substitui a consulta do estado financeiro na iugu.

Ao avaliar a integração em funcionamento, confira emissão, atualização, cancelamento permitido, conciliação e encerramento de agenda. O objetivo é manter uma competência explicável do início ao fim, sem presumir que a existência de uma API de assinaturas resolve automaticamente a lógica da locação.

Perguntas frequentes

Posso deixar iugu e SaaS gerando o mesmo aluguel mensal?

Não. Defina uma responsabilidade de emissão por obrigação para impedir duplicidade.

Fatura parcialmente paga deve virar quitação integral?

Não. Registre o valor efetivo e trate o saldo conforme o estado do provedor e a obrigação correspondente.