Configuração e Uso da API REST v1

Andrew Munro

Escrito por Andrew Munro
Atualizado em

Como Configurar e Usar a API REST v1

O AffiliateWP possui uma série de endpoints REST somente leitura que se baseiam na infraestrutura incluída no WordPress 4.4 e posterior.

Neste artigo, mostraremos como configurar e usar a API REST v1 para acessar os Dados do AffiliateWP.

API REST – Autenticação

Para aproveitar os endpoints REST principais, todos os consumidores da API devem se autenticar usando chaves de API geradas a partir de uma nova guia Chaves de API localizada em Afiliados → Ferramentas → Chaves de API.

A API REST usa autenticação básica com uma combinação de Chave Pública e Token.

Antes de autenticar uma solicitação de API, você precisa de um conjunto de chaves de API. Estas são específicas do usuário e podem ser criadas em Afiliados → Ferramentas → Chaves de API:

Para gerar um novo conjunto de chaves de API, insira o nome de usuário do usuário ao qual as chaves devem pertencer e clique em Gerar Novas Chaves de API.

Observação: A conta de usuário à qual as chaves de API estão associadas deve ter as permissões adequadas para que a API funcione. Normalmente, isso significa que o usuário precisa ter a função de Administrador. Veja nossa documentação sobre funções e permissões para mais informações.

Depois que as chaves de API forem criadas, você poderá se autenticar com a API REST incluindo as chaves no cabeçalho de autenticação. A Chave Pública deve ser passada como o usuário e o Token como a senha.

Por exemplo, usando o Postman, nossa solicitação autenticada ficaria assim:

Se estiver usando o curl, uma solicitação autenticada ficaria assim:

curl -u 229c1d4292800a4fdaa1099a4c646c9a:c7fd218923e058e1637698e5257855de http://local.wp/woo/wp-json/affwp/v1/affiliates

O cabeçalho de autorização deve ser incluído em todas as solicitações de API para autenticar corretamente com a API. Se a autenticação básica não for fornecida ou as credenciais estiverem incorretas, uma mensagem de erro será retornada: 

{
  "code": "rest_forbidden",
  "message": "Sorry, you are not allowed to do that.",
  "data": {
    "status": 403
  }
}

Rotas e Endpoints

O AffiliateWP oferece cinco rotas e múltiplos endpoints subjacentes. Essas cinco rotas são:

  1. Afiliados
  2. Criativos
  3. Pagamentos
  4. Indicações
  5. Visitas

Clique nos nomes das rotas acima para saber mais sobre seus respectivos endpoints, ver exemplos de solicitações e muito mais.

Observação: operações completas de Criação, Leitura, Atualização e Exclusão (CRUD) podem ser habilitadas através do add-on REST API Extended. Consulte a documentação da REST API Extended para obter informações sobre as operações de Criação, Atualização e Exclusão.

1. Endpoints de Afiliados

O AffiliateWP core 1.9+ oferece dois endpoints REST somente leitura para afiliados:

  1. afiliados – Recupera objetos de resposta para todos os afiliados no site atual
  2. afiliados/{ID} – Recupera um objeto de resposta para um afiliado com o ID de afiliado fornecido

Os endpoints de afiliados podem ser acessados via solicitações GET nos seguintes locais:

http://example.com/wp-json/affwp/v1/affiliates
http://example.com/wp-json/affwp/v1/affiliates/ID

Todos os endpoints de afiliados e suas várias opções também podem ser descobertos visitando o namespace REST do AffiliateWP diretamente:

http://example.com/wp-json/affwp/v1/
Endpoints

O endpoint affiliates aceita quaisquer argumentos válidos de get_affiliates():

  • number – O número de resultados a serem recuperados (se disponíveis)
  • offset – O número de resultados a serem deslocados na consulta. O padrão é 0 (sem deslocamento)
  • affiliate_id – O ID do afiliado ou um array de IDs para consultar.
  • user_id – O ID do usuário ou um array de IDs para consultar pagamentos.
  • exclude – ID do afiliado ou array de IDs a serem excluídos da solicitação.
  • search – Termos para pesquisar afiliados. Aceita um ID de afiliado ou uma string.
  • status – O status do afiliado. Aceita ‘active’, ‘inactive’, ‘pending’ ou ‘rejected’.
  • order – Como ordenar os resultados. Aceita ‘ASC’ (ascendente) ou ‘DESC’ (descendente).
  • orderby – Por qual campo ordenar os resultados da resposta. O padrão é ‘date’
  • fields – Campos específicos a serem retornados para cada afiliado na resposta. O padrão é ‘*’ (todos). Aceita ‘ids’ ou qualquer coluna válida

