Integração para ferramentas de Fidelização / Cashback

Crie um Token de Integração, clicando no botão no canto superior direito. 

Será criado um Token, vincule-o ao seu usuário e clique em “Criar”. 

*Não é necessário colocar uma data para expiração. 

Após, busque o channelCode do canal, clicando no menu lateral na área de Configurações / Canais

Onde irá encontrar o código do canal.

Fazendo as primeiras requisições

Com seu token e channelCode em mãos, já é possível fazer as primeiras requisições, abaixo vou demonstrar como fazer.

Observações:  

• Cada lojista novo que for integrar terá um Token e ChannelCode diferente, isso precisa ser dinâmico dentro de sua integração
• Abaixo coloquei os exemplos de channelCode e token na URL para facilitar, porém, por segurança, é recomendado enviar via Header da requisição.

1- API POST de Cupons, características: 

• A API de Cupons permite criar cupons personalizados com diversas opções, atendendo a diferentes necessidades promocionais.

Características dos Cupons:

• Obrigatório: Todos os cupons são de uso único.
• Disponível:
  • Tipos de desconto:
    • Valor fixo.
    • Porcentagem.
    • Frete grátis.
• Em breve:
  • Criação de cupons cumulativos.
  • Cupons exclusivos para a primeira compra.

---

Criar Cupom - POST

Endpoint:

https://api.uoou.com.br/api/v1/promotions/coupons/simple/new?channelCode=integracoes_uoou&token=abc123xyzExemploghi012jkl345mno678pqr901stu234vwx

 

Exemplo de Requisição CURL:

Exemplo documentação oficial.

Opções de Descontos e Benefícios Disponíveis

É possível enviar as seguintes opções na requisição:

1- orderDiscount:

• Desconto fixo aplicado no pedido.
• Exemplo: "orderDiscount": 10.00
  • Resultado: R$ 10,00 de desconto no valor total do pedido.

2- orderPercentageDiscount:

• Desconto percentual aplicado no pedido.
• Exemplo: "orderPercentageDiscount": 15
  • Resultado: 15% de desconto no valor total do pedido.

3- freeShipping:

• Define se o cliente terá frete grátis.
• Exemplo: "freeShipping": true
  • Resultado: O frete será gratuito para o cliente.
• Pode-se enviar true (ativado) ou false (desativado).

Essas ações podem ser combinadas para criar cupons personalizados que atendam às necessidades promocionais específicas.

Detalhamento dos campos

 

---

2- API GET de Cupons 

A API GET de Cupons permite consultar informações detalhadas sobre os cupons criados, incluindo dados básicos e informações opcionais sobre o status de uso.

Endpoint para retornar todos os cupons: 

https://api.uoou.com.br/api/v1/promotions/coupons/?channelCode=integracoes_uoou&token=abc123xyzExemploghi012jkl345mno678pqr901stu234vwx 

Como usar: 

Envie uma requisição GET para o endpoint acima, e você receberá uma resposta com todos os cupons disponíveis, incluindo informações opcionais sobre seu status de utilização. Lembre-se de usar o seu Token e channelCode no Header da requisição.

Além de poder listar todos os cupons, também é possível buscar um cupom pelo ID ou pelo código.

2.1- API GET de Cupons (por ID)

Endpoint:

https://api.uoou.com.br/api/v1/promotions/coupons/OWwzTXlHYjg

2.2- API GET de Cupons (por Código)

Endpoint:

https://api.uoou.com.br/api/v1/promotions/coupons/CUPOMSTARK

Exemplo de resposta:

---

3- API GET de Pedidos

Permite consultar informações detalhadas dos pedidos realizados na plataforma, com diversas opções de filtros e dados retornados. É possível:

• Filtrar pedidos por data de conclusão ou status atual.
• Retornar valores como frete, subtotal dos produtos, descontos aplicados e valor total do pedido.
• Obter dados do cliente, incluindo ID, CPF ou CNPJ, e outras informações relevantes.
• Consultar o cupom de desconto utilizado na compra (caso aplicável).

Mais detalhes sobre este endpoint na documentação oficial.

Endpoint: https://api.uoou.com.br/api/v1/orders/ 

3.1- GET de Pedidos - Exemplo filtrando por data:

Endpoint: https://api.uoou.com.br/api/v1/orders/?criteria[completedAtFrom]=2024-01-01&criteria[completedAtTo]=2024-07-19

 

3.2- GET de Pedidos - Exemplo filtrando por data status do pedido:

Endpoint: https://api.uoou.com.br/api/v1/orders/?criteria[completedAtFrom]=2024-01-01&criteria[completedAtTo]=2024-07-19&criteria[state][]=confirmed&&criteria[state][]=pending 

A API GET de Pedidos também permite filtrar os pedidos com base em datas e múltiplos status simultaneamente, oferecendo maior flexibilidade para análises específicas.

