Gatilhos

A iugu disponibiliza a funcionalidade de gatilhos (webhooks) para facilitar a integração entre sistemas.

📘

O que você irá aprender com esse artigo?

  • Conceito
  • Por que usar Gatilhos ao invés de fazer Pooling?
  • Lista de Eventos e dados que enviam

Conceito

Gatilhos de webhooks funcionam como alarmes automáticos que são acionados quando determinados eventos acontecem em um sistema ou aplicação. Eles esperam por um sinal específico e, quando detectam esse sinal, executam uma ação previamente programada.

Cabeçalho Content-Type

As chamadas dos nossos gatilhos são enviadas com o cabeçalho Content-Type definido como application/x-www-form-urlencoded, garantindo que os dados do formulário sejam adequadamente codificados e facilmente processados pelo servidor receptor. Esta escolha assegura compatibilidade e eficiência na transmissão de informações em formato chave=valor.

🚧

IP de Saída para liberação de gatilhos

Caso seja feito algum tipo de controle por Firewall, o IP de saída da iugu é 54.207.210.151


Por que usar Gatilhos ao invés de fazer Pooling?

Realizar pooling nas APIs da iugu pode não ser a melhor estratégia em muitos casos, principalmente devido ao impacto negativo que pode ocasionar em relação ao tempo de resposta e à complexidade do gerenciamento de chamadas. Aqui estão alguns motivos específicos:

  1. Atraso na Resposta: O pooling pode introduzir atrasos significativos nas respostas às requisições, pois as chamadas são agrupadas e processadas em lotes. Isso significa que uma requisição pode ter que esperar até que o lote esteja completo para ser enviada e processada, o que pode não ser ideal para operações que exigem respostas em tempo real ou mais rápidas.

  2. Complexidade no Gerenciamento de Chamadas: Gerenciar e manter um sistema de pooling requer uma lógica adicional para agrupar as chamadas, gerenciar os tempos de envio dos lotes, e lidar com as respostas correspondentes a cada chamada no lote. Isso aumenta a complexidade do código e a possibilidade de erros.

  3. Limitação na Escalabilidade: Embora o pooling possa reduzir a carga nos servidores ao diminuir o número de chamadas feitas, ele também pode limitar a escalabilidade da aplicação, pois o processamento em lote pode se tornar um gargalo se o volume de requisições for muito alto.

  4. Riscos de Falhas em Lote: Se um lote de chamadas falhar devido a um erro em uma única requisição, isso pode impactar todas as outras requisições no mesmo lote, o que não ocorreria se as chamadas fossem feitas individualmente.

Utilizando Gatilhos (Webhooks)

Em contraste, os gatilhos (webhooks) oferecem uma alternativa mais eficiente e direta para reagir a eventos específicos em tempo real. Quando um evento ocorre, um webhook é acionado imediatamente, enviando dados diretamente para o endpoint configurado sem a necessidade de pooling. Isso garante que as ações sejam processadas de forma mais rápida e confiável, sem atrasos inerentes ao agrupamento de chamadas e com menos complexidade no gerenciamento.

Em resumo

Os Gatilhos descartam a necessidade de realizar chamadas às APIs para consultar se os dados estão, ou não, disponíveis.


Como configurar um Gatilho?

Para configurar Gatilhos na iugu, há duas formas:

  1. Via Painel (Acesse alia.iugu.com > Configurações > Integrações > Comunicação via Gatilho)
  2. Via API

Painel

  1. Acesse alia.iugu.com > Configurações
  2. Na seção Integrações > Comunicação via Gatilho
  3. Escolha o evento > insira o URL que receberá os dados
  4. Clique em Salvar.

API

Utilize o endpoint Criar GatilhoPOST v1/web_hooks.


Lista de Eventos

Abaixo está uma lista com todos os eventos disponíveis na iugu, acompanhado dos dados que enviam quando acionados.

Fatura Criada

Será acionado sempre que uma fatura for criada.

ParâmetroDescriçãoExemplo
eventNome do eventoinvoice.created
data[id]ID da Fatura1757E1D7FD5E410A9C563024250015BF
data[payment_booklet_id]ID do Carnê98F604CD45B14777B6E7847F667A94AF
data[account_id]ID da Conta70CA234077134ED0BF2E0E46B0EDC36F
data[status]Status da Faturapending, paid, canceled, partially_paid,externally_paid, refunded, expired, authorized, in_protest, chargeback
data[subscription_id]ID da Assinatura a qual essa Fatura foi criada (Enviado apenas para faturas criadas por Assinaturas)F4115E5E28AE4CCA941FCCCCCABE9A0A
data[source]Recurso utilizado para criação da faturaapi, alia, payment_booklet (carnê), subscription
data[async_charged]Boolean que indica se a cobrança foi automática (Régua de Cobrança) ou nãotrue ou false
data[order_id]Número único que identifica o pedido de compra. Opcional. Auxilia na prevenção de pagamento da mesma fatura.N77579_31658163
data[external_reference]Informação de referência externa, possibilitando pesquisar através do endpoint Listar/Buscar FaturasN55548889
event: invoice.created
data[id]: 1757E1D7FD5E410A9C563024250015BF
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]: pending
data[subscription_id]: F4115E5E28AE4CCA941FCCCCCABE9A0A
data[source]: api
data[order_id]: N77579_31658163
data[async_charged]: true
data[external_reference]: N55548889

RAW BODY
event=invoice.created&data%5Bid%5D=1757E1D7FD5E410A9C563024250015BF&
data%5Bstatus%5D=pending&data%5Baccount_id%5D=70CA234077134ED0BF2E0E46B0EDC36F&
data%5Bsubscription_id%5D=F4115E5E28AE4CCA941FCCCCCABE9A0A