Argumentos adicionais:

  • user – Se user for passado como true, objetos de usuário personalizados serão recuperados dinamicamente para cada afiliado na resposta. Deve-se ter cuidado ao usar esta opção devido ao aumento de 1:1 nas consultas ao banco de dados associadas a cada afiliado
  • meta – Se passado como true, um array de metadados de afiliados será recuperado dinamicamente para cada afiliado na resposta. Assim como com user, deve-se ter cuidado devido ao impacto reduzido no desempenho.

Todos os argumentos válidos também podem ser derivados enviando uma solicitação OPTIONS para qualquer um dos endpoints.

O endpoint affiliates/{ID} aceita qualquer ID de afiliado válido. Além disso, se user e/ou meta forem passados como true, um objeto de usuário personalizado e/ou um array de metadados de afiliados serão respectivamente recuperados dinamicamente para incluir na resposta.

Visibilidade

Todos os endpoints exigem a chave de API e o token, exceto o endpoint principal affwp/v1.

Resposta

As respostas são retornadas em formato JSON.

Exemplo de resposta affiliates:

[
  {
    "affiliate_id": 2736,
    "user_id": 1336,
    "rate": "",
    "rate_type": "",
    "payment_email": "",
    "status": "active",
    "earnings": 6,
    "unpaid_earnings": 0,
    "referrals": 6,
    "visits": 0,
    "date_registered": "2016-08-17 19:46:25",
    "id": 2736
  },
  {
    "affiliate_id": 2737,
    "user_id": 1337,
    "rate": "",
    "rate_type": "",
    "payment_email": "",
    "status": "inactive",
    "earnings": 1,
    "unpaid_earnings": 3145.59,
    "referrals": 1,
    "visits": 0,
    "date_registered": "2016-08-17 19:46:25",
    "id": 2737
  }
]

Exemplo de resposta affiliates/{ID}:

{
  "affiliate_id": 2737,
  "user_id": 1337,
  "rate": "",
  "rate_type": "",
  "payment_email": "",
  "status": "inactive",
  "earnings": 1,
  "unpaid_earnings": 3145.59,
  "referrals": 1,
  "visits": 0,
  "date_registered": "2016-08-17 19:46:25"
}

Exemplo de resposta affiliates{ID}?user=1:

{
  "affiliate_id": 2737,
  "user_id": 1337,
  "rate": "",
  "rate_type": "",
  "payment_email": "",
  "status": "inactive",
  "earnings": 1,
  "unpaid_earnings": 3145.59,
  "referrals": 1,
  "visits": 0,
  "date_registered": "2016-08-17 19:46:25",
  "user": {
    "ID": "1337",
    "user_login": "user_1_11",
    "user_nicename": "user_1_11",
    "user_url": "",
    "user_registered": "2016-08-17 19:46:25",
    "user_status": "0",
    "display_name": "User 11",
    "spam": "0",
    "deleted": "0",
    "first_name": "",
    "last_name": ""
  }
}

Exemplo de resposta affiliates{ID}?meta=1:

{
  "affiliate_id": 2737,
  "user_id": 1337,
  "rate": "",
  "rate_type": "",
  "payment_email": "[email protected]",
  "status": "active",
  "earnings": 32039.07,
  "unpaid_earnings": 3145.59,
  "referrals": 3192,
  "visits": 0,
  "date_registered": "2016-08-17 19:46:25",
  "meta": {
    "some_key": [
      "some_value"
    ]
  },
  "id": 2737
}<br>

.

2. Endpoints de Criativos

O AffiliateWP core 1.9+ oferece dois endpoints REST somente leitura para criativos:

  1. creatives – Recupera objetos de resposta para todos os criativos no site atual
  2. creatives/{ID} – Recupera um objeto de resposta para um criativo com o ID de criativo fornecido

