Docs

App Afiliados

Referência da API

...

Nesta página

Introdução

Este guia foi elaborado com o objetivo de fornecer informações claras e abrangentes sobre a integração iugu - Afiliados. Aqui, você encontrará informações para compreender e utilizar eficientemente os recursos da API, permitindo uma integração perfeita e eficaz em seus projetos.

O base_url para todas as requisições é:

 https://api.affiliates.iugu.com

Autorização

A partir daqui vamos fazer requisições diretamente a aplicação de afiliados e para isso você já deve ter um token de acesso. Caso não tenha, consulte a documentação do OAuth 2.0.

Lendo a documentação de OAuth2 você terá as informações necessárias para fazer uma requisição ao console para obter o bearer token que será usado na autorização dos endpoints de afiliados.

Exemplo da requisição para obter o bearer token:

  curl --location --request POST 'https://identity.iugu.com/token?client_id=insira_o_client_id_do_app_instalado&client_secret=insira_o_client_secret_do_app_instalado&grant_type=client_credentials&audience=Iugu.Platform.insira_o_client_id_do_app_instalado'

Exemplo de resposta:

  {
      "access_token": "O token que você deve usar para fazer as requisições,
      "token_type": "Bearer",
      "expires_in": 300
  }

O Token tem duração de 5min e é renovado automaticamente a cada requisição no Afiliados, só é necessário pedir um novo token caso o tempo de duração do token tenha expirado.

Obs

É necessário no header de cada requisição informar o seu workspace, para isso basta adicionar o header workspace_id com o identificador do workspace no padrão short_id.

A Partir daqui você já pode fazer requisições para a aplicação de afiliados.

O que é um Afiliado?

Afiliado é um usuário que pode indicar novos clientes para o seu negócio e receber uma comissão por isso. O Afiliado pode ser uma pessoa física ou jurídica.

Como criar um Afiliado?

Um Afiliado pode ser criado através da API ou do painel de controle. Para criar um Afiliado através da API, basta fazer uma requisição POST para o endpoint abaixo:

/affiliates

Exemplo da requisição em cURL:

  curl --location 'https://api.affiliates.iugu.com/affiliates' \
  --header 'workspace_id: seu_workspace_id' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer seu_bearer_token' \
  --header 'Cookie: __profilin=p%3Dt' \
  --data '{
      "affiliate": {
          "name": "Nome do afiliado",
          "document": "Documento do afiliado",
          "workspace_id": "Identificador do workspace",
      }
  }'

Aqui você encontra a referência da requisição, com os campos necessários e exemplos de requisição e resposta:

Afiliados

Como consultar Afiliados?

Para consultar um Afiliado através da API, basta fazer uma requisição GET para o endpoint abaixo:

/affiliates

Exemplo da requisição em cURL:

  curl --location 'https://api.affiliates.iugu.com/affiliates' \
  --header 'workspace_id: seu_workspace_id' \
  --header 'Authorization: Bearer seu_bearer_token' \
  --header 'Cookie: __profilin=p%3Dt' \
  --data ''

Isso retornará uma lista com os afiliados salvos.

Aqui você encontra a referência da requisição e exemplos de resposta:

Afiliados

Cada afiliado criado tem um identificador que será utilizado juntamente aos links da aplicação da iugu, ex:

https://identity.iugu.com/a9b35d98-8006-4424-8d13-59f6815ead52

Onde a9b35d98-8006-4424-8d13-59f6815ead52 é o identificador do afiliado.

Isso garante a relação entre o afiliado e o cliente, que posteriormente durante o uso da plataforma irá gerar eventos que serão utilizados para calcular a comissão do afiliado dentro do periodo de campanha.

Detalhes sobre Afiliados

  • Um afiliado por ser indicado por outro afiliado e você pode fazer isso passando o identificador do afiliado que está indicando no campo parent_affiliate_id da requisição.
  • Um afiliado que já possui um indicador não pode ser indicado por outro afiliado e nem ter o indicador removido em uma requisição PATCH.

O que é uma Campanha?

Campanha é uma ação de marketing que tem como objetivo atrair novos clientes para o seu negócio. A campanha pode ser criada para um produto ou para todos os produtos do seu negócio, com periodo de duração e comissão definidos.

Como criar uma Campanha?

Uma Campanha pode ser criada através da API ou do painel de controle. Para criar uma Campanha através da API, basta fazer uma requisição POST para o endpoint abaixo:

/campaigns

Exemplo da requisição em cURL:

  curl --location 'https://api.affiliates.iugu.com/campaigns' \
  --header 'workspace_id: seu_workspace_id' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer seu_bearer_token' \
  --header 'Cookie: __profilin=p%3Dt' \
  --data '{
      "campaign": {
      "name": "Criado via api4",
      "event": "event",
      "amount": 10,
      "start_date": "2024-02-01",
      "end_date": "2024-05-05",
      "kind": "1",
      "level_config": {
                  "level_1": 99,
                  "level_2": 1
              }
      }
  }'

