From b638f57be56f0956fdebbff1938974b10d921eb4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1rio=20Alvial?= Date: Tue, 5 May 2026 14:42:19 -0300 Subject: [PATCH 1/2] docs(api): normalize base URL to api.tracefinance.com Drop the internal service segment (/account, /payment, /webhook) from every published server URL and switch the public host: - production: https://api.tracefinance.com - sandbox: https://api.sandbox.tracefinance.com Updated all three OpenAPI specs, docs.json (api.baseUrl + Mintlify variables), and the matching authoring rule in .claude/rules/openapi.md. Removed a redundant hardcoded literal in webhooks/test-in-sandbox.mdx that duplicated {{sandboxUrl}} and would have drifted on the next host change. --- .claude/rules/openapi.md | 7 +++++-- apis/fx-account/openapi.yml | 4 ++-- apis/fx-payment/openapi.yml | 4 ++-- apis/fx-webhook/openapi.yml | 4 ++-- docs.json | 8 ++++---- webhooks/test-in-sandbox.mdx | 2 +- 6 files changed, 16 insertions(+), 13 deletions(-) diff --git a/.claude/rules/openapi.md b/.claude/rules/openapi.md index 18a6d24..66e2e82 100644 --- a/.claude/rules/openapi.md +++ b/.claude/rules/openapi.md @@ -77,8 +77,11 @@ machine-checkable subset. - `/v1` is a **header selector** (`X-Trace-Version: 1`). It is **never** a URL path segment. Do not write paths like `/api/v1/...`. -- Server URL is per-service: `https://faas.{env}.tracefinance.io/account`, - `/payment`, `/webhook`. +- Server URL is the bare gateway host: `https://api.tracefinance.com` + (production) and `https://api.sandbox.tracefinance.com` (sandbox). Do + **not** include the internal service segment (`/account`, `/payment`, + `/webhook`) — service names are not exposed publicly. Paths begin at + the source channel (`/api/...`). - Strip `/dashboard` and `/admin` paths — only `/api` channel is documented. Public discovery endpoints (e.g., `/references/...`) sit outside `/api` and require no auth — set diff --git a/apis/fx-account/openapi.yml b/apis/fx-account/openapi.yml index f4084bd..f84c3ee 100644 --- a/apis/fx-account/openapi.yml +++ b/apis/fx-account/openapi.yml @@ -4,9 +4,9 @@ info: version: 1.0.0 description: API for managing multi-currency accounts on the Trace FX platform. servers: - - url: https://faas.sandbox.tracefinance.io/account + - url: https://api.sandbox.tracefinance.com description: Sandbox - - url: https://faas.tracefinance.io/account + - url: https://api.tracefinance.com description: Production security: - bearerAuth: [] diff --git a/apis/fx-payment/openapi.yml b/apis/fx-payment/openapi.yml index 683da86..a4e6354 100644 --- a/apis/fx-payment/openapi.yml +++ b/apis/fx-payment/openapi.yml @@ -6,9 +6,9 @@ info: API for deposits, withdrawals, swaps, and beneficiary management on the Trace FX platform. servers: - - url: https://faas.sandbox.tracefinance.io/payment + - url: https://api.sandbox.tracefinance.com description: Sandbox - - url: https://faas.tracefinance.io/payment + - url: https://api.tracefinance.com description: Production security: - bearerAuth: [] diff --git a/apis/fx-webhook/openapi.yml b/apis/fx-webhook/openapi.yml index 9c8e134..bcc6bf5 100644 --- a/apis/fx-webhook/openapi.yml +++ b/apis/fx-webhook/openapi.yml @@ -6,9 +6,9 @@ info: API for managing webhook subscriptions and inspecting webhook delivery history on the Trace FX platform. servers: - - url: https://faas.sandbox.tracefinance.io/webhook + - url: https://api.sandbox.tracefinance.com description: Sandbox - - url: https://faas.tracefinance.io/webhook + - url: https://api.tracefinance.com description: Production security: - bearerAuth: [] diff --git a/docs.json b/docs.json index 0545612..9e6413b 100644 --- a/docs.json +++ b/docs.json @@ -247,8 +247,8 @@ }, "api": { "baseUrl": [ - "https://faas.sandbox.tracefinance.io", - "https://faas.tracefinance.io" + "https://api.sandbox.tracefinance.com", + "https://api.tracefinance.com" ], "auth": { "method": "bearer" @@ -256,8 +256,8 @@ }, "description": "Explore guides, examples, and API references to build with Trace Finance.", "variables": { - "sandboxUrl": "https://faas.sandbox.tracefinance.io", - "productionUrl": "https://faas.tracefinance.io", + "sandboxUrl": "https://api.sandbox.tracefinance.com", + "productionUrl": "https://api.tracefinance.com", "authUrl": "https://auth.tracefinance.io" }, "seo": { diff --git a/webhooks/test-in-sandbox.mdx b/webhooks/test-in-sandbox.mdx index 95c26ad..6ab60b4 100644 --- a/webhooks/test-in-sandbox.mdx +++ b/webhooks/test-in-sandbox.mdx @@ -7,7 +7,7 @@ description: "Develop and verify webhook handlers against the Trace sandbox." The sandbox environment delivers real webhook events as you exercise the API — creating orders, registering beneficiaries, initiating PIX payments, and so on. Use it to develop and test your handler before going to production. -The sandbox base URL is `{{sandboxUrl}}` (`https://faas.sandbox.tracefinance.io`). +The sandbox base URL is `{{sandboxUrl}}`. ## Recommended workflow From 7e975a72d31ad9ce10863983aa86309b11a55074 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1rio=20Alvial?= Date: Tue, 5 May 2026 18:03:21 -0300 Subject: [PATCH 2/2] docs(api): drop production URL from public docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Only sandbox is published. The production base URL is shared with each customer at go-live, after their integration is validated in sandbox — exposing it ahead of that gives the wrong contract and risks pointing partners at a host that may not be routed yet. - removed the production servers: entry from all three OpenAPI specs - collapsed docs.json api.baseUrl to a single sandbox string and deleted the productionUrl Mintlify variable - rewrote guides/environments.mdx URL table as a one-liner naming sandbox and explaining how production access is granted - updated .claude/rules/openapi.md to forbid production URL entries in specs, docs.json, or MDX --- .claude/rules/openapi.md | 13 ++++++++----- apis/fx-account/openapi.yml | 2 -- apis/fx-payment/openapi.yml | 2 -- apis/fx-webhook/openapi.yml | 2 -- docs.json | 6 +----- guides/environments.mdx | 5 +---- 6 files changed, 10 insertions(+), 20 deletions(-) diff --git a/.claude/rules/openapi.md b/.claude/rules/openapi.md index 66e2e82..068a0d0 100644 --- a/.claude/rules/openapi.md +++ b/.claude/rules/openapi.md @@ -77,11 +77,14 @@ machine-checkable subset. - `/v1` is a **header selector** (`X-Trace-Version: 1`). It is **never** a URL path segment. Do not write paths like `/api/v1/...`. -- Server URL is the bare gateway host: `https://api.tracefinance.com` - (production) and `https://api.sandbox.tracefinance.com` (sandbox). Do - **not** include the internal service segment (`/account`, `/payment`, - `/webhook`) — service names are not exposed publicly. Paths begin at - the source channel (`/api/...`). +- Server URL is the bare gateway host. Only the sandbox host is + published: `https://api.sandbox.tracefinance.com`. The production + host is **not** documented publicly — it is shared with the customer + at go-live. Do **not** add a production `servers:` entry, a + `productionUrl` Mintlify variable, or any production URL in MDX. +- Do **not** include the internal service segment (`/account`, + `/payment`, `/webhook`) — service names are not exposed publicly. + Paths begin at the source channel (`/api/...`). - Strip `/dashboard` and `/admin` paths — only `/api` channel is documented. Public discovery endpoints (e.g., `/references/...`) sit outside `/api` and require no auth — set diff --git a/apis/fx-account/openapi.yml b/apis/fx-account/openapi.yml index f84c3ee..911b11c 100644 --- a/apis/fx-account/openapi.yml +++ b/apis/fx-account/openapi.yml @@ -6,8 +6,6 @@ info: servers: - url: https://api.sandbox.tracefinance.com description: Sandbox - - url: https://api.tracefinance.com - description: Production security: - bearerAuth: [] tags: diff --git a/apis/fx-payment/openapi.yml b/apis/fx-payment/openapi.yml index a4e6354..09f1f39 100644 --- a/apis/fx-payment/openapi.yml +++ b/apis/fx-payment/openapi.yml @@ -8,8 +8,6 @@ info: servers: - url: https://api.sandbox.tracefinance.com description: Sandbox - - url: https://api.tracefinance.com - description: Production security: - bearerAuth: [] tags: diff --git a/apis/fx-webhook/openapi.yml b/apis/fx-webhook/openapi.yml index bcc6bf5..97fad92 100644 --- a/apis/fx-webhook/openapi.yml +++ b/apis/fx-webhook/openapi.yml @@ -8,8 +8,6 @@ info: servers: - url: https://api.sandbox.tracefinance.com description: Sandbox - - url: https://api.tracefinance.com - description: Production security: - bearerAuth: [] tags: diff --git a/docs.json b/docs.json index 9e6413b..a02191f 100644 --- a/docs.json +++ b/docs.json @@ -246,10 +246,7 @@ ] }, "api": { - "baseUrl": [ - "https://api.sandbox.tracefinance.com", - "https://api.tracefinance.com" - ], + "baseUrl": "https://api.sandbox.tracefinance.com", "auth": { "method": "bearer" } @@ -257,7 +254,6 @@ "description": "Explore guides, examples, and API references to build with Trace Finance.", "variables": { "sandboxUrl": "https://api.sandbox.tracefinance.com", - "productionUrl": "https://api.tracefinance.com", "authUrl": "https://auth.tracefinance.io" }, "seo": { diff --git a/guides/environments.mdx b/guides/environments.mdx index bffe9f4..3e27fa9 100644 --- a/guides/environments.mdx +++ b/guides/environments.mdx @@ -7,10 +7,7 @@ description: "Sandbox and production base URLs, and what differs between them." Trace FX provides two environments. Use sandbox for development and testing, and production for live integrations. -| Environment | Base URL | -| --- | --- | -| Sandbox | `{{sandboxUrl}}` | -| Production | `{{productionUrl}}` | +The sandbox base URL is `{{sandboxUrl}}`. The production base URL is shared with you at go-live, after your integration has been validated in sandbox. ## Details