API Documentation

API Documentation

Access your Inventory app data programmatically through our external API.

Overview

What is the API?

The external API provides an interface to access Inventory app data from external programs.

Use Cases

  • Automation: Batch document processing through scripts
  • Third-party Integration: Data synchronization with other services
  • Bulk Operations: Mass template creation and sharing

Getting Started

Obtaining an API Key

To use the API, you first need an API key.

  1. Open the Profile screen in the Inventory app
  2. Find the API Key section
  3. Tap the Generate Key button
  4. Your API key will be displayed on screen

Important: The API key is shown only once when generated. Make sure to copy and store it in a safe place. You will need to regenerate if lost.

API Key Format

API keys follow this format:

inv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Starts with inv_ prefix
  • Approximately 50-character Base64URL encoded string

Managing API Keys

  • Regenerate: Revokes the existing key and issues a new one
  • Delete: Completely removes the API key (API access disabled)

Authentication

All API requests require an Authorization header.

Bearer Token

Authorization: Bearer inv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Request Example

curl -H "Authorization: Bearer inv_your_api_key" \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/items"

Rate Limiting

API usage is subject to limits.

Limit Type Threshold Description
Per Minute 60 requests Prevents excessive requests
Monthly Varies by account Determined by contract

When Limit is Exceeded

  • HTTP status code 429 Too Many Requests is returned
  • Please wait and try again later

API Endpoints

Base URL

https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1

Read APIs (GET)

Endpoint Description
GET /items List your items
GET /items/{token} Get item details
GET /templates List your templates
GET /templates/{token} Get template details
GET /templates/shared List shared templates
GET /user/stats Get user statistics

Write APIs (POST)

Endpoint Description
POST /templates Create new template
POST /templates/{token}/share Share template
POST /templates/revoke Revoke share
POST /templates/{token}/send Send template

Detailed API Reference

GET /items - List Items

Retrieves a list of items (documents) you own.

Request

curl -H "Authorization: Bearer inv_xxx" \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/items?page=1&pageSize=20"

Query Parameters

Parameter Type Default Description
page number 1 Page number
pageSize number 20 Items per page (max 100)
status string “active” Status filter (active, pending)
type string - Type filter (paper, stamp)

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "token": "encrypted_item_id",
        "title": "Item Title",
        "content": "Item Content",
        "type": "paper",
        "status": "active",
        "imageUrl": "https://...",
        "createdAt": "2025-01-01T00:00:00Z",
        "updatedAt": "2025-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalItems": 50,
      "totalPages": 3
    }
  }
}

GET /items/{token} - Item Details

Retrieves detailed information about a specific item.

Request

curl -H "Authorization: Bearer inv_xxx" \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/items/{token}"

Response

{
  "success": true,
  "data": {
    "token": "encrypted_item_id",
    "title": "Item Title",
    "content": "Item Content",
    "type": "paper",
    "status": "active",
    "imageUrl": "https://...",
    "keywords": ["key:value", "tag:example"],
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-01T00:00:00Z"
  }
}

GET /templates - List Templates

Retrieves a list of templates (stamps) you own.

Request

curl -H "Authorization: Bearer inv_xxx" \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/templates?page=1&pageSize=20"

Query Parameters

Parameter Type Default Description
page number 1 Page number
pageSize number 20 Items per page (max 100)

Response

{
  "success": true,
  "data": {
    "templates": [
      {
        "token": "encrypted_template_id",
        "title": "Template Title",
        "content": "Template Content",
        "imageUrl": "https://...",
        "commentMode": "independent",
        "isSharing": false,
        "createdAt": "2025-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalItems": 10,
      "totalPages": 1
    }
  }
}

GET /templates/shared - Shared Templates

Retrieves a list of templates you are currently sharing.

Request

curl -H "Authorization: Bearer inv_xxx" \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/templates/shared"

Response

{
  "success": true,
  "data": {
    "sharedTemplates": [
      {
        "token": "encrypted_template_id",
        "shareToken": "encrypted_share_id",
        "title": "Template Title",
        "tags": ["TAG1", "TAG2"],
        "expiresAt": "2025-01-02T00:00:00Z",
        "copyCount": 5
      }
    ]
  }
}

GET /user/stats - User Statistics

Retrieves your usage statistics.

Request

curl -H "Authorization: Bearer inv_xxx" \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/user/stats"

Response

{
  "success": true,
  "data": {
    "email": "user@example.com",
    "createdAt": "2024-01-01T00:00:00Z",
    "items": {
      "total": 50,
      "paper": 30,
      "stamp": 20
    },
    "api": {
      "enabled": true,
      "monthlyLimit": 1000,
      "monthlyUsed": 150,
      "lastUsedAt": "2025-01-01T12:00:00Z"
    }
  }
}

POST /templates - Create Template

Creates a new template (stamp).

Request

curl -X POST \
     -H "Authorization: Bearer inv_xxx" \
     -H "Content-Type: application/json" \
     -d '{
       "imageUrl": "https://example.com/image.png",
       "title": "Template Title",
       "content": "Template Content",
       "commentMode": "independent",
       "keywords": ["product:laptop", "price:$1500000KRW$"]
     }' \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/templates"