Mudança de Status da Fatura

Acionado sempre que o status de uma Fatura é alterado.

ParâmetroDescriçãoExemplo
eventNome do eventoinvoice.status_changed
data[id]ID da Fatura1757E1D7FD5E410A9C563024250015BF
data[payment_booklet_id]ID do Carnê98F604CD45B14777B6E7847F667A94AF
data[account_id]ID da Conta70CA234077134ED0BF2E0E46B0EDC36F
data[status]Status da Faturapaid, canceled, partially_paid, refunded, expired, authorized, externally_paid, in_protest, chargeback
data[payment_method]Método utilizado para pagamento da faturaiugu_bank_slip, iugu_credit_card ou iugu_pix
data[paid_at]Data de realização do pagamento2022-03-21T11:07:36.667Z
data[payer_cpf_cnpj]CPF ou CNPJ do pagador da fatura66535209008
data[subscription_id]ID da Assinatura a qual essa Fatura foi gerada (se gerada a partir de uma assinatura)F4115E5E28AE4CCA941FCCCCCABE9A0A
data[pix_end_to_end_id]End To End ID Para transações Pixc2403281-a401-496b-af0e-53b7e16ba207
data[paid_cents]Valor Pago da Fatura100
data[order_id]Número único que identifica o pedido de compra. Opcional. Auxilia na prevenção de pagamento da mesma fatura.N77579_31658163
data[async_charged]Boolean que indica se a cobrança foi automática (Régua de Cobrança) ou não.true ou false
data[external_reference]Informação de referência externa, possibilitando pesquisar através do endpoint Listar/Buscar FaturasN55548889
event: invoice.status_changed
data[id]: 84F982E1A10F4FF1B483B829F4762C2C
data[account_id]: E6495D15290D47D3950C2A723D07A24E
data[status]: paid
data[payment_method]: iugu_pix
data[paid_at]: 2022-03-21T11:07:36.667Z
data[payer_cpf_cnpj]: 66535209008
data[subscription_id]: F4115E5E28AE4CCA941FCCCCCABE9A0A
data[order_id]: N77579_31658163
data[async_charged]: true
data[external_reference]: N55548889


RAW BODY
event=invoice.status_changed&data%5Bid%5D=84F982E1A10F4FF1B483B829F4762C2C&data%5Bstatus%5D=paid&data%5Baccount_id%5D=E6495D15290D47D3950C2A723D07A24E&data%5Bpayment_method%5D=iugu_pix&data%5Bpaid_at%5D=2022-03-21T11%3A07%3A36.667Z&data%5Bpayer_cpf_cnpj%5D=66535209008&
data%5Bsubscription_id%5D=F4115E5E28AE4CCA941FCCCCCABE9A0A

Status de Registro de Fatura

Acionado sempre que um Boleto Bancário (bank_slip) é registrado. Permite, também, validar o status atual.

ParâmetroDescriçãoExemplo
eventNome do Eventoinvoice.bank_slip_status
data[id]ID da Fatura1757E1D7FD5E410A9C563024250015BF
data[payment_booklet_id]ID do Carnê98F604CD45B14777B6E7847F667A94AF
data[account_id]ID da Conta70CA234077134ED0BF2E0E46B0EDC36F
data[status]Estado do registro
Ex: processing
processing, registered, canceled, none, error
data[external_reference]Informação de referência externa, possibilitando pesquisar através do endpoint Listar/Buscar Faturas N55548889
event: invoice.bank_slip_status
data[id]: 1757E1D7FD5E410A9C563024250015BF
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]: processing
data[external_reference]:N55548889

event=invoice.bank_slip_status&data%5Bid%5D=1757E1D7FD5E410A9C563024250015BF&
data%5Bstatus%5D=processing&data%5Baccount_id%5D=70CA234077134ED0BF2E0E46B0EDC36F

Reembolso de fatura

Acionado sempre que uma Fatura tem seu status alterado para refunded (reembolsado).

ParâmetroDescriçãoExemplo
eventNome do Eventoinvoice.refund
data[id]ID da Fatura1757E1D7FD5E410A9C563024250015BF
data[payment_booklet_id]ID do Carnê98F604CD45B14777B6E7847F667A94AF
data[account_id]ID da Conta70CA234077134ED0BF2E0E46B0EDC36F
data[status]Status da Faturarefunded
data[subscription_id]ID da Assinatura a qual essa Fatura foi gerada (se gerada a partir de uma assinatura)F4115E5E28AE4CCA941FCCCCCABE9A0A
data[order_id]Número único que identifica o pedido de compra. Opcional. Auxilia na prevenção de pagamento da mesma fatura.N77579_31912363
data[external_reference]Informação de referência externa, possibilitando pesquisar através do endpoint Listar/Buscar FaturasN55548889
event: invoice.refund
data[id]: 1757E1D7FD5E410A9C563024250015BF
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]: refunded
data[subscription_id]: F4115E5E28AE4CCA941FCCCCCABE9A0A
data[order_id]: N77579_31912363
data[external_reference]: N55548889

RAW BODY
event=invoice.refund&data%5Bid%5D=1757E1D7FD5E410A9C563024250015BF&
data%5Bstatus%5D=refunded&data%5Baccount_id%5D=70CA234077134ED0BF2E0E46B0EDC36F&
data%5Bsubscription_id%5D=F4115E5E28AE4CCA941FCCCCCABE9A0A

Falha no pagamento da fatura

Acionado sempre que há falha no pagamento de qualquer fatura.

