Addon Estendido da API REST

Você é um desenvolvedor procurando obter controle total sobre seus dados de afiliados usando a REST API do AffiliateWP? O addon REST API Extended permite operações de Criação, Leitura, Atualização e Exclusão, permitindo que você gerencie afiliados, indicações, criativos e muito mais por meio de aplicativos externos.

Neste artigo, mostraremos como instalar e configurar o add-on REST API Extended para o AffiliateWP.

Instalando o addon REST API Extended

Antes de começarmos, certifique-se de instalar e ativar o AffiliateWP em seu site WordPress.

Depois de ter o AffiliateWP instalado e sua licença verificada, você poderá instalar e ativar rapidamente o addon REST API Extended.

Configurando o addon REST API Extended

Após ativar o add-on REST API Extended, você precisará configurar suas configurações. Para fazer isso, navegue até AffiliateWP » Configurações » REST API em seu painel do WordPress.

Aqui, você pode selecionar as caixas de seleção para habilitar os endpoints que deseja usar, como afiliados, indicações, pagamentos e criativos.

Seu site agora tem uma REST API CRUD completa para interagir com seus dados de afiliados.

Uma vez que essas configurações sejam configuradas, seu site estará equipado com uma REST API totalmente funcional habilitada para CRUD, permitindo que você crie, leia, atualize e exclua dados no AffiliateWP.

Gerenciando Afiliados

REST API Extended adiciona três endpoints, um para criar, editar e excluir afiliados, além dos dois endpoints somente leitura já disponíveis no núcleo do AffiliateWP.

Todos os cinco endpoints utilizam os mesmos dois padrões de rota:

1. Afiliados – Ao receber uma solicitação GET, uma lista de afiliados é retornada e pode ser filtrada com argumentos adicionais. Ao receber uma solicitação POST ou PUT, um novo afiliado pode ser criado.
2. Afiliados/[ID] – Ao receber uma solicitação GET, PATCH ou DELETE, um único afiliado pode ser recuperado, editado ou excluído, respectivamente.

Ambas as rotas também podem aceitar solicitações OPTIONS genéricas, que podem ser muito úteis para descobrir informações sobre endpoints disponíveis, tipos de solicitação e argumentos aceitos, e esquema de itens.

Se você planeja ler, escrever, editar ou excluir afiliados, este add-on o torna possível.

Todas as solicitações devem ser autenticadas usando chaves de API, que são geradas e gerenciadas através da aba AffiliateWP → Ferramentas → Chaves de API. Confira o artigo REST API – Autenticação para mais informações.

Criando um Afiliado

Afiliados podem ser criados enviando uma solicitação POST ou PUT para a rota afiliados:

https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates

O endpoint create aceita quaisquer dos seguintes argumentos de affwp_add_affiliate():

• user_id – (integer) Cada afiliado compartilha um relacionamento 1:1 com uma conta de usuário WordPress existente. Se nenhum ID de usuário adequado estiver disponível, o argumento create_user pode ser passado para tentar criar um afiliado e uma conta de usuário na mesma etapa.
• username – (string) Opcional. Usado para definir o user_login ao criar uma nova conta de usuário. Se não for fornecido, o payment_email será usado para gerar o user_login do usuário WordPress criado.
• create_user – (boolean)  Usado para criar uma nova conta de usuário, em vez de user_id. Deve ser acompanhado por um valor único de payment_email, que é usado ao registrar a conta de usuário.
• rate – (integer) Taxa de afiliado a ser usada. Se não especificado, o padrão global será usado.
• rate_type – (string) Tipo de taxa. Os tipos aceitos padrão são 'percentage' ou 'flat'. Se não especificado, o padrão global será usado.
• payment_email – (string) E-mail de pagamento do afiliado. Se omitido, o e-mail da conta do usuário será usado na recuperação. Obrigatório ao usar create_user.
• status – (string) Status do afiliado. Aceita 'active', 'inactive', 'pending' ou 'rejected'. O padrão é 'pending'.
• notes – (string) Notas do afiliado.

Criando um afiliado com user_id:

Method: PUT/POST
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates/?user_id=5&rate=25&rate_type=percentage

O novo afiliado seria associado ao user_id 5 e receberia uma taxa de comissão de 25 por cento.

Exemplo de resposta:

