Manual de Integração Assinaturas

Transcrição

1 Manual de Integração Assinaturas Versão 1.0 1

2 Índice 1. Ambiente de Testes Token da Conta Integração via API Login via API Criar Cobrança Recorrente Listar Assinatura Inativação de Assinatura

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 Caso queira recuperar a senha, utilize a 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 e clique no botão Acesse sua conta, localizado no canto superior direito da página. Informe seu 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 3

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 Ambiente de Produção 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) 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ó. No caso de erro, é retornado um nó. A primeira parte da resposta identifica se houve erro ou sucesso através do nó. 4

5 Exemplo de resposta com sucesso baseando no envio do exemplo acima: success</message> </message_response> <name>caue Fajoli</name> <session_id>863ab a7dffea1afc00122</session_id> </data_response> </response> Abaixo um detalhamento de cada nó do XML de resposta: XML de Resposta <name> < > <session_id> Nó principal da resposta Nó que contém o resultado da resposta Resposta sobre a solicitação Em caso de sucesso: sucess Em caso de erro: error Nó que contém os dados da resposta Nome da Conta da Conta ID de Sessão A seguir um exemplo de um retorno com erro: error</message> </message_response> <general_errors type="array"> <code>017002</code> e/ou senha inválidos</message> </general_error> </general_errors> </error_response> </response> 5

6 E o detalhamento de cada nó do XML de resposta: XML de Resposta <general_errors> <general_errors> <general_errors> <code> <general_errors type="array"> Nó principal da resposta Nó que contém o resultado da resposta Resposta sobre a solicitação Em caso de sucesso: sucess Em caso de erro: error Nó contendo os erros encontrados Nó contendo os erros encontrados Nó contendo o detalhamento de um erro Código do erro 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 Ambiente de Produção 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_ Sim char (150) do cliente que receberá a cobrança description Sim char (150) Descrição da cobrança 6

7 day_expiration Sim int (11) Dia do vencimento da cobrança date_expiration Sim date periodicity Sim int (11) quantity Sim int (11) price Sim decimal (10,2) source_register Não varchar (100) Data para vencimento da cobrança dd/mm/aaaa Periodicidade da cobrança Ex: 1 = cobrança mensal 6 = cobrança semestral Quantidade de cobranças geradas 0 indica tempo indeterminado Valor da cobrança Ex: 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=" > <input type="text" name="token_account" value="3e3ed4355b54adf" /> <input type="text" name="customer_name" value="chuck Norris" /> <input type="text" name="customer_ " 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ó. No caso de erro, é retornado um nó. A primeira parte da resposta identifica se houve erro ou sucesso através do nó. Exemplo de resposta com sucesso baseando no envio do exemplo acima: success</message> </message_response> <id type="integer">4362</id> <name> </name> <customer_name>chuck Norris</customer_name> <customer_ >[email protected]</customer_ > <seller_token>68b050ff82fe29c</seller_token> <day_expiration type="integer">20</day_expiration> <status_id type="integer">58</status_id> <status_name>pendente</status_name> 7

8 <source_register>criado por API</source_register> <billing_contract_token>9d30b3c246a68a487a35833e181095c6</billing_contract_token> <url_confirmation> </url_confirmation> <billing_contract_plans type="array"> <id type="integer">13770</id> <code> </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 <id> <name> <costumer_name> <costumer_ > Nó principal da resposta Nó que contém o resultado da resposta Resposta sobre a solicitação Em caso de sucesso: sucess Em caso de erro: error Nó que contém os dados da resposta Nó que contém os dados da cobrança ID da cobrança Dado gerado automaticamente pelo sistema Nome do cliente do cliente 8

9 <seller_token> <day_expiration> <status_id> <status_name> <source_register> <billing_contract_token> <url_confirmation> <id> <code> Token do vendedor Data de vencimento da cobrança ID de status da cobrança Status da cobrança Informação enviada no <source_register> de criação Token da cobrança gerada URL de confirmação e pagamento da cobrança Nó que contém os planos inclusos Nó que contém os dados do plano ID do plano Dados gerados automaticamente pelo sistema <description> Descrição do plano 9

10 <periodicity> <quantity> <price_setup> <price_discount> <price_due> Periodicidade do plano Quantidade de vezes que será feita a cobrança Valor de contratação do plano Valor de desconto do plano Valor do plano A seguir um exemplo de um retorno com erro: error</message> </message_response> <general_errors type="array"> <code>001001</code> Token inválido ou não encontrado</message> </general_error> </general_errors> </error_response> </response> 10

