pyBRPost 1.0.1
Python module to query Brazilian Post Office regarding shipping methods
License: MIT License

# Brazilian Post Office Module

This module is to help whoever needs a API to query the brazilian post office to know:
1. When the package will arrive
2. How much will it cost
3. Possibility to query different shipping methods

# Installation

To install this module simply add it via pip

    pip install pyBRPost

It requires some extra modules:

    pip install requests xmltodict

# Usage

To use this module all you need is to configure the package information and execute the get_fare()
method. Here's a simple test:

    from br_posts import fare, options

    tst = fare.Fare()
    tst.requestServices = [
        options.Service.SEDEX_10_RETAIL,
        options.Service.SEDEX_12,
        options.Service.SEDEX_CASH,
        options.Service.SEDEX_RETAIL,
        options.Service.SEDEX_TODAY_RETAIL,
        options.Service.PAC_CASH,
        options.Service.PAC_RETAIL
    ]
    tst.dimensions['weight'] = 0.875
    tst.dimensions['length'] = 16
    tst.dimensions['width'] = 11
    tst.dimensions['height'] = 10
    tst.dimensions['diameter'] = 10
    tst.cepDestination = '09571000'
    tst.cepOrigin = '24738791'
    tst.value = 2500.75
    tst.packageFormat = options.ObjectType.BOX
    tst.extras['receiving_warning'] = True
    try:
        fare_return = tst.get_fare()
    except Exception as error:
        print(error)
        exit(-1)
    for ret in fare_return:
        print('Service: {serv}'.format(serv=ret['service']))
        error_code = ret['error_code']
        if error_code != 0:
            print('Error ({code}): {desc}'.format(code=error_code, desc=ret['error_msg']))
        else:
            print('Time: {time} day{mult}'.format(time=ret['delivery_time'], mult='s' if ret['delivery_time'] > 1 else ''))
            print('Value: R$ {val}'.format(val=ret['value']))
            print('Deliver on saturday? {sat}'.format(sat=ret['delivery_saturday']))
            print('Delivery on: {delivery_date}'.format(
                delivery_date=tst.get_estimated_delivery_day(add_days=1,
                                                             travel_days=ret['delivery_time'],
                                                             deliver_on_saturday=ret['delivery_saturday']).strftime('%d/%m/%Y')))
            print('')

This is a little big, so let's drill down this example in 3 easy steps:

## Import

    from br_posts import fare, options

Those are the basic imports, there's also a 'ship.errors' import that you can use to capture
the exceptions.

The 'ship.options' file contains the enum classes Service and ObjectType that, are responsible to configure
the methods to send the package, and the format of the package.

Those are the options you have for the Service enum:
* SEDEX_RETAIL - Common Sedex type
* SEDEX_TO_CHARGE - Sedex to be charged on the receiver
* SEDEX_10_RETAIL - Sedex 10
* SEDEX_TODAY_RETAIL - Sedex on the same day
* SEDEX_CASH - Sedex payment on cash
* SEDEX_PAYMENT_ON_DELIVERY - Sedex payment on delivery
* SEDEX_12 - Sedex 12 
* PAC_RETAIL - Common PAC
* PAC_CASH - PAC on cash
* PAC_PAYMENT_ON_DELIVERY - PAC with payment on delivery

And those are the options you have for the ObjectType enum:
* BOX - Most common of Sedex for big products
* ROLL - Can be sometimes referred as "prism"
* LETTER - Anything that can be sent as ane Envelope

You can find more of those options on the [Correios site](http://correios.com.br/).

## Setup

After importing, you need to instantiate a 'ship.fare.Fare' object, and create the initial setup:

    tst = fare.Fare()
    tst.requestServices = [
        options.Service.SEDEX_10_RETAIL,
        options.Service.SEDEX_12,
        options.Service.SEDEX_CASH,
        options.Service.SEDEX_RETAIL,
        options.Service.SEDEX_TODAY_RETAIL,
        options.Service.PAC_CASH,
        options.Service.PAC_RETAIL
    ]
    tst.dimensions['weight'] = 0.875
    tst.dimensions['length'] = 16
    tst.dimensions['width'] = 11
    tst.dimensions['height'] = 10
    tst.dimensions['diameter'] = 10
    tst.cepDestination = '09571000'
    tst.cepOrigin = '24738791'
    tst.value = 2500.75
    tst.packageFormat = options.ObjectType.BOX
    tst.extras['receiving_warning'] = True

Of all those options, only those are mandatory:
* requestService
* dimenstions
* cepDestination
* cepOrigin
* packageFormat

If some of those are missing, or wrong, there's 2 possible exceptions that will be thrown when
executing the get_fare() method:
* InvalidParameterError
* MissingParametersError

## Getting the fare

After importing and setting up the information to query, you should call the get_fare() method:

    try:
        fare_return = tst.get_fare()
    except Exception as error:
        print(error)
        exit(-1)

This method will POST the Correios API with the setup you created before, if there's anything wrong
with the setup it'll raise an exception. If everything works out smoothly, it'll return a list
with all the results (usually one for 'requestService'), and you can easily read them as a dictionary:

     for ret in fare_return:
        print('Service: {serv}'.format(serv=ret['service']))
        error_code = ret['error_code']
        if error_code != 0:
            print('Error ({code}): {desc}'.format(code=error_code, desc=ret['error_msg']))
        else:
            print('Time: {time} day{mult}'.format(time=ret['delivery_time'], mult='s' if ret['delivery_time'] > 1 else ''))
            print('Value: R$ {val}'.format(val=ret['value']))
            print('Deliver on saturday? {sat}'.format(sat=ret['delivery_saturday']))

There's one "gift" inside this package that has **nothing** to do with the Correios API, an 
estimated delivery method, that you can call to get a possible date on the delivery: 

            print('Delivery on: {delivery_date}'.format(
                delivery_date=tst.get_estimated_delivery_day(add_days=1,
                                                             travel_days=ret['delivery_time'],
                                                             deliver_on_saturday=ret['delivery_saturday']).strftime('%d/%m/%Y')))
            print('')