Pix Sicoob - Easy to use interface for integrating with Sicoob Pix API in your Flutter Apps.


Logo

This package offers an easy-to-use interface for integrating with Sicoob Pix API. With this package, you can get transaction information quickly and efficiently in your Flutter apps.
Explore the docs »

Report Bug · Request Feature


License Pub Points Contributors Forks

Pub Publisher


Table of Contents
  1. About The Project
  2. How To Use
  3. Features
  4. Contributing
  5. License
  6. Contact
  7. Acknowledgements

About The Project



This package offers an easy-to-use interface for integrating with Sicoob's Pix API. With this package, you can get transaction information quickly and efficiently in your Flutter apps.

(back to top)

Pre Requirements

  • Key Pix registered with Sicoob
  • Exclusive for legal entities
  • Valid certificate issued by an external CAs complying with the international standard x.509
  • Registration on the Sicoob Developers Portal

Getting Started

To install This package in your project you can follow the instructions below:

a) Add in your pubspec.yaml:

 dependencies:
    pix_sicoob: <last-version>

b) or use:

 dart pub add pix_sicoob

(back to top)

How To Use

This package is ready for get transactions information quickly!

  1. First instantiate the class passing the appropriate parameters
  2. Second get the token
  3. Third fetch your Pix transactions quickly!

Instantiate the class

final pixSicoob = PixSicoob(
  clientID:'CLIENT_ID',
  certificateBase64String: 'X509_Parsed_TO_BASE64_STRING',
  /*
  This package offer a method to parses file certificate to base64 String
   Method:
    final certBase64String = pixSicoob.certFileToBase64String(
       pkcs12CertificateFile: File('test/cert/cert.pfx'),
       );
  */

  certificatePassword: 'CERTIFICATE_PASSWORD',
);

Get the token

final token = await pixSicoob.getToken();

Fetch your Pix transactions quickly!

final listPix = await pixSicoob.fetchTransactions(
  token: token,
);
// Returns the transactions from the last 4 days

For more examples, please refer to the Documentation

(back to top)

Features

  • ✅ Authentication: Securely retrieve OAuth2 tokens from Sicoob.
  • ✅ Fetch Transactions: Retrieve Pix transactions within a specified date range.
  • ✅ Certificate Management: Easily convert X.509 certificates to Base64 strings.

(back to top)

Use cases

Convert certificate file to Base64String

final certBase64String = pixSicoob.certFileToBase64String(
   pkcs12CertificateFile: File('test/cert/cert.pfx'));

Request a token

final token = await pixSicoob.getToken();

Fetch Pix Transactions

  • Default Time Range
final listPix = await pixSicoob.fetchTransactions(
  token: token,
);
//Returns the last 4 days transactions
  • Custom Time Range
final listPix = await pixSicoob.fetchTransactions(
  token: token,
  dateTimeRange: DateTimeRange(
    start: DateTime.now().subtract(Duration(days: 360)),
    end: DateTime.now(),
  );
);
//Returns the transactions of the specified date range

Handling errors

This package provides structured ways to map and handle different types of errors. Below are common error keys you might encounter:

  • the-certificate-password-is-incorrect: The certificate password provided is incorrect.
  • invalid-certificate-file: The provided certificate file is invalid.
  • invalid-certificate-base64string: The certificate Base64 string is malformed or invalid.
  • empty-certificate-password: The certificate password cannot be empty.
  • empty-certificate-base64string: The certificate Base64 string cannot be empty.
  • could-not-find-the-certificate-path: The system could not locate the certificate file at the specified path.
  • client-id-cannot-be-empty: The Client ID must be provided.
  • date-range-must-be-in-the-same-month: Filtering is restricted to within the same calendar month.

Troubleshooting

Common Issues

  1. Certificate Parsing Errors:
    • Ensure your .pfx or .p12 certificate is valid and not expired.
    • Double-check the password; it must match the one set when the certificate was exported.
  2. Connectivity Issues:
    • Ensure your application has internet access and can reach api.sicoob.com.br.
    • Verify that your Client ID is correctly registered on the Sicoob Developers Portal.
  3. Authentication Failures:
    • Confirm that the certificate corresponds to the Client ID used.
    • Ensure you are using the correct production or sandbox URLs (currently defaults to production).

Contributing

🚧 Contributing Guidelines - Currently being updated 🚧

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the appropriate tag. Don't forget to give the project a star! Thanks again!

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

Remember to include a tag, and to follow Conventional Commits and Semantic Versioning when uploading your commit and/or creating the issue.

(back to top)

License

Distributed under the MIT LICENSE.txt for more information.

(back to top)

Architecture

Check the architecture used in the project ARCHITECTURE.md

(back to top)

Acknowledgements

Thank you to all the people who contributed to this project. Without you, this project would not be here today.

(back to top)

Maintained by


Built and maintained by AcxTech Sistemas.

Libraries

pix_sicoob