gerencianet 0.0.1 → 0.0.2

data/docs/examples/update_parcel.rb

@@ -0,0 +1,20 @@
+require "gerencianet"
+require_relative "./credentials"
+
+options = {
+  client_id: CREDENTIALS::CLIENT_ID,
+  client_secret: CREDENTIALS::CLIENT_SECRET,
+  sandbox: true
+}
+
+params = {
+  id: 1008
+}
+
+body = {
+  parcel: 1,
+  expire_at: "2020-12-12"
+}
+
+gerencianet = Gerencianet.new(options)
+puts gerencianet.update_parcel(params: params, body: body)

data/docs/examples/update_subscription_metadata.rb

@@ -0,0 +1,20 @@
+require "gerencianet"
+require_relative "./credentials"
+
+options = {
+  client_id: CREDENTIALS::CLIENT_ID,
+  client_secret: CREDENTIALS::CLIENT_SECRET,
+  sandbox: true
+}
+
+params = {
+  id: 1009
+}
+
+body = {
+  notification_url: "http://yourdomain.com",
+  custom_id: "my_new_id"
+}
+
+gerencianet = Gerencianet.new(options)
+puts gerencianet.update_subscription_metadata(params: params, body: body)

data/docs/installments.md

@@ -0,0 +1,108 @@
+## Listing installments
+
+If you ever need to get the total value for a charge, including rates and interests, as well as each installment value, even before the payment itself, you can.
+
+Why would I need this?
+
+Sometimes you need to check the total for making a discount, or simple to show a combobox with the installments for your users.
+
+Stop bragging about. Here is the code:
+
+```ruby
+params = {
+  brand: "visa",
+  total: 5000
+}
+
+gerencianet = Gerencianet.new(options)
+gerencianet.get_installments(params: params)
+```
+
+And the response:
+
+```ruby
+{
+  "code": 200,
+  "data": {
+    "rate": 150,
+    "interest_percentage": 0,
+    "name": "visa",
+    "installments": [
+      {
+        "installment": 1,
+        "has_interest": false,
+        "value": 5150,
+        "currency": "51,50"
+      },
+      {
+        "installment": 2,
+        "has_interest": true,
+        "value": 2679,
+        "currency": "26,79"
+      },
+      {
+        "installment": 3,
+        "has_interest": true,
+        "value": 1821,
+        "currency": "18,21"
+      },
+      {
+        "installment": 4,
+        "has_interest": true,
+        "value": 1393,
+        "currency": "13,93"
+      },
+      {
+        "installment": 5,
+        "has_interest": true,
+        "value": 1137,
+        "currency": "11,37"
+      },
+      {
+        "installment": 6,
+        "has_interest": true,
+        "value": 966,
+        "currency": "9,66"
+      },
+      {
+        "installment": 7,
+        "has_interest": true,
+        "value": 845,
+        "currency": "8,45"
+      },
+      {
+        "installment": 8,
+        "has_interest": true,
+        "value": 754,
+        "currency": "7,54"
+      },
+      {
+        "installment": 9,
+        "has_interest": true,
+        "value": 683,
+        "currency": "6,83"
+      },
+      {
+        "installment": 10,
+        "has_interest": true,
+        "value": 627,
+        "currency": "6,27"
+      },
+      {
+        "installment": 11,
+        "has_interest": true,
+        "value": 581,
+        "currency": "5,81"
+      },
+      {
+        "installment": 12,
+        "has_interest": true,
+        "value": 544,
+        "currency": "5,44"
+      }
+    ]
+  }
+}
+```
+
+Observe that the response comes with an installments array of 12 positions at maximum. Each position matches one possible option of installment number, containing its value in currency and integer forms. The number of installments will vary according to the selected brand. Use it any way that suits your needs.

data/docs/notifications.md

