Vision ScanBarcode Intelligence
Start evaluation

Cloud REST with Ruby

Use Net::HTTP against the experimental Cloud API; VisionScan does not publish a native Ruby scanner gem.

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

Prerequisites

  • Ruby 3.2 or newer
  • VISIONSCAN_CLOUD_URL
  • VISIONSCAN_ACCESS_TOKEN
  • A supported image file

1. Use the Ruby standard library

Use the Ruby standard library
ruby --version  # Ruby 3.2+

No VisionScan gem is required for the REST contract.

2. Build a request

Build a request
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch('VISIONSCAN_ACCESS_TOKEN')}"
request["Content-Type"] = "application/json"

Never expose the token to browser code or application logs.

3. Upload and submit

Upload and submit
upload = post_json("/v1/uploads", idempotencyKey: SecureRandom.uuid, contentBase64: Base64.strict_encode64(image), contentType: "image/png")
job = post_json("/v1/jobs", idempotencyKey: SecureRandom.uuid, uploadIds: [upload.fetch("uploadId")], profile: "still-image-dense")
status = get_json("/v1/jobs/#{job.fetch('jobId')}")

Helpers must require TLS in production, apply timeouts, and raise on non-2xx status.

Errors and recovery

ConditionResolution
JSON parse failureCapture the status and request correlation metadata without logging tokens or image content.
ENGINE_ADAPTER_UNAVAILABLEWait for a production-certified Cloud engine adapter or evaluate the Android AAR.

Production checklist

  • Require HTTPS outside loopback development
  • Set open and read timeouts
  • Validate response fields with fetch
  • Do not claim a native Ruby gem

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.