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
Content-TypeAs 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:
-
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.
-
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.
-
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.
-
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:
- Via Painel (Acesse alia.iugu.com > Configurações > Integrações > Comunicação via Gatilho)
- Via API
Painel
- Acesse alia.iugu.com > Configurações
- Na seção Integrações > Comunicação via Gatilho
- Escolha o evento > insira o URL que receberá os dados
- Clique em Salvar.
API
Utilize o endpoint Criar Gatilho — POST 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âmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do evento | invoice.created |
| data[id] | ID da Fatura | 1757E1D7FD5E410A9C563024250015BF |
| data[payment_booklet_id] | ID do Carnê | 98F604CD45B14777B6E7847F667A94AF |
| data[account_id] | ID da Conta | 70CA234077134ED0BF2E0E46B0EDC36F |
| data[status] | Status da Fatura | pending, 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 fatura | api, 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ão | true 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 Faturas | N55548889 |
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âmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do evento | invoice.status_changed |
| data[id] | ID da Fatura | 1757E1D7FD5E410A9C563024250015BF |
| data[payment_booklet_id] | ID do Carnê | 98F604CD45B14777B6E7847F667A94AF |
| data[account_id] | ID da Conta | 70CA234077134ED0BF2E0E46B0EDC36F |
| data[status] | Status da Fatura | paid, canceled, partially_paid, refunded, expired, authorized, externally_paid, in_protest, chargeback |
| data[payment_method] | Método utilizado para pagamento da fatura | iugu_bank_slip, iugu_credit_card ou iugu_pix |
| data[paid_at] | Data de realização do pagamento | 2022-03-21T11:07:36.667Z |
| data[payer_cpf_cnpj] | CPF ou CNPJ do pagador da fatura | 66535209008 |
| 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 Pix | c2403281-a401-496b-af0e-53b7e16ba207 |
| data[paid_cents] | Valor Pago da Fatura | 100 |
| 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 Faturas | N55548889 |
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âmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do Evento | invoice.bank_slip_status |
| data[id] | ID da Fatura | 1757E1D7FD5E410A9C563024250015BF |
| data[payment_booklet_id] | ID do Carnê | 98F604CD45B14777B6E7847F667A94AF |
| data[account_id] | ID da Conta | 70CA234077134ED0BF2E0E46B0EDC36F |
| 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âmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do Evento | invoice.refund |
| data[id] | ID da Fatura | 1757E1D7FD5E410A9C563024250015BF |
| data[payment_booklet_id] | ID do Carnê | 98F604CD45B14777B6E7847F667A94AF |
| data[account_id] | ID da Conta | 70CA234077134ED0BF2E0E46B0EDC36F |
| data[status] | Status da Fatura | refunded |
| 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 Faturas | N55548889 |
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âmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do Evento | invoice.payment_failed |
| data[id] | ID da Fatura | 1757E1D7FD5E410A9C563024250015BF |
| data[payment_booklet_id] | ID do Carnê | 98F604CD45B14777B6E7847F667A94AF |
| data[account_id] | ID da Conta | 70CA234077134ED0BF2E0E46B0EDC36F |
| data[status] | Status da Fatura | pending |
| 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ão | 51Ver Tabela de LR |
| data[external_reference] | Informação de referência externa, possibilitando pesquisar através do endpoint Listar/Buscar Faturas | N77579_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âmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do Evento | invoice.due |
| data[id] | ID da Fatura | 1757E1D7FD5E410A9C563024250015BF |
| data[payment_booklet_id] | ID do Carnê | 98F604CD45B14777B6E7847F667A94AF |
| data[account_id] | ID da Conta | 70CA234077134ED0BF2E0E46B0EDC36F |
| data[status] | Status da Fatura | pending |
| 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 Faturas | N55548889 |
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âmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do Evento | invoice.dunning_action |
| data[id] | ID da Fatura | 1757E1D7FD5E410A9C563024250015BF |
| data[payment_booklet_id] | ID do Carnê | 98F604CD45B14777B6E7847F667A94AF |
| data[account_id] | ID da Conta | 70CA234077134ED0BF2E0E46B0EDC36F |
| data[status] | Status da Fatura | pending 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ça | charge ou expire |
| data[external_reference] | Informação de referência externa, possibilitando pesquisar através do endpoint Listar/Buscar Faturas | N55548889 |
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âmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do Evento | invoice.installment_released |
| data[id] | ID da Fatura | 1757E1D7FD5E410A9C563024250015BF |
| data[payment_booklet_id] | ID do Carnê | 98F604CD45B14777B6E7847F667A94AF |
| data[account_id] | ID da Conta | 70CA234077134ED0BF2E0E46B0EDC36F |
| data[status] | Status da Fatura | pending 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 liberada | de 1 a 12 |
| data[number_of_installments] | Total de parcelas da fatura | de 1 a 12 |
| data[amount] | Valor da parcela liberada | 10.00 |
| data[amount_cents] | Valor da parcela em centavos | 1000 |
| 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 Faturas | N55548889 |
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âmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do Evento | invoice.released |
| data[id] | ID da Fatura | 1757E1D7FD5E410A9C563024250015BF |
| data[payment_booklet_id] | ID do Carnê | 98F604CD45B14777B6E7847F667A94AF |
| data[account_id] | ID da Conta | 70CA234077134ED0BF2E0E46B0EDC36F |
| data[status] | Status da Fatura | paid |
| 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 fatura | de 1 a 12 |
| data[amount] | Valor da parcela liberada | 1000 |
| data[payment_method] | Método utilizado para pagamento da fatura | iugu_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 fatura | N77579_31912363 |
| data[fines] | Booleano que informa se houve ou não multa por atraso de pagamento | true ou false |
| data[discount] | Valor dos Descontos | 1000 |
| data[taxes] | Tarifas da iugu | |
| data[client_share] | Valor da fatura descontando as tarifas de processamento e comissões | 45799750 |
| data[net_value] | Valor da fatura descontando as tarifas de processamento e comissões | 45799750 |
| data[early_payment_discount] | Booleano que informa se houve ou não desconto por pagamento antecipado | true ou false |
| data[occurrence_date] | Data da ocorrência. Quando pagador efetuou pagamento | 2024-06-17 |
| data[account_number_last_digits] | Se o pagamento for em pix, ele traz os últimos 4 números da conta bancaria do pagador | 3730 |
| data[paid_at] | Data do pagamento. Quando foi, de fato, paga | 2022-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âmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do Evento | subscription.suspended |
| data[id] | ID da Assinatura | F4115E5E28AE4CCA941FCCCCCABE9A0A |
| data[account_id] | ID da Conta | 70CA234077134ED0BF2E0E46B0EDC36F |
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âmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do Evento | subscription.expired |
| data[id] | ID da Assinatura | F4115E5E28AE4CCA941FCCCCCABE9A0A |
| data[account_id] | ID da Conta | 70CA234077134ED0BF2E0E46B0EDC36F |
| data[customer_name] | Nome do Cliente | John 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âmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do Evento | subscription.activated |
| data[id] | ID da Assinatura | F4115E5E28AE4CCA941FCCCCCABE9A0A |
| data[account_id] | ID da Conta | 70CA234077134ED0BF2E0E46B0EDC36F |
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âmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do Evento | subscription.created |
| data[id] | ID da Assinatura | F4115E5E28AE4CCA941FCCCCCABE9A0 |
| data[account_id] | ID da Conta | 70CA234077134ED0BF2E0E46B0EDC36F |
| 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âmetro | Dados | Exemplo |
|---|---|---|
| event | Nome do Evento | subscription.renewed |
| data[id] | ID da Assinatura | F4115E5E28AE4CCA941FCCCCCABE9A0A |
| data[account_id] | ID da Conta | 70CA234077134ED0BF2E0E46B0EDC36F |
| data[customer_name] | Nome do Cliente | John 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âmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do Evento | subscription.changed |
| data[id] | ID da Assinatura | F4115E5E28AE4CCA941FCCCCCABE9A0A |
| data[id] | ID da Conta | 70CA234077134ED0BF2E0E46B0EDC36F |
| data[customer_name] | Nome do Cliente | John Doe |
| data[customer_email] | E-mail do Cliente | [email protected] |
| data[expires_at] | Data de Expiração | 2024-06-17 |
| data[plan_identifier] | Identificador do Plano | basic_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âmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do Evento | customer_payment_method.new |
| data[customer_payment_method_id] | ID do Método de Pagamento | 70CA234077134ED0BF2E0E46B0EDC36F |
| data[customer_id] | ID do Cliente | D667CDDA99054178952E8AD74E31141D |
| data[default_payment_method_id] | ID do Método de Pagamento Padrão | 70CA234077134ED0BF2E0E46B0EDC36F |
| data[credit_card][token] | Token de Pagamento | ad40638d-7060-4daa-b660-16a11387748a |
| data[credit_card][year] | An de expiração do cartão | 2028 |
| data[credit_card][month] | Mês da data de expiração do cartão | 12 |
| data[credit_card][brand] | Bandeira | visa |
| data[credit_card][holder] | Nome no cartão | John Silva |
| data[credit_card][masked_number] | Número do cartão, apresentando apenas os últimos 4 dígitos | XXXX-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âmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do Evento | transfer.debited |
| data[sender_account_id] | ID da Conta Debitada | 27016E1AD888499A98994E781B6C3762 |
| data[sender_account_name] | Nome da Conta remetente | IUGU INSTITUICAO DE PAGAMENTO S.A. |
| data[sender_bank_branch] | Agência da Conta Bancária | 0002 |
| data[sender_bank_account] | Conta Bancária | 1927794 |
| data[sender_bank_account_digit] | Dígito da Conta Bancária | 0 |
| data[sender_cpf_cnpj] | CPF ou CNPJ associada à conta remetente | 11343675030 |
Conta Recebedora (receiver)
| Parâmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do Evento | transfer.debited |
| data[receiver_account_id] | ID da Conta Recebedora | 27016E1AD888499A98994E781B6C3762 |
| data[receiver_account_name] | Nome da Conta remetente | IUGU INSTITUICAO DE PAGAMENTO S.A. |
| data[receiver_bank_branch] | Agência da Conta Bancária | 0002 |
| data[receiver_bank_account] | Conta Bancária | 1927794 |
| data[receiver_bank_account_digit] | Dígito da Conta Bancária | 0 |
| data[receiver_cpf_cnpj] | CPF ou CNPJ associada à conta remetente | 11343675030 |
transfer_type
| Parâmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do Evento | transfer_type |
| data[transfer_type] | Tipo de Transferência | account_requested |
| data[amount_cents] | Valor da Transferência em Centavos | 10000 |
{
"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âmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do Evento | deposit.accepted |
| data[deposit_id] | ID do Depósito | 56CBD1D7FD5E410A9C563024252043CE |
| data[account_id] | ID da Conta | 70CA234077134ED0BF2E0E46B0EDC36F |
| data[status] | Status do Depósito | accepted 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âmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do Evento | deposit.rejected |
| data[deposit_id] | ID do Depósito | 56CBD1D7FD5E410A9C563024252043CE |
| data[account_id] | ID da Conta | 70CA234077134ED0BF2E0E46B0EDC36F |
| data[status] | Status do Depósito | rejected |
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âmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do Evento | deposit.pix_status_changed |
| data[deposit_id] | ID do depósito recebido | 2BF8A5636B2F47317864C9B3D4E629B6 |
| data[status] | Estado do depósito | pending, processing, rejected, error, accepted, inconsistent, refunded, processing_refund |
| data[account_id] | ID da conta que recebeu o depósito | E6495D15290D47D3950C2A723D07A24E |
| data[amount_cents] | Valor do depósito em centavos | 10000 |
| data[deposit_type] | Tipo de transferência usada para o depósito | ted, pix, qrcode (se QRCode Estático = qrcode) |
| data[sender_ispb] | ISPB do Domicilio Bancário que realizou o depósito | 98723456 |
| data[sender_compe] | COMPE do Domicilio Bancário que realizou o depósito | 237 |
| data[sender_bank_name] | Nome do Domicilio Bancário que realizou o depósito | Bradesco/Next |
| data[sender_bank_branch] | Agência do Domicilio Bancário que realizou o depósito | 0101 |
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âmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do Evento | transfer_request.status_changed |
| data[id] | ID da Transferência para terceiros | A480797C10D84053A480D7C37C6F3521 |
| data[account_id] | ID da Conta | E6495D15290D47D3950C2A723D07A24E |
| data[status] | Estado da Transferência | pending, processing, rejected, refunded, done, error |
| data[total_refunded_amount_cents] | Valor total de estornos efetuados daquele pix de saída até agora | 10000 |
| 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ção —
v1/advancement_request/simulation
| Parâmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do Evento | advancement_request.simulation_status |
| data[status] | Estado da simulação | processing ou done |
| data[total_advance_fee_cents] | Valor total de tarifas de antecipação em centavos | 311 |
| 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 centavos | 50123 |
| 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âmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do Evento | advancement_request.advancement_status |
| data[status] | Estado da simulação | error ou done |
| data[total_advance_fee_cents] | Valor total de tarifas de antecipação em centavos | 9877 |
| data[total_advance_amount_cents] | Valor total alcançado na antecipação, esse será o valor final recebido em centavos | 76539 |
| data[advancement_request_date] | Data do pedido de antecipação | 2024-06-17 |
| data[transaction_ids] | ID da transação | A480797C10D840XXA480D7C37C6F3521 |
| data[account_id] | ID da conta | E6495D15290D47D3950C2A723D07A24E |
Mudança de Status do Split
Acionado sempre que um split tem o seu status alterado.
| Parâmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do Evento | invoice.split_status_changed |
| data[id] | ID da Fatura | 1757E1D7FD5E410A9C563024250015BF |
| data[status] | Status da Fatura | paid, canceled, partially_paid, refunded, expired, authorized, externally_paid, in_protest, chargeback |
| data[account_id] | ID da Conta que gerou a Fatura | E6495D15290D47D3950C2A723D07A24E |
| 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[payment_method] | Método utilizado para pagamento da fatura | iugu_bank_slip, iugu_credit_card ou iugu_pix |
| data[paid_at] | Data de realização do pagamento | 2022-03-21T11:07:36.667Z |
| data[payer_cpf_cnpj] | CPF ou CNPJ do pagador da fatura | 66535209008 |
| data[payer_name] | Nome do pagador da fatura | Maria Silva |
| data[paid_cents] | Valor pago da fatura em centavos | 1000 |
| data[pix_end_to_end_id] | End To End ID Para transações Pix | c2403281-a401-496b-af0e-53b7e16ba207 |
| data[recipient_account_id] | ID da Conta comissionada pelo Split | 70CA234077134ED0BF2E0E46B0EDC36F |
| data[amount_cents] | Valor do comissionamento em centavos | 900 |
| 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âmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do evento | invoice.split_released |
| data[id] | ID da fatura | 8166A5675D8F42DCBDE72E7DF7EE16D5 |
| data[status] | Status da fatura | paid |
| data[account_id] | ID da conta associada à fatura | 27016E1AD888499A98994E781B6C3762 |
| data[async_charged] | Cobrança assíncrona | true ou false |
| data[number_of_installments] | Número de parcelas | 1 |
| data[payment_method] | Método de pagamento utilizado | iugu_bank_slip, iugu_credit_card ou iugu_pix |
| data[total] | Valor total da fatura | 400 |
| data[taxes] | Valor dos impostos | 4 |
| data[fines] | Valor das multas | 0 |
| data[discount] | Valor do desconto aplicado | 10 |
| data[client_share] | Valor da parte do cliente | 196 |
| data[net_value] | Valor líquido da fatura | 396 |
| data[commission] | Valor do split | 200 |
| data[total_cents] | Valor total da fatura em centavos | 400 |
| data[taxes_cents] | Valor dos impostos em centavos | 4 |
| data[fines_cents] | Valor das multas em centavos | 0 |
| data[discount_cents] | Valor do desconto em centavos | 10 |
| data[client_share_cents] | Valor da parte do cliente em centavos | 196 |
| data[net_value_cents] | Valor líquido da fatura em centavos | 396 |
| data[commission_cents] | Valor do split em centavos | 200 |
| data[early_payment_discount] | Desconto por pagamento antecipado | 0 |
| data[occurrence_date] | Data da ocorrência | 2024-08-20 |
| data[total_paid_cents] | Valor total pago em centavos | 400 |
| data[total_paid] | Valor total pago | 4.0 |
| data[paid_at] | Data e hora do pagamento | 2024-08-20T19:41:40.526Z |
| data[amount] | Valor do pagamento | 3.96 |
| data[amount_cents] | Valor do pagamento em centavos | 200 |
| 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 Split | E638DCED176240E4A510510C065FB52D |
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âmetro | Descrição | Exemplo |
|---|---|---|
| event | Nome do evento | payment_request.status_changed |
| data[payment_request_id] | ID do Pedido de Pagamento | A123B4C5D6E7F8G9H1I2J3K4L5M6N7O |
| data[barcode] | Número da Linha Digitável | 12345678912345678912345678912345678912345678912345 |
| data[status] | Status do Pedido de Pagamento | done |
| data[amount_cents] | Quantia paga | 156250 |
| data[account_id] | ID da Conta que executou o pedido | A123B4C5D6789E2F5G6H7I8J9K8L9M8N8O8 |
| data[document_amount_cents] | Valor do Boleto | 156250 |
| data[cpf_cnpj_holder] | CPF ou CNPJ do recebedor | 28029399000152 |
| data[holder_name] | Nome do Recebedor | Nome Sobrenome |
| data[done_at] | Data do Pagamento | 2024-10-07T19:46:12.397Z |
Updated 19 days ago