Manual de Integração Assinaturas

(1)

Manual de Integração

Assinaturas

(2)

Índice

1. Ambiente de Testes ... 3

2. Token da Conta ... 3

3. Integração via API ... 4

3.1 Login via API ... 4

3.2 Criar Cobrança Recorrente... 6

3.3 Listar Assinatura ... 11

(3)

1. Ambiente de Testes

Para realizar as integrações, o TrayCheckout disponibiliza um ambiente de testes chamado Sandbox. Este

ambiente permite que sejam efetuadas todas as operações disponíveis em produção, com simulações sem

a necessidade de uso de dados reais.

Mesmo que você já possua uma conta no ambiente de produção, será necessário criar uma conta

específica para testes acessando

http://sandbox.traycheckout.com.br/criar-conta

.

Caso queira recuperar a senha, utilize a opção “Esqueci minha senha” acessando

http://checkout.sandbox.tray.com.br/session/login

.

2. Token da Conta

Para as integrações será necessário possuir o token da conta que será integrada.

Para obter esta informação, acesse o site

www.traycheckout.com.br

e clique no botão “Acesse sua conta”,

localizado no canto superior direito da página.

Informe seu e-mail e senha, e então terá acesso a sua conta.

(4)

3. Integração via API

A integração via API permite que o desenvolvedor utilize o TrayCheckout de uma forma transparente,

integrando com sua Loja Virtual, Aplicativo Mobile ou qualquer outro tipo de software, personalizando as

integrações com o usuário para melhor se adequar ao software existente.

3.1 Login via API

Para realizar qualquer tipo de consulta ou alteração por API. É necessário que faça um login através da API

de autenticação e utilize a SESSION retornada no XML.

Para esta integração, deverá ser feito uso da API a seguir:

Endereço de Integração

Ambiente de Testes http://api.sandbox.checkout.tray.com.br/v1/accesses/login_customer Ambiente de Produção http://api.checkout.tray.com.br/v1/accesses/login_customer

Protocolo Rest/HTTP

Os dados que devem ser enviados nessa API são:

Dados de Entrada

Obrigatório Formato / Tamanho Max Descrição

login Sim char (120) Email de acesso do Vendedor

password Sim char (10) Senha de acesso do Vendedor

Veja abaixo um exemplo de login:

</form>

Resposta da API

A API retorna a resposta em XML. No caso de sucesso, é retornado um nó

<data_response>

. No caso de

erro, é retornado um nó

<error_response>

. A primeira parte da resposta identifica se houve erro ou

sucesso através do nó

<message_response><message>

.

(5)

Exemplo de resposta com sucesso baseando no envio do exemplo acima:

<response> <message_response> <message>success</message> </message_response> <data_response> <name>Caue Fajoli</name> <email>[email protected]</email>

<session_id>863ab14956872571a7dffea1afc00122</session_id>

</data_response> </response>

Abaixo um detalhamento de cada nó do XML de resposta:

XML de Resposta

<response> Nó principal da resposta

<message_response> Nó que contém o resultado da resposta

<message_response>

<message>

Resposta sobre a solicitação Em caso de sucesso: sucess Em caso de erro: error

<data_response> Nó que contém os dados da resposta

<response> <data_response> <name> Nome da Conta <response> <data_response> <email> Email da Conta <response> <data_response> <session_id> ID de Sessão

A seguir um exemplo de um retorno com erro:

<response> <message_response> <message>error</message> </message_response> <error_response> <general_errors type="array"> <general_error> <code>017002</code>

<message>Email e/ou senha inválidos</message> </general_error>

</general_errors> </error_response> </response>

(6)

E o detalhamento de cada nó do XML de resposta:

XML de Resposta

<message_response>

<message>

<error_response> Nó contendo os erros encontrados

<error_response>

<general_errors>

Nó contendo os erros encontrados

<error_response> <general_errors>

<general_error>

Nó contendo o detalhamento de um erro

<response> <error_response> <general_errors> <general_error> <code> Código do erro <response> <error_response> <general_errors type="array"> <general_error> <message> Mensagem do erro

3.2 Criar Cobrança Recorrente

O TrayCheckout permite que seja criada cobranças recorrentes através de nossa API.

Para esta integração, deverá ser feito uso da API a seguir:

Endereço de Integração

Ambiente de Testes http://api.sandbox.checkout.tray.com.br/v1/billing_contracts/charge_recurrent Ambiente de Produção https://api.checkout.tray.com.br/v1/billing_contracts/charge_recurrent

Protocolo Rest/HTTP

Os dados que podem ser enviados nessa API são:

