unidays php
v1.2.2 Bug fix
Esta é a biblioteca PHP para integração com UNiDAYS. Isso deve ser usado para integrações codificadas e sem código. A documentação a seguir fornece descrições das implementações e exemplos.
Como usar este código?
Rastreamento direto
Verificação sem código
Contribuindo
Aqui está uma descrição de todos os parâmetros disponíveis. Quais deles você nos fornece dependem do contrato acordado.
| Parâmetro | Descrição | Tipo de dados | Exemplo |
|---|---|---|---|
| ID do parceiro | Seu PartnerId conforme fornecido pela UNiDAYS. Se você opera em várias regiões geográficas, PODE ter um PartnerId diferente para cada região | Guia codificado em Base64 | XaxptFh0sK8Co6pI== |
| ID da transação | Um ID exclusivo para a transação em seu sistema | Corda | Pedido123 |
| Moeda | O código de moeda ISO 4217 | Corda | GBP |
Ter Code ou MemberID como parâmetro também é obrigatório:
| Parâmetro | Descrição | Tipo de dados | Exemplo |
|---|---|---|---|
| Código | O código de desconto UNiDAYS usado | Corda | ABC123 |
| ID do membro | A ser fornecido apenas se você estiver usando uma integração sem código | Guia codificado em Base64 | 0LTio6iVNaKj861RM9azJQ== |
Observe que qualquer uma das propriedades a seguir cujo valor é desconhecido deve ser omitida das chamadas. Qual dos seguintes valores você nos fornecer dependerá do contrato acordado.
| Parâmetro | Descrição | Tipo de dados | Exemplo |
|---|---|---|---|
| Total do pedido | Valor monetário total pago, formatado com 2 casas decimais | Decimal | 209,00 |
| ItensUNiDAYSDesconto | Valor monetário total do desconto UNiDAYS aplicado sobre o valor bruto do item ItemsGross , formatado com 2 casas decimais | Decimal | 13h00 |
| Imposto sobre itens | Valor monetário total do imposto aplicado aos itens, formatado com 2 casas decimais | Decimal | 34,50 |
| FreteBruto | Valor monetário total do custo de envio, antes de qualquer desconto ou imposto de envio aplicado, formatado com 2 casas decimais | Decimal | 5h00 |
| FreteDesconto | Valor monetário total do desconto de frete (UNiDAYS ou outro) aplicado ao pedido, formatado com 2 casas decimais | Decimal | 3h00 |
| Itens Bruto | Valor monetário total dos itens, incluindo impostos, antes da aplicação de quaisquer descontos, formatado com 2 casas decimais | Decimal | 230,00 |
| ItensOutrosDescontos | Valor monetário total de todos os descontos não UNiDAYS aplicados a ItemsGross , formatado com 2 casas decimais | Decimal | 10h00 |
| Porcentagem de desconto UNiDAYS | O desconto UNiDAYS aplicado, em forma percentual, formatado com 2 casas decimais | Decimal | 10h00 |
| Novo Cliente | O usuário é um cliente novo (em vez de antigo) para você? | Booleano | verdadeiro ou falso |
Aqui está um exemplo de cesta com os campos relacionados aos parâmetros de rastreamento UNiDAYS,
| Item | Bruto | Desconto UNiDAYS | Outro desconto | Imposto | Total Líquido | Total de linhas |
|---|---|---|---|---|---|---|
| Sapato | 100,00 | 0,00 | 0,00 | 16,67 | 83,33 | 100,00 |
| Camisa | 50,00 | 5h00 | 0,00 | 7h50 | 37,50 | 45,00 |
| Jeans | 80,00 | 8h00 | 10h00 | 10h33 | 51,67 | 62,00 |
| Totais | 230,00 | 13h00 | 10h00 | 34,50 | 172,50 | 207,00 |
| Envio | 5h00 | |||||
| Desconto de envio | 3h00 | |||||
| Total do pedido | 209,00 |
Abaixo estão as três opções para implementar sua integração. Esses exemplos abrangem integrações codificadas e sem código (consulte o PDF de análise ao vivo para obter detalhes) e incluem todos os parâmetros opcionais. Eles pretendem ser uma diretriz para implementação.
Este método retorna um URL que você pode usar para chamar a API.
É um requisito obrigatório que todos os URLs do servidor estejam assinados. Isso significa que você deve passar a chave de assinatura fornecida pelo UNiDAYS como um dos argumentos. A chave de assinatura é um GUID codificado em Base64. Este endpoint aceita solicitações GET e POST .
O método para obter a URL para fazer uma solicitação de servidor para servidor é create_server_url($key) . Para implementar esse método, primeiro você precisa usar DirectTrackingDetailsBuilder para criar um objeto de rastreamento direto com as propriedades que deseja enviar para nós. Mais detalhes sobre este construtor podem ser encontrados aqui.
Depois que o objeto contendo os detalhes que você precisa nos enviar for criado, crie um auxiliar Tracking, fornecendo esses detalhes como um argumento new TrackingHelper($directTrackingDetails) e chame ->create_server_url($key) onde $key é a chave fornecida a você por UNiDAYS.
Um URL será retornado para você, que poderá ser usado para chamar nossa API. Se for bem-sucedida, uma resposta com um código de status 204 No Content será retornada. Isso funcionará para solicitações POST e GET .
<?php
use Unidays ;
// UNiDAYS will provide your partnerId and key
$ partnerId = " somePartnerId " ;
$ key = " someSigningKey " ;
$ details = new DirectTrackingDetailsBuilder ( $ partnerId , ' order123 ' , ' GBP ' );
$ details -> withOrderTotal ( 209.00 );
$ details -> withItemsUnidaysDiscount ( 13.00 );
$ details -> withCode ( ' UNI123 ' );
$ details -> withItemsTax ( 34.50 );
$ details -> withShippingGross ( 5.00 );
$ details -> withShippingDiscount ( 3.00 );
$ details -> withItemsGross ( 230.00 );
$ details -> withItemsOtherDiscount ( 10.00 );
$ details -> withUnidaysDiscountPercentage ( 10.00 );
$ details -> withNewCustomer ( true );
$ directTrackingDetails = $ details -> build ();
$ helper = new TrackingHelper ( $ directTrackingDetails );
$ url = $ helper -> create_server_url ( $ key );Isso também é conhecido como nossa integração cliente-servidor. Este método retorna um URL que pode ser colocado em um elemento de script em sua página de pós-pagamento/sucesso do pedido para chamar a API.
É uma opção para criar uma URL assinada para sua solicitação de script. Para fazer isso, você precisará nos enviar a chave de assinatura fornecida pelo UNiDAYS como um dos argumentos para o método assinado.
$url = $helper->create_signed_script_url($key);
em vez de
$url = $helper->create_script_url();
O método para obter o URL para fazer uma solicitação de cliente para servidor é create_script_url() ou create_signed_script_url($key) se você optou por retornar um URL assinado. Para implementar esse método, primeiro você precisa usar DirectTrackingDetailsBuilder para criar um objeto de rastreamento direto com as propriedades que deseja enviar para nós. Mais detalhes sobre este construtor podem ser encontrados aqui.
Depois que o objeto contendo os detalhes que você precisa nos enviar for criado, crie um auxiliar Tracking, fornecendo esses detalhes como um argumento new TrackingHelper($directTrackingDetails) e chame ->create_script_url() para um URL não assinado, ou ->create_signed_script_url($key) , onde $key é a chave fornecida a você por UNiDAYS.
Um URL será retornado a você, que pode ser colocado em um elemento de script em sua página de pós-pagamento/sucesso do pedido para chamar a API. Se for bem-sucedido, uma resposta com um código de status 200 OK será retornada. Isso funcionará apenas para solicitações GET .
O exemplo abaixo é uma solicitação de um URL de script não assinado.
<?php
use Unidays ;
// UNiDAYS will provide your partnerId and key
$ partnerId = " somePartnerId " ;
$ details = new DirectTrackingDetailsBuilder ( $ partnerId , ' order123 ' , ' GBP ' );
$ details -> withOrderTotal ( 209.00 );
$ details -> withItemsUnidaysDiscount ( 13.00 );
$ details -> withCode ( ' UNI123 ' );
$ details -> withItemsTax ( 34.50 );
$ details -> withShippingGross ( 5.00 );
$ details -> withShippingDiscount ( 3.00 );
$ details -> withItemsGross ( 230.00 );
$ details -> withItemsOtherDiscount ( 10.00 );
$ details -> withUnidaysDiscountPercentage ( 10.00 );
$ details -> withNewCustomer ( true );
$ directTrackingDetails = $ details -> build ();
$ helper = new TrackingHelper ( $ directTrackingDetails );
$ url = $ helper -> create_script_url ();As chamadas para o Cliente de Rastreamento são semelhantes à criação de URL do servidor, mas em vez de retornar uma URL, UNiDAYS envia a solicitação e retorna uma resposta.
É obrigatório que todas as chamadas do Cliente de Rastreamento sejam fornecidas com uma chave, pois as solicitações enviadas pela UNiDAYS são assinadas.
Para implementar esse método, primeiro você precisa usar DirectTrackingDetailsBuilder para criar um objeto de rastreamento direto com as propriedades que deseja enviar para nós. Mais detalhes sobre este construtor podem ser encontrados aqui.
Depois que o objeto contendo os detalhes que você precisa nos enviar for criado, crie uma instância do cliente de rastreamento, fornecendo esses detalhes como parâmetro, junto com a chave de assinatura que UNiDAYS forneceu a você new TrackingClient($directTrackingDetails, $key) e ligue ->sendRequest() .
Um HttpResponseMessage é retornado. Se for bem-sucedida, a resposta deverá ter um código de status 204 Sem conteúdo.
O exemplo abaixo configura alguns detalhes de rastreamento direto, chama sendRequest no cliente e ecoa o código de resposta no console.
<?php
use Unidays ;
// UNiDAYS will provide your partnerId and key
$ partnerId = " somePartnerId " ;
$ key = " someSigningKey " ;
$ details = new DirectTrackingDetailsBuilder ( $ partnerId , ' order123 ' , ' GBP ' );
$ details -> withOrderTotal ( 209.00 );
$ details -> withItemsUnidaysDiscount ( 13.00 );
$ details -> withCode ( ' UNI123 ' );
$ details -> withItemsTax ( 34.50 );
$ details -> withShippingGross ( 5.00 );
$ details -> withShippingDiscount ( 3.00 );
$ details -> withItemsGross ( 230.00 );
$ details -> withItemsOtherDiscount ( 10.00 );
$ details -> withUnidaysDiscountPercentage ( 10.00 );
$ details -> withNewCustomer ( true );
$ directTrackingDetails = $ details -> build ();
$ client = new TrackingClient ( $ directTrackingDetails , $ key );
$ response = $ client -> sendRequest ();
echo $ response -> code ; UNiDAYS fornece uma configuração de terminal de teste do objeto TrackingHelper .
O objeto TrackingHelper, configurado no modo de teste, adicionará um parâmetro extra ( &Test=True ) à URL que é retornada ou enviada para você.
<?php
use Unidays ;
// UNiDAYS will provide your partnerId and key
$ partnerId = " somePartnerId " ;
$ key = " someSigningKey " ;
$ details = new DirectTrackingDetailsBuilder ( $ partnerId , ' order123 ' , ' GBP ' );
$ details -> withOrderTotal ( 209.00 );
$ details -> withItemsUnidaysDiscount ( 13.00 );
$ details -> withCode ( ' UNI123 ' );
$ details -> withItemsTax ( 34.50 );
$ details -> withShippingGross ( 5.00 );
$ details -> withShippingDiscount ( 3.00 );
$ details -> withItemsGross ( 230.00 );
$ details -> withItemsOtherDiscount ( 10.00 );
$ details -> withUnidaysDiscountPercentage ( 10.00 );
$ details -> withNewCustomer ( true );
$ directTrackingDetails = $ details -> build ();
// Pass in an aditional argument of true to instantiate the TrackingHelper object in test mode
$ helper = new TrackingHelper ( $ directTrackingDetails , true );
// The url generated will now contain the appended $Test=True parameter, this url will call our test endpoint
$ url = $ helper -> create_server_url ( $ key );O objetivo do construtor é tornar simples e intuitivo a construção de qualquer solicitação de rastreamento para UNiDAYS.
Os argumentos no construtor são os parâmetros obrigatórios:
$directTrackingDetails = new DirectTrackingDetailsBuilder($partnerId, $currency, $transactionId)
Existem vários métodos disponíveis para construir as informações que você deseja nos enviar, que podem ser encadeadas conforme o exemplo. Eles correspondem aos parâmetros no início deste documento.
base64 encoded guid )string )decimal )decimal )decimal )decimal )decimal )decimal )decimal )decimal )bool )Encadeie apenas os valores que você concordou contratualmente em fornecer. Não é um requisito usar todos os métodos.
A chamada final a ser encadeada é ->build() que cria o objeto.
<?php
use Unidays ;
$ details = new DirectTrackingDetailsBuilder ( ' somePartnerId ' , ' order123 ' , ' GBP ' );
$ details -> withOrderTotal ( 209.00 );
$ details -> withItemsUnidaysDiscount ( 13.00 );
$ details -> withCode ( ' UNI123 ' );
$ details -> withItemsTax ( 34.50 );
$ details -> withShippingGross ( 5.00 );
$ details -> withShippingDiscount ( 3.00 );
$ details -> withItemsGross ( 230.00 );
$ details -> withItemsOtherDiscount ( 10.00 );
$ details -> withUnidaysDiscountPercentage ( 10.00 );
$ details -> withNewCustomer ( true );
$ directTrackingDetails = $ details -> build ();Se você concordou em fornecer aos membros UNiDAYS uma experiência sem código, juntamente com o rastreamento direto, você também precisará implementar a 'API sem código', que o ajudará a analisar e validar o tráfego assinado que direcionamos para o seu site.
Primeiro chame o CodelessUrlVerifier com a chave fornecida por UNiDAYS new CodelessUrlVerifier($key) . Em seguida, chame o método verify_url_params($ud_s, $ud_t, $ud_h) com os valores para ud_s, ud_t e ud_h como argumentos.
| Parâmetro | Descrição | Tipo de dados | Comprimento máximo | Exemplo |
|---|---|---|---|---|
| ud_s | ID de estudante verificada pela UNiDAYS | Corda | 256 caracteres | Faça/faqh330SGgCnn4t3X4g== |
| ud_t | Carimbo de data e hora da solicitação | Corda | 64 bits | 1395741712 |
| ud_h | Assinatura hash dos outros dois parâmetros | Sequência Base64 | 256 caracteres | o9Cg3q2eVElZxYlJsEAQ== |
Se o método validar com êxito o hash da solicitação recebida, um DateTime para a solicitação será retornado; caso contrário, null será retornado.
<?php
use Unidays ;
// Your key as provided by UNiDAYS
$ key = " someSigningKey " ;
// Obtain parameters from the query string. Be sure to URL Decode them
$ ud_s = " Do/faqh330SGgCnn4t3X4g== " ;
$ ud_t = " 1395741712 " ;
$ ud_h = " i38dJdX+XLKuE4F5tv+Knpl5NPtu5zrdsjnqBQliJEJE4NkMmfurVnUaT46WluRYoD1/f5spAqU36YgeTMCNeg== " ;
$ verifier = new CodelessUrlVerifier ( $ key );
$ verifiedAt = $ verifier -> verify_url_params ( $ ud_s , $ ud_t , $ ud_h );Este projeto está configurado como um projeto de código aberto. Assim, se você tiver alguma sugestão de recursos, de melhoria do código em si, ou se tiver encontrado algum problema; você pode levantá-los e/ou sugerir mudanças na implementação.
Se você estiver interessado em contribuir para esta base de código, siga as diretrizes de contribuição. Contém guias sobre como contribuir diretamente e gerar solicitações de recursos ou relatórios de bugs. Siga nosso código de conduta ao realizar qualquer uma das ações acima.
