NAME

Business::Fixflo - Perl library for interacting with the Fixflo API (https://www.fixflo.com)

VERSION

0.08

DESCRIPTION

Business::Fixflo is a library for easy interface to the fixflo property repair service, it implements all of the functionality currently found in the service's API documentation: http://www.fixflo.com/Tech/WebAPI

You should refer to the official fixflo API documentation in conjunction with this perldoc, as the official API documentation explains in more depth some of the functionality including required / optional parameters for certain methods.

Please note this library is a work in progress

SYNOPSIS

    # agency API:
    my $ff = Business::Fixflo->new(
        custom_domain => $domain,
        api_key       => $api_key,

        # if api_key is not supplied:
        username      => $username,
        password      => $password,
    );

    my $issues   = $ff->issues,
    my $agencies = $ff->agencies,

    while ( my @issues = $issues->next ) {
        foreach my $issue ( @issues ) {
            $issue->get;
            ...
        }
    }

    my $issue = $ff->issue( $id );
    my $json  = $issue->to_json;

    # third party API:
    my $ff = Business::Fixflo->new(
        api_key       => $third_party_api_key,
        username      => $third_party_username,
        password      => $third_party_password,
    );

    my $agency = Business::Fixflo::Agency->new(
        client     => $ff->client,
        AgencyName => 'foo',
    );

    $agency->create;
    $agency->delete;

ERROR HANDLING

Any problems or errors will result in a Business::Fixflo::Exception object being thrown, so you should wrap any calls to the library in the appropriate error catching code (TryCatch in the below example):

    use TryCatch;

    try {
        ...
    }
    catch ( Business::Fixflo::Exception $e ) {
        # error specific to Business::Fixflo
        ...
        say $e->message;  # error message
        say $e->code;     # HTTP status code
        say $e->response; # HTTP status message
    }
    catch ( $e ) {
        # some other failure?
        ...
    }

You can view some useful debugging information by setting the FIXFLO_DEBUG env varible, this will show the calls to the Fixflo endpoints as well as a stack trace in the event of exceptions:

    $ENV{FIXFLO_DEBUG} = 1;

ATTRIBUTES

username

Your Fixflo username (required if api_key not supplied)

password

Your Fixflo password (required if api_key not supplied)

api_key

Your Fixflo API Key (required if username and password not supplied)

custom_domain

Your Fixflo custom domain, defaults to "api" (which will in fact call the third party Fixflo API)

url_suffix

The url suffix to use after the custom domain, defaults to fixflo.com

client

A Business::Fixflo::Client object, this will be constructed for you so you shouldn't need to pass this

METHODS

    issues
    agencies
    properties
    property_addresses
    issue
    agency
    property
    property_address
    quick_view_panels

Get a [list of] issue(s) / agenc(y|ies) / propert(y|ies) / property address(es):

    my $paginator = $ff->issues( %query_params );

    my $issue     = $ff->issue( $id );

Will return a Business::Fixflo::Paginator object (when calling endpoints that return lists of items) or a Business::Fixflo:: object for the Issue, Agency, etc.

%query_params refers to the possible query params as shown in the currency Fixflo API documentation. For example: page=[n]. You can pass DateTime objects through and these will be correctly changed into strings when calling the API:

    # issues raised in the previous month
    my $paginator = $ff->issues(
        CreatedSince  => DateTime->now->subtract( months => 1 ),
    );

    # properties in given postal code
    my $paginator = $ff->properties(
        Keywords => 'NW1',
    );

Refer to the Business::Fixflo::Paginator documentation for what to do with the returned paginator object.

Note the property method can take a flag to indicate that the passed $id is an external reference:

    my $Property = $ff->property( 'P123',1 );

EXAMPLES

See the t/002_end_to_end.t test included with this distribution. you can run this test against the fixflo test server (requires ENV variables to set the Fixflo credentials)

SEE ALSO

Business::Fixflo::Address

Business::Fixflo::Agency

Business::Fixflo::Client

Business::Fixflo::Issue

Business::Fixflo::Paginator

Business::Fixflo::Property

Business::Fixflo::PropertyAddress

Business::Fixflo::QuickViewPanel

http://www.fixflo.com/Tech/Api/V2/Urls

AUTHOR

Lee Johnson - leejo@cpan.org

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. If you would like to contribute documentation, features, bug fixes, or anything else then please raise an issue / pull request:

    https://github.com/leejo/business-fixflo

cpanm Business::Fixflo

perl -MCPAN -e shell
install Business::Fixflo