API 연동이란?

기업용 API 연동의 기본형은 여전히 REST입니다. HTTP 메서드(GET, POST, PUT, PATCH, DELETE)로 자원을 다루고 JSON으로 데이터를 주고받는 단순한 구조 덕분에 도구·언어·플랫폼이 폭넓게 지원합니다. 한 번에 여러 종류의 데이터를 가져와야 하는 모바일·복합 UI에는 필요한 필드만 골라 받을 수 있는 GraphQL이 자주 쓰입니다. 고볼륨·저지연이 필요한 내부 서비스 간 통신에는 Protocol Buffers와 HTTP/2를 쓰는 gRPC가 선택됩니다. 모두 같은 통합 문제를 다른 각도에서 해결하는 패턴들입니다.

통합 방향성도 두 갈래입니다. 한쪽은 요청–응답형(request–response)으로, 받는 쪽이 필요할 때 호출하는 pull 패턴입니다. 또 한쪽은 이벤트 기반(event-driven)으로, 상태가 바뀌면 웹훅이나 메시지 큐로 알림이 흘러가는 push 패턴입니다. 잘 설계된 시스템은 두 가지를 함께 씁니다 — 실시간 트리거에는 push, 상세 조회와 쓰기에는 pull.

음성 에이전트가 통화 중에 자율적으로 일을 처리하려면, 모델 옆에 외부 시스템 호출이 항상 붙어 있어야 합니다. 고객이 '지난주 주문 상태를 확인해 주세요'라고 말하면 에이전트는 CRM 또는 주문 시스템 API를 호출해 주문 ID를 조회하고, 배송 API에서 현재 상태를 가져와 TTS로 다시 말로 전해 줍니다. 예약 변경, 결제 안내, 상담 라우팅, 통화 요약 저장까지 거의 모든 단계가 API 호출의 묶음으로 이루어집니다.

이때 통화 도중 호출되는 API는 두 가지 추가 제약을 받습니다. 첫째, 응답이 통화 흐름을 끊지 않을 만큼 빨라야 합니다. 보통 단일 API 호출 p95 800ms 이하를 권장 budget으로 두며, 길어질 가능성이 있는 호출에는 모델이 "잠시 확인해 드릴게요" 같은 다리 멘트를 미리 깔게 프롬프트가 설계됩니다. 둘째, 호출의 결과(성공·실패·부분 성공·타임아웃)가 자연어로 다시 고객에게 설명될 수 있도록 명확한 오류 형식이 필요합니다.

동일한 API라도 통화 도중 호출과 통화 종료 후 호출은 budget이 다릅니다. 종료 후 작성하는 상담원 연결 기록이나 통화 요약 저장은 수초 정도 늘어져도 고객 경험에 영향이 없지만, 통화 중 호출이 늘어지면 바로 dead air가 됩니다. 운영팀이 API 연동을 검토할 때 통화 단계별 latency budget을 분리해 두는 것이 일반적입니다.

운영 가능한 API 연동에는 몇 가지 항목이 항상 함께 따라옵니다. 첫째는 인증입니다. 서버 간 호출에는 API key, 사용자 대리 호출에는 OAuth 2.0이 표준입니다. 액세스 토큰은 짧게 만료되도록 두고(Stripe·Xero 모두 30~60분), refresh 토큰으로 만료 직전 proactive refresh를 거는 패턴이 안전합니다. 401 응답이 오면 토큰을 갱신하고 한 번만 재시도하는 것이 권장 원칙입니다. 무한 retry는 thundering herd로 이어집니다.

둘째, 쓰기 작업에는 idempotency를 설계합니다. 네트워크가 끊겨 응답을 못 받은 상태에서 같은 요청을 다시 보내면 결제·예약·통화 발신이 중복 실행될 수 있습니다. Stripe는 `Idempotency-Key` 헤더로 클라이언트가 UUID를 보내면 서버가 같은 키에 대해 첫 번째 응답을 그대로 돌려주는 패턴을 표준화했고, 자체 시스템에서도 Redis SETNX와 24시간 TTL로 같은 효과를 만들 수 있습니다.

셋째는 rate limit입니다. 대부분의 공개 API는 `X-RateLimit-Remaining`, `X-RateLimit-Reset` 헤더로 남은 호출 수를 알려 줍니다. 클라이언트는 이 값을 매 응답마다 읽어 임계치 근처에서 호출 속도를 자체적으로 늦추고, 429 응답에는 `Retry-After` 헤더를 그대로 따르는 것이 권장됩니다. 넷째는 오류 처리입니다. 4xx는 클라이언트 잘못으로 보고 재시도하지 않으며, 5xx와 timeout만 exponential backoff로 재시도합니다. 모든 호출에는 connect/read timeout이 분리되어 걸려 있어야 한 호출이 통화 전체를 막지 않습니다.

API 연동은 MCP, 웹훅, SDK는 각자 다른 layer에서 같은 통합 문제를 푸는 도구입니다. REST API는 가장 일반적인 호출 계층이고, SDK는 그 API를 특정 언어에서 쉽게 쓰도록 감싼 라이브러리이며, 웹훅은 그 API의 상태 변화 알림을 push로 받는 보조 채널입니다. MCP는 AI 에이전트가 같은 API들을 도구 발견·자격 증명 격리·표준 인터페이스로 묶어 호출하게 만드는 위 layer 프로토콜입니다.

실제 연동 설계에서는 셋이 함께 등장합니다. 예약 시스템은 REST API로 노출되고, SDK가 백엔드 코드에서 그것을 호출하기 쉽게 하며, 예약 상태 변경은 웹훅으로 외부에 알리고, AI 에이전트는 MCP 서버를 통해 같은 도구를 발견·호출합니다. 어느 한 가지로 모든 시나리오를 풀려고 하면 한쪽이 무리해집니다. 통화 도중 실시간 호출은 REST API + SDK, 통화 후 이벤트 알림은 웹훅, AI 에이전트의 도구 묶음은 MCP — 이 정도의 역할 분담이 일반적입니다.

도입 시점에는 운영 측면도 같이 봐야 합니다. 통화에 등장할 수 있는 모든 API 호출에 대해 개인정보 마스킹 정책과 AI 가드레일이 어디서 enforce되는지를 결정해 둬야 하며, 인증 자격 증명은 비밀 관리자(secret manager)에 두고 정기 로테이션 절차를 함께 마련해야 합니다. API 연동의 품질은 호출 자체보다 주변 안전장치의 설계에서 결정됩니다.