@@ -0,0 +1,105 @@
+## Notifications
+
+Any changes that happen in the charges will trigger an event that notifies the `notification_url` provided at creation time (see [creating charges](https://github.com/gerencianet/gn-api-sdk-node/tree/master/docs/charges.md)).
+
+It's also possible to set or change the `notification_url` for existing charges, see [updating informations](https://github.com/gerencianet/gn-api-sdk-node/tree/master/docs/charge-update.md).
+
+Given that a charge has a valid `notification_url`, when the notification time comes you'll receive a post with a `token`. This token must be used to get the notification payload data.
+
+The example below assumes that you're using a **Rails** app. It's easier showing than explaining with words:
+
+```ruby
+class TicketsController < ApplicationController
+  # this is a post route
+  def notification_route
+    params = {
+      token: params[:token]
+    }
+
+    gerencianet = Gerencianet.new(options)
+    gerencianet.get_notification(params: params)
+  end
+end
+```
+
+Response:
+
+```ruby
+{
+  "code": 200,
+  "data": [{
+    "id": 1,
+    "type": "charge",
+    "custom_id": null,
+    "status": {
+      "current": "new",
+      "previous": null
+    },
+    "identifiers": {
+      "charge_id": 1002
+    }
+  }, {
+    "id": 2,
+    "type": "charge",
+    "custom_id": null,
+    "status": {
+      "current": "waiting",
+      "previous": "new"
+    },
+    "identifiers": {
+      "charge_id": 1002
+    }
+  }, {
+    "id": 3,
+    "type": "charge",
+    "custom_id": null,
+    "status": {
+      "current": "paid",
+      "previous": "waiting"
+    },
+    "identifiers": {
+      "charge_id": 1002
+    },
+    "value": 2000
+  }, {
+    "id": 4,
+    "type": "charge",
+    "custom_id": null,
+    "status": {
+      "current": "refunded",
+      "previous": "paid"
+    },
+    "identifiers": {
+      "charge_id": 1002
+    }
+  }]
+}
+```
+
+The response will be an array with all the changes of a certain token that happened within the past 6 months. It will have the following parameters:
+
+* id: Each notification has its own sequence, starting from `1`. The `id` parameter identifies this sequence. This is useful if you need to keep track of what changes you have already processed.
+
+* type: Available values are:
+  * `charge` - a charge have changed
+  * `subscription` - a subscription have changed
+  * `carnet` - a carnet have changed
+  * `subscription_charge` - one subscription's parcel have changed
+  * `carnet_charge` - one carnet's parcel have changed
+
+* custom_id: your custom_id.
+
+* status: Contains the `current` and `previous` (before the change) status  of the transaction.
+
+ p.s.: if there is no `previous` status (i.e.: for new charges), the `previous` value will be null.
+
+* identifiers: Identifiers related to the change. It may have one or more identifier, depending on the type:
+  * for `charge` type: identifiers will contain only `charge_id`.
+  * for `subscription` type: identifiers will contain only `subscription_id`.
+  * for `carnet` type: identifiers will contain only `carnet_id`.
+  * for `subscription_charge` type: identifiers will contain both `charge_id` and `subscription_id`.
+  * for `carnet_charge` type: identifiers will contain both `charge_id` and `carnet_id`.
+
+* value: This parameter will only be shown when the status changes to paid.
+
+ For more informations about notifications, please refer to [Gerencianet](https://docs.gerencianet.com.br/#!/charges/notifications).

data/docs/subscription-detailing.md

@@ -0,0 +1,56 @@
+## Detailing subscriptions
+
+Works just like the charge detailing, but here you pass the subscription id:
+
+```ruby
+params = {
+  id: 1120
+}
+
+gerencianet = Gerencianet.new(options)
+gerencianet.detail_subscription(params: params)
+```
+
+Response:
+
+```ruby
+{
+  "code": 200,
+  "data": {
+    "subscription_id": 12,
+    "value": 2000,
+    "status": "new",
+    "payment_method": null,
+    "next_execution": null,
+    "next_expire_at": null,
+    "interval": 1,
+    "repeats": 2,
+    "processed_amount": 0,
+    "created_at": "2015-05-14 15:39:14",
+    "history": [
+      {
+        "charge_id": 233,
+        "status": "new",
+        "created_at": "2015-05-14 15:39:14"
+      }
+    ]
+  }
+}
+```
+
+Note that if you [detail a charge](/docs/charge-detailing.md) that belongs to a subscription, the response will have a `subscription` block with data about it, including the `subscription_id`. If you need the subscription information, you can do this:
+
+```ruby
+params = {
+  charge_id: 2332
+}
+
+gerencianet = Gerencianet.new(options)
+charge = gerencianet.detail_charge(params: params)
+
+params = {
+  id: charge["data"]["subscription_id"]
+}
+
+gerencianet.detail_subscription(params: params)
+```

data/docs/subscription-payment.md

@@ -0,0 +1,100 @@
+## Paying subscriptions
+
+### 1. Banking billets
+
+```ruby
+params = {
+  id: 1113
+}
+
+var body = {
+  payment: {
+    banking_billet: {
+      expire_at: "2016-12-12",
+      customer: {
+        name: "Gorbadoc Oldbuck",
+        email: "oldbuck@gerencianet.com.br",
+        cpf: "04267484171",
+        birth: "1977-01-15",
+        phone_number: "5144916523"
+      }
+    }
+  }
+}
+
+gerencianet = Gerencianet.new(options)
+gerencianet.pay_subscription(params: params, body: body)
+```
+
+### 2. Credit card
+
+Here it's necessary to use the customer's *credit card* to submit the payment. A `payment_token` represents a credit card, as explained at the end of this page.
+
+```ruby
+params = {
+  id: 1113
+}
+
+body = {
+  payment: {
+    credit_card: {
+      payment_token: "e0c210bb679fea225a586256234f8ce179fd16c5",
+      billing_address: {
+        street: "Av. JK",
+        number: 909,
+        neighborhood: "Bauxita",
+        zipcode: "35400000",
+        city: "Ouro Preto",
+        state: "MG"
+      },
+      customer: {
+        name: "Gorbadoc Oldbuck",
+        email: "oldbuck@gerencianet.com.br",
+        cpf: "04267484171",
+        birth: "1977-01-15",
+        phone_number: "5144916523"
+      }
+    }
+  }
+}
+
+gerencianet = Gerencianet.new(options)
+gerencianet.pay_subscription(params: params, body: body)
+```
+
+Response:
+
+```js
+{
+  "code": 200,
+  "data": {
+    "subscription_id": 11,
+    "status": "active",
+    "plan": {
+      "id": 1000,
+      "interval": 2,
+      "repeats": null
+    },
+    "charge": {
+      "id": 1053,
+      "status": "waiting"
+    },
+    "total": 1150,
+    "payment": "credit_card"
+  }
+}
+```
+
+For getting installment values, including interests, check [Getting Installments](/docs/payment-data.md).
+
+##### Payment tokens
+
+A `payment_token` represents a credit card number at Gerencianet.
+
+For testing purposes, you can go to your application playground in your Gerencianet's account. At the payment endpoint you'll see a button that generates one token for you. This payment token will point to a random test credit card number.
+
+When in production, it will depend if your project is a web app or a mobile app.
+
+For web apps you should follow this [guide](https://api.gerencianet.com.br/checkout/card). It basically consists of copying/pasting a script tag in your checkout page.
+
+For mobile apps you should use this [SDK for Android](https://github.com/gerencianet/gn-api-sdk-android) or this [SDK for iOS](https://github.com/gerencianet/gn-api-sdk-ios).

data/docs/subscription-update.md

@@ -0,0 +1,29 @@
+## Updating subscriptions
+
+### Changing the metadata
+
+You can update the `custom_id` or the `notification_url` of a subscription.
+
+It is important to keep in mind that all the subscription charges will be updated. If you want to update only one, check [Updating charges](/docs/charge-update).
+
+```ruby
+params = {
+  id: 1009
+}
+
+body = {
+  notification_url: "http://yourdomain.com",
+  custom_id: "my_new_id"
+}
+
+gerencianet = Gerencianet.new(options)
+puts gerencianet.update_subscription_metadata(params: params, body: body)
+```
+
+If everything goes well, the return will be:
+
+```ruby
+{
+  "code": 200
+}
+```

data/docs/subscriptions.md

@@ -0,0 +1,69 @@
+## Creating subscriptions
+
+If you ever have to recurrently charge your clients, you can create a different kind of charge, one that belongs to a subscription. This way, subsequent charges will be automatically created based on plan configuration and the charge value is charged in your customers' credit card, or the banking billet is generated and sent to the custumer, accoding to the plan’s configuration.
+
+The plan configuration receive two params: `repeats` and `interval`:
+
+The `repeats` parameter defines how many times the transaction will be repeated. If you don't provide it, the subscription will create charges indefinitely.
+
+The `interval` parameter defines the interval, in months, that a charge has to be generated. The minimum value is 1, and the maximum is 24.
+
+It's worth to mention that this mechanics is triggered only if the customer commits the subscription. In other words, it takes effect when the customer pays the first charge.
+
+At last, it boils down to creating a plan and then the subscription. The plan can be reused for generating other subscriptions:
+
+```ruby
+plan = {
+  name: "My first plan",
+  repeats: 24,
+  interval: 2
+}
+
+subscription = {
+  items: [{
+    name: "Product 1",
+    value: 1000,
+    amount: 2
+  }]
+}
+
+gerencianet = Gerencianet.new(options)
+plan = gerencianet.create_plan(body: plan)
+
+params = {
+  id: plan["data"]["plan_id"]
+}
+
+gerencianet.create_subscription(params: params, body: subscription)
+```
+
+### Deleting a plan:
+*(works just for plans that doesn't have a subscription associated):*
+
+```ruby
+params = {
+  id: 1
+}
+
+gerencianet = Gerencianet.new(options)
+gerencianet.delete_plan(params: params)
+```
+
+### Canceling subscriptions
+
+You can cancel active subscriptions at any time:
+
+```ruby
+params = {
+  id: 1111
+}
+
+gerencianet = Gerencianet.new(options)
+puts gerencianet.cancel_subscription(params: params)
+```
+
+```js
+{
+  "code": 200
+}
+```