{
  "affiliate_id": 30,
  "user_id": 5,
  "rate": "25",
  "rate_type": "percentage",
  "payment_email": "",
  "status": "pending",
  "earnings": 0,
  "unpaid_earnings": 0,
  "referrals": 0,
  "visits": 0,
  "date_registered": "2024-01-26 07:27:52",
  "id": 30
}

Criando um afiliado e um usuário com create_user:

Method: PUT/POST
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates/?create_user=1&[email protected]

O novo afiliado seria associado ao novo usuário (ID 10) e receberia um e-mail de pagamento de [email protected].

Exemplo de resposta:

{
  "affiliate_id": 31,
  "user_id": 10,
  "rate": "",
  "rate_type": "",
  "payment_email": "[email protected]",
  "status": "pending",
  "earnings": 0,
  "unpaid_earnings": 0,
  "referrals": 0,
  "visits": 0,
  "date_registered": "2024-01-26 07:27:52",
  "id": 31
}

Editando um Afiliado Existente

Afiliados individuais podem ser atualizados enviando uma requisição POST ou PATCH para a rota affiliates/[id]:

https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates/[id]

O endpoint edit aceita quaisquer dos seguintes argumentos de affwp_update_affiliate():

• account_email – (string) Novo e-mail da conta para a conta de usuário associada.
• payment_email – (string) Novo e-mail de pagamento.
• rate – (integer) Taxa de afiliado a ser usada
• rate_type – (string) Tipo de taxa.
• status – (string) Status do afiliado. Aceita 'active', 'inactive', 'pending' ou 'rejected'.
• notes – (string) Notas do afiliado.

Atualizando um Afiliado

Neste exemplo, atualizaremos o status de um afiliado de pending para active.

Method: POST/PATCH
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates/31?status=active

Resposta:

{
  "affiliate_id": 31,
  "user_id": 10,
  "rate": "",
  "rate_type": "",
  "payment_email": "[email protected]",
  "status": "active",
  "earnings": 0,
  "unpaid_earnings": 0,
  "referrals": 0,
  "visits": 0,
  "date_registered": "2024-01-26 07:27:52",
  "id": 31
}

Excluindo um Afiliado

Um afiliado pode ser excluído enviando uma requisição DELETE para a rota affiliates/[id]:

https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates/[id]

O endpoint delete não aceita argumentos adicionais. Quando um afiliado for excluído com sucesso, um par chave/valor de deleted: true será incluído na resposta, juntamente com uma cópia da resposta do afiliado anterior.

Exemplo de requisição:

Method: DELETE
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates/31

Resposta:

{
  "deleted": true,
  "previous": {
    "affiliate_id": 31,
    "user_id": 10,
    "rate": "",
    "rate_type": "",
    "payment_email": "[email protected]",
    "status": "active",
    "earnings": 0,
    "unpaid_earnings": 0,
    "referrals": 0,
    "visits": 0,
    "date_registered": "2024-01-26 07:27:52",
    "id": 31
  }
}

Gerenciando Criativos

REST API Extended adiciona três endpoints, um para cada para criar, editar e excluir criativos, além dos dois endpoints somente leitura já disponíveis no núcleo do AffiliateWP.

Todos os cinco endpoints utilizam os mesmos dois padrões de rota:

1. Criativos – Ao receber uma solicitação GET, uma lista de criativos é retornada e pode ser filtrada com argumentos adicionais. Ao receber uma solicitação POST ou PUT, um novo criativo pode ser criado.
2. Criativos/[id] – Ao receber uma solicitação GET, PATCH ou DELETE, um único criativo pode ser recuperado, editado ou excluído, respectivamente.

Ambas as rotas também podem aceitar solicitações OPTIONS genéricas, que podem ser muito úteis para descobrir informações sobre endpoints disponíveis, tipos de solicitação e argumentos aceitos, e esquema de itens.

Se você planeja ler, escrever, editar ou excluir criativos, este complemento torna isso possível.

Todas as solicitações devem ser autenticadas usando chaves de API, que são geradas e gerenciadas através da aba AffiliateWP → Ferramentas → Chaves de API. Confira o artigo REST API – Autenticação para mais informações.

Criando um Criativo

Criativos podem ser criados enviando uma solicitação POST ou PUT para a rota criativos:

https://alfsflowersandgifts.com/wp-json/affwp/v1/creatives

O endpoint create aceita quaisquer dos seguintes argumentos affwp_add_creative():

