Updating Resources with RAVE Connections

31 min

rave connections let you keep your paccurate resource library in sync with external data sources — whether that's a dimensioning system like qboid, a wms, an erp, or any rest api that can return json once a connection is configured, you can pull data in on a schedule, trigger an import manually, or push data directly via the rave rest api rave connections are available to premium & enterprise plans only please reach out to your customer success manager to enable them on your account this guide walks through setting up a connection, understanding how data is mapped, and using the api to read and write resource data what is a rave connection? a rave connection is a bridge between an external data source and a paccurate resource library list (items, cartons, or orders) each connection defines where to pull data from (a third party api endpoint) how to authenticate with that source how to translate the incoming data fields into paccurate resource fields (schema map) when to run automatically (scheduling) which resource to create or update each connection also generates its own api credentials, enabling direct programmatic writes to the resource without going through the third party source at all rave is an acronym for “really awesome value extractor” — paccurate decided to keep the working name because our customers are awesome, and so is their data \ step 1 — create a connection navigate to your plan's rave connections page https //manage paccurate io/plans/\<plan id>/rave connections click new rave connection to open the connection editor general settings field description name a short, descriptive label for this connection account which paccurate account to use for resource access resource type the type of resource to populate items, cartons, or orders new resource base name prefix used when creating a new resource (e g qboid items) resource to update leave blank to always create a new resource, or select an existing resource to overwrite/update it on each sync connection details this section tells paccurate where to pull data from and how to authenticate with the external source field description third party api url the fully qualified endpoint url that returns the source data third party api key stored credential, accessible as {{ api key }} in the headers template third party api token stored credential, accessible as {{ api token }} in the headers template api headers template valid json sent as headers on each webhook request use {{ api key }} and {{ api token }} as placeholders example headers template { "authorization" "bearer {{ api token }}", "x api key" "{{ api key }}" } step 2 — map your data this is where you tell paccurate how to translate fields from your external source into resource properties schema root path the name of the top level property in the api response that contains the array of records to import for example, if the api returns { "scans" \[ { "id" 1, "l" 10, "w" 8, "h" 6 } ] } …then your schema root path is scans schema map a json object where each key is a paccurate resource property and each value is the corresponding field name in your source data dot notation is supported for nested fields format { "\<paccurate property>" "\<source field>" } example (qboid → paccurate items) { "refid" "id", "weight" "weight", "sequence" "barcode", "dimensions x" "h", "dimensions y" "w", "dimensions z" "l", "properties batt" "attributes batt", "properties fold" "attributes fold item", "properties frgl" "attributes frgl", "properties hazmat" "attributes hazmat" } available paccurate item properties property required type refid ✅ yes integer or string dimensions x ✅ yes float dimensions y ✅ yes float dimensions z ✅ yes float weight no float name no string color no string sequence no string properties no json object step 3 — set a schedule (optional) if you want paccurate to automatically pull from the external source on a recurring basis, configure scheduling field description start date & time the first time the sync should run; all future runs are calculated from this baseline sync frequency hourly, daily, weekly, or monthly if you don't need automatic scheduling, you can skip this and trigger syncs manually or via the api step 4 — save and get your api secret click create after saving, paccurate will generate an api secret for this connection ⚠️ copy your secret immediately it will not be shown again the first 10 characters (the secret stem ) are saved and displayed in the editor so you can confirm which secret is active you can regenerate credentials at any time from the connection editor regenerating immediately invalidates the previous values triggering an import manually to run a one time pull from the third party source open the connection in pacmanage go to connection details click trigger webhook after the import runs, check the connection log to confirm success and see how many records were processed newly imported resources appear in the resource library under the applicable type (items, cartons, orders), prefixed with the new resource base name you set unit conversions the rave rest api supports automatic unit conversion during data ingestion pass conversion parameters as url parameters or request headers on any post, put, or patch request conversions are applied after the schema map is evaluated, so values are stored already in the converted unit parameter header values converts dim conv x paccurate dim conv mm to in, in to mm dimensions x/y/z weight conv x paccurate weight conv gr to lb, lb to gr weight example url https //manage paccurate io/rave api/your public api id/rest?dim conv=mm to in\&weight conv=gr to lb using the rave rest api in addition to scheduled and manual webhook imports, each rave connection exposes a rest api that lets you push data directly into a resource — no third party source required this is useful for integrations where your system wants to send data to paccurate in real time authentication pass your api secret on every request using one of two methods url parameter ?pac api secret=your secret here request header x paccurate api secret your secret here base urls purpose url trigger webhook import https //manage paccurate io/rave api/{public api id}/webhook direct resource manipulation https //manage paccurate io/rave api/{public api id}/rest api reference get — trigger webhook import triggers a pull from the third party api url configured in connection details and imports the result into the connected resource behaves identically to clicking trigger webhook in pacmanage if resource to update is blank → creates a new resource if resource to update is set → overwrites that resource with the imported data endpoint \ get \ /rave api/{public api id}/webhook post — create or upsert send data directly to create a new resource or upsert rows into an existing one no resource to update set → creates a new resource from the payload resource to update set → upserts into the existing resource (same behavior as patch) endpoint \ post \ /rave api/{public api id}/rest response { "packresourceid" 12345, "status" "success" } create a new resource with a single item { "payload" { "id" 325144, "l" 111, "w" 106, "h" 10, "weight" 55793, "barcode" "", "attributes" { "stackable" "yes" } } } create a new resource with multiple items { "payload" \[ { "id" 325144, "l" 111, "w" 106, "h" 10, "weight" 55793, "attributes" { "stackable" "yes" } }, { "id" 325053, "l" 240, "w" 170, "h" 87, "barcode" "0901b001", "attributes" { "foldable" true } } ] } upsert into an existing resource (with row matching) use row key to specify which field(s) should be used to match incoming rows against existing rows use mapped property names (e g refid, not id) matched rows are updated; unmatched rows are inserted { "payload" \[ { "id" 325144, "weight" 50, "attributes" { "foldable" true } }, { "id" 325053, "weight" 100, "attributes" { "foldable" true } }, { "id" 325131, "l" 141, "w" 49, "h" 32, "barcode" "", "attributes" { "other" "orientation lock" } } ], "row key" \["refid"] } in this example, the first two records exist in the resource and will be updated the third is new and will be inserted — which is why it requires a full/complete object put — overwrite replaces the entire contents of an existing resource with the payload data resource to update must be set payload must be an array of complete objects (no partial records) all existing rows are removed before the new data is written endpoint \ put \ /rave api/{public api id}/rest response { "status" "success" } overwrite a resource with three items { "payload" \[ { "id" 325144, "l" 111, "w" 106, "h" 10, "weight" 55793, "barcode" "", "attributes" { "stack item" "ruleneeded" } }, { "id" 325053, "l" 240, "w" 170, "h" 87, "barcode" "0901b001", "attributes" { "stack item" "internalspace" } }, { "id" 325131, "l" 141, "w" 49, "h" 32, "barcode" "", "attributes" { "other" "orientation lock" } } ] } patch — upsert / append adds or merges rows into an existing resource without clearing it first resource to update must be set with row key incoming rows are matched against existing rows matches are merged; non matches are inserted as new rows without row key all incoming rows are appended to the end of the resource without any deduplication row key can be passed three ways method example body property "row key" \["refid"] url parameter ?row key=\["refid"] header x paccurate rave row key \["refid"] endpoint \ patch \ /rave api/{public api id}/rest response { "status" "success" } upsert with row matching { "payload" \[ { "id" 325144, "weight" 50, "attributes" { "foldable" true } }, { "id" 325053, "weight" 100, "attributes" { "foldable" true } }, { "id" 325131, "l" 141, "w" 49, "h" 32, "barcode" "", "attributes" { "other" "orientation lock" } } ], "row key" \["refid"] } append without matching (no row key) { "payload" \[ { "id" 325999, "l" 50, "w" 40, "h" 20, "weight" 1000, "barcode" "new item 001", "attributes" {} } ] } response codes & errors applies to all post, put, and patch requests to /rave api/{public api id}/rest http status response body when it happens 200 ok { "status" "success" } (post also includes "packresourceid") the write completed successfully 200 ok { "status" "failure" } (post also includes "packresourceid" null) the request was authenticated but the write didn't complete — e g resource to update isn't set for put/patch, or the upsert/overwrite failed internally check the connection log for details 400 bad request { "error" "invalid json payload" } payload could not be parsed as json 400 bad request { "error" "invalid row key format" } row key (body, url parameter, or header) was not a string or a json array 401 unauthorized { "error" "unauthorized" } the api secret is missing, incorrect, or doesn't match the public api id in the url ⚠️ a 200 response does not guarantee the write succeeded — always check the status field in the response body, not just the http status code quick reference which action should i use? goal method pull from external api (scheduled or manual) \ get \ /webhook create a brand new resource from scratch \ post \ /rest (no resource to update set) replace everything in a resource \ put \ /rest add new rows without touching existing rows \ patch \ /rest (no row key) update specific rows by matching key, insert new \ patch \ /rest with row key update specific rows or insert, via post \ post \ /rest with row key and resource to update set