Search QuickBooks, or sync records to it

PUT/v1/api/store/{team_slug}/setting/external_integration/{id}/public_action

v1InternalOperation ID v1_public_external_integration_public_action

Internal

Built for YoPrint's own apps, not for integrations. It is listed so the reference is complete; don't build on it, and use the other operations in this section.

Built for YoPrint's web app, which uses it to link YoPrint records to QuickBooks Online and to push them there. Only QuickBooks Online answers it; other integrations answer 422 invalid_public_action. Send an action:

• query_customer, query_vendor: up to 20 QuickBooks records whose display name contains query. query_invoice, query_bill, query_purchase_order: up to 20 whose document number contains it. Records come as QuickBooks returns them.
• sync_order and sync_purchase_order: queue a sync to QuickBooks of 1 to 100 sales orders or purchase orders, by their ids in objects. The answer is data: null; the sync runs afterwards, on exactly the records YoPrint checked.

Each action checks a permission before anything else, so a member without Manage Settings who lacks it gets 403 user_is_not_authorized (see Permission). The {id} is the integration's id from the list.

Permission

The team owner and members with Manage Settings can run every action. Other members need, per action: query_customer, permission to view all customers (view_all_customer); query_vendor, permission to view vendors (view_vendor); sync_order, permission to view all sales orders (view_all_order) or their own (view_self_order), and every order in objects must be one they can view (their own: created by them or assigned to them); sync_purchase_order, the same with purchase orders (view_all_po, view_self_po). query_invoice, query_bill and query_purchase_order need Manage Settings.

Side effects

• Calls QuickBooks Online. The sync_ actions queue writes of your records to QuickBooks.

Path parameters

• team_slugstringrequired

  Your team slug, shown as Team ID next to your API key in Profile.

  • Example your-team
• idstringrequired

  The QuickBooks Online integration. Its hash id from an earlier answer; there is no unique key for it.

  • Example QF3K07jFrQ1P1B

Request body

application/json, required.

• actionstringrequired
  • One of: "query_customer", "query_vendor", "query_invoice", "query_bill", "query_purchase_order", "sync_order", "sync_purchase_order"
• objectsarray of strings or integers

  For the sync_ actions: 1 to 100 sales order or purchase order ids, as this API returns them. Don't send document numbers such as 1001: a whole number, or a string of digits only, is read as YoPrint's internal record number and can name a different record.

• querystring

  For the query_ actions: text the display name contains.

More examples (1)

Sync two sales orders

curl

curl -X PUT 'https://secure.yoprint.com/v1/api/store/your-team/setting/external_integration/QF3K07jFrQ1P1B/public_action' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "action": "sync_order",    "objects": [      "zGZRXNGeh5cs6M",      "VDG1ZqxwDQCaZ0"    ]  }'

Response

200Successful response.

A 200 answer can still be a refusal

Check success (and the fields named below) as well as the HTTP status:

• The owner or a member with Manage Settings sends an action that is missing or not one of the seven: HTTP 200 with an empty body (not JSON), and nothing happens. Fix: Send an action from the list.

• dataarray of objects | nullrequired

  For a query_ action, up to 20 QuickBooks records as QuickBooks returns them. For a sync_ action, null.

• statusintegerrequired
• successbooleanrequired

Errors

• 401The API key is missing or wrong (unauthenticated).

• 403You are not allowed to do this. api_access_not_in_plan: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only {"message": "Insufficient Permission"}. Other refusals use the error envelope, with unauthorized or user_is_not_authorized.

  When

  You are not the owner, have no Manage Settings, and lack the permission the action needs (or can't view one of the records in objects). Members without Manage Settings get this for other integrations and for an action that is missing or unknown, too. error.code user_is_not_authorized, "Your role does not allow this integration action. Ask your team owner to review your permissions." (for a sales order you can't view, the message names sales order permissions). Nothing is synced.

  Fix

  Ask the team owner to give your permission group the permission the action needs, or leave out records you can't view.

• 404Not found. page_not_found: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. code: null, with a message that starts "No query results for": there is no record with that id.

• 422The request was refused and changed nothing. validation_failed lists what to fix in error.fields; other codes name a business rule, explained in error.message. A few checks answer with only {"message": "..."}. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer connect_timeout ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.

  When

  sync_order or sync_purchase_order: an entry in objects is not one of your team's ids or a positive whole number: error.code unreadable_records, "Some selected records could not be read. Reload the page and try again." Nothing is synced.

  Fix

  Send the ids this API returns.

  When

  The integration is not QuickBooks Online (invalid_public_action), or objects is empty or has more than 100 ids (validation_error).

  Fix

  Use the QuickBooks integration's id and 1 to 100 records.

  When

  A Shopify order can't be synced to QuickBooks (validation_error).

  Fix

  Leave Shopify orders out.

  When

  query is not a string, or objects is not a list on a query_ action (validation_failed); or the integration is retired or not in your plan.

  Fix

  Send query as text and objects as a list of ids.

Notes

• AI apps (MCP connections) can't call this operation: they get 403 agent_operation_not_available. Use a personal API key.

Example request

curl

curl -X PUT 'https://secure.yoprint.com/v1/api/store/your-team/setting/external_integration/QF3K07jFrQ1P1B/public_action' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "action": "query_customer",    "query": "Northwind"  }'

Example response 200

Response

{
  "data": [
    {
      "DisplayName": "Northwind Apparel",
      "Id": "58"
    }
  ],
  "status": 200,
  "success": true
}