Os endpoints de criativos podem ser acessados via requisições GET nos seguintes locais:

http://example.com/wp-json/affwp/v1/creatives
http://example.com/wp-json/affwp/v1/creatives/ID

Todos os endpoints de criativos e suas várias opções também podem ser descobertos visitando o namespace REST do AffiliateWP diretamente:

http://example.com/wp-json/affwp/v1/
Endpoints

O endpoint creatives aceita quaisquer argumentos válidos de get_creatives():

  • number – O número de resultados a serem recuperados (se disponíveis)
  • offset – O número de resultados a serem deslocados na consulta. O padrão é 0 (sem deslocamento)
  • creative_id – O ID do criativo ou array de IDs para consultar.
  • status – O status do criativo. Aceita ‘active’ ou ‘inactive’.
  • order – Como ordenar os resultados. Aceita ‘ASC’ (ascendente) ou ‘DESC’ (descendente).
  • orderby – Coluna da tabela de criativos para ordenar.
  • fields – Campos específicos a serem retornados para cada criativo na resposta. Padrão ‘*’ (todos). Aceita ‘ids’ ou qualquer coluna válida.

Todos os argumentos válidos também podem ser derivados enviando uma solicitação OPTIONS para qualquer um dos endpoints.

O endpoint creatives/{ID} aceita qualquer ID de criativo válido.

Visibilidade

Todos os endpoints exigem a chave de API e o token, exceto o endpoint principal affwp/v1.

Resposta

As respostas são retornadas em formato JSON.

Exemplo de resposta creatives s:

  {
    "creative_id": 2,
    "name": "My Other Creative",
    "description": "",
    "url": "http://affiliate.dev",
    "text": "AffiliateWP Plugin Testing",
    "image": "",
    "status": "inactive",
    "date": "2016-05-11 23:35:58",
    "id": 2
  },
  {
    "creative_id": 3,
    "name": "Special Case",
    "description": "",
    "url": "http://affiliate.dev",
    "text": "AffiliateWP Plugin Testing",
    "image": "https://affwp.dev/wp-content/images/brand-assets/affiliatewp-1v.png",
    "status": "active",
    "date": "2016-05-11 23:43:02",
    "id": 3
  },

Exemplo de resposta creatives/{ID}:

{
  "creative_id": 2,
  "name": "My Other Creative",
  "description": "",
  "url": "http://affiliate.dev",
  "text": "AffiliateWP Plugin Testing",
  "image": "",
  "status": "inactive",
  "date": "2016-05-11 23:35:58",
  "id": 2
}

.

3. Endpoints de Pagamentos

O AffiliateWP core 1.9+ oferece dois endpoints REST somente leitura para pagamentos:

  1. payouts – Recupera objetos de resposta para todos os pagamentos no site atual
  2. payouts/{ID} – Recupera um objeto de resposta para um pagamento com o ID de pagamento fornecido

Os endpoints de pagamento podem ser acessados via requisições GET nos seguintes locais:

http://example.com/wp-json/affwp/v1/payouts
http://example.com/wp-json/affwp/v1/payouts/ID

Todos os endpoints de pagamento e suas várias opções também podem ser descobertos visitando o namespace REST do AffiliateWP diretamente:

http://example.com/wp-json/affwp/v1/
Endpoints

O endpoint payouts aceita quaisquer argumentos válidos de get_payouts():

  • number – O número de resultados a serem recuperados (se disponíveis)
  • offset – O número de resultados a serem deslocados na consulta. O padrão é 0 (sem deslocamento)
  • payout_id – O ID do pagamento ou array de IDs para consultar.
  • affiliate_id – O ID do afiliado ou array de IDs para consultar pagamentos.
  • referrals – ID de referência ou array de IDs de referência para recuperar pagamentos.
  • amount – Valor do pagamento (float) ou intervalo min/max (array) para recuperar pagamentos.
  • amount_compare – Operador de comparação usado com amount. Aceita ‘>’, ‘<‘, ‘>=’, ‘<=’, ‘=’, ou ‘!=’.
  • status – O status do pagamento. Aceita ‘paid’ ou ‘failed’
  • date – O array ou string de data para consultar pagamentos dentro.
  • order – Como ordenar os resultados. Aceita ‘ASC’ (ascendente) ou ‘DESC’ (descendente).
  • orderby – Por qual campo ordenar os resultados da resposta. O padrão é ‘date’
  • fields – Campos específicos a serem retornados para cada pagamento na resposta. Padrão ‘*’ (todos). Aceita ‘ids’ ou qualquer coluna válida