Request Body

Field Type Required Description
imageUrl string Yes Image URL (HTTPS recommended)
title string Yes Title (max 32 characters)
content string Yes Content (max 1024 characters)
commentMode string No Comment mode: “independent” or “shared”
keywords string[] No Keyword array (max 128)
publishDate string No Publish start date (ISO 8601)
validUntil string No Valid until date (ISO 8601)

Keyword Format

Keywords must follow the key:value format.

Type Format Example
General key:value product:pen
Date key:@YYYY-MM-DD@ start:@2025-01-15@
Phone key:#phone# contact:#+82 10-1234-5678#
Location key:%address% place:%Seoul, Gangnam%
Amount key:$amountCurrency$ price:$50000KRW$

Restrictions

  • Key length: max 8 characters
  • Keyword total length: max 256 characters
  • Keyword count: max 128

Response

{
  "success": true,
  "data": {
    "token": "encrypted_template_id",
    "title": "Template Title",
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

POST /templates/{token}/share - Share Template

Shares a template so other users can discover it.

Request

curl -X POST \
     -H "Authorization: Bearer inv_xxx" \
     -H "Content-Type: application/json" \
     -d '{
       "durationMinutes": 1440,
       "tags": ["TAG1", "TAG2"]
     }' \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/templates/{token}/share"

Request Body

Field Type Required Description
durationMinutes number Yes Share duration (minutes). 60-43200 or 0 (unlimited)
tags string[] Yes Search tags (1-16, auto-uppercased)

Share Duration

Value Meaning
60 1 hour
1440 1 day (24 hours)
10080 1 week
43200 30 days (maximum)
0 Unlimited

Response

{
  "success": true,
  "data": {
    "shareToken": "encrypted_share_id",
    "expiresAt": "2025-01-02T00:00:00Z",
    "tags": ["TAG1", "TAG2"]
  }
}

POST /templates/revoke - Revoke Share

Cancels sharing of a template that is currently being shared.

Request

curl -X POST \
     -H "Authorization: Bearer inv_xxx" \
     -H "Content-Type: application/json" \
     -d '{
       "shareToken": "encrypted_share_id"
     }' \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/templates/revoke"

Request Body

Field Type Required Description
shareToken string Yes The shareToken received when sharing

Response

{
  "success": true,
  "data": {
    "message": "Share revoked successfully"
  }
}

POST /templates/{token}/send - Send Template

Clones a template and sends it to another user.

Request

curl -X POST \
     -H "Authorization: Bearer inv_xxx" \
     -H "Content-Type: application/json" \
     -d '{
       "recipientEmail": "recipient@example.com",
       "message": "A gift for you!"
     }' \
     "https://asia-northeast3-inventory-app-service.cloudfunctions.net/apiV1/templates/{token}/send"

Request Body

Field Type Required Description
recipientEmail string Yes Recipient’s email
message string No Message (max 200 characters)

Response

{
  "success": true,
  "data": {
    "itemToken": "encrypted_item_id",
    "recipientEmail": "recipient@example.com",
    "status": "sent"
  }
}

Error Codes

When an API request fails, errors are returned in this format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Error description"
  }
}

Error Code List

Code HTTP Status Description
INVALID_API_KEY 401 Invalid API key
API_KEY_EXPIRED 401 Expired API key
API_DISABLED 403 API disabled
RATE_LIMIT_EXCEEDED 429 Request limit exceeded
SCOPE_DENIED 403 Insufficient permissions
VALIDATION_ERROR 400 Invalid input
INVALID_TOKEN 400 Invalid token
NOT_FOUND 404 Resource not found
FORBIDDEN 403 Access denied (not owner)
RECIPIENT_NOT_FOUND 404 Recipient not found
INVALID_IMAGE 400 Image URL error
ALREADY_SHARED 400 Template already being shared
NOT_SHARED 400 Template not currently shared

Security Recommendations

  1. Protect API Keys: Never expose API keys in public repositories or client code
  2. Use HTTPS: All requests are transmitted via HTTPS
  3. Key Rotation: Regenerate API keys periodically
  4. Least Privilege: Only perform necessary operations

Contact

If you have issues using the API, please contact us through the Suggest page.