주문 흐름에서 앱 쓰기
주문 흐름의 알림을 앱으로 받고(매개변수 연결), 앱이 흐름에 사건을 돌려보내는 방법
주문 흐름은 상태가 바뀔 때 앱에 알림을 보낼 수 있고, 앱은 흐름에 사건을 돌려보내 다음 상태로 넘길 수 있습니다. 흐름이 앱을 부르는 것은 흐름 알림, 앱이 흐름을 움직이는 것은 흐름 사건입니다.
흐름 「시안 확인 대기」로 이동 ──알림 send-proof { proofUrl, engraveText, round }──▶ 앱 (메일 발송)
구매자가 메일 링크에서 「확정」 ──▶ 앱 공개 HTTP ──사건 app.dodam-proof.PROOF_CONFIRMED──▶ 흐름 「제작중」매니페스트
{
"handle": "dodam-proof",
"name": "도담 시안 메일",
"scopes": ["order:rw"],
"network": { "hosts": ["api.resend.com"] },
"http": { "public": ["GET /proof/:orderItemId", "POST /proof/:orderItemId"] },
"flow": {
"notifications": {
"send-proof": {
"label": "시안 메일 보내기",
"params": {
"proofUrl": { "type": "string", "label": "시안 이미지 주소", "required": true },
"engraveText": { "type": "string", "label": "각인 문구" },
"round": { "type": "number", "label": "몇 번째 시안" }
}
}
},
"events": {
"PROOF_CONFIRMED": { "label": "구매자 시안 확정" },
"PROOF_REVISION": { "label": "구매자 수정 요청" }
}
}
}| 필드 | 규칙 |
|---|---|
flow.notifications | 이름(소문자·숫자·하이픈 40자) → label(60자)·description·params. 20개까지 |
params | 이름(영문으로 시작 40자) → type(string · number · boolean)·label·required. 20개까지 |
flow.events | 이름(대문자·숫자·밑줄 40자) → label·description. 20개까지 |
알림과 사건은 셀러가 흐름 편집기에서 직접 연결해야 동작합니다. 매니페스트에 적는 것만으로는 아무 일도 일어나지 않으므로 동의 화면에 따로
보이지 않습니다. 흐름 사건을 보내려면 order:rw 권한이 필요합니다.
흐름 알림 받기
셀러는 연결선 실행에 알림을 더하고 채널에서 「앱 › 도담 시안 메일 › 시안 메일 보내기」를 고른 뒤, 매개변수마다 값을 식으로 넣습니다. 식은 흐름의 다른 식과 같은 문법입니다.
| 매개변수 | 셀러가 넣는 식 | 뜻 |
|---|---|---|
| 시안 이미지 주소 | fields.proofUrl | 「시안 등록」 행동에서 셀러가 올린 이미지(흐름 필드) |
| 각인 문구 | item.customInputs["각인 문구"] | 구매자가 주문할 때 입력한 직접 입력 옵션 |
| 몇 번째 시안 | fields.revisionCount + 1 | 흐름 필드 |
앱 코드는 flows에 알림 이름마다 함수를 둡니다.
export default defineApp({
flows: {
"send-proof": async (notice, ctx) => {
// notice: { name, orderId, orderItemIds, flowId, flowVersion, state, params }
const { proofUrl, engraveText, round } = notice.params;
const link = ctx.publicUrl(`/proof/${notice.orderItemIds[0]}`);
await sendProofMail({ proofUrl, engraveText, round, link }, ctx);
},
},
});- 알림은 그 상점에 이 앱이 설치돼 있고 실행 버전 매니페스트에 그 알림이 있을 때만 갑니다. 없으면 흐름은 그대로 진행하고 실행 기록에 「보내지 않음」으로 남습니다.
- 이벤트 함수와 같이 최소 한 번 전달되고 실패하면 다시 실행됩니다. 같은 호출은 같은
ctx.invocationId로 옵니다. - 셀러가 비워 둔 매개변수는
null입니다.required매개변수가 비어 있으면 흐름 편집기에 표시됩니다. 식 평가가 실패한 값도null입니다. - 구매자 개인정보(이름·연락처)는 매개변수로 넘기지 마십시오. 필요하면
order:r권한으로 주문을 읽습니다. - 함수가 없는 알림이 매니페스트에 있으면 빌드가
HANDLER_MISSING으로 실패합니다.
흐름 사건 보내기
앱은 app.<handle>.<사건 이름> 사건을 주문상품의 흐름에 보냅니다.
await ctx.api.orderItems.emitEvent(orderItemId, "app.dodam-proof.PROOF_REVISION", {
request: "글씨체를 더 굵게",
});POST /v1/order-items/{orderItemId}/events/app.dodam-proof.PROOF_REVISION
Authorization: Bearer <설치 토큰>
{ "input": { "request": "글씨체를 더 굵게" } }- 셀러는 흐름 편집기에서 연결선 조건을 「외부 사건」으로 두고 사건 이름에
app.dodam-proof.PROOF_REVISION을 넣습니다. app.으로 시작하는 사건은 그 앱의 설치 토큰으로만 보낼 수 있고, 실행 버전 매니페스트flow.events에 있는 이름이어야 합니다. 아니면403 FLOW_EVENT_APP_FORBIDDEN입니다.- 지금 상태가 그 사건을 받지 않으면
409 FLOW_EVENT_NOT_ACCEPTED입니다.input은 연결선 실행의 식에서input.<이름>으로 읽습니다. Idempotency-Key를 넣으면 같은 요청의 재시도가 안전합니다.
로컬에서
npx sayren app trigger --flow send-proof --data '{"orderItemIds":["oi_1"],"params":{"proofUrl":"https://…"}}'가 흐름 알림을 흉내 냅니다.