Aqui você encontra a referência da requisição, com os campos necessários e exemplos de requisição e resposta:

Campanhas

Como consultar Campanhas?

Para consultar uma Campanha através da API, basta fazer uma requisição GET para o endpoint abaixo:

/campaigns

Exemplo da requisição em cURL:

  curl --location 'https://api.affiliates.iugu.com/campaigns' \
  --header 'workspace_id: seu_workspace_id' \
  --header 'Authorization: Bearer seu_bearer_token' \
  --header 'Cookie: __profilin=p%3Dt' \
  --data ''

Isso retornará uma lista com as campanhas salvas.

Aqui você encontra a referência da requisição e exemplos de resposta:

Campanhas

Detalhes sobre Campanhas

  • Criar campanhas sem definir parametros de niveis de configuração config_level resultará em uma campanha com apenas um nivel e com 100% do valor da comissão definida na campanha.
  • Campanhas podem ter até dez niveis de configuração config_level e cada nivel pode ter uma comissão diferente, desde que a soma das comissões dos niveis seja igual a 100%.
  • Um afiliado adicionado a uma campanha não pode ser removido enquanto a campanha estiver ativa (dentro do periodo de duração). Isso garante que o afiliado não perca a comissão por indicações feitas durante o periodo de duração da campanha.

O que é um Evento?

Evento é uma ação realizada por um cliente que foi indicado por um afiliado. Os eventos são gerados automaticamente pela plataforma e são utilizados para calcular a comissão do afiliado dentro do periodo de duração da campanha.

Como consultar Eventos?

Para consultar um Evento através da API, basta fazer uma requisição GET para o endpoint abaixo:

/events

Exemplo da requisição em cURL:

  curl --location 'https://api.affiliates.iugu.com/events' \
  --header 'workspace_id: seu_workspace_id' \
  --header 'Authorization: Bearer seu_bearer_token' \
  --header 'Cookie: __profilin=p%3Dt' \
  --data ''

Isso retornará uma lista com os eventos salvos.

Aqui você encontra a referência da requisição e exemplos de resposta:

Eventos

Gerar Eventos Manualmente

Você pode gerar eventos manualmente para testar o calculo de comissão de um afiliado. Para isso basta fazer uma requisição POST para o endpoint abaixo:

/events

Exemplo da requisição em cURL:

  curl --location 'https://api.affiliates.iugu.com/events' \
  --header 'workspace_id: seu_workspace_id' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer seu_bearer_token' \
  --header 'Cookie: __profilin=p%3Dt' \
  --data '{
      "event": {
          "affiliate_id": "Identificador do afiliado",
          "event": "event",
          "amount": 10
      }
  }'

Aqui você encontra a referência da requisição, com os campos necessários e exemplos de requisição e resposta:

Eventos

Detalhes sobre Eventos

  • Gerar eventos automaticamente é uma funcionalidade que ainda não está disponível, mas será implementada em breve.
  • No momento só é possível gerar eventos manualmente. O recomendável no momento é gerar um evento com a soma dos valores de todas as transações realizadas pelo cliente durante o periodo de duração da campanha.
  • Eventos tem três status: ‘pendente’, ‘em processamento’ e ‘processado’.
    • Eventos são gerados com status ‘pendente’.
    • Eventos com status ‘em processamento’ estão sendo calculados e não podem ser alterados.
    • Eventos ao serem usados no calculo de pagamento de comissão são atualizados para o status ‘processado’ e recebem o identificador do pagamento de comissão gerado.

O que é um Pagamento?

Pagamento é a comissão que o afiliado recebe por indicar novos clientes para o seu negócio. Os pagamentos são gerados automaticamente pela plataforma e são utilizados para pagar a comissão do afiliado após o periodo de duração da campanha.

Como consultar Pagamentos?

Para consultar um Pagamento através da API, basta fazer uma requisição GET para o endpoint abaixo:

/payments

Exemplo da requisição em cURL:

  curl --location 'https://api.affiliates.iugu.com/payments' \
  --header 'workspace_id: seu_workspace_id' \
  --header 'Authorization: Bearer seu_bearer_token' \
  --header 'Cookie: __profilin=p%3Dt' \
  --data ''

Isso retornará uma lista com os pagamentos salvos.

Aqui você encontra a referência da requisição e exemplos de resposta:

Pagamentos

Detalhes sobre Pagamentos

  • Os pagamentos são gerados via background job após a data de término da campanha, levando em consideração os eventos gerados por cada afiliado e o nivel de configuração da campanha.