• Nome – (inteiro) Rótulo do nome para o criativo.
• Descrição – (string) Descrição do criativo.
• Url – (string) URL para onde o criativo apontará.
• Texto – (string) Texto a ser exibido com o criativo.
• Imagem – (string) URL da imagem a ser associada ao criativo.
• Status – (string) Status do criativo. Aceita ‘active’ ou ‘inactive’. Padrão ‘active’.

Criando um criativo

Method: PUT/POST
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/creatives/?name=New+Creative&text=REST

O novo criativo, chamado “New Creative”, conteria o texto “REST”.

Exemplo de resposta:

{
  "creative_id": 20,
  "name": "New Creative",
  "description": "",
  "url": "",
  "text": "REST",
  "image": "",
  "status": "",
  "date": "2024-01-26 09:25:05",
  "id": 20
}

Editando um Criativo Existente

Criativos individuais podem ser atualizados enviando uma solicitação POST ou PATCH para a rota criativos/[id]:

https://alfsflowersandgifts.com/wp-json/affwp/v1/creatives/[id]

O endpoint edit aceita quaisquer dos seguintes argumentos affwp_update_creative():

• Nome – (inteiro) Rótulo do nome para o criativo.
• Descrição – (string) Descrição do criativo.
• Url – (string) URL para onde o criativo apontará.
• Texto – (string) Texto a ser exibido com o criativo.
• Imagem – (string) URL da imagem a ser associada ao criativo.
• Status – (string) Status do criativo. Aceita ‘active’ ou ‘inactive’.

Atualizando um Criativo

Neste exemplo, atualizaremos o status de um criativo de ativo para inativo.

Method: POST/PATCH
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/creatives/20?status=inactive

Resposta:

{
  "creative_id": 20,
  "name": "Creative",
  "description": "",
  "url": "http://alfsflowersandgifts.com",
  "text": "AffiliateWP Plugin Testing",
  "image": "",
  "status": "inactive",
  "date": "2024-01-26 09:25:05",
  "id": 20
}

Excluindo um Criativo

Um pode ser excluído enviando uma solicitação DELETE para a rota criativos/[id]:

https://alfsflowersandgifts.com/wp-json/affwp/v1/creatives/[id]

O endpoint delete não aceita argumentos adicionais. Quando um criativo for excluído com sucesso, um par chave/valor de deleted: true será incluído na resposta, juntamente com uma cópia da resposta do criativo antigo.

Exemplo de requisição:

Method: DELETE
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/creatives/20

Resposta:

{
  "deleted": true,
  "previous": {
    "creative_id": 20,
    "name": "Creative",
    "description": "",
    "url": "http://alfsflowersandgifts.com",
    "text": "AffiliateWP Plugin Testing",
    "image": "",
    "status": "inactive",
    "date": "2024-01-26 09:25:05",
    "id": 20
  }
}

Gerenciando Pagamentos

REST API Extended adiciona três endpoints, um para cada para criar, editar e excluir pagamentos, além dos dois endpoints somente leitura já disponíveis no núcleo do AffiliateWP.

Todos os cinco endpoints utilizam os mesmos dois padrões de rota:

1. Pagamentos – Ao receber uma solicitação GET, uma lista de pagamentos é retornada e pode ser filtrada com argumentos adicionais. Ao receber uma solicitação POST ou PUT, um novo pagamento pode ser criado.
2. Pagamentos/[id] – Ao receber uma solicitação GET, PATCH ou DELETE, um único pagamento pode ser recuperado, editado ou excluído, respectivamente.

Ambas as rotas também podem aceitar solicitações OPTIONS genéricas, que podem ser muito úteis para descobrir informações sobre endpoints disponíveis, tipos de solicitação e argumentos aceitos, e esquema de itens.

Todas as solicitações devem ser autenticadas usando chaves de API, que são geradas e gerenciadas através da aba AffiliateWP → Ferramentas → Chaves de API. Confira o artigo REST API – Autenticação para mais informações.

Criando um Pagamento

Pagamentos podem ser criados enviando uma requisição POST ou PUT para a rota payouts:

https://alfsflowersandgifts.com/wp-json/affwp/v1/payouts

O endpoint create aceita qualquer um dos seguintes argumentos de affwp_add_payout():

• affiliate_id – (integer) ID do afiliado ao qual o pagamento será associado. Este campo é obrigatório.
• referrals – (array|string) Array ou lista separada por vírgulas de IDs de indicações a serem incluídas no pagamento.
• amount – (float) Valor do pagamento (geralmente derivado dos valores das indicações).
• payout_method – (string) Método de pagamento.
• status – (string) Aceita ‘paid’ ou ‘failed’. Padrão ‘paid’.

