Authentication

Send your API key with every call. The key decides which store you read and which endpoints you may call.

Send the key

Authorization: Bearer <your key>

Send it on every request, over HTTPS. Only the status calls and the OpenAPI document need no key.

• No key, or a key that is not a key: 401 unauthorized.
• A revoked key: 401 key_revoked.
• A key that may not call this endpoint: 403 capability_not_enabled.

Keys

You create and revoke keys at account.compudime.com. A key belongs to one store.

Both read the same store data. Only orders differ: a test key's orders never reach the store. Build with a test key, and switch to a live key when you go live. cd_ keys are older keys; they keep working.

Working across stores

A developer who builds for many stores gets one key per store, once each store's owner approves. There is no key for several stores: for ten stores you hold ten keys, and GET /v1/me names the store a key reads.

• Approval. CompuDime opens your developer organization with the stores you may reach and the capabilities you may use there: write to support@compudime.com to be opened, or to reach more stores. Then you ask each store yourself, on the Stores page at account.compudime.com: pick the store, the capabilities you need and why (the store's owner reads your reason), and agree to the developer terms. A store can be asked only once its owner has opened it to third-party developers; when the store is closed to developers, outside the stores you may reach, or a capability is not on for it, the page says which. The store's owners and billing admins get your request by email and in their CompuConnect account, and there they approve it as asked, approve less, or decline it. CompuDime can also record an owner's answer on the owner's behalf. The approval names the capabilities you may use on that store. Then you create the store's key at account.compudime.com, and it carries those capabilities and no more.
• Who pays. Your organization pays for the calls, unless the store owner chose to pay when approving. Either way your key never sees the store's plan, card or credits: GET /v1/me leaves credits out and links your organization's usage in usageUrl, and GET /v1/usage/current answers 403 usage_not_available_for_key. Your organization's usage is at account.compudime.com/usage. When the store pays, each call still says what it cost, but not the store's balance: there is no X-Credits-Remaining, and when the store cannot be charged you get 402 payer_billing_blocked, whatever the reason.
• The owner's settings stay with the approval, not the key. Your access level, whether you get customer account figures, and your field policy are the store owner's choice. Replace a key and the new key reads exactly as the old one did, with the same own customers and the same webhook receivers. A new approval starts again at own, without account figures.
• One budget. The keys of one approval share one rate limit for each capability: one for its live keys, another for its test keys.
• Test keys read apart. An approval's test keys read through their own integration for each capability, never the live keys'. They start at own, without account figures, with own customers and webhook receivers of their own; a replacement test key keeps them.
• Withdrawn. When the owner withdraws the approval, its keys stop for good at once, on their very next call: 401 key_revoked. Its webhook receivers, live and test, are removed at the same moment: no order event is sent to them afterwards, not even a retry that was waiting.

Test orders

An order you send with a test key (POST /v1/orders) is checked exactly like a live key's order: the body, the lines, the Idempotency-Key and what your key may do. You get the same 202 and the same body. But the order is simulated. It never reaches the store's POS.

• orderId starts with test_. A live order's id never does.
• dispatchState is simulated. It never changes.
• The billing block says "mode": "test". The order uses the sandbox allowance like any other test call.
• No webhook is sent for it.
• Send the same Idempotency-Key again and you get the same simulated order back.
• Read it with GET /v1/orders/{orderId} or GET /v1/orders/external/{externalOrderId} and a test key. A live key never sees a test order, and a test key never sees a live order: you get 404 order_not_found.

What a test order does not check: the store looks up each productCode and sets the prices only when a live order reaches it. A simulated order proves your request is right, not that the store carries the products.

Request ids

Send X-Request-Id with an id of your own: 1 to 128 letters, digits, dots, underscores or dashes, starting with a letter or digit. It comes back as requestId in the body and in the X-Request-Id header. Without one, the API makes one up. Log it, and quote it when you write to support.

What a key may do

A key carries one or more capabilities. Each endpoint needs one. GET /v1/capabilities is free and says what your key carries. The store owner decides which capabilities a store turns on.

GET /v1/me, also free, describes the key itself: its integration and access level, its store, the fields it may ask for on each endpoint it can call, its rate limit and, for the store's own keys, the store's credits. It never shows the key.

accounting-data

• GET /v1/accounting/journal-entries List mapped journal entries by store-day live
• GET /v1/accounting/mapping Get the store's account mapping keys live
• GET /v1/accounting/sales-summaries List register-log sales summaries by store-day live

catalog-feed

• GET /v1/brands List the store's brands live
• GET /v1/catalog/snapshots/current Get current catalog snapshot
• GET /v1/categories List the store's departments, categories and sub-categories live
• GET /v1/products List catalog products
• GET /v1/products/lookup/{code} Look up a product live by any code
• GET /v1/products/{productCode} Get catalog product
• GET /v1/promotions List the store's promotions live
• GET /v1/promotions/mix-match/{groupId} Get a mix and match group live
• GET /v1/reasons List the register's discount and return reasons live
• GET /v1/store Get the store's business profile live
• GET /v1/tags List the store's product tags live

customer-access

• GET /v1/customers List the store's customers live
• GET /v1/customers/lookup Look up POS customers by phone
• GET /v1/customers/{posCustomerId} Get a customer live by POS customer id
• GET /v1/sales/daily List daily register totals
• GET /v1/tenders List the register's tender types

sales-data

• GET /v1/delivery/routes List the store's delivery routes live
• GET /v1/inventory/onhand List on-hand quantities live
• GET /v1/invoices List the store's POS invoices live
• GET /v1/invoices/external/{externalId} Get an invoice live by the placing system's order id
• GET /v1/invoices/{posInvoiceId} Get an invoice live by POS invoice id
• GET /v1/sales/movement List sales movement
• GET /v1/sales/zreport Get the register Z reports of a business day live
• GET /v1/tickets List the store's register tickets live
• GET /v1/tickets/{ticketId} Get a register ticket live with its lines and tenders

order-intake

• POST /v1/orders Create order intake request
• GET /v1/orders/external/{externalOrderId} Get order intake status by external order id
• GET /v1/orders/{orderId} Get order intake status
• POST /v1/webhooks Register a webhook receiver
• POST /v1/webhooks/{webhookId}/rotate-secret Rotate a receiver's signing secret
• POST /v1/webhooks/{webhookId}/test Send a test event to a receiver

purchasing-data

• GET /v1/purchase-orders List the store's vendor purchase orders live
• GET /v1/purchase-orders/{posPurchaseOrderId} Get a purchase order live by POS purchase order id
• GET /v1/receiving List the store's receiving documents live
• GET /v1/receiving/{posReceivingId} Get a receiving document live by POS receiving id

Each endpoint also names a scope (x-compudime-scope in the reference). Scopes come with the capability; you do not ask for them.

Access levels: own or all customers

Every integration has an access level, own or all. The store owner sets it. GET /v1/capabilities returns it as accessLevel. It changes the customer reads and nothing else.

• all reads the store's whole customer file. It is the sensitive level, and the owner grants it on purpose.
• own reads only the customers linked to your integration: the customers your own orders landed on in the store's POS, matched by the customer's main phone. With a cc_ key, your own orders are the orders sent with that key, or with any key of the same store approval (see Working across stores). A new integration is own unless the owner makes it all.

A customer outside your level is answered like a customer the store does not have. You never get a 403 for it, so an answer never tells you a customer exists. A cursor belongs to the level it was made at: if the owner changes your level, start the listing again.

Scoped keys

A key can carry a fixed data scope, set by the store owner:

• a field policy: which product fields the key may see;
• row rules: which products the key may see, such as brand eq X. The rules use eq, in and prefix on productCode, upc, brand, department, category and active.

A scoped key pages, looks up and counts only inside its slice. There is no parameter that widens it. Reads whose totals cover every product of the store (invoices, delivery routes, purchase orders, receiving, register tickets and the Z report) answer a scoped key with 422 scope_not_applicable, which is never charged.