Vision ScanBarcode Intelligence
Start evaluation

Cloud REST with JavaScript

Use standard fetch against the experimental Cloud API; VisionScan does not publish a native npm scanner package.

Status
Experimental
Integration
Cloud REST client
Distribution
HTTP API
Version
0.1.0-RC4

Prerequisites

  • Node.js 20 or a modern browser server environment
  • VISIONSCAN_CLOUD_URL
  • VISIONSCAN_ACCESS_TOKEN
  • A PNG, JPEG, or WebP image

1. Use the platform HTTP client

Use the platform HTTP client
# Node.js 20 includes fetch; no VisionScan npm package is required.

Keep bearer-token calls on a trusted server, not in public browser JavaScript.

2. Prepare headers

Prepare headers
const headers = {
  Authorization: `Bearer ${process.env.VISIONSCAN_ACCESS_TOKEN}`,
  "Content-Type": "application/json",
};

Reject startup when the token or base URL is absent.

3. Upload and submit

Upload and submit
const upload = await post("/v1/uploads", { idempotencyKey: crypto.randomUUID(), contentBase64: image.toString("base64"), contentType: "image/png" });
const job = await post("/v1/jobs", { idempotencyKey: crypto.randomUUID(), uploadIds: [upload.uploadId], profile: "still-image-dense" });
const status = await get(`/v1/jobs/${job.jobId}`);

The post/get helpers must check response.ok, apply timeouts, and parse structured errors.

Errors and recovery

ConditionResolution
401 or 403Refresh the bearer token and confirm it grants cloud-scan for the intended tenant and site.
Request times outAbort the fetch, retain the idempotency key, and retry with bounded backoff.

Production checklist

  • Keep credentials server-side
  • Use AbortController timeouts
  • Reuse idempotency keys only for identical retries
  • Do not advertise this REST client as an npm SDK

Public contract reference

These are the callable methods and HTTP operations used by this guide. Inputs, results, lifecycle rules, and denial behavior are part of the versioned customer contract.

Cloud upload contract

Upload bytes are authenticated, bounded, MIME-checked, idempotent, and tenant-scoped.

POST /v1/uploads

http

Persist one validated image and return a tenant-scoped upload identifier.

Inputs for POST /v1/uploads
InputTypeRequiredMeaning
AuthorizationBearer tokenYesProduction RS256 token with bounded time claims and cloud-scan entitlement.
idempotencyKeyUUID/stringYesTenant-scoped key reused only for an identical retry.
contentBase64base64 stringYesLocally bounded PNG, JPEG, or WebP bytes.
contentTypestringYesimage/png, image/jpeg, or image/webp matching the file magic bytes.
Result
2xx JSON containing uploadId and non-sensitive upload metadata.
Lifecycle
Upload before creating a job; retain the idempotency key for retries of the same bytes.
Trust boundary
Tenant and site come only from the verified token; request bodies cannot override tenant scope.
Failure behavior
  • 401/403 for invalid or unentitled identity.
  • 409 for a reused key with different content.
  • 4xx for invalid MIME, magic bytes, base64, or size; 429 for quota limits.

Cloud job creation contract

A job references same-tenant uploads and selects a bounded scan profile.

POST /v1/jobs

http

Create an asynchronous scan job from one or more previously accepted uploads.

Inputs for POST /v1/jobs
InputTypeRequiredMeaning
idempotencyKeyUUID/stringYesTenant-scoped key for identical job retries.
uploadIdsstring[]YesExisting upload IDs owned by the authenticated tenant and site.
profilestringYesAn allowlisted profile such as still-image-dense.
callbackHTTPS URLNoOptional policy-validated callback; production delivery requires the documented callback controls.
Result
2xx JSON containing jobId, queued status, and correlation metadata.
Lifecycle
Create after uploads succeed, then poll status until completed or failed.
Trust boundary
Callbacks reject non-HTTPS and non-global destinations, pin validated addresses, follow no redirects, and HMAC-sign payloads.
Failure behavior
  • Cross-tenant or unknown uploads are denied.
  • 409 reports idempotency conflict; 429 reports quota pressure; invalid profiles fail validation.

Cloud job status contract

Status retrieval distinguishes completed, failed, and unavailable-engine outcomes from an empty scan.

GET /v1/jobs/{jobId}

http

Read the authenticated tenant's job state, receipt, structured error, and callback delivery state.

Inputs for GET /v1/jobs/{jobId}
InputTypeRequiredMeaning
jobIdpath stringYesThe job identifier returned by POST /v1/jobs.
AuthorizationBearer tokenYesThe same tenant/site scope that owns the job.
Result
JSON status that becomes completed or failed; completed identity evidence remains GTIN-first and preserves review-required OCR provenance.
Lifecycle
Poll with bounded backoff and stop on a terminal state.
Trust boundary
Do not log bearer tokens, encoded images, or sensitive receipt payloads; retain only non-sensitive correlation metadata.
Failure behavior
  • Cross-tenant and unknown identifiers do not expose another tenant's data.
  • ENGINE_ADAPTER_UNAVAILABLE is a failed job, not a successful scan with zero observations.
  • Unknown response shapes fail closed.

Review the release support matrix before deployment. Support status and contract failure behavior remain authoritative even when an example is copied.