Central do Desenvolvedor

Documentação do Desenvolvedor

A central do desenvolvedor é um repositório com referências técnicas, conceitos e materiais passo a passo sobre o funcionamento e comunicação através de API.

Introdução

📘

Você conhece os conceitos básicos de gatilhos?

Caso não conheça, temos um documento que pode lhe ajudar em Conceitos Técnicos - Gatilhos

Gatilhos (ou Webhooks) são endereços (URLs) para onde a Iugu dispara avisos (Via método POST) para certos eventos que ocorrem em sua conta.

As chamadas são enviadas com content-type application/x-www-form-urlencoded.

Os gatilhos podem ser cadastrados pelo painel da iugu, menu: Administração -> Gatilhos
ou via API - https://dev.iugu.com/v1.0/reference#criar-gatilho

Estes são os eventos e seus respectivos dados enviados:

Fatura Criada

ParâmetroDados
eventinvoice.created
data[id]ID da Fatura
Ex: 1757E1D7FD5E410A9C563024250015BF
data[account_id]ID da Conta
Ex: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]Estado da Fatura (pending, paid, canceled, partially_paid, refunded, expired, authorized, in_protest, chargeback)
Ex: pending
data[subscription_id]ID da Assinatura a qual essa Fatura foi criada (Somente é enviado caso a fatura seja de uma assinatura)
Ex: F4115E5E28AE4CCA941FCCCCCABE9A0A
event: invoice.created
data[id]: 1757E1D7FD5E410A9C563024250015BF
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]: pending
data[subscription_id]: F4115E5E28AE4CCA941FCCCCCABE9A0A

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 estado da fatura

ParâmetroDados
eventinvoice.status_changed
data[id]ID da Fatura
Ex: 1757E1D7FD5E410A9C563024250015BF
data[account_id]ID da Conta
Ex: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]Estado da Fatura (pending, paid, canceled, partially_paid, refunded, expired, authorized, in_protest, chargeback)
Ex: pending
data[subscription_id]ID da Assinatura a qual essa Fatura foi criada (Somente é enviado caso a fatura seja de uma assinatura)
Ex: F4115E5E28AE4CCA941FCCCCCABE9A0A
event: invoice.status_changed
data[id]: 1757E1D7FD5E410A9C563024250015BF
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]: paid
data[subscription_id]: F4115E5E28AE4CCA941FCCCCCABE9A0A

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

Status de registro de fatura

eventinvoice.bank_slip_status
data[id]ID da Fatura
Ex: 1757E1D7FD5E410A9C563024250015BF
data[account_id]ID da Conta
Ex: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]Estado do registro (processing, registered, canceled, none, error)
Ex: processing
event: invoice.bank_slip_status
data[id]: 1757E1D7FD5E410A9C563024250015BF
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]: processing

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

Reembolso de fatura

ParâmetroDados
eventinvoice.refund
data[id]ID da Fatura
Ex: 1757E1D7FD5E410A9C563024250015BF
data[account_id]ID da Conta
Ex: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]refunded
data[subscription_id]ID da Assinatura a qual essa Fatura foi criada (Somente é enviado caso a fatura seja de uma assinatura)
Ex: F4115E5E28AE4CCA941FCCCCCABE9A0A
event: invoice.refund
data[id]: 1757E1D7FD5E410A9C563024250015BF
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]: refunded
data[subscription_id]: F4115E5E28AE4CCA941FCCCCCABE9A0A

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

ParâmetroDados
eventinvoice.payment_failed
data[id]ID da Fatura
Ex: 1757E1D7FD5E410A9C563024250015BF
data[account_id]ID da Conta
Ex: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]pending
data[subscription_id]ID da Assinatura a qual essa Fatura foi criada (Somente é enviado caso afatura seja de uma assinatura)
Ex: F4115E5E28AE4CCA941FCCCCCABE9A0A
data[lr]Código de retorno da operadora do cartão
Ex: 51

Ver Tabela de LR
event: invoice.payment_failed
data[id]: 1757E1D7FD5E410A9C563024250015BF
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]: pending
data[subscription_id]: F4115E5E28AE4CCA941FCCCCCABE9A0A
data[lr]: 51

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

Notificação enviada na data do vencimento.

ParâmetroDados
eventinvoice.due
data[id]ID da Fatura
Ex: 1757E1D7FD5E410A9C563024250015BF
data[account_id]ID da Conta
Ex: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]pending
data[subscription_id]ID da Assinatura a qual essa Fatura foi criada (Somente é enviado caso a fatura seja de uma assinatura)
Ex: F4115E5E28AE4CCA941FCCCCCABE9A0A
event: invoice.due
data[id]: 1757E1D7FD5E410A9C563024250015BF
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]: pending
data[subscription_id]: F4115E5E28AE4CCA941FCCCCCABE9A0A

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

