Manual de Integração Assinaturas Versão 1.0 Suporte a Desenvolvedores: [email protected] www.traycheckout.com.br 1 Í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.4 Inativação de Assinatura ........................................................................................................................ 15 Suporte a Desenvolvedores: [email protected] www.traycheckout.com.br 2 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 http://checkout.sandbox.tray.com.br/session/login. opção “Esqueci minha senha” acessando 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. Clique então no menu “Perfil da Conta” e então no item “Minha Conta” Suporte a Desenvolvedores: [email protected] www.traycheckout.com.br 3 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: Obrigatório Dados de Entrada 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 id="form1" name="form1" method="post" action="/api/v1/accesses/login_customer" target="_blank"> <input type="text" name="login" id="login" /> <input type="password" name="password" id="password" /> <input type="submit" name="button" id="button" value="Logar" /> </p> </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>. Suporte a Desenvolvedores: [email protected] www.traycheckout.com.br 4 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 <response> <message_response> Nó que contém o resultado da resposta <response> <message_response> <message> Resposta sobre a solicitação Em caso de sucesso: sucess Em caso de erro: error <response> <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> Suporte a Desenvolvedores: [email protected] www.traycheckout.com.br 5 E o detalhamento de cada nó do XML de resposta: XML de Resposta <response> Nó principal da resposta <response> <message_response> Nó que contém o resultado da resposta <response> <message_response> <message> Resposta sobre a solicitação Em caso de sucesso: sucess Em caso de erro: error <response> <error_response> Nó contendo os erros encontrados <response> <error_response> <general_errors> Nó contendo os erros encontrados <response> <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 Obrigatório Formato / Tamanho Max Descrição 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 description Sim char (150) Descrição da cobrança Suporte a Desenvolvedores: [email protected] www.traycheckout.com.br 6 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 viceversa. 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 method="post" action="http://api.checkout.tray.com.br/v1/billing_contracts/charge_recurrent" > <input type="text" name="token_account" value="3e3ed4355b54adf" /> <input type="text" name="customer_name" value="Chuck Norris" /> <input type="text" name="customer_email" value="[email protected]" /> <input type="text" name="description" value="Suplementos" /> <input type="text" name="day_expiration" value="20" /> <input type="text" name="periodicity" value="1" /> <input type="text" name="quantity" value="12" /> <input type="text" name="price" value="500.00" /> <input type="text" name="source_register" value="Criado por API" /> <input type="submit"> </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> <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> Suporte a Desenvolvedores: [email protected] www.traycheckout.com.br 7 <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 <response> Nó principal da resposta <response> <message_response> Nó que contém o resultado da resposta <response> <message_response> <message> Resposta sobre a solicitação Em caso de sucesso: sucess Em caso de erro: error <response> <data_response> Nó que contém os dados da resposta <response> <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 Suporte a Desenvolvedores: [email protected] www.traycheckout.com.br 8 <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 <response> <data_response> <billing_contract> <billing_contract_token> Token da cobrança gerada <response> <data_response> <billing_contract> <url_confirmation> URL de confirmação e pagamento da cobrança <response> <data_response> <billing_contract> <billing_contract_plans> Nó que contém os planos inclusos <response> <data_response> <billing_contract> <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 Suporte a Desenvolvedores: [email protected] www.traycheckout.com.br 9 <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: <response> <message_response> <message>error</message> </message_response> <error_response> <general_errors type="array"> <general_error> <code>001001</code> <message>Token inválido ou não encontrado</message> </general_error> </general_errors> </error_response> </response> Suporte a Desenvolvedores: [email protected] www.traycheckout.com.br 10 E o detalhamento de cada nó do XML de resposta: XML de Resposta <response> Nó principal da resposta <response> <message_response> Nó que contém o resultado da resposta <response> <message_response> <message> Resposta sobre a solicitação Em caso de sucesso: sucess Em caso de erro: error <response> <error_response> Nó contendo os erros encontrados <response> <error_response> <general_errors> Nó contendo os erros encontrados <response> <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.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 Protocolo Rest/HTTP Suporte a Desenvolvedores: [email protected] www.traycheckout.com.br 11 Os dados que podem ser enviados nessa API são: Dados de Entrada Obrigatório Formato / Tamanho Max Descrição 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 method="post" action="http://api.checkout.tray.com.br/api/billing_contracts/search"> <input type="text" name="session_id" value="dc02a3351f7c85ba0b38db49e80680b2" /> <input type="text" name="name" value="" /> <input type="text" name="customer_email" value="" /> <input type="text" name="billing_contract_id" value="" /> <input type="text" name="day_expiration" value="" /> <input type="text" name="status_id" value="56" /> <input type="submit"> </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> Suporte a Desenvolvedores: [email protected] www.traycheckout.com.br 12 <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 <response> Nó principal da resposta <response> <data_response> Nó que contém o resultado da busca <response> <data_response> <billing_contract> 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 <response> <data_response> <billing_contract> <day_expiration> Dia de Vencimento da Assinatura Suporte a Desenvolvedores: [email protected] www.traycheckout.com.br 13 <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> <code>017001</code> <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> Mensagem de erro Suporte a Desenvolvedores: [email protected] www.traycheckout.com.br 14 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 Obrigatório Formato / Tamanho Max Descrição 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: <form method="post" action="http://api.checkout.tray.com.br/api/billing_contracts/inactive"> <input type="text" name="session_id" value="638c637de7be97eda4e0dee5f628d624" /> <input type="text" name="id" value="3126" /> <input type="submit"> </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> <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> Suporte a Desenvolvedores: [email protected] www.traycheckout.com.br 15 <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 <response> Nó principal da resposta <response> <message_response> Nó que contém o resultado da resposta <response> <message_response> <message> Resposta sobre a solicitação Em caso de sucesso: sucess Em caso de erro: error <response> <data_response> Nó que contém os dados da resposta <response> <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 <response> <data_response> <billing_contract> <seller_token> Token do vendedor Suporte a Desenvolvedores: [email protected] www.traycheckout.com.br 16 <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 <response> <data_response> <billing_contract> <billing_contract_token> Token da cobrança gerada <response> <data_response> <billing_contract> <billing_contract_plans> Nó que contém os planos inclusos <response> <data_response> <billing_contract> <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> <data_response> Quantidade de vezes que será feita a cobrança Suporte a Desenvolvedores: [email protected] www.traycheckout.com.br 17 <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: <response> <message_response> <message>error</message> </message_response> <error_response> <general_errors type="array"> <general_error> <code>001001</code> <message>Token inválido ou não encontrado</message> </general_error> </general_errors> </error_response> </response> E o detalhamento de cada nó do XML de resposta: XML de Resposta <response> Nó principal da resposta <response> <message_response> Nó que contém o resultado da resposta <response> <message_response> <message> Resposta sobre a solicitação Em caso de sucesso: sucess Em caso de erro: error <response> <error_response> Nó contendo os erros encontrados Suporte a Desenvolvedores: [email protected] www.traycheckout.com.br 18 <response> <error_response> <general_errors> Nó contendo os erros encontrados <response> <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 Suporte a Desenvolvedores: [email protected] www.traycheckout.com.br 19