11 E o detalhamento de cada nó do XML de resposta: XML de Resposta <general_errors> <general_errors> <general_errors> <code> <general_errors type="array"> Nó principal da resposta Nó que contém o resultado da resposta Resposta sobre a solicitação Em caso de sucesso: sucess Em caso de erro: error Nó contendo os erros encontrados Nó contendo os erros encontrados Nó contendo o detalhamento de um erro Código do erro 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 Ambiente de Produção Protocolo Rest/HTTP 11

12 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_ Não char(150) 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=" <input type="text" name="session_id" value="dc02a3351f7c85ba0b38db49e80680b2" /> <input type="text" name="name" value="" /> <input type="text" name="customer_ " 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ó. No caso de erro, é retornado um nó. A primeira parte da resposta identifica se houve erro ou sucesso através do nó. Exemplo de resposta com sucesso baseando no envio do exemplo acima: <billing_contracts type="array"> <id type="integer">4597</id> <name>venda de Suplementos</name> <customer_name>jose da Silva</customer_name> <customer_ >[email protected]</customer_ > <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> <id type="integer">4594</id> <name> </name> <customer_name>silvana de Souza</customer_name> <customer_ >[email protected]</customer_ > <seller_token>68b047ff82fe29c</seller_token> 12

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>9c32e3867bde282f5a d99</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> success</message> </message_response> </response> E o detalhamento de cada nó do XML de resposta: XML de Resposta <id> <name> <costumer_name> <costumer_ > <seller_token> <day_expiration> Nó principal da resposta Nó que contém o resultado da busca Nó contendo os dados da assinatura Id da Assinatura Nome da Assinatura Nome do Cliente do Cliente Token de Conta do Vendedor Dia de Vencimento da Assinatura 13

14 <status_id> <status_name> <source_register> ID do status da Assinatura Status da Assinatura Campo de preenchimento livre na criação da cobrança A seguir um exemplo de um retorno com erro: <errors type="array"> <error> <code>017001</code> Token de sessão inválido</message> </error> </errors> </error_response> error</message> </message_response> </billing_contract> E o detalhamento de cada nó do XML de resposta: XML de Resposta <error> <erro> <code> <erro> Nó principal da resposta Nó principal com os erros Nó que contem os erros encontrados Código do erro. Mensagem de erro Nó contendo as mensagens de erro Mensagem de erro 14

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 Ambiente de Produção 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=" <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ó. No caso de erro, é retornado um nó. A primeira parte da resposta identifica se houve erro ou sucesso através do nó. Exemplo de resposta com sucesso baseando no envio do exemplo acima: success</message> </message_response> <id type="integer">4339</id> <name> </name> <customer_name>chuck Norris</customer_name> <customer_ >[email protected]</customer_ > <seller_token>68b050ff82fe29c</seller_token> <day_expiration type="integer">20</day_expiration> <status_id type="integer">57</status_id> <status_name>inativo</status_name> 15

16 <source_register>criado por API</source_register> <billing_contract_token>df51310f123d441dd60d0acacbd0a05d</billing_contract_token> <billing_contract_plans type="array"> <id type="integer">13733</id> <code> </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 <id> <name> <costumer_name> <costumer_ > <seller_token> Nó principal da resposta Nó que contém o resultado da resposta Resposta sobre a solicitação Em caso de sucesso: sucess Em caso de erro: error Nó que contém os dados da resposta Nó que contém os dados da cobrança ID da cobrança Dado gerado automaticamente pelo sistema Nome do cliente do cliente Token do vendedor 16

17 <day_expiration> <status_id> <status_name> <source_register> <billing_contract_token> <id> <code> <description> <periodicity> Data de vencimento da cobrança ID de status da cobrança Status da cobrança Informação enviada no <source_register> de criação Token da cobrança gerada Nó que contém os planos inclusos Nó que contém os dados do plano ID do plano Dados gerados automaticamente pelo sistema Descrição do plano Periodicidade do plano Quantidade de vezes que será feita a cobrança 17

18 <quantity> <price_setup> <price_discount> <price_due> Valor de contratação do plano Valor de desconto do plano Valor do plano A seguir um exemplo de um retorno com erro: error</message> </message_response> <general_errors type="array"> <code>001001</code> 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 Nó principal da resposta Nó que contém o resultado da resposta Resposta sobre a solicitação Em caso de sucesso: sucess Em caso de erro: error Nó contendo os erros encontrados 18

19 <general_errors> <general_errors> <general_errors> <code> <general_errors type="array"> Nó contendo os erros encontrados Nó contendo o detalhamento de um erro Código do erro Mensagem do erro 19