API REST de serviços
Em seguida, é especificada a API de serviços adicionais do Tuidd, que será consumida pelos provedores de serviços em seus sites ou aplicativos.
Eles são os serviços adicionais para o serviço de autenticação de um usuário, cuja especificação pode ser consultada em API REST de autenticação . Detalhadamente:
-
Micropagamentos
-
Publicidade
-
Pesquisas
-
Cupons
-
Notificações
Esta lista não é final e novos serviços podem ser adicionados no futuro.
Os serviços são consumidos através de um ponto de acesso comum. Dependendo da configuração enviada, é o serviço que será executado.
Requisito
Método HTTP:
POST
URI:
service
Exemplo:
POST https://idgw.tuidd.com/service
Headers:
|
Header |
Valor |
Obrigatório |
Descrição |
|
Authorization |
Bearer $pass |
Autorização |
Base64( client_id:client_secret ) obtido no Discovery. Ver API REST de autenticação . |
|
Content-type |
Application/ json |
Obrigatório |
Corpo:
|
Field |
Digite |
Obrigatório |
Descrição |
|
service_token |
String |
Obrigatório |
UUID recebido pela API de autenticação. Para certos serviços, pode ser um token específico para o site ou empresa.< |
|
seq_num |
Int |
Obrigatório |
É usado no caso de uma transação requer o envio de mais de uma mensagem para o usuário. Leva valores de 0 ??? 1000. O primeiro valor é ramdom, o seguinte sequencial. |
|
state |
String |
Obrigatório |
Seqüências de caracteres definidas pelo provedor de serviços, como um valor de contexto para identificar uma transação após o recebimento de uma notificação (consulte Notificação de serviço ). |
|
notification_uri |
String |
Condicional |
URL em que as notificações são recebidas (consulte Notificação de serviço ). Só é necessário para serviços de tipo: pagamento, notificação . Ele deve corresponder ao URL de retorno, configurado no site de administração do Tuidd. |
|
login_hint |
String |
Obrigatório |
Diz ao servidor qual ID do destinatário do serviço. O formato é o seguinte: PCR:<valor del PCR> Exemplo: PCR: d5f38a8fcc52e931d4fb4da47b2f2bb0 |
|
service_type |
String |
Obrigatório |
Tipo de serviço a consumir. Os valores possíveis são: advertisement : Publicidade notification : Notificação payment : pagamento. survey : Pesquisas coupon : Cupão. |
|
service_info |
Objeto |
Obrigatório |
Objeto JSON com os detalhes do serviço a ser consumido. Ver Definição de Objetos de Serviço . |
|
display |
String |
Opcional |
Indica como as telas com as informações de serviço serão mostradas ao usuário: empurrar : uma mensagem será enviada ao PUSH ao usuário, de acordo com o canal definido pelo operador. url_redirect : um redirecionamento será feito para o usuário em uma página WEB |
|
constraints |
Arreglo |
Opcional |
Indica um conjunto de restrições ou condições forçadas que o serviço terá que levar em conta ao executar. A lista de valores possíveis que esse campo pode assumir depende de cada serviço. Exemplo: ["no-repeat", "force-filter", ...] |
Responder
Um código de resposta HTTP é retornado, dependendo do resultado, conforme definido em Códigos de Resposta .
Além disso, informações no formato JSON com uma estrutura comum a todos os serviços estão incluídas no corpo:
|
Field |
Digite |
Obrigatório |
Descrição |
|
status |
Objeto |
Obrigatório |
Objeto composto com as informações de status. Veja a definição do objeto status . |
|
service_id |
Int |
Obrigatório |
ID do serviço consumido. |
|
transaction_id |
String |
Obrigatório |
Identificação da transação na plataforma do MCG. |
|
seq_num |
Int |
Obrigatório |
Valor de 0-1000. É o mesmo último no requisito. |
|
url_redirect |
String |
Opcional |
É a URL para a qual o usuário será redirecionado para mostrar as telas de serviço. |
Quando um serviço que gera um processo assíncrono é consumido (por exemplo: Micropayment), o provedor gera um requisito para a plataforma por meio dessa API de serviço e um ID de transação é retornado ( transaction_id ).
Quando o processo do lado do servidor é concluído, de forma assíncrona, a plataforma do provedor é notificada de que a transação terminou e o status da transação. Para fazer isso, ele é enviado como um tipo JSON para o ponto de extremidade de notificações indicado pelo provedor na solicitação de serviço original, no campo notification_uri .
Em caso de falha ao receber a notificação (sem resposta), ela será tentada novamente apenas uma vez em 2 minutos e depois descartada. No caso de receber qualquer outra resposta de erro, ela não será tentada novamente.
Requisito
Método HTTP:
POST
Endpoint:
notification_uri passou a exigência de consumo de serviço
Headers:
|
Header |
Valor |
Obrigatório |
Descrição |
|
Autorization |
Bearer $ pass |
Obrigatório |
$pass = base64(<client_id>:< client_secret>) |
|
Content-type |
Application/json |
Obrigatório |
|
Corpo:
|
Field |
Digite |
Obrigatório |
Descrição |
|
status |
String |
Obrigatório |
Strings definidas pelo provedor de serviços, como um valor de contexto transmitido no requisito de serviço original. |
|
transaction_id |
String |
Obrigatório |
Identificação da transação na plataforma do MCG. |
|
service_type |
Int |
Obrigatório |
Tipo de serviço consumido. Os valores possíveis são: publicidade : Publicidade notificação : Notificação pagamento : pagamento. pesquisa : Pesquisas cupão : Cupão autenticação : Autenticação |
|
status |
Objeto |
Obrigatório |
Detalhe do estado de conclusão do processo. Ver em Definição de Objetos Gerais . |
|
notification_data |
Objeto |
Obrigatório |
Resposta específica do serviço consumido. |
Responder
Um código de resposta HTTP é retornado, sem qualquer informação adicional. Ver Códigos de resposta .
Códigos de Resposta
|
Code |
Status |
Descrição |
|
200 |
Ok |
Código de resposta bem-sucedido para uso geral. É o código mais comum. É usado para indicar o sucesso da operação. |
|
400 |
BAD REQUEST |
Erro geral quando um estado inválido é gerado, processando a solicitação. Por exemplo, erros em validações de domínio, falta de informações obrigatórias, etc. |
|
401 |
NÃO AUTORIZADO |
Erro gerado quando o token de autenticação não foi encontrado ou o token de autenticação é inválido ou as credenciais client_id: client_secret são inválidas. |
|
500 |
ERRO DO SERVIDOR INTERNO |
Erro inesperado no servidor. Possivelmente você deve tentar novamente a operação em outro momento e, em caso de persistência do erro, entre em contato com o suporte da plataforma. |
A seguir, descrevemos os objetos JSON que geralmente são manipulados na plataforma:
status
|
Field |
Digite |
Obrigatório |
Descrição |
|
String |
Obrigatório |
Indica se a operação foi OK ou não. Valores possíveis: OK NOK |
|
|
Objeto |
Obrigatório |
Detalhe do erro |
error_data
|
Field |
Digite |
Obrigatório |
Descrição |
|
String |
Obrigatório |
Nome do identificador do erro |
|
|
String |
Obrigatório |
Descrição do erro |
A seguir, descrevemos os objetos JSON que representam os dados dos serviços.
Em todos os casos, existem duas maneiras de passar os detalhes de um serviço:
1. Indicando o identificador de um serviço carregado na plataforma pelo provedor de serviços.
2. Indicando todos os parâmetros que o serviço terá.
anúncio
Representa um anúncio.
Os campos são:
|
Field |
Digite |
Obrigatório |
Descrição |
|
service_id |
String |
Obrigatório |
É o identificador de um anúncio registrado pelo provedor. |
|
title |
String |
Opcional |
Título da publicidade com no máximo 32 caracteres. |
|
message |
String |
Opcional |
Texto da mensagem publicitária. Não maior que 166 caracteres. |
|
link |
String |
Opcional |
URL do site para redirecionar o usuário no caso de clicar na publicidade. |
|
link_text |
String |
Opcional |
Texto que aparece no botão que leva o usuário ao URL configurado no parâmetro "link". |
|
image_link |
String |
Opcional |
URL da imagem que aparecerá no anúncio. Deve entrar em URL Encoding. Dependendo do canal, pode ou não estar disponível. |
|
redirect_link |
String |
Opcional |
URL da imagem que aparecerá no anúncio. Deve ir na codificação de URL. |
|
source |
String |
Opcional |
Restringir a origem da publicidade, para indicar se você deseja receber sua própria publicidade ou terceiros. Os valores possíveis são:
Se este campo não for especificado, o valor padrão é any. |
pagamento
É o corpo da solicitação de pagamento que será enviada ao usuário:
|
Field |
Digite |
Obrigatório |
Descrição |
|
price |
Int |
Obrigatório |
Valor à pagar. |
|
detail |
String |
Obrigatório |
Uma breve descrição do que está sendo pago. |
|
concept |
String |
Obrigatório |
O conceito que gerou o pedido de pagamento. |
|
currency |
String |
Obrigatório |
Códigos da moeda com a qual opera no formato ISO 4217 alpha-3. Exemplo: USD |
notificação
Representa uma notificação.
Os campos são:
|
Field |
Digite |
Obrigatório |
Descrição |
|
service_id |
String |
Obrigatório |
É o identificador da notificação registrada pelo provedor. |
|
title |
String |
Opcional |
Título da notificação com menos de 32 caracteres. |
|
message |
String |
Opcional |
Conteúdo da notificação. Não maior que 166 caracteres. |
|
need_confirm |
String |
Opcional |
Indica se deve ou não receber confirmação do usuário. Valores possíveis: "true" / "false" |
|
confirm_text |
String |
Opcional |
Texto do botão de confirmação que será mostrado ao usuário. |
|
link |
String |
Opcional |
Link para onde você deseja direcionar o usuário em caso de aceitar a notificação. Dependendo do canal, esse link pode fazer parte da mensagem |
cupão
Representa um cupom de benefício:
|
Field |
Digite |
Obrigatório |
Descrição |
|
service_id |
String |
Obrigatório |
É o identificador de um cupom registrado pelo provedor. |
|
title |
String |
Opcional |
Título do cupom com mais de 32 caracteres. |
|
menssage |
String |
Opcional |
Texto da mensagem do cupom. Não maior que 166 caracteres. |
|
coupon_type |
String |
Opcional |
Indica o tipo de cupom a ser usado. Os valores possíveis são: qr_code : o que deve ser enviado ao usuário é um código QR. pin_code : o que deve ser enviado ao usuário é um PIN. Os pinos gerados são alfanuméricos.
|
|
link |
String |
Opcional |
URL do site onde você deseja redirecionar o usuário em caso de clicar no cupom. |
|
image_link |
String |
Opcional |
URL da imagem que aparecerá no cupom. Deve ir na codificação de URL. Dependendo do canal, essa imagem pode ou não estar disponível. |
|
action |
String |
Obligatorio |
Indique o tipo de ação: gerar: gerar um novo cupom. consumir: consumir um cupom |
|
coupon_code |
String |
Condicional |
Indica o PIN ou o código QR que o provedor deseja consumir. É obrigatório se “action” = “consume” |
pesquisa
Representa uma pesquisa Os campos são:
|
Field |
Digite |
Obrigatório |
Descrição |
|
service_id |
String |
Condicional |
É o identificador de uma pesquisa registrada pelo provedor. |
Nota: Para este serviço, ao contrário dos outros, você não pode enviar questionários que não tenham sido previamente registrados.