# EZR (上海驿氪 / Shanghai EasyRetailPro)

> EZR is a Shanghai-based retail marketing technology company, founded 2015, that builds SCRM
> and new-retail CRM software for multi-store chain brands. Its EZR Open Platform (开放平台)
> exposes 236 documented interfaces across 11 business domains — stores and staff, member
> master data, loyalty points, coupons, sales receipts, a WeChat mall, gift cards, messaging
> and third-party platform binding. This file was GENERATED by API Evangelist from the
> provider's own published reference; EZR does not serve an llms.txt.

## What this API actually is

- Not REST despite the marketing wording. Every one of the 236 interfaces is an HTTP POST to a
  verb-named route, `application/x-www-form-urlencoded`, UTF-8, with the business payload as a
  JSON string inside a single `Args` form field.
- No OpenAPI, no AsyncAPI, no GraphQL, no gRPC, no MCP server, no A2A agent card.
- Failures return HTTP 200. The real outcome is the numeric `StatusCode` inside the JSON body.
- Access is gated: credentials come from an EZR account manager, and the caller's IP must be
  allowlisted. There is no self-service sign-up and no public sandbox credential.

## Envelope

Request (form fields): `AppId`, `Sign`, `Timestamp` (yyyyMMddHHmmss), `AppSystem`, `Args`.
Response (JSON): `Status` (bool), `StatusCode` (int, 200 = success), `Msg`, `Sign`, `Timestamp`, `Result`.

Signature: uppercase hex SHA1 (default) or MD5-32 over `AppId={AppId}&Timestamp={Timestamp}&Token={Token}`,
parameters sorted alphabetically, UTF-8 bytes. The response carries its own `Sign` — verify it before
acting on `Result`, and skip verification when `Status` is false. Timestamps older than 10 minutes are
rejected with `StatusCode` 308.

## Hosts

- Production (QCloud): https://open-tp.ezrpro.com
- Production (UCloud): https://open-up.ezrpro.com
- Test: https://open-q1.ezrpro.com
- KOS production: https://open-kos-tp.ezrpro.com
- KOS test: https://open-kos-q1.ezrpro.com

## Docs

- Developer portal (EZR开放平台): https://open.ezrpro.com/
- API reference (文档中心): https://open.ezrpro.com/#/apiFile
- Developer guide (开发指南): https://open.ezrpro.com/#/apiFile/guide/00001
- Status code conventions (编码规范): https://open.ezrpro.com/#/apiFile/guide/00002
- Signing algorithm (加签、验签算法): https://open.ezrpro.com/#/apiFile/guide/00003
- KOS developer guide: https://open.ezrpro.com/#/apiFile/kos
- Agent Skill page (EZR接口对接Skill): https://open.ezrpro.com/#/apiFile/guide/20003
- Open Platform overview: https://www.ezrpro.com/ecology/link
- Company site: https://www.ezrpro.com/
- Contact / support: https://www.ezrpro.com/contact
- Privacy policy: http://www.ezrpro.com/privacy.html

## Machine-readable reference (anonymous)

The developer portal is a JS-rendered SPA, but it is backed by an unauthenticated JSON API that
returns the entire reference. This is the most useful entry point for an agent:

- Full catalogue: https://open.ezrpro.com/api/Book
- Book: https://open.ezrpro.com/api/Book/1
- One interface: https://open.ezrpro.com/api/Doc/{id}
- Keyword search: https://open.ezrpro.com/api/Doc/List?keyword={q}

Each `/api/Doc/{id}` record carries `Route`, `Description`, `Envs`, `PublicReqParam`,
`PublicResParam`, a typed `ReqParam`/`ResParam` tree, `ReqExample`, `ResExample`, `ErrorParam`
and `LastModifiedOn`. It is a documentation API, not an API description format — it is not
OpenAPI and no OpenAPI has been derived from it.

## Interface domains (236 interfaces)

- 会员主数据 Member master data — 48 interfaces (registration, offline card issuance, profile
  edit, query, deregistration, card merge, tags, grades, paid membership cards)