ParâmetroDescriçãoExemplo
eventNome do Eventoinvoice.payment_failed
data[id]ID da Fatura1757E1D7FD5E410A9C563024250015BF
data[payment_booklet_id]ID do Carnê98F604CD45B14777B6E7847F667A94AF
data[account_id]ID da Conta70CA234077134ED0BF2E0E46B0EDC36F
data[status]Status da Faturapending
data[subscription_id]ID da Assinatura a qual essa Fatura foi gerada (se gerada a partir de uma assinatura)F4115E5E28AE4CCA941FCCCCCABE9A0A
data[lr]Código de retorno da operadora do cartão51
Ver Tabela de LR
data[external_reference]Informação de referência externa, possibilitando pesquisar através do endpoint Listar/Buscar FaturasN77579_31912363
event: invoice.payment_failed
data[id]: 1757E1D7FD5E410A9C563024250015BF
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]: pending
data[subscription_id]: F4115E5E28AE4CCA941FCCCCCABE9A0A
data[lr]: 51
data[external_reference]:N77579_31912363

RAW BODY
event=invoice.payment_failed&data%5Bid%5D=1757E1D7FD5E410A9C563024250015BF&
data%5Bstatus%5D=pending&data%5Baccount_id%5D=70CA234077134ED0BF2E0E46B0EDC36F&
data%5Bsubscription_id%5D=F4115E5E28AE4CCA941FCCCCCABE9A0A&data%5Blr%5D=51

Vencimento de Fatura

Acionado sempre que a data de vencimento de uma fatura é atingida.

ParâmetroDescriçãoExemplo
eventNome do Eventoinvoice.due
data[id]ID da Fatura1757E1D7FD5E410A9C563024250015BF
data[payment_booklet_id]ID do Carnê98F604CD45B14777B6E7847F667A94AF
data[account_id]ID da Conta70CA234077134ED0BF2E0E46B0EDC36F
data[status]Status da Faturapending
data[subscription_id]ID da Assinatura a qual essa Fatura foi gerada (se gerada a partir de uma assinatura)F4115E5E28AE4CCA941FCCCCCABE9A0A
data[external_reference]Informação de referência externa, possibilitando pesquisar através do endpoint Listar/Buscar FaturasN55548889
event: invoice.due
data[id]: 1757E1D7FD5E410A9C563024250015BF
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]: pending
data[subscription_id]: F4115E5E28AE4CCA941FCCCCCABE9A0A
data[external_reference]:N77579_31912363

RAW BODY
event=invoice.due&data%5Bid%5D=1757E1D7FD5E410A9C563024250015BF&
data%5Bstatus%5D=pending&data%5Baccount_id%5D=70CA234077134ED0BF2E0E46B0EDC36F&
data%5Bsubscription_id%5D=F4115E5E28AE4CCA941FCCCCCABE9A0A

Ação de Gestão de Cobrança

Acionado sempre que a cobrança realizada pela Régua de Cobrança não é bem sucedida.

ParâmetroDescriçãoExemplo
eventNome do Eventoinvoice.dunning_action
data[id]ID da Fatura1757E1D7FD5E410A9C563024250015BF
data[payment_booklet_id]ID do Carnê98F604CD45B14777B6E7847F667A94AF
data[account_id]ID da Conta70CA234077134ED0BF2E0E46B0EDC36F
data[status]Status da Faturapending ou expired
data[subscription_id]ID da Assinatura a qual essa Fatura foi gerada (se gerada a partir de uma assinatura)F4115E5E28AE4CCA941FCCCCCABE9A0A
data[action]Ação realizada pela gestão de cobrançacharge ou expire
data[external_reference]Informação de referência externa, possibilitando pesquisar através do endpoint Listar/Buscar FaturasN55548889
event: invoice.dunning_action
data[id]: 1757E1D7FD5E410A9C563024250015BF
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]: pending
data[subscription_id]: F4115E5E28AE4CCA941FCCCCCABE9A0A
data[action]: charge
data[external_reference]:N77579_31912363


RAW BODY
event=invoice.dunning_action&data%5Bid%5D=1757E1D7FD5E410A9C563024250015BF&
data%5Bstatus%5D=pending&data%5Baccount_id%5D=70CA234077134ED0BF2E0E46B0EDC36F&
data%5Bsubscription_id%5D=F4115E5E28AE4CCA941FCCCCCABE9A0A&
data%5Baction%5D=charge

Parcela da Fatura liberada

Acionado sempre que uma parcela de uma fatura for paga, informando o valor e o número da parcela.

🚧

Importante

Este gatilho funciona apenas em ambiente de produção (live_mode)

ParâmetroDescriçãoExemplo
eventNome do Eventoinvoice.installment_released
data[id]ID da Fatura1757E1D7FD5E410A9C563024250015BF
data[payment_booklet_id]ID do Carnê98F604CD45B14777B6E7847F667A94AF
data[account_id]ID da Conta70CA234077134ED0BF2E0E46B0EDC36F
data[status]Status da Faturapending ou paid
data[subscription_id]ID da Assinatura a qual essa Fatura foi gerada (se gerada a partir de uma assinatura)F4115E5E28AE4CCA941FCCCCCABE9A0A
data[installment]Número da parcela liberadade 1 a 12
data[number_of_installments]Total de parcelas da faturade 1 a 12
data[amount]Valor da parcela liberada10.00
data[amount_cents]Valor da parcela em centavos1000
data[order_id]Número único que identifica o pedido de compra. Opcional. Auxilia na prevenção de pagamento da mesma fatura.N77579_31912363
data[external_reference]Informação de referência externa, possibilitando pesquisar através do endpoint Listar/Buscar FaturasN55548889
event: invoice.installment_released
data[id]: 1757E1D7FD5E410A9C563024250015BF
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]: paid
data[subscription_id]: F4115E5E28AE4CCA941FCCCCCABE9A0A
data[installment]: 1
data[number_of_installments]: 12
data[amount]: 10.00
data[amount_cents]: 1000
data[order_id]: N77579_31912363
data[external_reference]:N55548889