ParâmetroDados
eventinvoice.dunning_action
data[id]ID da Fatura
Ex: 1757E1D7FD5E410A9C563024250015BF
data[account_id]ID da Conta
Ex: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]Estado da Fatura (pending ou expired)
Ex: pending
data[subscription_id]ID da Assinatura a qual essa Fatura foi criada (Somente é enviado caso a fatura seja de uma assinatura)
Ex: F4115E5E28AE4CCA941FCCCCCABE9A0A
data[action]Ação realizada pela gestão de cobrança (charge ou expire)
Ex: charge
event: invoice.dunning_action
data[id]: 1757E1D7FD5E410A9C563024250015BF
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]: pending
data[subscription_id]: F4115E5E28AE4CCA941FCCCCCABE9A0A
data[action]: charge

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

🚧

Aviso

Este gatilho é enviado somente em ambiente produção. (live mode)

ParâmetroDados
eventinvoice.installment_released
data[id]ID da Fatura
Ex: 1757E1D7FD5E410A9C563024250015BF
data[account_id]ID da Conta
Ex: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]paid
data[subscription_id]ID da Assinatura a qual essa Fatura foi criada (Somente é enviado caso a fatura seja de uma assinatura)
Ex: F4115E5E28AE4CCA941FCCCCCABE9A0A
data[installment]Número da parcela liberada
Ex: 1
data[number_of_installments]Total de parcelas da fatura
Ex: 12
data[amount]Valor da parcela liberada
Ex: 10.00
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

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

🚧

Aviso

Este gatilho é enviado somente em ambiente produção. (live mode)

ParâmetroDados
eventinvoice.released
data[id]ID da Fatura
Ex: 1757E1D7FD5E410A9C563024250015BF
data[account_id]ID da Conta
Ex: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]paid
data[subscription_id]ID da Assinatura a qual essa Fatura foi criada (Somente é enviado caso a fatura seja de uma assinatura)
Ex: F4115E5E28AE4CCA941FCCCCCABE9A0A
data[number_of_installments]Total de parcelas da fatura
Ex: 12
data[amount]Valor da parcela liberada
Ex: 10.00
data[payment_method]Método utilizado para pagamento da fatura
Ex: iugu_bank_slip ou iugu_credit_card
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

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

ParâmetroDados
eventsubscription.suspended
data[id]ID da Assinatura
Ex: F4115E5E28AE4CCA941FCCCCCABE9A0A
data[account_id]ID da Conta
Ex: 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

ParâmetroDados
eventsubscription.expired
data[id]ID da Assinatura
Ex: F4115E5E28AE4CCA941FCCCCCABE9A0A
data[account_id]ID da Conta
Ex: 70CA234077134ED0BF2E0E46B0EDC36F
data[customer_name]Nome do Cliente
Ex: John Doe
data[customer_email]E-mail do Cliente
Ex: [email protected]
data[expires_at]Data de Expiração (Vencimento)
Ex: 2017-06-15
event: subscription.expired
data[id]: 1757E1D7FD5E410A9C563024250015BF
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[customer_name]: John Doe
data[customer_email]: [email protected]
data[expires_at]: 2017-06-15

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

ParâmetroDados
eventsubscription.activated
data[id]ID da Assinatura
Ex: F4115E5E28AE4CCA941FCCCCCABE9A0A
data[account_id]ID da Conta
Ex: 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

ParâmetroDados
eventsubscription.created
data[id]ID da Assinatura
Ex: F4115E5E28AE4CCA941FCCCCCABE9A0
data[account_id]ID da Conta
Ex: 70CA234077134ED0BF2E0E46B0EDC36F
data[customer_name]Nome do Cliente
Ex: John Doe
data[customer_email]E-mail do Cliente
Ex: [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

ParâmetroDados
eventsubscription.renewed
data[id]ID da Assinatura
Ex: F4115E5E28AE4CCA941FCCCCCABE9A0A
data[account_id]ID da Conta
Ex: 70CA234077134ED0BF2E0E46B0EDC36F
data[customer_name]Nome do Cliente
Ex: John Doe
data[customer_email]E-mail do Cliente
Ex: [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

ParâmetroDados
eventsubscription.changed
data[id]ID da Assinatura
Ex: F4115E5E28AE4CCA941FCCCCCABE9A0A
data[account_id]ID da Conta
Ex: 70CA234077134ED0BF2E0E46B0EDC36F
data[customer_name]Nome do Cliente
Ex: John Doe
data[customer_email]E-mail do Cliente
Ex: [email protected]
data[expires_at]Data de Expiração
Ex: 2017-06-15
data[plan_identifier]Identificador do Plano
Ex: 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

❗️

Alerta

Os gatilhos abaixo, referentes as ações de subcontas, são enviados somente em modo produção (live mode).

Verificação de Subconta

ParâmetroDados
eventreferrals.verification
data[id]ID da Verificação
Ex: 4857E1D7FD5E410A9C563024250015TC
data[account_id]ID da Conta
Ex: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]Status da Verificação (accepted ou rejected)
Ex: accepted
data[feedback]Mensagem de Rejeicão (Somente quando a verificação for rejeitada)
data[charge_limit_cents]Limite da Conta em centavos (Caso seja verificada)
event: referrals.verification
data[id]: 4857E1D7FD5E410A9C563024250015TC
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]: rejected
data[feedback]: dados invalidos
data[charge_limit_cents]: null