Exemplo de requisição:

Method: PUT/POST
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/payouts/?affilite_id=30&referrals=10,15,20

O novo pagamento, com payout_id 15, cobriria as indicações 10, 15 e 20 para o affiliate_id 30.

Resposta:

{
  "payout_id": 15,
  "affiliate_id": 30,
  "referrals": "10,15,20",
  "amount": 27.87,
  "payout_method": "manual",
  "status": "paid",
  "date": "2024-01-26 12:55:13",
  "owner": 1,
  "id": 15
}

Editando um Pagamento Existente

Pagamentos individuais podem ser atualizados enviando uma requisição POST ou PATCH para a rota payouts/[id]:

https://alfsflowersandgifts.com/wp-json/affwp/v1/payouts/[id]

O endpoint edit aceita qualquer um dos seguintes argumentos:

• affiliate_id – (integer) ID do afiliado ao qual o pagamento será associado. Este campo é obrigatório.
• referrals – (array|string) Array ou lista separada por vírgulas de IDs de indicações a serem incluídas no pagamento.
• amount – (float) Valor do pagamento (geralmente derivado dos valores das indicações).
• payout_method – (string) Método de pagamento.
• status – (string) Aceita ‘paid’ ou ‘failed’. Padrão ‘paid’.

Atualizando um Pagamento

Neste exemplo, atualizaremos o status de um pagamento de failed para paid.

Method: POST/PATCH
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/payouts/15?status=paid

Resposta:

{
  "payout_id": 15,
  "affiliate_id": 30,
  "referrals": "10,15,20",
  "amount": 30,
  "payout_method": "manual",
  "status": "paid",
  "date": "2024-01-26 12:55:13",
  "owner": 1,
  "id": 15
}

Excluindo um Pagamento

Um pagamento pode ser excluído enviando uma requisição DELETE para a rota payouts/[id]:

https://alfsflowersandgifts.com/wp-json/affwp/v1/payouts/[id]

O endpoint delete não aceita argumentos adicionais. Quando um pagamento for excluído com sucesso, um par chave/valor de deleted: true será incluído na resposta, juntamente com uma cópia da resposta do pagamento antigo.

Exemplo de requisição:

Method: DELETE
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/payouts/15

Resposta:

{
  "deleted": true,
  "previous": {
    "payout_id": 6751,
    "affiliate_id": 5454,
    "referrals": "35878,35877,35876",
    "amount": 30,
    "payout_method": "manual",
    "status": "paid",
    "date": "2024-01-26 12:55:13",
    "owner": 1,
    "id": 6751
  }
}

Gerenciando Indicações

REST API Extended adiciona três endpoints, um para criar, editar e excluir indicações, além dos dois endpoints somente leitura já disponíveis no núcleo do AffiliateWP.

Todos os cinco endpoints utilizam os mesmos dois padrões de rota:

1. referrals – Quando uma requisição GET é enviada, uma lista de indicações é retornada e pode ser filtrada com argumentos adicionais. Quando uma requisição POST ou PUT é enviada, uma nova indicação pode ser criada.
2. referrals/[id] – Quando uma requisição GET, PATCH ou DELETE é enviada, uma única indicação pode ser recuperada, editada ou excluída, respectivamente.

Ambas as rotas também podem aceitar solicitações OPTIONS genéricas, que podem ser muito úteis para descobrir informações sobre endpoints disponíveis, tipos de solicitação e argumentos aceitos, e esquema de itens.

Todas as solicitações devem ser autenticadas usando chaves de API, que são geradas e gerenciadas através da aba AffiliateWP → Ferramentas → Chaves de API. Confira o artigo REST API – Autenticação para mais informações.

Criando uma Indicação

Indicações podem ser criadas enviando uma requisição POST ou PUT para a rota referrals:

https://alfsflowersandgifts.com/wp-json/affwp/v1/referrals

O endpoint create aceita qualquer um dos seguintes argumentos de affwp_add_referral():

