gerencianet 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: db0dc12a8bb152c33bb1386d2ead264880cf56c0
-  data.tar.gz: 5e72412e908a0369f4cded139d779bea0159601b
+  metadata.gz: c51582bc8d3f69e20fd2ae7ddfeb364ca88395ed
+  data.tar.gz: 7a34a05694cc686bbc15486c443022dd3e584636
 SHA512:
-  metadata.gz: 076b82eac8e238d2115de2c38254b899fa47d2a15dd8d9cf0bc1b8484189a44b70ca5e73974960f3a130b3e99a19c7be43d5a706845ee111d5f10a5ec40afe76
-  data.tar.gz: 518f72c4a4e0a794bd3c0e7b203dde35d6c1865f45ec0eefa3e7b94affb1906f96b9dd9ba205be9410d5b3e847835e0a354139ed925c11fdff1587b7804ce0ce
+  metadata.gz: 8c6ca03e6e20f3d1b2377f74f41f4a83afa9d4944ae737ad2dada29d2fd1103a649cba9479a3b93047514828a88411f5baf833d8c9f3fb663977fcbe2bb1f2c0
+  data.tar.gz: 00269412bb8ee22c3bd481162d4cc920884a0b73786c3cc9d29ed61712c97cecded6c7123e6cd546439d4dcad71283849b97a7073ba2e17594424f045e8976cc

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# 0.0.2
+
+- Changed: Functions now receive a single hash param like `{params: params, body: body}` instead of receiving two params `params, body` as before.
+- Added: Docs and examples
+
+# 0.0.1
+
+- Initial release

data/README.md