RAW BODY
event=invoice.installment_released&data%5Bid%5D=1757E1D7FD5E410A9C563024250015BF&
data%5Bstatus%5D=paid&data%5Baccount_id%5D=70CA234077134ED0BF2E0E46B0EDC36F&
data%5Bsubscription_id%5D=F4115E5E28AE4CCA941FCCCCCABE9A0A&
data%5Binstallment%5D=1&data%5Bnumber_of_installments%5D=12&
data%5Bamount%5D=10.00

Fatura liberada

Acionado sempre quando uma Fatura é totalmente paga. Cada método de pagamento é acionado da seguinte forma:

  • Cartão de Crédito (credit_card): Quando o pagamento é realizado à vista ou a última parcela é quitada.
  • Boleto Bancário (bank_slip): Quando o valor da Fatura é compensado.
  • Pix (pix): Quando pagamento é realizado com sucesso.

🚧

Aviso

Este gatilho funciona exclusivamente em ambiente de produção (live_mode)

ParâmetroDescriçãoExemplo
eventNome do Eventoinvoice.released
data[id]ID da Fatura1757E1D7FD5E410A9C563024250015BF
data[payment_booklet_id]ID do Carnê98F604CD45B14777B6E7847F667A94AF
data[account_id]ID da Conta70CA234077134ED0BF2E0E46B0EDC36F
data[status]Status da Faturapaid
data[subscription_id]ID da Assinatura a qual essa Fatura foi gerada (se gerada a partir de uma assinatura)F4115E5E28AE4CCA941FCCCCCABE9A0A
data[number_of_installments]Total de parcelas da faturade 1 a 12
data[amount]Valor da parcela liberada1000
data[payment_method]Método utilizado para pagamento da faturaiugu_bank_slip, iugu_credit_card ou iugu_pix
data[total]Total cobrado.45800000
data[order_id]Número único que identifica o pedido de compra. Opcional. Auxilia na prevenção de pagamento da mesma faturaN77579_31912363
data[fines]Booleano que informa se houve ou não multa por atraso de pagamentotrue ou false
data[discount]Valor dos Descontos1000
data[taxes]Tarifas da iugu
data[client_share]Valor da fatura descontando as tarifas de processamento e comissões45799750
data[net_value]Valor da fatura descontando as tarifas de processamento e comissões45799750
data[early_payment_discount]Booleano que informa se houve ou não desconto por pagamento antecipadotrue ou false
data[occurrence_date]Data da ocorrência. Quando pagador efetuou pagamento2024-06-17
data[account_number_last_digits]Se o pagamento for em pix, ele traz os últimos 4 números da conta bancaria do pagador3730
data[paid_at]Data do pagamento. Quando foi, de fato, paga2022-07-12 17:33:20.699791368
event: invoice.released
data[id]: 1757E1D7FD5E410A9C563024250015BF
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]: paid
data[subscription_id]: F4115E5E28AE4CCA941FCCCCCABE9A0A
data[number_of_installments]: 12
data[amount]: 10.00
data[payment_method]: iugu_bank_slip
data[total]: 45800000	
data[taxes]: 250
data[fines]: 0
data[discount]: 1000
data[client_share]: 45799750
data[net_value]: 45799750
data[early_payment_discount]: 0
data[occurrence_date]: '2022-07-12'
data[account_number_last_digits]: '3730'
data[paid_at]: 2022-07-12 17:33:20.699791368

RAW BODY
event=invoice.released&data%5Bid%5D=1757E1D7FD5E410A9C563024250015BF&
data%5Bstatus%5D=paid&data%5Baccount_id%5D=70CA234077134ED0BF2E0E46B0EDC36F&
data%5Bsubscription_id%5D=F4115E5E28AE4CCA941FCCCCCABE9A0A&
data%5Bnumber_of_installments%5D=12&data%5Bamount%5D=10.00&
data%5Bpayment_method%5D=iugu_bank_slip

Assinatura Suspensa

Acionado sempre que uma Assinatura é suspensa.

ParâmetroDescriçãoExemplo
eventNome do Eventosubscription.suspended
data[id]ID da AssinaturaF4115E5E28AE4CCA941FCCCCCABE9A0A
data[account_id]ID da Conta70CA234077134ED0BF2E0E46B0EDC36F
event: subscription.suspended
data[id]: 1757E1D7FD5E410A9C563024250015BF
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F

RAW BODY
event=subscription.suspended&data%5Bid%5D=1757E1D7FD5E410A9C563024250015BF&
data%5Baccount_id%5D=70CA234077134ED0BF2E0E46B0EDC36F

Assinatura Expirada

Acionado sempre que uma Assinatura expira, ou seja, não haverá mais nenhuma cobrança.

ParâmetroDescriçãoExemplo
eventNome do Eventosubscription.expired
data[id]ID da AssinaturaF4115E5E28AE4CCA941FCCCCCABE9A0A
data[account_id]ID da Conta70CA234077134ED0BF2E0E46B0EDC36F
data[customer_name]Nome do ClienteJohn Doe
data[customer_email]E-mail do Cliente[email protected]
data[expires_at]Data de Expiração (Vencimento)2024-05-03
event: subscription.expired
data[id]: 1757E1D7FD5E410A9C563024250015BF
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[customer_name]: John Doe
data[customer_email]: [email protected]
data[expires_at]: 2024-05-03

