External Platform Integration Postmortem: From Unknown Code and New Workflow Pitfalls to AI Agent‑Driven Flow Clarity

Using an Agent to Read the Project

Manual code inspection was too slow, so I asked the AI Agent to locate every entry related to the external platform: inbound callbacks, outbound calls, old and new service invocations, and three‑party relationship handling. Identifying these entry points clarified the project's skeleton, reducing days of reading to a half‑day.

First Pitfall: Misunderstanding the "Create Appointment" Step

The new instant‑appointment flow differs from the old pay‑then‑appoint flow. I mistakenly thought the existing "create appointment" API was the third step of the new flow. The Agent cross‑referenced code, external documentation, and business semantics, revealing that in the instant‑appointment mode the platform creates the appointment itself after payment, and our service only consumes the pushed appointment data.

Second Pitfall: Using the Wrong Appointment ID

In the legacy flow, the ID sent to the external platform came from the old three‑party relationship's fulfillment field. In the instant‑appointment mode the same API expects the newly added instant‑appointment fulfillment field. Because the field names and locations differ, many calls failed with "order not found" or "invalid appointment ID" until the correct source was identified.

Signature Verification Issues

During integration the first blocker was signature verification. For outbound calls we sign with our application private key and the platform verifies with our public key; for inbound callbacks the platform signs with its private key and we verify with its public key. I temporarily disabled verification, then added a configurable switch that logs the raw signature, public key source, timestamp, and nonce when disabled, ensuring safe debugging in non‑production environments.

Documentation Gaps and On‑Call Clarifications

Several fields marked as optional in the official docs were actually required in the instant‑appointment mode, causing errors that only on‑call responses clarified. Additional undocumented behaviors included: merchant refunds not triggering callbacks, absence of cancellation callbacks in the new mode, and platform‑side service‑time mismatches during verification.

Refund Handling Complexity

Refund logic intertwined with appointment cancellation, zero‑amount refunds, and platform discounts. Multiple git commits over two days adjusted refund initiation and amount calculations. The integration required testing not just the happy‑path order flow but also refunds, cancellations, verification, timeouts, and edge‑case branches to avoid hidden failures.

Five Ways the Agent Added Value

Reading unfamiliar code : Quickly mapped all platform‑related entry points.

Structuring oral requirements : Turned verbal explanations into a documented redesign covering background, mode differences, routing design, interface list, field mapping, and changed files.

Identifying non‑core code paths : Clarified that the "create appointment" API is unused in the new flow.

Generating curl commands from logs : Enabled local replay of real requests, speeding up debugging without waiting for the external platform.

Documenting integration conclusions : Captured undocumented platform behaviors and on‑call findings into a permanent reference.

Lessons Learned

Before coding, I would now produce three artifacts: a full‑chain sequence diagram, an interface matrix (direction, entry point, key fields, mode differences), and a field dictionary mapping all order, appointment, refund, and fulfillment IDs. These preparations are more valuable than jumping straight into implementation.

Final Timeline

The original four‑day schedule expanded to nearly a week due to development and integration. The key takeaway is that the uncontrollable factors are mismatched docs, on‑call delays, and the need to align multiple system state machines, not the raw coding effort.