결제 게이트웨이
eSewa, Khalti, Stripe, PayPal, 은행 게이트웨이. 콜백, 검증, 환불 처리까지 포함합니다.
API 연동 — 네팔
네팔에서 진행하는 API 연동장애 상황까지 고려해 설계합니다
Soft Himalaya는 카트만두에서 결제 게이트웨이, CRM, ERP, 택배사, 자체 API를 연결합니다. 네팔, 영국, 호주, 미국, 캐나다의 기업과 함께 일합니다.
- 필드 매핑과 레코드 소유 주체를 가장 먼저 합의
- 재시도, 중복, 타임아웃을 의도적으로 처리
- 로그와 알림으로 장애를 일찍 드러냄
실제 운영 환경을 위한 엔지니어링
필드 소유권, 인증 정보, 재시도, 알림은 데이터가 시스템 사이를 오가기 전에 설계합니다.
- 규약을 먼저
- 엔드포인트, 필드, 오류 형식은 어느 쪽도 코드를 쓰기 전에 합의하고 문서로 남깁니다.
- 재시도해도 안전하게
- 쓰기 작업은 멱등하게 만들어, 타임아웃 후 같은 호출이 반복돼도 주문이나 결제가 중복 생성되지 않습니다.
- 장애는 드러나게
- 외부 서비스가 멈추면 연동이 로그를 남기고 알림을 보냅니다. 조용히 실패해 기록을 잃지 않습니다.
- 인증 정보의 올바른 취급
- 키는 환경 변수나 시크릿 저장소에 두고 저장소에는 절대 넣지 않으며, 연동에 필요한 범위로만 권한을 제한합니다.
무엇을 연동하는가
이미 돌아가는 시스템들을 잇습니다
연동 작업 대부분은 특별하지 않습니다. 고객, 주문, 청구서가 무엇인지에 대해 두 시스템의 인식을 맞추고, 한쪽을 쓸 수 없을 때를 처리하는 일입니다.
CRM과 영업 도구
연락처, 거래, 활동 기록을 웹사이트·폼과 팀이 쓰는 CRM 사이에서 동기화합니다.
ERP와 회계
청구서, 재고, 원장 기록을 기준이 되는 회계 시스템 또는 ERP와 주고받습니다.
물류와 배송
택배 접수, 송장 생성, 운임 조회, 배송 상태를 자사 화면으로 가져옵니다.
SMS, 이메일, 알림
각 제공사를 통한 트랜잭션 메시지. 발송 상태와 재시도 동작을 명시적으로 처리합니다.
마켓플레이스·채널 동기화
자사 플랫폼과 입점한 마켓플레이스 사이에서 상품, 재고, 주문을 맞춥니다.
맞춤 REST·GraphQL API
자사 제품이나 파트너를 위한 API를 버전 관리, 인증, 문서와 함께 구축합니다.
웹훅과 이벤트 처리
들어오는 이벤트를 수신·검증하고 큐에 넣어 처리하므로, 트래픽이 몰려도 기록이 유실되지 않습니다.
레거시·데이터베이스 브리지
오래된 시스템은 데이터베이스 직접 접근을 허용하는 대신 정의된 인터페이스로 노출합니다.
왜 중요한가
비용은 장애 상황에서 발생합니다
아무 문제 없는 날에 두 시스템을 잇는 일은 간단합니다. 값을 치를 가치가 있는 작업은 제공사가 타임아웃되고, 필드를 바꾸고, 호출을 제한하고, 같은 이벤트를 두 번 보낼 때 무슨 일이 일어나는가입니다.
손으로 다시 입력하는 비용은 큽니다
직원이 시스템 사이에서 주문을 옮겨 적는 방식은 느리고, 몇 주 뒤 대사 과정에서야 드러나는 불일치를 만듭니다.
외부 서비스는 멈춥니다
제공사에도 장애와 점검 시간이 있습니다. 큐와 재시도, 명확한 대체 동작이 있으면 상대가 복구되는 동안에도 우리 쪽은 계속 돌아갑니다.
중복이 가장 흔한 버그입니다
타임아웃이 실패를 뜻하지는 않습니다. 멱등 키와 대사가 없으면 재시도는 두 번째 청구나 두 번째 출고가 됩니다.
API는 바뀝니다
필드는 폐기되고 버전은 종료됩니다. 연동에는 모니터링과 책임자가 필요하지, 한 번 만들고 잘되기를 바라는 것으로는 부족합니다.
진행 방식
정리하고, 만들고, 일부러 깨뜨립니다
기간은 제공사 문서의 품질, 샌드박스 제공 여부, 인증 정보와 승인이 얼마나 빨리 나오는지에 달려 있습니다. 대개 마지막 항목이 가장 오래 걸립니다.
- 01
조사와 문서 검토
제공사의 API 문서를 읽고 현재 요금제에서 실제로 무엇이 가능한지 확인하며, 호출 제한과 샌드박스, 승인 절차를 파악합니다.
- 02
데이터 매핑과 규약
시스템 간 필드를 대응시키고 각 레코드의 기준이 되는 쪽을 정한 뒤, 구현 전에 인터페이스를 문서화합니다.
- 03
샌드박스 구현
제공사의 테스트 환경을 대상으로 개발하며, 인증 정보는 처음부터 코드베이스 밖에 둡니다.
- 04
오류와 재시도 설계
타임아웃, 부분 실패, 중복 이벤트, 호출 제한을 의도적으로 처리하고, 레코드가 생성되는 지점에는 멱등성을 둡니다.
- 05
실패 경로 테스트
정상 경로뿐 아니라 비정상 경로도 시험합니다. 제공사 장애, 잘못된 응답, 재전송된 웹훅, 만료된 인증 정보 등입니다.
- 06
배포와 모니터링
로깅과 알림, 장애 대응 문서를 갖춘 채 운영에 올립니다. 고객보다 먼저 여러분이 장애를 알아차리도록 합니다.
연동 설계
모든 연동에 필요한 네 가지 결정
처리한 요청 수를 꾸며낸 대시보드를 보여드리는 대신, 연동이 안정적으로 돌아갈지 아니면 반복되는 지원 티켓이 될지를 가르는 결정들을 정리했습니다.
인증 방식
API 키, OAuth, 서명된 요청 중 무엇을 쓸지 — 그리고 인증 정보를 어떻게 교체하고 누가 보관할지.
데이터 매핑
각 필드를 어느 시스템이 소유하는지, 레코드를 어떻게 맞추는지, 양쪽이 같은 레코드를 바꾸면 어떻게 되는지.
장애 시 동작
재시도 정책, 백오프, 데드레터 처리, 그리고 제공사를 쓸 수 없는 동안 사용자에게 무엇이 보이는지.
모니터링과 알림
무엇을 기록하고, 무엇이 알림을 발생시키며, 연동이 멈췄을 때 누가 움직여야 하는지.
인증 정보와 제공사 계정은 고객사 명의로 등록되므로, 접근 권한이 저희에게 묶이지 않습니다.
도구
무엇으로 만드는가
기술 선택은 연결하려는 시스템과, 인계 후 고객사 팀이 유지할 수 있는 범위를 따릅니다.
Node.js와 TypeScript
연동 서비스, 웹훅, API 계층
Laravel과 PHP
기존 PHP 애플리케이션 내부의 연동
Python
대용량 데이터 동기화와 예약 작업
REST와 GraphQL
인터페이스 설계, 버전 관리, 문서화
큐와 워커
재시도, 백오프, 트래픽 폭증 처리
PostgreSQL과 Redis
레코드 저장, 멱등 키, 캐싱
보안과 안정성
보장이 아니라 실천
깨지지 않는 연동은 없으며, 보안을 보장한다고 말하는 업체는 과장하는 것입니다. 저희가 약속할 수 있는 것은 일관되게 적용하는 실천 목록과, 연동이 고객사 데이터를 어떻게 다루는지에 대한 분명한 설명입니다.
인증 정보 취급
키는 환경 변수나 시크릿 저장소에 두고 저장소에는 넣지 않으며, 연동에 필요한 최소 권한으로 제한합니다.
전송과 검증
호출은 TLS로 이뤄지며, 들어오는 웹훅은 제공사 시크릿으로 서명이 검증되지 않으면 거부합니다.
호출 제한과 백오프
제공사가 공개한 한도를 지키고, 실패하는 엔드포인트를 두드리는 대신 지수 백오프와 큐를 사용합니다.
데이터와 로깅 원칙
개인정보와 결제 정보는 꼭 필요한 곳에만 기록하고, 그 외에는 가리며, 보관 기간은 합의한 바에 따릅니다.
프로젝트 견적
범위를 먼저, 가격은 그다음
비용은 제공사 API의 품질, 관련된 시스템 수, 샌드박스 유무, 필요한 대사 로직의 양에 따라 달라집니다. 견적 전에 문서를 먼저 검토합니다.
단일 연동
제공사 하나를 시스템 하나에 연결합니다 — 결제 게이트웨이, 택배사, 메시지 발송 서비스 등입니다.
- 문서 검토
- 샌드박스 구현
- 오류와 재시도 처리
- 배포와 인계
다중 시스템 동기화
둘 이상의 시스템을 일치된 상태로 유지하며, 소유 규칙과 상호 대사를 설계합니다.
- 필드와 소유권 매핑
- 예약 실행과 이벤트 기반 동기화
- 중복과 충돌 처리
- 모니터링과 알림
맞춤 API 플랫폼
파트너나 자사 애플리케이션에 공개하는 API를 버전 관리와 문서와 함께 제공합니다.
- 인터페이스 설계
- 인증과 호출 제한
- 공개 문서
- 지원과 버전 정책
질문
자주 묻는 질문
제공사, 일정, 장애 처리, 그리고 연동 작업의 견적 방식에 대해 자주 받는 질문입니다.
두 시스템을 연결해 누군가 데이터를 다시 입력하지 않아도 서로 주고받게 하는 것입니다. 예를 들어 웹사이트와 CRM, 스토어와 택배사, 애플리케이션과 결제 게이트웨이를 연결합니다. 작업의 대부분은 각 레코드를 어느 시스템이 관리하는지, 한쪽을 사용할 수 없을 때 어떻게 할지를 정하는 일입니다.
함께 일하는 방식
분명한 연동 협업 관계
익명 고객 후기, 가동률 수치, 확인할 수 없는 요청량 그래프는 싣지 않습니다. 대신 저희가 스스로에게 적용하는 기준을 밝힙니다.
문서화된 인터페이스
필드, 엔드포인트, 오류 코드, 재시도 동작을 기록해 인계합니다. 개발자 한 사람의 머릿속에 남겨두지 않습니다.
인증 정보는 고객사의 것
제공사 계정은 고객사 명의로 개설하며, 저희 접근 권한은 범위가 제한되고 언제든 회수할 수 있습니다.
장애 상황까지 테스트
정상 경로가 돌아간다는 것뿐 아니라, 제공사가 멈추거나 오류를 반환할 때 무슨 일이 일어나는지도 보여드립니다.
유지할 수 있는 인계
소스 코드, 환경 설정, 흔한 장애를 위한 대응 문서를 다음에 시스템을 맡을 담당자에게 전달합니다.
프로젝트 시작하기
어떤 시스템들이서로 연결돼야 하나요
관련된 시스템, 가지고 계시다면 제공사 API 문서 링크, 그리고 지금 손으로 처리하는 일을 보내주세요. 확인할 사항과 제안 범위, 예상 견적을 회신해 드립니다.