RAW BODY
event=subscription.expired&data%5Bid%5D=1757E1D7FD5E410A9C563024250015BF&
data%5Baccount_id%5D=70CA234077134ED0BF2E0E46B0EDC36F&
data%5Bcustomer_name%5D=John%20Doe&data%5Bcustomer_email%[email protected]&
data%5Bexpires_at%5D=2017-06-15

Assinatura Ativada

Acionado sempre que o status de Assinatura for alterado para active.

ParâmetroDescriçãoExemplo
eventNome do Eventosubscription.activated
data[id]ID da AssinaturaF4115E5E28AE4CCA941FCCCCCABE9A0A
data[account_id]ID da Conta70CA234077134ED0BF2E0E46B0EDC36F
event: subscription.activated
data[id]: 1757E1D7FD5E410A9C563024250015BF
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F

RAW BODY
event=subscription.activated&data%5Bid%5D=1757E1D7FD5E410A9C563024250015BF&
data%5Baccount_id%5D=70CA234077134ED0BF2E0E46B0EDC36F

Assinatura Criada

Acionado sempre que uma Assinatura é criada.

ParâmetroDescriçãoExemplo
eventNome do Eventosubscription.created
data[id]ID da AssinaturaF4115E5E28AE4CCA941FCCCCCABE9A0
data[account_id]ID da Conta70CA234077134ED0BF2E0E46B0EDC36F
data[customer_name]Nome do Cliente John Doe
data[customer_email]E-mail do Cliente[email protected]
event: subscription.created
data[id]: 1757E1D7FD5E410A9C563024250015BF
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[customer_name]: John Doe
data[customer_email]: [email protected]

RAW BODY
event=subscription.expired&data%5Bid%5D=1757E1D7FD5E410A9C563024250015BF&
data%5Baccount_id%5D=70CA234077134ED0BF2E0E46B0EDC36F&
data%5Bcustomer_name%5D=John%20Doe&data%5Bcustomer_email%[email protected]

Assinatura Renovada

Acionado sempre que uma Assinatura é renovada.

ParâmetroDadosExemplo
eventNome do Eventosubscription.renewed
data[id]ID da AssinaturaF4115E5E28AE4CCA941FCCCCCABE9A0A
data[account_id]ID da Conta70CA234077134ED0BF2E0E46B0EDC36F
data[customer_name]Nome do ClienteJohn Doe
data[customer_email]E-mail do Cliente[email protected]
event: subscription.renewed
data[id]: 1757E1D7FD5E410A9C563024250015BF
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[customer_name]: John Doe
data[customer_email]: [email protected]

RAW BODY
event=subscription.renewed&data%5Bid%5D=1757E1D7FD5E410A9C563024250015BF&
data%5Baccount_id%5D=70CA234077134ED0BF2E0E46B0EDC36F&
data%5Bcustomer_name%5D=John%20Doe&data%5Bcustomer_email%[email protected]

Assinatura Alterada

Acionado sempre que uma Assinatura é alterada.

ParâmetroDescriçãoExemplo
eventNome do Eventosubscription.changed
data[id]ID da AssinaturaF4115E5E28AE4CCA941FCCCCCABE9A0A
data[id]ID da Conta70CA234077134ED0BF2E0E46B0EDC36F
data[customer_name]Nome do ClienteJohn Doe
data[customer_email]E-mail do Cliente[email protected]
data[expires_at]Data de Expiração2024-06-17
data[plan_identifier]Identificador do Planobasic_plan
event: subscription.changed
data[id]: 1757E1D7FD5E410A9C563024250015BF
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[customer_name]: John Doe
data[customer_email]: [email protected]
data[expires_at]: 2017-06-15
data[plan_identifier]: basic_plan

RAW BODY
event=subscription.changed&data%5Bid%5D=1757E1D7FD5E410A9C563024250015BF&
data%5Baccount_id%5D=70CA234077134ED0BF2E0E46B0EDC36F&
data%5Bcustomer_name%5D=John%20Doe&data%5Bcustomer_email%[email protected]&
data%5Bexpires_at%5D=2017-06-15&data%5Bplan_identifier%5D=basic_plan

Forma de Pagamento do Cliente Criada

Acionado sempre que uma Forma de Pagamento é criada para um Cliente.