• affiliate_id – (integer) ID do afiliado ao qual a indicação será associada. Este campo é obrigatório. Veja user_id e user_name.
• user_id – (integer) ID do usuário usado para recuperar o ID do afiliado associado se affiliate_id não for enviado.
• user_name – (string) Nome de usuário usado para recuperar o ID do afiliado associado se affiliate_id não for enviado.
• amount – (float) Valor final calculado da indicação, não o valor da transação ou venda.
• currency – (string) Moeda do valor da indicação.
• description – (string) Descrição da indicação.
• referência – (string) Referência de encaminhamento. Geralmente contém informações do produto, como IDs de produtos.
• contexto – (string) Contexto sob o qual o encaminhamento foi criado. Geralmente é o slug da integração.
• status – (string) Aceita ‘pago’, ‘não pago’, ‘pendente’ ou ‘rejeitado’. Padrão ‘pendente’.

Criando um encaminhamento

Method: PUT/POST
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/referrals/?affilite_id=30&amount=15

O acima criaria um novo encaminhamento associado ao ID de afiliado 30 no valor de R$ 15 com status ‘pendente’.

Exemplo de resposta:

{
  "referral_id": 450,
  "affiliate_id": 30,
  "visit_id": 0,
  "description": "",
  "status": "pending",
  "amount": "15.00",
  "currency": "USD",
  "custom": "",
  "context": "",
  "campaign": "",
  "reference": "",
  "products": "",
  "date": "2024-01-26 22:28:54",
  "payout_id": "0",
  "id": 450
}

Editando um Encaminhamento Existente

Encaminhamentos individuais podem ser atualizados enviando uma solicitação POST ou PATCH para a rota referrals/[id]:

https://alfsflowersandgifts.com/wp-json/affwp/v1/referrals/[id]

O endpoint edit aceita qualquer um dos seguintes argumentos affwp_process_update_referral():

• affiliate_id – (integer) ID do afiliado ao qual associar o encaminhamento.
• visit_id – (integer) ID da visita à qual associar o encaminhamento.
• amount – (float) Valor atualizado do encaminhamento.
• currency – (string) Moeda do valor atualizado do encaminhamento.
• description – (string) Descrição atualizada do encaminhamento.
• referência – (string) Referência de encaminhamento. Geralmente contém informações do produto, como IDs de produtos.
• contexto – (string) Contexto sob o qual o encaminhamento foi criado. Geralmente é o slug da integração.
• status – (string) Aceita ‘pago’, ‘não pago’, ‘pendente’ ou ‘rejeitado’.

Atualizando um Encaminhamento

Neste exemplo, atualizaremos o status de um encaminhamento de  pendente para pago.

Method: POST/PATCH
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/referrals/450?status=paid

Resposta:

{
  "referral_id": 450,
  "affiliate_id": 30,
  "visit_id": 0,
  "description": "",
  "status": "paid",
  "amount": "",
  "currency": "",
  "custom": "",
  "context": "",
  "campaign": "",
  "reference": "",
  "products": "",
  "date": "2024-01-26 22:28:54",
  "payout_id": "0",
  "id": 450
}

Excluindo um Encaminhamento

Um encaminhamento pode ser excluído enviando uma solicitação DELETE para a rota referrals/[id]:

https://alfsflowersandgifts.com/wp-json/affwp/v1/referrals/[id]

O endpoint delete não aceita argumentos adicionais. Quando um encaminhamento for excluído com sucesso, um par chave/valor de deleted: true será incluído na resposta, juntamente com uma cópia da resposta do encaminhamento antigo.

Exemplo de requisição:

Method: DELETE
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/referrals/450

Resposta:

{
  "deleted": true,
  "previous": {
    "referral_id": 35879,
    "affiliate_id": 5454,
    "visit_id": 0,
    "description": "",
    "status": "paid",
    "amount": "",
    "currency": "",
    "custom": "",
    "context": "",
    "campaign": "",
    "reference": "",
    "products": "",
    "date": "2024-01-26 22:28:54",
    "payout_id": "0",
    "id": 35879
  }
}

Gerenciando Visitas

REST API Extended adiciona três endpoints, um para criar, editar e excluir visitas, além dos dois endpoints somente leitura já disponíveis no núcleo do AffiliateWP.

Todos os cinco endpoints utilizam os mesmos dois padrões de rota:

1. visits – Quando uma solicitação GET é enviada, uma lista de visitas é retornada e pode ser filtrada com argumentos adicionais. Quando uma solicitação POST ou PUT é enviada, um novo encaminhamento pode ser criado.
2. visits/[id] – Quando uma solicitação GET, PATCH ou DELETE é enviada, uma única visita pode ser recuperada, editada ou excluída, respectivamente.

Ambas as rotas também podem aceitar solicitações OPTIONS genéricas, que podem ser muito úteis para descobrir informações sobre endpoints disponíveis, tipos de solicitação e argumentos aceitos, e esquema de itens.