Dados de Entrada

token_account Sim char (15) Token de identificação da conta customer_name Não char (150) Nome do cliente que receberá a cobrança customer_email Sim char (150) E-mail do cliente que receberá a cobrança

(7)

day_expiration Sim int (11) Dia do vencimento da cobrança

date_expiration Sim date Data para vencimento da cobrança

dd/mm/aaaa

periodicity Sim int (11)

Periodicidade da cobrança Ex: 1 = cobrança mensal

6 = cobrança semestral

quantity Sim int (11) Quantidade de cobranças geradas

0 indica tempo indeterminado

price Sim decimal (10,2) Valor da cobrança

Ex: 500.00

source_register Não varchar (100) Parâmetro livre

utilizado para relatórios

*Caso o campo “day_expiration” seja preenchido, o campo “date_expiration” não é necessário e

vice-versa.

Veja abaixo um exemplo do envio de uma cobrança mensal no valor de R$ 500,00, durante um período de

12 meses e com o vencimento para o dia 20 de cada mês:

</form>

Resposta da API

A API retorna a resposta em XML. No caso de sucesso, é retornado um nó

<data_response>

. No caso de

erro, é retornado um nó

<error_response>

. A primeira parte da resposta identifica se houve erro ou

sucesso através do nó

<message_response><message>

.

Exemplo de resposta com sucesso baseando no envio do exemplo acima:

<message_response>

<message>success</message> </message_response> <data_response> <billing_contract> <id type="integer">4362</id> <name>1368791435</name> <customer_name>Chuck Norris</customer_name> <customer_email>[email protected]</customer_email> <seller_token>68b050ff82fe29c</seller_token> <day_expiration type="integer">20</day_expiration> <status_id type="integer">58</status_id> <status_name>Pendente</status_name>

(8)

<source_register>Criado por API</source_register> <billing_contract_token>9d30b3c246a68a487a35833e181095c6</billing_contract_token> <url_confirmation> http://checkout.tray.com.br/payment/billing/64e9ba070882d50cdde3c0f42d459ea2 </url_confirmation> <billing_contract_plans type="array"> <billing_contract_plan> <id type="integer">13770</id> <code>1368791435</code> <description>Suplementos</description> <periodicity type="integer">1</periodicity> <quantity type="integer">12</quantity> <price_setup type="decimal">0.0</price_setup> <price_discount type="decimal">0.0</price_discount> <price_due type="decimal">500.0</price_due> </billing_contract_plan> </billing_contract_plans> </billing_contract> </data_response> </response>

Abaixo um detalhamento de cada nó do XML de resposta:

XML de Resposta

<message_response>

<message>

<data_response>

<billing_contract>

Nó que contém os dados da cobrança

<response> <data_response> <billing_contract> <id> ID da cobrança <response> <data_response> <billing_contract> <name>

Dado gerado automaticamente pelo sistema

<response> <data_response> <billing_contract> <costumer_name> Nome do cliente <response> <data_response> <billing_contract> <costumer_email> Email do cliente

(9)

<response> <data_response> <billing_contract> <seller_token> Token do vendedor <response> <data_response> <billing_contract> <day_expiration>

Data de vencimento da cobrança

<response> <data_response> <billing_contract> <status_id> ID de status da cobrança <response> <data_response> <billing_contract> <status_name> Status da cobrança <response> <data_response> <billing_contract> <source_register>

Informação enviada no <source_register> de criação

<data_response> <billing_contract>

<billing_contract_token>

Token da cobrança gerada

<url_confirmation>

URL de confirmação e pagamento da cobrança

<billing_contract_plans>

Nó que contém os planos inclusos

<billing_contract_plans>

<billing_contract_plan>

Nó que contém os dados do plano

<response> <data_response> <billing_contract> <billing_contract_plans> <billing_contract_plan> <id> ID do plano <response> <data_response> <billing_contract> <billing_contract_plans> <billing_contract_plan> <code>

Dados gerados automaticamente pelo sistema

<response> <data_response> <billing_contract> <billing_contract_plans> <billing_contract_plan> <description> Descrição do plano

(10)

<response> <data_response> <billing_contract> <billing_contract_plans> <billing_contract_plan> <periodicity> Periodicidade do plano <response> <data_response> <billing_contract> <billing_contract_plans> <billing_contract_plan> <quantity>

Quantidade de vezes que será feita a cobrança

<response> <data_response> <billing_contract> <billing_contract_plans> <billing_contract_plan> <price_setup>

Valor de contratação do plano

<response> <data_response> <billing_contract> <billing_contract_plans> <billing_contract_plan> <price_discount>