ParâmetroDescriçãoExemplo
eventNome do Eventocustomer_payment_method.new
data[customer_payment_method_id]ID do Método de Pagamento70CA234077134ED0BF2E0E46B0EDC36F
data[customer_id]ID do ClienteD667CDDA99054178952E8AD74E31141D
data[default_payment_method_id]ID do Método de Pagamento Padrão70CA234077134ED0BF2E0E46B0EDC36F
data[credit_card][token]Token de Pagamentoad40638d-7060-4daa-b660-16a11387748a
data[credit_card][year]An de expiração do cartão2028
data[credit_card][month]Mês da data de expiração do cartão12
data[credit_card][brand]Bandeiravisa
data[credit_card][holder]Nome no cartãoJohn Silva
data[credit_card][masked_number]Número do cartão, apresentando apenas os últimos 4 dígitosXXXX-XXXX-XXXX-1234
event: customer_payment_method.new
data[customer_payment_method_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[customer_id]: D667CDDA99054178952E8AD74E31141D
data[default_payment_method_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[credit_card][token]: ad40638d-7060-4daa-b660-16a11387748a
data[credit_card][year]: 2028
data[credit_card][month]: 12
data[credit_card][brand]: Master
data[credit_card][holder]: John Doe
data[credit_card][masked_number]: XXXX-XXXX-XXXX-1234

RAW BODY
event=customer_payment_method.new&
data%5customer_payment_method_id%5D=70CA234077134ED0BF2E0E46B0EDC36F&
data%5customer_id%5D=D667CDDA99054178952E8AD74E31141D&
data%5default_payment_method_id%5D=70CA234077134ED0BF2E0E46B0EDC36F&
data%5credit_card%5D%5token%5D=ad40638d-7060-4daa-b660-16a11387748a&
data%5credit_card%5D%5year%5D=2028&
data%5credit_card%5D%5month%5D=12&data%5credit_card%5D%5brand%5D=Master&
data%5credit_card%5D%5holder%5D=John%20Doe&
data%5credit_card%5D%5masked_number%5D=XXXX-XXXX-XXXX-1234

Transferência entre Contas iugu

Acionado sempre que há transferências entre contas iugu. São enviados dois eventos: transfer.debited ou transfer.credited e também transfer_type.

Conta Remetente (sender)

ParâmetroDescriçãoExemplo
eventNome do Eventotransfer.debited
data[sender_account_id]ID da Conta Debitada27016E1AD888499A98994E781B6C3762
data[sender_account_name]Nome da Conta remetenteIUGU INSTITUICAO DE PAGAMENTO S.A.
data[sender_bank_branch]Agência da Conta Bancária0002
data[sender_bank_account]Conta Bancária1927794
data[sender_bank_account_digit]Dígito da Conta Bancária0
data[sender_cpf_cnpj]CPF ou CNPJ associada à conta remetente11343675030

Conta Recebedora (receiver)

ParâmetroDescriçãoExemplo
eventNome do Eventotransfer.debited
data[receiver_account_id]ID da Conta Recebedora27016E1AD888499A98994E781B6C3762
data[receiver_account_name]Nome da Conta remetenteIUGU INSTITUICAO DE PAGAMENTO S.A.
data[receiver_bank_branch]Agência da Conta Bancária0002
data[receiver_bank_account]Conta Bancária1927794
data[receiver_bank_account_digit]Dígito da Conta Bancária0
data[receiver_cpf_cnpj]CPF ou CNPJ associada à conta remetente11343675030

transfer_type

ParâmetroDescriçãoExemplo
eventNome do Eventotransfer_type
data[transfer_type]Tipo de Transferênciaaccount_requested
data[amount_cents]Valor da Transferência em Centavos10000
	
{
  "sender": {
    "account_id": "id da conta debitada",
    "bank_branch": "agência",
    "bank_account": "número da conta",
    "bank_account_digit": "dígito da conta",
    "cpf_cnpj": "cpf cnpj"
  },
  "receiver": {
    "account_id": "id da conta debitada",
    "bank_branch": "agência",
    "bank_account": "número da conta",
    "bank_account_digit": "dígito da conta",
    "cpf_cnpj": "cpf cnpj"
  },
  "transfer_type": "tipo de transferência = "Mirror",
  "amount_cents": valor em centavos,
  "event": "transfer.debited" ou "transfer.credited" 
}

Depósito Recebido

Acionado sempre que um depósito recebido é bem sucedido.

ParâmetroDescriçãoExemplo
eventNome do Eventodeposit.accepted
data[deposit_id]ID do Depósito56CBD1D7FD5E410A9C563024252043CE
data[account_id]ID da Conta70CA234077134ED0BF2E0E46B0EDC36F
data[status]Status do Depósitoaccepted ou rejected
event: deposit.accepted
data[deposit_id]: 56CBD1D7FD5E410A9C563024252043CE
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]: accepted

RAW BODY
event=deposit.accepted&
data%deposit_id%5D=56CBD1D7FD5E410A9C563024252043CE&
data%5Baccount_id%5D=70CA234077134ED0BF2E0E46B0EDC36F&
data%5Bstatus%5D=accepted

Depósito Rejeitado

Acionado sempre que um depósito recebido é mal sucedido.

ParâmetroDescriçãoExemplo
eventNome do Eventodeposit.rejected
data[deposit_id]ID do Depósito56CBD1D7FD5E410A9C563024252043CE
data[account_id]ID da Conta70CA234077134ED0BF2E0E46B0EDC36F
data[status]Status do Depósitorejected
event: deposit.rejected
data[deposit_id]: 56CBD1D7FD5E410A9C563024252043CE
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]: rejected

RAW BODY
event=deposit.rejected&
data%deposit_id%5D=56CBD1D7FD5E410A9C563024252043CE&
data%5Baccount_id%5D=70CA234077134ED0BF2E0E46B0EDC36F&
data%5Bstatus%5D=rejected

Mudança de status do Depósito Recebido

Acionado sempre que o status de um depósito recebido é alterado.

ParâmetroDescriçãoExemplo
eventNome do Eventodeposit.pix_status_changed
data[deposit_id]ID do depósito recebido2BF8A5636B2F47317864C9B3D4E629B6
data[status]Estado do depósitopending, processing, rejected, error, accepted, inconsistent, refunded, processing_refund
data[account_id]ID da conta que recebeu o depósitoE6495D15290D47D3950C2A723D07A24E
data[amount_cents]Valor do depósito em centavos10000
data[deposit_type]Tipo de transferência usada para o depósitoted, pix, qrcode (se QRCode Estático = qrcode)
data[sender_ispb]ISPB do Domicilio Bancário que realizou o depósito98723456
data[sender_compe]COMPE do Domicilio Bancário que realizou o depósito237
data[sender_bank_name]Nome do Domicilio Bancário que realizou o depósitoBradesco/Next
data[sender_bank_branch]Agência do Domicilio Bancário que realizou o depósito0101
  event: deposit.pix_status_changed
  data[deposit_id]]: 2BF8A5636B2F47317864C9B3D4E629B6
  data[status]: pending
  data[account_id]: E6495D15290D47D3950C2A723D07A24E
  data[amount_cents]: 10000
  data[deposit_type]: PIX
  data[sender_ispb]: 98723456
  data[sender_compe]: 237
  data[sender_bank_name]: Bradesco/Next
  data[sender_bank_branch]: 0101
  data[sender_bank_account]: 162534
  data[sender_name]: Fernando Souza
  data[sender_cpf_cnpj]: 19569121009
  data[receiver_ispb]: 28734982
  data[receiver_compe]: 401
  data[receiver_bank_name]: IUGU IP S.A.
  data[receiver_bank_branch]: 0202
  data[receiver_bank_account]: 9281375
  data[receiver_bank_account_digit]: 0
  data[receiver_name]: Rodrigo Nascimento
  data[receiver_cpf_cnpj]: 83206207088
  data[transfered_at]: 2024-02-22T20]:19]:37.152Z
  data[description]: Doação
  data[statement_identifier]: B60746648202602662019B2036BO954d