RAW BODY
event=referrals.verification&data%5Bid%5D=4857E1D7FD5E410A9C563024250015TC&
data%5Baccount_id%5D=70CA234077134ED0BF2E0E46B0EDC36F&
data%5Bstatus%5D=rejected&data%5Bfeedback%5D=dados%20invalidos&
data%5Bcharge_limit_cents%5D=null

Mudança de dados bancários de Subconta

ParâmetroDados
eventreferrals.bank_verification
data[id]ID da Verificação
Ex: 4857E1D7FD5E410A9C563024250015TC
data[account_id]ID da Conta
Ex: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]Status da Verificação (accepted ou rejected)
Ex: accepted
data[feedback]Mensagem de Rejeicão (Somente quando a verificação foi rejeitada)
Ex: Dados incorretos
event: referrals.bank_verification
data[id]: 4857E1D7FD5E410A9C563024250015TC
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]: accepted
data[feedback]: null

RAW BODY
event=referrals.bank_verification&data%5Bid%5D=4857E1D7FD5E410A9C563024250015TC&
data%5Baccount_id%5D=70CA234077134ED0BF2E0E46B0EDC36F&
data%5Bstatus%5D=accepted&data%5Bfeedback%5D=null

Requisição de transferência bancária criada

ParâmetroDados
eventwithdraw_request.created
data[withdraw_request_id]ID da Requisição de transferência bancária
Ex: 56CBD1D7FD5E410A9C563024252043CE
data[account_id]ID da Conta
Ex: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]Status da Requisição de transferência bancária
Ex: pending
event: withdraw_request.created
data[withdraw_request_id]: 56CBD1D7FD5E410A9C563024252043CE
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]: pending

RAW BODY
event=withdraw_request.created&
data%5Bwithdraw_request_id%5D=56CBD1D7FD5E410A9C563024252043CE&
data%5Baccount_id%5D=70CA234077134ED0BF2E0E46B0EDC36F&
data%5Bstatus%5D=pending

Mudança de estado de requisição de transferência bancária

ParâmetroDados
eventwithdraw_request.status_changed
data[withdraw_request_id]ID da Requisição de transferência bancária
Ex: 56CBD1D7FD5E410A9C563024252043CE
data[account_id]ID da Conta
Ex: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]Status da Requisição de transferência bancária (processing, accepted ou rejected)
Ex: rejected
data[feedback]Mensagem de Rejeicão (Somente quando a transferência for rejeitada)
Ex: Conta não existente
event: withdraw_request.status_changed
data[withdraw_request_id]: 56CBD1D7FD5E410A9C563024252043CE
data[account_id]: 70CA234077134ED0BF2E0E46B0EDC36F
data[status]: rejected
data[feedback]: agencia ou conta inexistente

RAW BODY
event=withdraw_request.status_changed&
data%5Bwithdraw_request_id%5D=56CBD1D7FD5E410A9C563024252043CE&
data%5Baccount_id%5D=70CA234077134ED0BF2E0E46B0EDC36F&
data%5Bstatus%5D=rejected&data%5Bfeedback%5D=agencia%20ou%20conta%20inexistente

Forma de Pagamento do Cliente Criada

ParâmetroDados
event"customer_payment_method.new"
data[customer_id]ID do Cliente
Ex: D667CDDA99054178952E8AD74E31141D
data[default_payment_id]ID da Método de Pagamento Padrão
Ex: 70CA234077134ED0BF2E0E46B0EDC36F
data[credit_card][token]Token de Pagamento
ex: ad40638d-7060-4daa-b660-16a11387748a
data[credit_card][year]Ano da data de expiração do cartão
Ex: 2028
data[credit_card][month]Mês da data de expiração do cartão
Ex: 12
data[credit_card][brand]Bandeira
data[credit_card][holder]Nome no cartão
data[credit_card][masked_number]Número do cartão, apresentando apenas os últimos 4 dígitos
Ex: XXXX-XXXX-XXXX-1234
event: customer_payment_method.new
data[customer_id]: D667CDDA99054178952E8AD74E31141D
data[default_payment_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_id%5D=D667CDDA99054178952E8AD74E31141D&
data%5default_payment_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

Updated 4 months ago

Gatilhos


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.