QuickBooks Custom Fields Sample App

This is a sample Rails application that demonstrates how to integrate with QuickBooks APIs using OAuth 2.0 authentication and use custom fields.

Features

• OAuth 2.0 authentication with QuickBooks
• Custom Fields API integration via GraphQL

Prerequisites

• Ruby 3.4.7 or higher
• Rails 7.2.0 or higher
• QuickBooks Developer Account
• QuickBooks Online Account
• ngrok (for local development)

Required OAuth Scopes

The API requires the following OAuth scopes for full functionality:

• com.intuit.quickbooks.accounting - Access to QuickBooks accounting data
• app-foundations.custom-field-definitions - Required for Custom Fields API access
• app-foundations.custom-field-definitions.read - Required for Custom Fields API access

Test Company

Please note that the company you test this app with needs to have some customers and products so that an invoice with the defined custom field can be created.

Optional: Install ngrok

• Create an account at this link: https://dashboard.ngrok.com/get-started/setup/macos
• Run this command in the terminal : brew install ngrok
• Run the following command to add your authtoken to the default ngrok.yml configuration file then run
• ngrok config add-authtoken <TOKEN-VALUE>
• In the terminal run: ngrok http 3000for this project or replace the 3000 with the port number of your choosing
• You should now see a url in the Forwarding section in the terminal that starts with https and forwards to a local host adddress (https://234562f900c4.ngrok-free.app -> http://localhost:3000 ).
• Copy that url and paste in the QB_REDIRECT_URI in your .env file with /callback at the end as well as in your App's production redirect urls section

Setup

1. Clone the repository:

   git clone <repository-url>
   cd SampleApp-CustomFields-Ruby

2. Configure your QuickBooks app:

   • Go to Intuit Developer Portal
   • Create a new app or use an existing one
   • Enable Custom Fields and Accounting API scopes
   • Add your redirect URI (e.g., https://your-ngrok-url/callback)

3. Update configuration:

   • Open config/quickbooks.yml
   • Update the OAuth2 provider details with your app credentials:

   oauth:
     client_id: YOUR_CLIENT_ID
     client_secret: YOUR_CLIENT_SECRET
     redirect_uri: YOUR_REDIRECT_URI

   • Or, set them in environment variables: QB_CLIENT_ID, QB_CLIENT_SECRET, QB_REDIRECT_URI

4. Start ngrok:

   ngrok http 3000

5. Run the application in a separate terminal window:

   bundle exec rails server

Usage

1. Visit http://localhost:3000 in your browser
2. Step 1: Connect to QuickBooks - Click "Connect to QuickBooks" to authenticate
3. Step 2: Enter Custom Field Name - Enter the name of the custom field click "Create Custom Field" to generate the new definition
4. Step 3: Enter Info for a new Invoice - Select Customer, Item, Custom Field Value and enter an amount.
5. Step 4: Create Invoice - Click "Create Invoice" to create the specified invoice for your company.

API Endpoints

• / - Home page with multi-step workflow
• /qbo-login - Initiates OAuth flow
• /callback - OAuth callback handler
• /create_custom_field - Creates a custom field in QuickBooks
• /create_invoice - Creates an invoice in QuickBooks
• /logout - Logs out of QuickBooks

Error Handling

The application includes error handling for:

• OAuth authentication failures
• API request failures
• Missing parameters
• Invalid scopes

Common Issues

1. "Forbidden" Error

   • Ensure app-foundations.custom-field-definitions and app-foundations.custom-field-definitions.read scopes are included in OAuth authorization
   • Check that all required scopes are configured in quickbooks.yml

2. "Invalid URI or environment" Error

   • Verify Environment is set to "production"
   • Check that RedirectUri matches your QuickBooks app configuration

3. GraphQL Query Errors

   • Mutation uses AppFoundationsCreateCustomFieldDefinition
   • In the variables file, "associatedEntity" should be set to "SALE_INVOICE"

4. Nothing happens after creating a custom field

   • Make sure you have customers and items in your company

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Support

For support, please visit the Intuit Developer Community or create an issue in this repository.