고객
고객 객체는 비즈니스의 고객을 표현합니다. 이 객체를 사용해 반복 청구를 연결하고, 결제 및 연락처 정보를 저장하고, 같은 고객에 속한 결제를 추적할 수 있습니다.
고객 객체
| 필드 이름 | 설명 | 필수 여부 | 형식 | 예시 | 수정 가능 | 고유 여부 |
|---|---|---|---|---|---|---|
| uid | 시스템 고객 ID | 예 | uuidv4 | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx | 아니오 | 예 |
| uuid | 외부 시스템 기준 고객 식별자 | 아니오 | uuidv4 | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx | 예 | 예 (제공 시) |
| name | 고객 이름 | 아니오 | - | John Doe | 예 | 아니오 |
| 고객 이메일 | 아니오 | user+1@example.com | 예 | 아니오 | ||
| phone | 고객 전화번호 | 아니오 | E.164 | +14155552671 | 예 | 아니오 |
| description | 고객 설명 | 아니오 | - | 고객에 대한 간단한 설명 | 예 | 아니오 |
| tags | 고객에 연결된 태그 목록 | 아니오 | text[] | ["premium", "vip", "new-customer"] | 예 | 아니오 |
| metadata | 고객에 대한 추가 메타데이터 K:V | 아니오 | json | {"my_custom_field_1":"value"} | 예 | 아니오 |
uid
uid는 시스템이 생성하는 uuidv4 형식의 고유 식별자입니다. 사용자가 직접 제공하거나 수정할 수 없습니다.
uuid
uuid는 고객의 uuidv4 형식 외부 식별자입니다. 사용자가 직접 제공할 수 있습니다.
이 값은 다른 시스템에서 생성된 고객 레코드와 동기화할 때 유용합니다.
또한 CRM 및 관련 기능 안에서 고객의 고유성을 보장하는 데 사용할 수 있습니다.
예:
- 자체 데이터베이스의 고객
- Salesforce의 고객
phone
phone은 E.164 형식의 고객 전화번호입니다. 형식을 맞추기 어렵다면 Grida E.164 도구를 사용할 수 있습니다.
tags
태그는 고객과 연결되는 태그 목록입니다. 태그는 프로젝트 단위로 관리되며, 설명을 가질 수 있고, 분류, 세그먼트 관리, 빠른 필터링에 유용합니다.
고객 생성 또는 업데이트 시 제공된 태그가 아직 없다면 자동으로 생성됩니다.
예:
{
"tags": ["premium", "vip", "new-customer"]
}
- 태그는 프로젝트 범위에서 이름 기준으로 고유합니다.
- 태그 이름을 바꾸면 모든 고객-태그 연결이 자동으로 갱신됩니다.
- 태그를 삭제하면 고객-태그 연결만 제거되며 고객 자체는 삭제되지 않습니다.
CSV 참고: CSV 파일에서
tags를 전달할 때는"tag1,tag2,tag3"처럼 쉼표로 구분된 문자열을 큰따옴표로 감싸서 입력해야 합니다.
태그 문서도 참고하세요.
metadata
고객 객체에 연결할 수 있는 키-값 메타데이터입니다. 추가 정보를 구조화해서 저장할 때 유용합니다.
CSV 참고: CSV에서
metadata.*필드를 사용할 때는 평탄화된 키 이름으로 전달해야 합니다.
예를 들어 다음 JSON을 업로드하려면:
{
"my_custom_field_1": "value 1",
"my_custom_field_2": "value 2"
}
CSV는 다음처럼 작성합니다.
metadata.my_custom_field_1,metadata.my_custom_field_2
value 1,value 2
중요:
metadata는 부분 업데이트를 지원하지 않습니다. 메타데이터를 갱신할 때는 기존 값을 포함한 전체 메타데이터를 다시 제공해야 합니다.
CSV로 작업하기
CSV 파일을 사용해 Grida 고객 객체에 데이터를 대량으로 삽입하거나 업데이트할 수 있습니다.
CSV 파일만으로 upsert는 지원하지 않습니다. upsert가 필요하면 API를 사용해야 합니다.
고객 CSV 파일 필드 설명
| 필드 이름 | 설명 | 필수 여부 | 형식 | 예시 |
|---|---|---|---|---|
| uuid | 외부 시스템 기준 고객 식별자 | 아니오 | uuidv4 | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| name | 고객 이름 | 아니오 | - | John Doe |
| 고객 이메일 | 아니오 | user+1@example.com | ||
| phone | 고객 전화번호 | 아니오 | E.164 | +14155552671 |
| description | 고객 설명 | 아니오 | - | 고객에 대한 간단한 설명 |
| tags | 태그를 쉼표로 나열한 문자열 | 아니오 | - | "tag1,tag2,tag3" |
| metadata.* | 고객 메타데이터 | 아니오 | - | value |
삽입
삽입 시에는 아래 필드만 제공해야 합니다.
| 필드 이름 | 설명 | 필수 여부 | 형식 | 예시 |
|---|---|---|---|---|
| uuid | 외부 시스템 기준 고객 식별자 | 아니오 | uuidv4 | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| name | 고객 이름 | 아니오 | - | John Doe |
| 고객 이메일 | 아니오 | user+1@example.com | ||
| phone | 고객 전화번호 | 아니오 | E.164 | +14155552671 |
| description | 고객 설명 | 아니오 | - | 고객에 대한 간단한 설명 |
| tags | 태그를 쉼표로 나열한 문자열 | 아니오 | - | "tag1,tag2,tag3" |
| metadata.* | 고객 메타데이터 | 아니오 | - | value |
uuid는 선택 사항이지만, 나중에 고객을 업데이트하려면 제공하는 것이 좋습니다.
업데이트 (불안정)
업데이트하려면 CSV 파일에 uid 또는 uuid 필드를 제공해야 합니다.
| 필드 이름 | 설명 | 필수 여부 | 형식 | 예시 |
|---|---|---|---|---|
| uid / uuid | 고객 식별자 | 예 | uuidv4 | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| name | 고객 이름 | 아니오 | - | John Doe |
| 고객 이메일 | 아니오 | user+1@example.com | ||
| phone | 고객 전화번호 | 아니오 | E.164 | +14155552671 |
| description | 고객 설명 | 아니오 | - | 고객에 대한 간단한 설명 |
| metadata.* | 고객 메타데이터 | 아니오 | - | value |
업데이트 시 제공하지 않은 필드는 변경되지 않습니다.
중요: metadata는 한 번 제공되면 새 메타데이터 전체로 교체됩니다.
중요: 태그는 CSV 파일로 업데이트할 수 없습니다. 자세한 내용은 support로 문의하세요.