Valor de desconto do plano

<response> <data_response> <billing_contract> <billing_contract_plans> <billing_contract_plan> <price_due> Valor do plano

A seguir um exemplo de um retorno com erro:

<message>Token inválido ou não encontrado</message> </general_error>

(11)

E o detalhamento de cada nó do XML de resposta:

XML de Resposta

<message_response>

<message>

<error_response> Nó contendo os erros encontrados

<error_response>

<general_error>

3.3 Listar Assinatura

Esse método é utilizado para listar as assinaturas relacionadas a uma determinada conta.

*Para sua utilização, é necessário possuir o parâmetro SESSION_ID que pode ser obtido com a API de Login

descrita no início do manual.

Para esta integração, deverá ser feito uso da API a seguir:

Endereço de Integração

Ambiente de Testes http://api.sandbox.checkout.tray.com.br/v1/billing_contracts/search Ambiente de Produção http://api.checkout.tray.com.br/v1/billing_contracts/search

(12)

Os dados que podem ser enviados nessa API são:

Dados de Entrada

session_id Sim char (120) Token de autenticação do Vendedor

name Não char(150) Nome da Assinatura

customer_email Não char(150) Email do Cliente

billing_contract_id Não int(11) ID da Assinatura

day_expiration Não int(11) Dia de Vencimento

status_id Não int(11) Status da Assinatura

Veja abaixo um exemplo de listagem de assinaturas de uma conta:

</form>

Resposta da API

A API retorna a resposta em XML. No caso de sucesso, é retornado um nó

<data_response>

. No caso de

erro, é retornado um nó

<error_response>

. A primeira parte da resposta identifica se houve erro ou

sucesso através do nó

<message_response><message>

.

Exemplo de resposta com sucesso baseando no envio do exemplo acima:

<response> <data_response> <billing_contracts type="array"> <billing_contract> <id type="integer">4597</id> <name>Venda de Suplementos</name> <customer_name>Jose da Silva</customer_name> <customer_email>[email protected]</customer_email> <seller_token>68b0d0ff82fe29c</seller_token> <day_expiration type="integer">26</day_expiration> <status_id type="integer">65</status_id> <status_name>Confirmado</status_name> <source_register/> <billing_contract_token>1947c284af42c224dc40255c2274fa3a</billing_contract_token> </billing_contract> <billing_contract> <id type="integer">4594</id> <name>1369055549</name> <customer_name>Silvana de Souza</customer_name> <customer_email>[email protected]</customer_email> <seller_token>68b047ff82fe29c</seller_token>

(13)

<day_expiration type="integer">15</day_expiration> <status_id type="integer">57</status_id> <status_name>Inativo</status_name> <source_register/> <billing_contract_token>78e6b4169b336af5f61d911d577a9efe</billing_contract_token> </billing_contract> </billing_contracts> <session_id>9c32e3867bde282f5a26201821309d99</session_id> <paginate> <current_page type="integer">0</current_page> <per_page type="integer">20</per_page> <amount_page type="integer">1</amount_page> <count type="integer">7</count> </paginate> </data_response> <message_response> <message>success</message> </message_response> </response>

E o detalhamento de cada nó do XML de resposta:

XML de Resposta

<data_response> Nó que contém o resultado da busca

<data_response>

Nó contendo os dados da assinatura

<response> <data_response> <billing_contract> <id> Id da Assinatura <response> <data_response> <billing_contract> <name> Nome da Assinatura <response> <data_response> <billing_contract> <costumer_name> Nome do Cliente <response> <data_response> <billing_contract> <costumer_email> Email do Cliente <response> <data_response> <billing_contract> <seller_token>

Token de Conta do Vendedor

<day_expiration>

(14)

<response> <data_response> <billing_contract> <status_id> ID do status da Assinatura <response> <data_response> <billing_contract> <status_name> Status da Assinatura <response> <data_response> <billing_contract> <source_register>

Campo de preenchimento livre na criação da cobrança

A seguir um exemplo de um retorno com erro:

<billing_contract>

<error_response> <errors type="array"> <error>

<message>Token de sessão inválido</message> </error> </errors> </error_response> <message_response> <message>error</message> </message_response> </billing_contract>

E o detalhamento de cada nó do XML de resposta:

XML de Resposta

<billing_contract> Nó principal da resposta

<billing_contract>

<error_response> Nó principal com os erros

<billing_contract> <error_response>

<error>

Nó que contem os erros encontrados

<billing_contract> <error_response> <erro> <code> Código do erro. <billing_contract> <error_response> <erro> <message> Mensagem de erro <billing_contract>