Todos os argumentos válidos também podem ser derivados enviando uma solicitação OPTIONS para qualquer um dos endpoints.

O endpoint payouts/{ID} aceita qualquer ID de pagamento válido.

Visibilidade

Todos os endpoints exigem a chave de API e o token, exceto o endpoint principal affwp/v1.

Resposta

As respostas são retornadas em formato JSON.

Exemplo de resposta payouts :

[
  {
    "payout_id": 1,
    "affiliate_id": 22,
    "referrals": "2,3",
    "amount": 1,
    "payout_method": "manual",
    "status": "paid",
    "date": "2016-08-04 16:54:21",
    "owner": 0,
    "id": 1
  },
  {
    "payout_id": 2,
    "affiliate_id": 22,
    "referrals": "2,3",
    "amount": 1,
    "payout_method": "manual",
    "status": "paid",
    "date": "2016-08-04 16:54:24",
    "owner": 0,
    "id": 2
  },

Exemplo de resposta payouts/{ID}:

{
  "payout_id": 2,
  "affiliate_id": 22,
  "referrals": "2,3",
  "amount": 1,
  "payout_method": "manual",
  "status": "paid",
  "date": "2016-08-04 16:54:24",
  "owner": 0,
  "id": 2
}<br>

.

4. Endpoints de Indicações

O AffiliateWP core 1.9+ oferece dois endpoints REST somente leitura para indicações:

  1. referrals – Recupera objetos de resposta para todas as indicações no site atual
  2. referrals/{ID} – Recupera um objeto de resposta para uma indicação com o ID de indicação fornecido

Os endpoints de indicação podem ser acessados via requisições GET nos seguintes locais:

http://example.com/wp-json/affwp/v1/referrals
http://example.com/wp-json/affwp/v1/referrals/ID

Todos os endpoints de indicação e suas várias opções também são descobertos visitando o namespace REST do AffiliateWP diretamente:

http://example.com/wp-json/affwp/v1/
Endpoints

O endpoint referrals aceita quaisquer argumentos válidos de get_referrals():

  • number – O número de resultados a serem recuperados (se disponíveis)
  • offset – O número de resultados a serem deslocados na consulta. O padrão é 0 (sem deslocamento)
  • referral_id – O ID da indicação ou array de IDs para consultar.
  • affiliate_id – O ID do afiliado ou um array de IDs para consultar.
  • reference – Informações de referência (ID do produto) para a indicação.
  • ref_context – O contexto sob o qual a indicação foi criada (integração).
  • campaign – A campanha associada.
  • status – O status da indicação ou array de status. Aceita ‘paid’, ‘unpaid’, ‘pending’, ou ‘rejected’.
  • order – Como ordenar os resultados. Aceita ‘ASC’ (ascendente) ou ‘DESC’ (descendente).
  • orderby – Por qual campo ordenar os resultados da resposta. O padrão é ‘date’
  • search – Um ID de indicação ou a string de busca para consultar indicações.
  • date – O array de datas ou string para consultar indicações dentro.
  • fields – Campos específicos a serem retornados para cada indicação na resposta. Padrão ‘*’ (todos). Aceita ‘ids’ ou qualquer coluna válida

Todos os argumentos válidos também podem ser derivados enviando uma solicitação OPTIONS para qualquer um dos endpoints.

O endpoint referrals/{ID} aceita qualquer ID de indicação válido.

Visibilidade

Todos os endpoints exigem a chave de API e o token, exceto o endpoint principal affwp/v1.

Resposta

As respostas são retornadas em formato JSON.

Exemplo de resposta referrals :

  {
    "referral_id": 21,
    "affiliate_id": 0,
    "visit_id": 0,
    "description": "",
    "status": "",
    "amount": "",
    "currency": "",
    "custom": "",
    "context": "",
    "campaign": "",
    "reference": "",
    "products": "",
    "date": "2016-08-17 19:57:30",
    "payout_id": "102",
    "id": 21
  },
  {
    "referral_id": 22,
    "affiliate_id": 2736,
    "visit_id": 0,
    "description": "",
    "status": "paid",
    "amount": "1.00",
    "currency": "USD",
    "custom": "",
    "context": "",
    "campaign": "",
    "reference": "",
    "products": "",
    "date": "2016-08-17 19:57:43",
    "payout_id": "81",
    "id": 22
  },

Exemplo de resposta referrals/{ID}:

{
  "referral_id": 21,
  "affiliate_id": 0,
  "visit_id": 0,
  "description": "",
  "status": "",
  "amount": "",
  "currency": "",
  "custom": "",
  "context": "",
  "campaign": "",
  "reference": "",
  "products": "",
  "date": "2016-08-17 19:57:30",
  "payout_id": "102",
  "id": 21
}

.

5. Endpoints de Visitas

O AffiliateWP core 1.9+ oferece dois endpoints REST somente leitura para visitas:

  1. visits – Recupera objetos de resposta para todas as visitas no site atual
  2. visits/{ID} – Recupera um objeto de resposta para uma visita com o ID de visita fornecido

Os endpoints de visita podem ser acessados via requisições GET nos seguintes locais:

http://example.com/wp-json/affwp/v1/visits
http://example.com/wp-json/affwp/v1/visits/ID

Todos os endpoints de visita e suas várias opções também são descobertos visitando o namespace REST do AffiliateWP diretamente:

http://example.com/wp-json/affwp/v1/
Endpoints

O endpoint visits aceita quaisquer argumentos válidos de get_visits():

  • number – O número de resultados a serem recuperados (se disponíveis)
  • offset – O número de resultados a serem deslocados na consulta. O padrão é 0 (sem deslocamento)
  • visit_id – O ID da visita ou array de IDs para consultar visitas.
  • affiliate_id – O ID do afiliado ou array de IDs para consultar visitas.
  • referral_id – O ID da indicação ou array de IDs para consultar visitas.
  • referral_status – O status da indicação ou array de status para recuperar visitas.
  • campaign – A campanha associada.
  • order – Como ordenar a visita na resposta. O padrão é ‘ASC’ (ascendente)
  • orderby – Por qual campo ordenar os resultados da resposta. O padrão é ‘date’
  • campos – Campos específicos a serem retornados para cada visita na resposta. Padrão ‘*’ (todos). Aceita ‘ids’ ou qualquer coluna válida

Todos os argumentos válidos também podem ser derivados enviando uma solicitação OPTIONS para qualquer um dos endpoints.

O endpoint visits/{ID} aceita qualquer ID de visita válido.

Visibilidade

Todos os endpoints exigem a chave de API e o token, exceto o endpoint principal affwp/v1.

Resposta

As respostas são retornadas em formato JSON.

Exemplo de resposta visits:

  {
    "visit_id": 1,
    "affiliate_id": 5464,
    "referral_id": 0,
    "url": "http://google.com",
    "referrer": "https://affiliatewp.com",
    "campaign": "test",
    "ip": "",
    "date": "2016-09-20 21:58:09",
    "id": 1
  },
  {
    "visit_id": 2,
    "affiliate_id": 5464,
    "referral_id": 0,
    "url": "http://google.com",
    "referrer": "https://affiliatewp.com",
    "campaign": "test",
    "ip": "",
    "date": "2016-09-18 21:58:11",
    "id": 2
  },

Exemplo de resposta visits/{ID}:

{
  "visit_id": 2,
  "affiliate_id": 5464,
  "referral_id": 0,
  "url": "http://google.com",
  "referrer": "https://affiliatewp.com",
  "campaign": "test",
  "ip": "",
  "date": "2016-09-18 21:58:11",
  "id": 2
}

.

Ainda preso? Envie um ticket e a equipe que o criou ajudará.

Comece a Obter Mais Vendas Hoje com o AffiliateWP

Lance seu programa de afiliados hoje e desbloqueie um novo canal de receita para expandir seus negócios mais rapidamente.

Obtenha o AffiliateWP Agora