- 微商城 WeChat mall — 62 interfaces (mall products, orders, returns, refunds, exchanges, logistics)
- 会员券 Coupons — 28 interfaces (coupon pools, issuance, redemption, cancellation, transfer)
- 会员积分 Loyalty points — 27 interfaces (balance, ledger upload, deduction, lock/unlock/spend,
  points-for-cash discount preview/apply/refund)
- 基础数据 Base data — 21 interfaces (stores, store groups, districts, staff, products, media)
- 第三方平台 Third-party platform — 16 interfaces (member binding/unbinding, aggregate payment)
- 礼品卡 Gift / stored-value cards — 14 interfaces
- 销售数据 Sales data — 7 interfaces (member receipt upload, transaction paging)
- 微商城(外部商城分销) External mall distribution — 7 interfaces
- 消息接口 Messaging — 3 interfaces (SMS, WeChat template messages)
- 接口拓展信息 Extension references — 3 enumeration/format references

## Push callbacks (webhooks)

31 of the 236 interfaces are EZR-to-integrator pushes. The integrator supplies the receiving URL;
EZR POSTs the same signed form-encoded envelope. Timeout is 3 seconds; a failed push is retried 6
times — 3 attempts at 30-second intervals, then 3 at 20-minute intervals. **EZR requires the
receiver to be idempotent under concurrency** (第三方系统需做并发幂等处理); EZR itself offers no
idempotency key on inbound calls.

Notable events: 1210 member profile push, 12105 member deregistration, 1214 grade change,
1211 points ledger, 1213 / 12131 coupon issuance, 1217 coupon redemption, 1219 coupon transfer,
1310 / 1312 coupon pool, 2001 mall order, 2002 return, 2113 refund, 101201 store change,
18001 SMS relay.

## Limits

- Production default: 10 concurrent requests per second, per interface, per `AppSystem`.
  Negotiated per customer with the account manager.
- Exhaustion: `StatusCode` 407 (访问频率过快). No rate-limit response headers of any kind.
- IP not allowlisted: `StatusCode` 400.
- Payload over length: `StatusCode` 1001. Batch caps are per interface (e.g. 500 rows on the
  member data-cleansing import).

## First-party downloads

- .NET sample: http://apidoc.ezrpro.com/OpenApiDemo-v1.0.1.zip (v1.0.1)
- Java sample: http://apidoc.ezrpro.com/JavaOpenApiDemo-v1.0.2.zip (v1.0.2)
- Agent Skill: https://skills-cdn-tp.ezrpro.com/skills/ezr-skills-openapi.zip (ezr-openapi-creator v1.0.0)

There are no published packages on npm, PyPI, Maven Central, NuGet, RubyGems, Packagist,
crates.io or pkg.go.dev, and no GitHub organisation.

## API Evangelist artifacts in this repo

- apis.yml — the APIs.json profile
- skills/ — EZR's own packaged Agent Skill, saved verbatim
- authentication/ezr-authentication.yml — the signed-request scheme
- conventions/ezr-conventions.yml — envelope, pagination, batching, versioning, replay window
- errors/ezr-status-codes.yml — all 24 published status codes plus push errors
- asyncapi/ezr-webhooks.yml — the 31-event push catalogue
- data-model/ezr-data-model.yml — entities and the identifier graph
- lifecycle/ezr-lifecycle.yml — versioning, deprecation, SLA and status-page findings
- changelog/ezr-changelog.yml — dated interface revisions read from the reference
- rate-limits/ezr-rate-limits.yml — the one published limit
- sandbox/ezr-sandbox.yml — the test environment and what it lacks
- plans/ezr-plans-pricing.yml — no published pricing
- conformance/ezr-conformance.yml — standards measured, mostly negative
- security/ — TLS/DNS posture; no vulnerability-disclosure programme, no trust centre
- well-known/ezr-well-known.yml — a verified all-miss probe, including the soft-404 trap