<message_response> Nó contendo as mensagens de erro

<billing_contract> <message_response>

<message>

(15)

3.4 Inativação de Assinatura

Esse método é utilizado para inativar uma cobrança específica.

*Para sua utilização, é necessário possuir o parâmetro SESSION_ID que pode ser obtido com a API de Login

descrita nesse manual.

Para esta integração, deverá ser feito uso da API a seguir:

Endereço de Integração

Ambiente de Testes http://api.sandbox.checkout.tray.com.br/v1/billing_contracts/inactive Ambiente de Produção https://api.checkout.tray.com.br/v1/billing_contracts/inactive Protocolo Rest/HTTP

Os dados que podem ser enviados nessa API são:

Dados de Entrada

Session_id Sim char (15) Token de autenticação do Vendedor

id Sim Int (11) ID da cobrança a ser inativada

Veja abaixo um exemplo de inativação de uma Assinatura:

Resposta da API

A API retorna a resposta em XML. No caso de sucesso, é retornado um nó

<data_response>

. No caso de

erro, é retornado um nó

<error_response>

. A primeira parte da resposta identifica se houve erro ou

sucesso através do nó

<message_response><message>

.

Exemplo de resposta com sucesso baseando no envio do exemplo acima:

<response> <message_response> <message>success</message> </message_response> <data_response> <billing_contract> <id type="integer">4339</id> <name>1368736580</name> <customer_name>Chuck Norris</customer_name> <customer_email>[email protected]</customer_email> <seller_token>68b050ff82fe29c</seller_token> <day_expiration type="integer">20</day_expiration> <status_id type="integer">57</status_id> <status_name>Inativo</status_name>

(16)

<source_register>Criado por API</source_register> <billing_contract_token>df51310f123d441dd60d0acacbd0a05d</billing_contract_token> <billing_contract_plans type="array"> <billing_contract_plan> <id type="integer">13733</id> <code>1368736580</code> <description>Suplementos</description> <periodicity type="integer">1</periodicity> <quantity type="integer">12</quantity> <price_setup type="decimal">0.0</price_setup> <price_discount type="decimal">0.0</price_discount> <price_due type="decimal">500.0</price_due> </billing_contract_plan> </billing_contract_plans> </billing_contract> </data_response> </response>

Abaixo um detalhamento de cada nó do XML de resposta:

XML de Resposta

<message_response>

<message>

<data_response>

Nó que contém os dados da cobrança

<response> <data_response> <billing_contract> <id> ID da cobrança <response> <data_response> <billing_contract> <name>

Dado gerado automaticamente pelo sistema

<response> <data_response> <billing_contract> <costumer_name> Nome do cliente <response> <data_response> <billing_contract> <costumer_email> Email do cliente <response> <data_response> <billing_contract> <seller_token> Token do vendedor

(17)

<day_expiration>

Data de vencimento da cobrança

<response> <data_response> <billing_contract> <status_id> ID de status da cobrança <response> <data_response> <billing_contract> <status_name> Status da cobrança <response> <data_response> <billing_contract> <source_register>

Informação enviada no <source_register> de criação

<billing_contract_token>

Token da cobrança gerada

<billing_contract_plans>

Nó que contém os planos inclusos

<billing_contract_plans>

<billing_contract_plan>

Nó que contém os dados do plano

<response> <data_response> <billing_contract> <billing_contract_plans> <billing_contract_plan> <id> ID do plano <response> <data_response> <billing_contract> <billing_contract_plans> <billing_contract_plan> <code>

Dados gerados automaticamente pelo sistema

<response> <data_response> <billing_contract> <billing_contract_plans> <billing_contract_plan> <description> Descrição do plano <response> <data_response> <billing_contract> <billing_contract_plans> <billing_contract_plan> <periodicity> Periodicidade do plano <response>

(18)

<billing_contract> <billing_contract_plans> <billing_contract_plan> <quantity> <response> <data_response> <billing_contract> <billing_contract_plans> <billing_contract_plan> <price_setup>

Valor de contratação do plano

<response> <data_response> <billing_contract> <billing_contract_plans> <billing_contract_plan> <price_discount>

Valor de desconto do plano

<response> <data_response> <billing_contract> <billing_contract_plans> <billing_contract_plan> <price_due> Valor do plano

A seguir um exemplo de um retorno com erro:

<message>Token inválido ou não encontrado</message> </general_error>

E o detalhamento de cada nó do XML de resposta:

XML de Resposta

<message_response>

<message>

(19)

<error_response>

<general_error>