@@ -6,6 +6,7 @@ provided by [Gerencianet](http://gerencianet.com.br).
 [![Build Status](https://travis-ci.org/gerencianet/gn-api-sdk-ruby.svg)](https://travis-ci.org/gerencianet/gn-api-sdk-ruby)
 [![Coverage Status](https://coveralls.io/repos/gerencianet/gn-api-sdk-ruby/badge.svg?branch=master&service=github)](https://coveralls.io/github/gerencianet/gn-api-sdk-ruby?branch=master)
 [![Code Climate](https://codeclimate.com/github/gerencianet/gn-api-sdk-ruby/badges/gpa.svg)](https://codeclimate.com/github/gerencianet/gn-api-sdk-ruby)
+[![Gem Version](https://badge.fury.io/rb/gerencianet.svg)](https://badge.fury.io/rb/gerencianet)
 
 :warning: **Gerencianet API is under BETA version, meaning that it's not available for all users right now. If you're interested, you can always send an email to
 desenvolvedores@gerencianet.com.br and we'll enable it for your account**
@@ -23,6 +24,7 @@ And then execute:
 ```bash
 $ bundle
 ```
+
 Or install it yourself as:
 
 ```bash
@@ -40,9 +42,9 @@ options = {
   sandbox: true
 }
 
-gerencianet = Gerencianet.new(@options)
+gerencianet = Gerencianet.new(options)
 
-input = {
+charge = {
   items: [{
     name: "Product A",
     value: 1000,
@@ -50,9 +52,19 @@ input = {
   }]
 }
 
-response = gerencianet.create_charge(input)
+response = gerencianet.create_charge(body: charge)
 ```
 
+## Examples
+
+You can run the examples inside `docs/examples` with `$ ruby docs/examples/example.rb`:
+
+```bash
+$ ruby docs/examples/create_charge.rb
+```
+
+Just remember to set the correct credentials inside `docs/examples/credentials.rb` before running.
+
 ## Tests
 
 To run the tests, just run *rspec*:

data/docs/all-in-one.md

@@ -0,0 +1,92 @@
+## Create charge and payment
+
+The most common case scenarios consist of the two steps mentioned in the title. The other examples show each part separately. Here goes the most used endpoints grouped in one example.
+
+Create the inputs for the three endpoints:
+
+```ruby
+charge = {
+  items: [{
+    name: "Product 1",
+    value: 1000,
+    amount: 2
+  }],
+  shippings: [{
+    name: "Default Shipping Cost",
+    value: 100
+  }, {
+    name: "Adicional Shipping Cost",
+    value: 150
+  }]
+}
+
+payment = {
+  payment: {
+    credit_card: {
+      installments: 1,
+      payment_token: "88faabaa35f9d9ff29c315e03255c5644554a771",
+      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"
+      }
+    }
+  }
+}
+```
+
+Call the endpoints:
+
+```ruby
+require "gerencianet"
+
+options = {
+  client_id: "client_id",
+  client_secret: "client_secret",
+  sandbox: true
+}
+
+gerencianet = Gerencianet.new(options)
+
+charge = gerencianet.create_charge(body: charge)
+
+params = {
+  id: charge["data"]["charge_id"]
+}
+
+puts gerencianet.pay_charge(params: params, body: payment)
+```
+
+Response:
+
+```ruby
+{ "code": 200,
+  "data": {
+     "charge_id": 260,
+     "total": 2250,
+     "status": 'new',
+     "custom_id": null,
+     "created_at": "2015-05-18"
+   }
+} #charge created
+
+{ "code": 200,
+  "data": {
+     "charge_id": 260,
+     "total": 2400,
+     "payment": "credit_card",
+     "installments": 1,
+     "installment_value": 2400
+  }
+} #payment created
+```

data/docs/carnet-detailing.md

@@ -0,0 +1,61 @@
+## Detailing carnets
+
+In order to retrieve carnets, just provide the id:
+
+```ruby
+params = {
+  id: 1000
+}
+
+gerencianet = Gerencianet.new(options)
+puts gerencianet.detail_carnet(params: params)
+```
+
+The response you'll receive contains all the information about the carnet:
+
+```ruby
+{
+  "code": 200,
+  "data": {
+    "carnet_id": 6,
+    "status": "active",
+    "repeats": 4,
+    "cover": "https://visualizacao.gerencianet.com.br/emissao/28333_2385_ZEMAL5/A5CC-28333-61428-LEENA9/28333-61428-LEENA9",
+    "value": 4000,
+    "split_items": false,
+    "charges": [{
+        "charge_id": 357,
+        "parcel": "1",
+        "status": "waiting",
+        "value": 2000,
+        "expire_at": '2015-06-01',
+        "url": "https://visualizacao.gerencianet.com.br/emissao/28333_2385_ZEMAL5/A5CL-28333-61428-LEENA9/28333-61428-LEENA9",
+        "barcode": "00190.00009 01523.894002 00061.428181 1 64780000002000"
+      }, {
+        "charge_id": 358,
+        "parcel": "2",
+        "status": "waiting",
+        "value": 2000,
+        "expire_at": '2015-07-01',
+        "url": "https://visualizacao.gerencianet.com.br/emissao/28333_2385_ZEMAL5/A5CL-28333-61428-LEENA9/28333-61429-CORZE4",
+        "barcode": "00190.00009 01523.894002 00061.428181 8 65090000002000"
+      }, {
+        "charge_id": 359,
+        "parcel": "3",
+        "status": "waiting",
+        "value": 2000,
+        "expire_at": '2015-08-01',
+        "url": "https://visualizacao.gerencianet.com.br/emissao/28333_2385_ZEMAL5/A5CL-28333-61428-LEENA9/28333-61430-HIRRA4",
+        "barcode": "00190.00009 01523.894002 00061.428181 7 65400000002000"
+      }, {
+        "charge_id": 360,
+        "parcel": "4",
+        "status": "waiting",
+        "value": 2000,
+        "expire_at": '2015-09-01',
+        "url": "https://visualizacao.gerencianet.com.br/emissao/28333_2385_ZEMAL5/A5CL-28333-61428-LEENA9/28333-61431-HIRRA4",
+        "barcode": "00190.00009 01523.894002 00061.428181 5 65400000002000"
+      }
+    ]
+  }
+}

data/docs/carnet-update.md

@@ -0,0 +1,55 @@
+## Updating carnets
+
+### Changing the metadata
+
+You can update the `custom_id` and the `notification_url` of a carnet at any time.
+
+It's important to keep in mind that all the charges of the carnet will be updated. If you want to update only one charge, check [Updating charges](/docs/charge-update.md).
+
+```ruby
+params = {
+  id: 1004
+}
+
+body = {
+  notification_url: "http://yourdomain.com",
+  custom_id: "my_new_id"
+}
+
+gerencianet = Gerencianet.new(options)
+puts gerencianet.update_carnet_metadata(params: params, body: body)
+```
+
+If everything goes well, the response will be:
+
+```ruby
+{
+  "code": 200
+}
+```
+
+### Updating the expiration date of a parcel
+
+Only parcels with status `waiting` or `unpaid` can have expiration date set or updated:
+
+```ruby
+params = {
+  id: 1008
+}
+
+body = {
+  parcel: 1,
+  expire_at: "2020-12-12"
+}
+
+gerencianet = Gerencianet.new(options)
+puts gerencianet.update_parcel(params: params, body: body)
+```
+
+If everything goes well, the response will be:
+
+```ruby
+{
+  "code": 200
+}
+```

data/docs/carnets.md

@@ -0,0 +1,217 @@
+## Creating carnet billets
+
+Carnet is a payment method that generates a bundle of charges with the same payment information and customer.
+
+In order to generate a carnet, you'll need the items, the customer and the number of repeats (or parcels).
+
+The carnets can also be generated with the `metadata` attribute, just like in the banking billet, containing the `notification_url` and/or `custom_id`
+
+There are other optional params:
+
+- `expiration date` of the first charge
+- `post_office_service`, which tells if the carnet must be sent via post office service (to you or to your clients)
+- `split_items`, identifying if the total value must be splitted among the charges (defaults to `false`)
+- The carnet `instructions`
+
+### Required properties:
+
+```ruby
+body = {
+  expire_at: tomorrow.strftime,
+  items: [{
+    name: "Carnet Item 1",
+    value: 1000,
+    amount: 2
+  }],
+  customer: {
+    name: "Gorbadoc Oldbuck",
+    email: "oldbuck@gerencianet.com.br",
+    cpf: "04267484171",
+    birth: "1977-01-15",
+    phone_number: "5144916523"
+  },
+  repeats: 12,
+  split_items: false
+}
+```
+
+### Required properties plus metadata **(optional)**:
+
+```ruby
+body = {
+  expire_at: tomorrow.strftime,
+  items: [{
+    name: "Carnet Item 1",
+    value: 1000,
+    amount: 2
+  }],
+  customer: {
+    name: "Gorbadoc Oldbuck",
+    email: "oldbuck@gerencianet.com.br",
+    cpf: "04267484171",
+    birth: "1977-01-15",
+    phone_number: "5144916523"
+  },
+  repeats: 12,
+  metadata: {
+    custom_id: "my_id",
+    notification_url: "http://yourdomain.com"
+  }
+}
+```
+
+The `notification_url` property will be used for sending notifications once things happen with charges statuses, as when it's payment was approved, for example. More about notifications [here](https://github.com/gerencianet/gn-api-sdk-node/tree/master/docs/notifications.md). The `custom_id` property can be used to set your own reference to the carnet.
+
+### Required properties plus expiration date of the first charge **(optional)**:
+
+If you don't provide the expiration date of the first charge, the defaut value will be the current day + 8.
+
+```ruby
+body = {
+  items: [{
+    name: "Carnet Item 1",
+    value: 1000,
+    amount: 2
+  }],
+  customer: {
+    name: "Gorbadoc Oldbuck",
+    email: "oldbuck@gerencianet.com.br",
+    cpf: "04267484171",
+    birth: "1977-01-15",
+    phone_number: "5144916523"
+  },
+  repeats: 4,
+  expire_at: "2020-12-12"
+}
+```
+
+### Required properties plus post office service information **(optional)**:
+
+If you want the carnet to arrive at your house or at your client's house, you can count on Gerencianet's post office service. Just send an extra attribute:
+
+```ruby
+body = {
+  items: [{
+    name: "Carnet Item 1",
+    value: 1000,
+    amount: 2
+  }],
+  customer: {
+    name: "Gorbadoc Oldbuck",
+    email: "oldbuck@gerencianet.com.br",
+    cpf: "04267484171",
+    birth: "1977-01-15",
+    phone_number: "5144916523"
+  },
+  repeats: 4,
+  post_office_service: {
+    send_to: "customer"
+  }
+}
+```
+
+If `send_to` is set to *customer*, the carnet arrives at you customer's. If it is set to *seller*, just wait for it to arrive at your place!
+
+
+### split_items attribute **(optional)**
+
+By default, each parcel has the total value of the carnet. If you want to divide the total value among the parcels, change `split_items` property to *true*.
+
+```ruby
+var body = {
+  items: [{
+    name: "Carnet Item 1",
+    value: 1000,
+    amount: 2
+  }],
+  customer: {
+    name: "Gorbadoc Oldbuck",
+    email: "oldbuck@gerencianet.com.br",
+    cpf: "04267484171",
+    birth: "1977-01-15",
+    phone_number: "5144916523"
+  },
+  repeats: 4,
+  split_items: true
+}
+```
+
+### Setting instructions **(optional)**
+
+If you want the carnet billet to have extra instructions, it's possible to send a maximum of 4 different instructions with a maximum of 90 caracters, just as follows:
+
+```ruby
+body = {
+  items: [{
+    name: "Carnet Item 1",
+    value: 1000,
+    amount: 2
+  }],
+  customer: {
+    name: "Gorbadoc Oldbuck",
+    email: "oldbuck@gerencianet.com.br",
+    cpf: "04267484171",
+    birth: "1977-01-15",
+    phone_number: "5144916523"
+  },
+  repeats: 4,
+  instructions: [
+    "Pay only with money",
+    "Do not pay with gold"
+  ]
+}
+```
+
+### Finally, create the carnet:
+
+```ruby
+gerencianet.create_carnet(body: body)
+```
+
+Check out the response:
+
+```ruby
+{
+  "code": 200,
+  "data": {
+    "carnet_id": 6,
+    "cover": "https://visualizacao.gerencianet.com.br/emissao/28333_2385_ZEMAL5/A5CC-28333-61428-LEENA9/28333-61428-LEENA9",
+    "charges": [{
+        "charge_id": 357,
+        "parcel": "1",
+        "status": "waiting",
+        "value": 2000,
+        "expire_at": "2015-06-01",
+        "url": "https://visualizacao.gerencianet.com.br/emissao/28333_2385_ZEMAL5/A5CL-28333-61428-LEENA9/28333-61428-LEENA9",
+        "barcode": "00190.00009 01523.894002 00061.428181 1 64780000002000"
+      }, {
+        "charge_id": 358,
+        "parcel": "2",
+        "status": "waiting",
+        "value": 2000,
+        "expire_at": "2015-07-01",
+        "url": "https://visualizacao.gerencianet.com.br/emissao/28333_2385_ZEMAL5/A5CL-28333-61428-LEENA9/28333-61429-CORZE4",
+        "barcode": "00190.00009 01523.894002 00061.428181 8 65090000002000"
+      }, {
+        "charge_id": 359,
+        "parcel": "3",
+        "status": "waiting",
+        "value": 2000,
+        "expire_at": "2015-08-01",
+        "url": "https://visualizacao.gerencianet.com.br/emissao/28333_2385_ZEMAL5/A5CL-28333-61428-LEENA9/28333-61430-HIRRA4",
+        "barcode": "00190.00009 01523.894002 00061.428181 7 65400000002000"
+      }, {
+        "charge_id": 360,
+        "parcel": "4",
+        "status": "waiting",
+        "value": 2000,
+        "expire_at": "2015-09-01",
+        "url": "https://visualizacao.gerencianet.com.br/emissao/28333_2385_ZEMAL5/A5CL-28333-61428-LEENA9/28333-61431-HIRRA4",
+        "barcode": "00190.00009 01523.894002 00061.428181 5 65400000002000"
+      }
+    ]
+  }
+}
+```
+
+Notice that, as the `repeats` were set to 4, the output contains 4 charges with `waiting` status. The value of each charge is the sum of the items values, because the `split_items` property was set to *false*. Also notice that `expire_at` increases monthly.