Mudança de status da Transferência para Terceiros

Acionado sempre que o status de uma Transferência para Terceiros é alterado.

ParâmetroDescriçãoExemplo
eventNome do Eventotransfer_request.status_changed
data[id]ID da Transferência para terceirosA480797C10D84053A480D7C37C6F3521
data[account_id]ID da ContaE6495D15290D47D3950C2A723D07A24E
data[status]Estado da Transferênciapending, processing, rejected, refunded, done, error
data[total_refunded_amount_cents]Valor total de estornos efetuados daquele pix de saída até agora10000
data[refunded_amount_cents]Valor de um estorno em especifico (parcial)1000
event: transfer_request.status_changed
data[id]: A480797C10D84053A480D7C37C6F3521
data[account_id]: E6495D15290D47D3950C2A723D07A24E
data[status]: done
data[total_refunded_amount_cents]: 100.00
data[refunded_amount_cents]: 10.00


RAW BODY
event=transfer_request.status_changed&data%5Bid%5D=A480797C10D84053A480D7C37C6F3521&data%5Bstatus%5D=done&data%5Baccount_id%5D=E6495D15290D47D3950C2A723D07A24E

Status Simulação da Antecipação

Acionado sempre que uma simulação de Antecipação de recebíveis for finalizada.

🚧

Importante

Este gatilho é acionado por simulações de antecipação pelo Alia ou API Criar Simulação Antecipaçãov1/advancement_request/simulation

ParâmetroDescriçãoExemplo
eventNome do Eventoadvancement_request.simulation_status
data[status]Estado da simulaçãoprocessing ou done
data[total_advance_fee_cents]Valor total de tarifas de antecipação em centavos311
data[reached_amount_cents]Valor total alcançado na antecipação, esse será o valor final recebido em centavos. Valor que de fato será liberado para a antecipação.13900
data[average_days]Tempo médio de dias que as parcelas serão antecipadas.3
data[available_amount_cents]Valor total disponível para antecipar em centavos50123
data[simulation_amount_cents]Valor utilizado para antecipar em centavos`13904
data[requested_amount_cents]Valor solicitado para antecipar em centavos`13904
event: advancement_request.simulation_status
  "data[status]": "done",
  "data[total_advance_fee_cents]": "311",
  "data[reached_amount_cents]": "13904",
  "data[average_days]": "3",
  "data[available_amount_cents]": "13904",
  "data[simulation_amount_cents]": "13904",
  "data[requested_amount_cents]": "13904"

RAW BODY
event=advancement_request.simulation_status&data%5Bstatus%5D=done&data%5Btotal_advance_fee_cents%5D=49&data%5Breached_amount_cents%5D=14587&data%5Baverage_days%5D=3&data%5Bavailable_amount_cents%5D=48378&data%5Bsimulation_amount_cents%5D=20000&data%5Brequested_amount_cents%5D=20000

Status da Antecipação

Acionado sempre que uma Antecipação for concluída.

ParâmetroDescriçãoExemplo
eventNome do Eventoadvancement_request.advancement_status
data[status]Estado da simulaçãoerror ou done
data[total_advance_fee_cents]Valor total de tarifas de antecipação em centavos9877
data[total_advance_amount_cents]Valor total alcançado na antecipação, esse será o valor final recebido em centavos76539
data[advancement_request_date]Data do pedido de antecipação2024-06-17
data[transaction_ids]ID da transaçãoA480797C10D840XXA480D7C37C6F3521
data[account_id]ID da contaE6495D15290D47D3950C2A723D07A24E

Mudança de Status do Split

Acionado sempre que um split tem o seu status alterado.

ParâmetroDescriçãoExemplo
eventNome do Eventoinvoice.split_status_changed
data[id]ID da Fatura1757E1D7FD5E410A9C563024250015BF
data[status]Status da Faturapaid, canceled, partially_paid, refunded, expired, authorized, externally_paid, in_protest, chargeback
data[account_id]ID da Conta que gerou a FaturaE6495D15290D47D3950C2A723D07A24E
data[async_charged]Boolean que indica se a cobrança foi automática (Régua de Cobrança) ou nãotrue ou false
data[payment_method]Método utilizado para pagamento da faturaiugu_bank_slip, iugu_credit_card ou iugu_pix
data[paid_at]Data de realização do pagamento2022-03-21T11:07:36.667Z
data[payer_cpf_cnpj]CPF ou CNPJ do pagador da fatura66535209008
data[payer_name]Nome do pagador da faturaMaria Silva
data[paid_cents]Valor pago da fatura em centavos1000
data[pix_end_to_end_id]End To End ID Para transações Pixc2403281-a401-496b-af0e-53b7e16ba207
data[recipient_account_id]ID da Conta comissionada pelo Split70CA234077134ED0BF2E0E46B0EDC36F
data[amount_cents]Valor do comissionamento em centavos900
data[order_id]Número único que identifica o pedido de compra. Opcional. Auxilia na prevenção de pagamento da mesma fatura.N77579_31912363
  event: invoice.split_status_changed,
  data[id]: 713D49698EAC45BD8F1235675E88365F,
  data[status]: paid,
  data[account_id]: C95D9BC7C2F123456DDF16990E9E3D51,
  data[async_charged]: null,
  data[payment_method]: iugu_pix,
  data[paid_at]: 2023-12-11T17:45:00.772Z,
  data[payer_cpf_cnpj]: 12356678801,
  data[payer_name]: Maria Silva
  data[paid_cents]: 300,
  data[pix_end_to_end_id]: E18236121345672111744s001bd2b1f6,
  data[recipient_account_id]: AEA384CE1234567A8862D76F354022EF,Va
  data[amount_cents]: 30,
  retry_count: 0
  data[order_id]: N77579_31912363

