Skip to main content
Version: 1.0.0

API de Pontos

Autenticação​

Cada requisição à API ira incluir um token de autenticação configurada no sistema da Niara.

O Niara vai incluir este token no cabeçalho Authorization ao fazer requisições para seu endpoint assim:

Authorization: <token>

O token pode ser qualquer string mas recomendamos o formato JSON Web Token (JWT).

Fluxos​

Abaixo ilustramos o fluxo padrão, considerando sucesso em todas as operações.

1. Pesquisa de balanço​

  • Durante a experiência de compra no site podemos pedir a atualização do balanço. Erros nessa etapa podem impedir que o usuário realize o resgate já que o balanço é importante para interface mostrar de forma adequada as ações pro usuário.
  • Erros do servidor não vão ser mostrados para o usuário nesse fluxo.

2. Fluxo de Checkout​

2.1 Autorização​

  • Antes de iniciar o checkout vamos consultar o seu servidor para verificar se o usuário pode fazer a operação.
  • O resultado dessa operação é uma transação (identificada por um transactionId) que será usada nas próximas etapas.
  • No mínimo esperamos que o sistema valide o saldo do usuário com o valor enviado.
  • Erros 4XX serão mostrados para o usuário afim. Erros 5XX apresentarão uma mensagem padrão. Os dois impedem o usuário de fazer a compra com pontos.

2.1.1 Autorização com desafio​

  • Você pode indicar a necessidade do usuário responder um desafio. Entre os passos 6 e 7 você pode mandar a instrução por e-mail, whatsapp ou sms diretamente pro usuário. Exemplo: "Seu código de checkout é 12345"
  • Durante o processo de checkout (entre passo 8 e 9) nosso sistema vai apresentar uma caixa de diálogo para usuário inserir a informação. Por enquanto o sistema aceita apenas desafios númericos.

2.2 Commit​

  • Durante o processo de checkout vamos finalizar a transação enviando um comando de commit.
  • Caso tenha sido passado um desafio, esse será enviado para validação.
  • Erros 4XX serão mostrados para o usuário afim. Esse erro pode reverter outras etapas do processo: cancelar pagamentos com cartão e cancelar reservas por exemplo.
  • Erros 5XX não serão mostrados para o usuário final. O processo fica em um estado indefinido já que não sabemos o resultado da operação. Precisa ser feito alguma intervenção manual nessa compra.

2.3 Rollback​

  • Durante o processo de checkout o usuário pode se arrepender do resgate. Se ainda não foi chamado o commit vamos chamar o método de rollback para desbloquear e indicar o cancelamento da operação.
  • Erros 4XX serão mostrados para o usuário afim. Erros 5XX apresentarão uma mensagem padrão.
  • Os dois erros não vão permitir retentativa e o usuário deve começar a experiência novamente.

2.4 Estorno​

  • Depois do envio de commit o sistema pode estornar parcial ou totalmente o falor resgatado.
  • Erros 4XX serão mostrados para o usuário afim. Erros 5XX apresentarão uma mensagem padrão.
  • Pode haver retentativas da operação.
  • Atente para não permitir que estornos multiplos gerem um crédito extra ao usuário. Niara não vai garantir que o estorno não seja maior que o valor da operação.

2.4 Detalhes da Transação​

  • Em qualquer momento o Niara pode consultar a transação para verificar a sincronia dos dados ou atualizar as informações em caso de algum erro 5XX.

2.5 Detalhes da Reserva​

  • Durante o fluxo de commit será enviado o identificador da compra do usuário (orderId).
  • Você pode usar esse identificado e a api de notificação. para pegar mais detalhes sobre a compra.

3. Fluxo do Webhook​

3.1 Envio do URL de notificação​

  • Enviaremos ao seu sistema o URL do nosso webhook que será usado para receber notificações de eventos de mudança de nível de fidelidade.

3.2 Notificação de evento​

  • Em nosso webhook cujo o URL já foi enviado, receberemos o tier e value do usuário do programa de fidelidade.

Abaixo o fluxo do webhook ilustrado.

Authentication​

Cada requisição precisa incluir o token de autenticação no cabeçalho Authorization:

Authorization: <token>
Security Scheme Type:apiKey
Header parameter name:Authorization