# Cheqi API

Cheqi provides APIs for creating receipts and reading receipts for customers

Version: v1

## Servers

Production
```
https://api.cheqi.io
```

Sandbox
```
https://sandbox.api.cheqi.io
```

## Security

### cheqi_oauth

OAuth 2.0 for company integrations. Authorization creates explicit company grants. The client_credentials token request must select one grant_id and a scope subset, and returns a short-lived token bound to the Company authorized by that Grant.

Type: oauth2
Token URL: https://sandbox.api.cheqi.io/oauth2/token
Scopes:
- `receipt:read`: Receive receipts automatically from the companies, payment accounts, or email addresses a user authorizes
- `receipt:read:user-shared`: Allow users to share individual receipts with connected applications and company integrations
- `receipt:issue`: Issue digital receipts on behalf of an authorized company
- `store:read`: View store and location information for an authorized company
- `store:manage`: Create and manage stores and locations for an authorized company
- `company:read`: View profile and authorization metadata for an authorized company
- `company:members:invite`: Invite ordinary members to an authorized company

### cheqi_api_key

Company API key. Send it as `Authorization: Bearer sk_...`.

Type: http
Scheme: bearer

## Download OpenAPI description

 - [Cheqi API](https://docs.cheqi.io/_bundle/apis/api-docs.yaml)

## Store Management

 - [GET /company/{companyId}/stores/{storeId}](https://docs.cheqi.io/apis/api-docs/store-management/getstore.md): Gets a specific lightweight store/location record under the specified company. OAuth client applications require the store:read scope.
 - [PUT /company/{companyId}/stores/{storeId}](https://docs.cheqi.io/apis/api-docs/store-management/updatestore.md): Updates a lightweight store/location record under the specified company. OAuth client applications require the store:manage scope.
 - [GET /company/{companyId}/stores](https://docs.cheqi.io/apis/api-docs/store-management/getstores.md): Lists lightweight store/location records. When companyId is omitted, the company is derived from the authenticated principal. This does not list child companies. OAuth client applications require the
 - [POST /company/{companyId}/stores](https://docs.cheqi.io/apis/api-docs/store-management/createstore.md): Creates a lightweight store/location record. When companyId is omitted, the company is derived from the authenticated principal. Use child companies instead when the branch or franchisee needs its own
 - [PATCH /company/{companyId}/stores/{storeId}/deactivate](https://docs.cheqi.io/apis/api-docs/store-management/deactivatestore.md): Deactivates a store/location without deleting its history. OAuth client applications require the store:manage scope.
 - [PATCH /company/{companyId}/stores/{storeId}/activate](https://docs.cheqi.io/apis/api-docs/store-management/activatestore.md): Reactivates a previously deactivated store/location. OAuth client applications require the store:manage scope.
## Client Application Management

 - [GET /client-application/{clientApplicationId}/public-key](https://docs.cheqi.io/apis/api-docs/client-application-management/getclientapplicationpublickey.md): Retrieves the public key information for a client application, including the key data, algorithm, and upload timestamp. This key is used to verify signatures from the client application. **Accessible
 - [POST /client-application/{clientApplicationId}/public-key](https://docs.cheqi.io/apis/api-docs/client-application-management/uploadclientapplicationpublickey.md): Uploads a public key for the client application. This key is used to verify signatures from the client application when it signs receipts or other data. Can be called by company admins or using compan
 - [POST /client-application/public-key](https://docs.cheqi.io/apis/api-docs/client-application-management/registerpublickey.md): Authenticates an approved confidential application using client_id and an active client_secret in the request body, then registers its public encryption key. Alternatively, omit client_secret and send
 - [GET /client-application/authorized-resources](https://docs.cheqi.io/apis/api-docs/client-application-management/getauthorizedresources.md): Returns receipt-routing resources for the authenticated company or user context only. Requires receipt:read. Company tokens must reference the active company grant and revision; application-wide crede
## OAuth2 Authorization

 - [GET /oauth2/authorize](https://docs.cheqi.io/apis/api-docs/oauth2-authorization/authorize.md): Initiates the OAuth2 authorization flow. Redirects to the frontend authorization page where users can approve or deny access.
 - [POST /oauth2/authorization-code/exchange](https://docs.cheqi.io/apis/api-docs/oauth2-authorization/exchangeauthorizationcode.md): Consume a one-time authorization code and return the approved Grant metadata.
 - [GET /oauth2/grants/{grantId}](https://docs.cheqi.io/apis/api-docs/oauth2-authorization/getgrantdetails.md): Returns the current Company and Store metadata for the Grant bound to the access token.
 - [POST /oauth2/token](https://docs.cheqi.io/apis/api-docs/oauth2-authorization/gettoken.md): Request a short-lived Company token for an approved Grant.
## Credit Note Management

 - [CreditNoteInitiationRequest](https://docs.cheqi.io/apis/api-docs/credit-note-management/creditnoteinitiationrequest.md): Schema: #/components/schemas/CreditNoteInitiationRequest
 - [POST /credit-note/encrypted](https://docs.cheqi.io/apis/api-docs/credit-note-management/submitencryptedreceipt_1.md): Submits independently encrypted credit-note generation input for every matched owner device. Devices generate CHEQI JSON and any requested UBL CreditNote locally. **Accessible for:** Company, Client A
 - [PATCH /credit-note/requests/{requestId}/status](https://docs.cheqi.io/apis/api-docs/credit-note-management/updaterequeststatus.md): Updates a return request owned by the authenticated company and issuing application. Requires receipt:issue; delegated company grants and selected-store restrictions are revalidated. The encrypted req
 - [GET /credit-note](https://docs.cheqi.io/apis/api-docs/credit-note-management/getallcreditnotes.md): Retrieves outstanding customer return requests for the authenticated company and issuing application only. Requires receipt:read; delegated company grants and selected-store restrictions are revalidat
## Company Management

 - [POST /company/{parentId}/children](https://docs.cheqi.io/apis/api-docs/company-management/addchildcompany.md): Creates a child company under an existing parent company. Use this when a branch, franchisee, or location should be modeled as its own Cheqi company with its own company identity. This is different fr
 - [POST /company/{id}/invite/employees](https://docs.cheqi.io/apis/api-docs/company-management/inviteemployees.md): Invites employees as ordinary company members without receipt permissions. Addresses are normalized and deduplicated. Already existing company members are returned with their Cheqi user IDs, including
 - [GET /company/receipt-destinations](https://docs.cheqi.io/apis/api-docs/company-management/list.md): Requires company receipt:read access. Returns the active destinations for the authenticated company without webhook signing secrets. **Accessible for:** Company
 - [POST /company/receipt-destinations](https://docs.cheqi.io/apis/api-docs/company-management/register.md): Requires a company API key with receipt:read. Register an RSA public key for encrypted receipt delivery; the response includes the destination ID and webhook signing secret. Create webhook subscriptio
 - [POST /company/receipt-destinations/{id}/receipts/queue/acknowledge](https://docs.cheqi.io/apis/api-docs/company-management/acknowledge.md): Requires company receipt:read access. Removes the specified receipt IDs from this destination's recovery queue after the consumer has processed them. **Accessible for:** Company
 - [GET /company/{companyId}/invitation-acceptances](https://docs.cheqi.io/apis/api-docs/company-management/list_1.md): Recover missed COMPANY_INVITATION_ACCEPTED events. Requires the matching company context and company:members:invite for delegated clients. Results are ordered by acceptance time and invitation ID. Use
 - [GET /company/receipt-destinations/{id}/receipts/queue](https://docs.cheqi.io/apis/api-docs/company-management/queue.md): Requires company receipt:read access. Returns encrypted receipt envelopes retained for this company-owned destination so a consumer can recover missed webhook deliveries. **Accessible for:** Company
 - [DELETE /company/receipt-destinations/{id}](https://docs.cheqi.io/apis/api-docs/company-management/deactivate.md): Requires company receipt:read access. Deactivates the destination and its active webhook subscriptions. **Accessible for:** Company
## Recipient Management

 - [POST /recipient/resolve](https://docs.cheqi.io/apis/api-docs/recipient-management/matchcustomer.md): Matches the customer from the provided identification details and returns one temporary recipient for every device owned by the matched customer. Each device receives an independently encrypted genera
 - [GET /recipient/matches/{matchId}](https://docs.cheqi.io/apis/api-docs/recipient-management/getmatch.md): Returns MATCHED with original recipient keys, SUBMITTED with the original acceptance result, IN_PROGRESS with retryAfterSeconds, or EXPIRED. Matches are bound to the original authenticated subject, co
## Receipt Management

 - [CheqiReceipt](https://docs.cheqi.io/apis/api-docs/receipt-management/cheqireceipt.md): Schema: #/components/schemas/CheqiReceipt
 - [ReceiptEnvelope](https://docs.cheqi.io/apis/api-docs/receipt-management/receiptenvelope.md): Schema: #/components/schemas/ReceiptEnvelope
 - [ReceiptEnvelopeDocument](https://docs.cheqi.io/apis/api-docs/receipt-management/receiptenvelopedocument.md): Schema: #/components/schemas/ReceiptEnvelopeDocument
 - [ReceiptPayload](https://docs.cheqi.io/apis/api-docs/receipt-management/receiptpayload.md): Schema: #/components/schemas/ReceiptPayload
 - [POST /receipts/queue/acknowledge/received](https://docs.cheqi.io/apis/api-docs/receipt-management/acknowledgequeuedreceipts.md): Acknowledges successfully processed queued receipts for the authenticated company or client application. Requires an applicable receipt read scope. **Accessible for:** Client Application, Company
 - [POST /receipts/queue/acknowledge/failed-permanent](https://docs.cheqi.io/apis/api-docs/receipt-management/acknowledgequeuedreceiptspermanentfailure.md): Marks queued receipts as permanently failed for the authenticated company or client application. Requires an applicable receipt read scope. **Accessible for:** Client Application, Company
 - [POST /receipt/encrypted](https://docs.cheqi.io/apis/api-docs/receipt-management/submitencryptedreceipt.md): Queues independently encrypted definitive receipt payloads for the devices returned by POST /recipient/resolve. Replays by the original requester return the original acceptance result even with regene
 - [POST /receipt/email](https://docs.cheqi.io/apis/api-docs/receipt-management/submitreceiptwithemail.md): Sends a purchase receipt directly to a customer via email. The receipt is delivered as a PDF attachment. Requires the receipt:issue scope. **Accessible for:** Company, Client Application
 - [POST /receipt/download](https://docs.cheqi.io/apis/api-docs/receipt-management/uploadclientencryptedreceipt.md): Stores the ciphertext behind a download id the SDK generated locally, so the QR code worked before this upload. First write wins: resubmitting the same downloadId with identical bytes returns 200 with
 - [GET /receipts/queue](https://docs.cheqi.io/apis/api-docs/receipt-management/getqueuedreceipts.md): Returns pending encrypted receipts for the authenticated company or client application. Receipts remain in the queue until they are explicitly acknowledged or marked as permanently failed. Delegated c
 - [GET /receipt/document-capabilities](https://docs.cheqi.io/apis/api-docs/receipt-management/get.md): Public metadata for formatPreferences. Each ReceiptFormat value selects a representation and, for versioned invoice formats, its UBL schema and conformance profile. Newer UBL schema compatibility does
## Webhook Management

 - [POST /webhook/subscription](https://docs.cheqi.io/apis/api-docs/webhook-management/handlewebhook.md): Creates subscriptions for requested events. COMPANY_INVITATION_ACCEPTED requires a company context and company:members:invite for delegated clients. Receipt events require receipt:read or receipt:read
 - [PATCH /webhook/subscription/{id}](https://docs.cheqi.io/apis/api-docs/webhook-management/updatesubscriptionurl.md): Changes where the owner's subscription is delivered. Requires the same scope as subscribing to its event. **Accessible for:** Company, Client Application