• Filtro por data: Você pode definir um intervalo de tempo para buscar pedidos concluídos, utilizando os parâmetros completedAtFrom e completedAtTo.
• Filtro por status do pedido: É possível consultar diversos status de uma única vez, como confirmed, pending, entre outros, especificando o campo state[].
• A documentação da API fornece a lista completa de status disponíveis para uso no filtro.

Exemplo de resposta de GET de Pedidos:

Algumas das informações importantes que podem ser obtidas no GET de Pedidos

As informações do cliente estão disponíveis em cada pedido exibido na listagem. Os principais dados incluídos são:

• ID do cliente: Identificador único do cliente.
• E-mail: Endereço de e-mail associado ao cliente.
• Nome completo: Incluindo o primeiro nome (first_name) e sobrenome (last_name).
• Data de nascimento: Data de nascimento do cliente (birthday).
• Gênero: Gênero do cliente (gender).
• CPF ou CNPJ: Identificação fiscal do cliente exibida no campo identity.
• Telefone e celular: Contatos do cliente.
• Situação: Status da conta do cliente (situation).

Exemplo:

Endpoint: https://api.uoou.com.br/api/v1/orders/?criteria[completedAtFrom]=2024-01-01&criteria[completedAtTo]=2024-11-25&criteria[customerQuery]=093.722.390-54 

Esse endpoint permite buscar pedidos específicos com base no CPF, CNPJ ou e-mail do cliente. Além disso, é possível combinar o filtro com um intervalo de datas para refinar os resultados. Isso facilita identificar pedidos associados a um cliente em particular. 

No exemplo do endpoint, os seguintes filtros foram utilizados:

1. criteria[completedAtFrom]=2024-01-01
   Filtra os pedidos cuja data de conclusão seja a partir de 01/01/2024.

2. criteria[completedAtTo]=2024-11-25
   Filtra os pedidos cuja data de conclusão seja até 25/11/2024.

3. criteria[customerQuery]=093.722.390-54
   Filtra os pedidos com base no CPF, CNPJ ou e-mail do cliente informado. No caso do exemplo, o filtro está utilizando o CPF 093.722.390-54.

Esses filtros combinados retornam pedidos concluídos em um intervalo de datas específico e relacionados a um cliente identificado pelo dado fornecido.

3.4- GET Pedidos - Retornar Cupom Utilizado na Compra

No endpoint de GET Pedidos, dentro do campo adjustments, é possível verificar se um cupom de desconto foi utilizado na compra.

• Quando um cupom é utilizado, as informações sobre ele são exibidas no objeto custom_origin, incluindo:

  • Nome e descrição do cupom.
  • Período de validade (starts_at e ends_at).
  • Informações de uso, como se o cupom é exclusivo, se está relacionado a produtos promocionais e o limite de uso.
  • Valores de desconto e prioridade do cupom.

• Caso nenhum cupom tenha sido utilizado, o campo custom_origin será null.

Esse recurso é útil para rastrear e analisar os descontos aplicados em cada pedido.

4. GET Pedidos - Retornar Cupom Utilizado na Compra

A API GET de Clientes permite realizar diversas consultas utilizando diferentes filtros para facilitar a busca e organização dos dados dos clientes. Confira as principais formas de uso:

1. Listar todos os clientes:

   • Endpoint: https://api.uoou.com.br/api/v1/customers/
   • Retorna todos os clientes cadastrados no sistema sem aplicar nenhum filtro.

1. Filtrar por Data de Criação:

   • Endpoint:
     https://api.uoou.com.br/api/v1/customers/?criteria[createdAtFrom]=2024-01-01&criteria[createdAtTo]=2024-11-25
   • Permite listar clientes cadastrados dentro de um período específico (os parâmetros createdAtFrom e createdAtTo são opcionais).

1. Filtrar por ID:

   • Endpoint:
     https://api.uoou.com.br/api/v1/customers/OUZuS3ptMzhsZz09
   • Retorna os dados de um cliente específico ao passar o ID diretamente na URL.

1. Filtrar por CPF/CNPJ:

   • Endpoint:
     https://api.uoou.com.br/api/v1/customers/?criteria[query]=093.722.390-54
   • Busca clientes utilizando CPF/CNPJ formatado com pontuação.

1. Busca multifuncional (CPF/CNPJ, E-mail ou Nome):

   • O campo criteria[query] pode ser usado para buscar clientes com base em CPF/CNPJ, endereço de e-mail ou nome.

Dica:

A consulta por criteria[query] é bastante versátil e pode facilitar a localização de clientes utilizando diferentes identificadores.

Exemplo de resposta:

Para mais informações sobre esses e outros filtros, consulte a documentação oficial.

Desejamos a você excelente integração!
Caso tenha alguma dúvida ou precise de suporte em qualquer etapa do processo, nossa equipe está à disposição para ajudar.