RAW BODY
event=invoice.split_status_changed&data%5Bid%5D=713D1234567C45BD8F6114305E88365F&data%5Bstatus%5D=paid&data%5Baccount_id%5D=C95D9BC7C34556B88DDF16990E9E3D51&data%5Basync_charged%5D&data%5Bpayment_method%5D=iugu_pix&data%5Bpaid_at%5D=2023-12-11T17%3A45%3A00.772Z&data%5Bpayer_cpf_cnpj%5D=12356670801&data%5Bpayer_name%5D=Maria+Silva&data%5Bpaid_cents%5D=300&data%5Bpix_end_to_end_id%5D=E11345620202312111744s001bd2b1f6&data%5Brecipient_account_id%5D=AEA384CEBFCC491A8862D76F354022EF&data%5Bamount_cents%5D=30&retry_count=0

Valor do Split Liberado

Acionado sempre que o valor do Split é liberado.

ParâmetroDescriçãoExemplo
eventNome do eventoinvoice.split_released
data[id]ID da fatura8166A5675D8F42DCBDE72E7DF7EE16D5
data[status]Status da faturapaid
data[account_id]ID da conta associada à fatura27016E1AD888499A98994E781B6C3762
data[async_charged]Cobrança assíncronatrue ou false
data[number_of_installments]Número de parcelas1
data[payment_method]Método de pagamento utilizadoiugu_bank_slip, iugu_credit_card ou iugu_pix
data[total]Valor total da fatura400
data[taxes]Valor dos impostos4
data[fines]Valor das multas0
data[discount]Valor do desconto aplicado10
data[client_share]Valor da parte do cliente196
data[net_value]Valor líquido da fatura396
data[commission]Valor do split200
data[total_cents]Valor total da fatura em centavos400
data[taxes_cents]Valor dos impostos em centavos4
data[fines_cents]Valor das multas em centavos0
data[discount_cents]Valor do desconto em centavos10
data[client_share_cents]Valor da parte do cliente em centavos196
data[net_value_cents]Valor líquido da fatura em centavos396
data[commission_cents]Valor do split em centavos200
data[early_payment_discount]Desconto por pagamento antecipado0
data[occurrence_date]Data da ocorrência2024-08-20
data[total_paid_cents]Valor total pago em centavos400
data[total_paid]Valor total pago4.0
data[paid_at]Data e hora do pagamento2024-08-20T19:41:40.526Z
data[amount]Valor do pagamento3.96
data[amount_cents]Valor do pagamento em centavos200
data[account_number_last_digits]Últimos dígitos do número da conta do pagador
data[recipient_account_id]ID da conta que recebeu o valor do SplitE638DCED176240E4A510510C065FB52D
event: invoice.split_released
data[id]: 8166A5675D8F42DCBDE72E7DF7EE16D5
data[status]: paid
data[account_id]: 27016E1AD888499A98994E781B6C3762
data[async_charged]: 
data[number_of_installments]: 1
data[payment_method]: iugu_pix
data[total]: 400
data[taxes]: 4
data[fines]: 0
data[discount]: 
data[client_share]: 196
data[net_value]: 396
data[commission]: 200
data[total_cents]: 400
data[taxes_cents]: 4
data[fines_cents]: 0
data[discount_cents]: 
data[client_share_cents]: 196
data[net_value_cents]: 396
data[commission_cents]: 200
data[early_payment_discount]: 0
data[occurrence_date]: 2024-08-20
data[total_paid_cents]: 400
data[total_paid]: 4.0
data[paid_at]: 2024-08-20T19:41:40.526Z
data[amount]: 3.96
data[amount_cents]: 200
data[account_number_last_digits]: 
data[recipient_account_id]: E638DCED176240E4A510510C065FB52D


Mundança de Status de Pedido de Pagamento

Acionado sempre que há alteração no status de Pedido de Saque.

ParâmetroDescriçãoExemplo
eventNome do eventopayment_request.status_changed
data[payment_request_id]ID do Pedido de PagamentoA123B4C5D6E7F8G9H1I2J3K4L5M6N7O
data[barcode]Número da Linha Digitável12345678912345678912345678912345678912345678912345
data[status]Status do Pedido de Pagamentodone
data[amount_cents]Quantia paga156250
data[account_id]ID da Conta que executou o pedidoA123B4C5D6789E2F5G6H7I8J9K8L9M8N8O8
data[document_amount_cents]Valor do Boleto156250
data[cpf_cnpj_holder]CPF ou CNPJ do recebedor28029399000152
data[holder_name]Nome do RecebedorNome Sobrenome
data[done_at]Data do Pagamento2024-10-07T19:46:12.397Z