Todas as solicitações devem ser autenticadas usando chaves de API, que são geradas e gerenciadas através da aba AffiliateWP → Ferramentas → Chaves de API. Confira o artigo REST API – Autenticação para mais informações.

Criando uma Visita

Visitas podem ser criadas enviando uma solicitação POST ou PUT para a rota visits:

https://alfsflowersandgifts.com/wp-json/affwp/v1/visits

O endpoint create aceita qualquer um dos seguintes argumentos:

• affiliate_id – (integer) ID do afiliado a ser associado à visita. Este campo é obrigatório.
• referral_id – (integer) ID do encaminhamento a ser associado à visita.
• url – (string) URL da visita.
• referrer – (string) URL de referência
• campanha – (string) Campanha associada.
• ip – (string) Endereço IP do visitante.

Exemplo de requisição:

Method: PUT/POST
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/visits/?affilite_id=30&url=https%3A%2F%2Faffiliatewp.com

O acima criaria uma nova visita associada ao ID de afiliado 30 que tem uma URL armazenada de https://affiliatewp.com.

Resposta:

{
  "visit_id": 541,
  "affiliate_id": 30,
  "referral_id": 0,
  "url": "https://affiliatewp.com",
  "referrer": "",
  "campaign": "",
  "ip": "",
  "date": "2024-01-26 23:05:21",
  "id": 541
}

Editando uma Visita Existente

Visitas únicas podem ser atualizadas enviando uma solicitação POST ou PATCH para a rota visits/[id]:

https://alfsflowersandgifts.com/wp-json/affwp/v1/visits/[id]

O endpoint edit aceita qualquer um dos seguintes argumentos:

• visit_id – (integer) ID da visita. Este campo é obrigatório.
• referral_id – (integer) ID do encaminhamento a ser associado à visita.
• affiliate_id – (integer) ID do afiliado a ser associado à visita.
• url – (string) URL da visita.
• referrer – (string) URL de referência
• campanha – (string) Campanha associada.
• ip – (string) Endereço IP do visitante.

Atualizando uma Visita

Neste exemplo, atualizaremos a campanha associada de uma visita:

Method: POST/PATCH
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/visits/541?campaign=spring-sale

Resposta:

{
  "visit_id": 541,
  "affiliate_id": 30,
  "referral_id": 0,
  "url": "https://affiliatewp.com",
  "referrer": "",
  "campaign": "spring-sale",
  "ip": "",
  "date": "2024-01-26 23:05:21",
  "id": 541
}

Excluindo uma Visita

Uma visita pode ser excluída enviando uma solicitação DELETE para a rota visits/[id]:

https://alfsflowersandgifts.com/wp-json/affwp/v1/visits/[id]

O endpoint delete não aceita argumentos adicionais. Quando uma visita for excluída com sucesso, um par chave/valor de deleted: true será incluído na resposta, juntamente com uma cópia da resposta da visita antiga.

Exemplo de requisição:

Method: DELETE
Endpoint: https://alfsflowersandgifts.com/wp-json/affwp/v1/visits/541

Resposta:

{
  "deleted": true,
  "previous": {
    "visit_id": 541,
    "affiliate_id": 30,
    "referral_id": 0,
    "url": "https://affiliatewp.com",
    "referrer": "",
    "campaign": "spring-sale",
    "ip": "",
    "date": "2024-01-26 23:05:21",
    "id": 541
  }
}

Exemplo: Integração da API REST Entre Dois Sites WordPress

Um dos casos de uso mais comuns para o add-on REST API Extended é permitir que um site WordPress interaja com outro site executando o AffiliateWP.

Por exemplo, você pode criar um afiliado em um site WordPress (Site A) e registrá-lo como afiliado em um site separado com tecnologia WordPress (Site B) usando a API. Essa integração permite uma comunicação perfeita entre os dois sites.

Os exemplos a seguir pressupõem que você tenha um conhecimento básico sobre como o WordPress lida com o envio de solicitações remotas e a recuperação de respostas.

Se você não estiver familiarizado com a API HTTP ou a API REST, recomendamos consultar o artigo da API HTTP no manual oficial do desenvolvedor do plugin, bem como o manual da API REST.

Descoberta de Informações

Conforme descrito nas seções Gerenciando Afiliados, Criativos, Pagamentos, Referências e Visitas, o add-on REST API Extended traz funcionalidades completas de CRUD (Criar, Ler, Atualizar e Excluir) ao interagir com o AffiliateWP remotamente.

Na maioria das vezes, as respostas remotas são estruturadas de forma consistente entre os tipos de objeto. Dito isso, dependendo do endpoint usado, certos campos específicos dos tipos de objeto fornecidos serão necessários em várias circunstâncias.

A maneira mais fácil de determinar quais campos são necessários ou quais parâmetros são aceitos é enviar uma solicitação OPTIONS para o endpoint; a resposta da solicitação OPTIONS deve dizer tudo o que você precisa saber.

Por exemplo, a seguir está uma seção da resposta de uma solicitação OPTIONS enviada para o endpoint /v1/creatives/ com o REST API Extended ativado:

{
  "namespace": "affwp/v1",
  "methods": [
    "GET",
    "POST",
    "PUT",
    "PATCH"
  ],
  "endpoints": [
    {
      "methods": [
        "POST",
        "PUT",
        "PATCH"
      ],
      "args": {
        "name": {
          "required": false,
          "description": "Name of the creative.",
          "type": "string"
        },
        "description": {
          "required": false,
          "description": "Description for the creative.",
          "type": "string"
        },
        "url": {
          "required": false,
          "description": "URL the creative points to.",
          "type": "string"
        },
        "text": {
          "required": false,
          "description": "Text for the creative.",
          "type": "string"
        },
        "image": {
          "required": false,
          "description": "ID of the media library image associated with the creative",
          "type": "integer"
        },
        "status": {
          "required": false,
          "description": "The creative status.",
          "type": "string"
        },
        "date": {
          "required": false,
          "description": "The date the creative was created.",
          "type": "string"
        }
      }
    }
  ],

Você pode ver que os métodos de solicitação disponíveis para este endpoint estão claramente listados e os argumentos disponíveis para cada um definidos e listados dentro da hierarquia abaixo. Outras informações úteis retornadas em uma solicitação OPTIONS incluem informações de esquema – definindo os campos que estarão presentes em um único objeto, e mais.

Construindo Solicitações

Agora que você tem uma boa base sobre o que precisa saber e como obter mais informações, vamos criar algumas solicitações de exemplo.

Autenticação

Se você se lembra do artigo Visão Geral da API REST v1, todas as solicitações enviadas precisam incluir um cabeçalho de Autorização construído usando o esquema de Autenticação Básica. O cabeçalho de Autenticação Básica no AffiliateWP é obtido usando os valores da chave pública e do token. O seguinte é um exemplo de um cabeçalho de Autenticação Básica:

Authorization : Basic N2Q4NTM1OWM4NzlkYWNjOWE2ZmMxZjgxYjQ2ZDYyZDE6YmE3YjUwZGUyMjZkOGI2YzRkNjQyMjA1YjcwNDUwMjY=

“Authorization” é a chave, e “Basic N2Q4NTM…” é o valor. O valor é construído codificando a combinação dos valores da chave pública e do token, separados por dois pontos, e concatenando “Basic ” na frente. Por exemplo:

"Basic " . base64_encode( "{$public_key}:{$token}" );

Ao usar as funções da API HTTP do WordPress, o cabeçalho Authorization deve ser enviado da seguinte forma:

wp_remote_*( 'request_url', array(<br>    'headers' => array(<br>        'Authorization' => 'Basic hash_value'<br>    )<br>) );

Para mais informações sobre como a API REST do AffiliateWP autentica, confira o artigo API REST – Autenticação.

Exemplo de Solicitação: Criar um afiliado

Conforme observado na seção Gerenciando Afiliados, um user_id é necessário ao criar um afiliado. Alternativamente, o argumento create_user pode ser enviado junto com um valor payment_email para criar um usuário e um afiliado na mesma etapa.

O código WordPress a seguir é necessário para criar remotamente um afiliado quando você já possui um user_id válido:

$request_url = add_query_arg( array( 
    'user_id' => 5 
), 

'https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates' );

$response = wp_remote_post( $request_url, array(
    'headers' => array(
        'Authorization' => 'Basic hash_value'
    )
) );

No trecho acima, observe que o valor user_id é passado via $request_url em vez de via argumento ‘body’, o que é suportado para solicitações POST. Isso é feito para consistência com exemplos de outros endpoints, especificamente aqueles que utilizam os métodos PUT ou PATCH, que não suportam o envio de parâmetros via corpo da solicitação.

Exemplo de Solicitação: Criar um pagamento

Semelhante à criação de afiliados, novos pagamentos também exigem campos específicos, especificamente os valores affiliate_id e referrals.

O código a seguir é necessário para criar remotamente um novo pagamento, dado um affiliate_id válido e uma lista de IDs de referência:

$request_url = add_query_arg( array(
    'affiliate_id'  => 2,
    'referrals'     => '2,3,4',
    'payout_method' => 'REST',
), 

'https://alfsflowersandgifts.com/wp-json/affwp/v1/payouts' );

$response = wp_remote_post( $request_url, array(
    'headers' => array(
        'Authorization' => 'Basic hash_value'
    )
) );

Observe que o valor payout_method não é necessariamente necessário, apenas útil para fornecer contexto de que o pagamento foi gerado via REST.

Exemplo de Solicitação: Atualizando uma referência

Ao atualizar um objeto via REST, vale notar que, como o ID do objeto que você está modificando faz parte do endpoint, o valor dessa chave primária não precisa ser enviado com a solicitação.

O seguinte é um exemplo de como atualizar o status de uma referência de não paga para paga:

$request_url = add_query_arg( array( 
'status' => 'paid', 

'https://alfsflowersandgifts.com/wp-json/affwp/v1/referrals/3' );

$response = wp_remote_request( $request_url, array(
    'method'  => 'PATCH',
    'headers' => array(
        'Authorization' => 'Basic hash_value'
    )
) );

Observe que, em vez de wp_remote_post() como antes, esta solicitação usa wp_remote_request() com o argumento ‘method’ => ‘PATCH’ passado. Isso informa à API REST que você está enviando especificamente uma solicitação PATCH.

Além disso, observe que o ID da referência 3 é passado como parte do endpoint em vez de no status semelhante a uma URL.

Analisando Respostas

Além de elaborar solicitações, é importante ter um bom domínio sobre como as respostas são estruturadas e estar familiarizado com a validação de que uma solicitação foi bem-sucedida no ambiente WordPress.

Nos dois primeiros exemplos em “Construindo Requisições”, falamos sobre como criar requisições para a criação de novos afiliados e pagamentos.

Ao examinar uma resposta, uma das maneiras mais simples de confirmar que ela foi bem-sucedida é observar o código da resposta:

$response_code = wp_remote_retrieve_response_code( $response );

if ( 201 === $response_code ) {
    // success
}

No caso dos endpoints de criação e atualização do AffiliateWP, requisições bem-sucedidas retornarão respostas com o código de status 201. Para requisições de exclusão bem-sucedidas, os códigos de resposta serão o padrão 200.

Respostas enviadas para requisições de exclusão bem-sucedidas também incluirão um par chave:valor deleted: true, juntamente com uma cópia do objeto anterior:

{
  "deleted": true,
  "previous": {
    "affiliate_id": 35,
    "user_id": 11,
    "rate": "",
    "rate_type": "",
    "payment_email": "[email protected]",
    "status": "active",
    "earnings": 0,
    "unpaid_earnings": 0,
    "referrals": 0,
    "visits": 0,
    "date_registered": "2024-01-31 07:31:05",
    "id": 35
  }
}

Agora que cobrimos como criar requisições e analisar respostas, vamos ver como criar uma requisição de criação de afiliado, em seguida, examinar e prosseguir com a análise das informações recuperadas em caso de sucesso:

$request_url = add_query_arg( array( 
   'user_id' => 5 ), 

'https://alfsflowersandgifts.com/wp-json/affwp/v1/affiliates' );

// Send the request, storing the return in $response.
$response = wp_remote_post( $request_url, array(
    'headers' => array(
        'Authorization' => 'Basic hash_value'
    )
) );

// Check for the requisite response code. If 201, retrieve the response body and continue.
if ( 201 === wp_remote_retrieve_response_code( $response ) ) {
    $body = wp_remote_retrieve_body( $response );
    // do something successful
} else {
    // maybe display an error message
}

Perguntas Frequentes

---

É isso! O add-on REST API Extended para AffiliateWP oferece aos desenvolvedores uma ferramenta poderosa para gerenciar afiliados, referências, pagamentos, criativos e visitas programaticamente. Ao habilitar operações CRUD completas, este add-on abre uma gama de possibilidades para integrar o AffiliateWP com sistemas externos, automatizar processos e personalizar o gerenciamento de afiliados para atender a necessidades específicas.