{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Sofe Capital API","version":"2026-09-01","summary":"Lead intake and agent-readable content for Sofe Capital.","description":"Public contract for submitting an authorized service inquiry and retrieving Markdown content. Agents must obtain the user’s authorization before transmitting personal data. Marketing consent is optional and must never be inferred.","contact":{"name":"Sofe Capital","url":"https://sofecapital.com/contact","email":"contato@mail.sofecapital.com"}},"x-versioning-policy":{"scheme":"Calendar-based version string (YYYY-MM-DD), echoed on every JSON response via the Api-Version response header.","currentVersion":"2026-09-01","breakingChangePolicy":"A new dated version is issued for breaking changes. The previous version keeps working for at least 6 months and is listed below with a sunset date before removal.","deprecations":[]},"x-rate-limits":{"POST /api/lead":{"limit":20,"windowSeconds":60,"headers":["RateLimit-Limit","RateLimit-Remaining","RateLimit-Reset"],"onExceeded":"HTTP 429 with a JSON error body and a Retry-After header in seconds."}},"servers":[{"url":"https://sofecapital.com","description":"Production"}],"tags":[{"name":"Leads","description":"Authorized service inquiries sent to the Sofe Capital CRM."},{"name":"Agent content","description":"Public Markdown content for retrieval and navigation."},{"name":"Webhooks","description":"Signed callbacks reserved for GoHighLevel."}],"paths":{"/api/lead":{"post":{"operationId":"submitSofeServiceInquiry","summary":"Submit a service inquiry","description":"Creates or updates a CRM contact after validating the request. Use only with the person’s authorization. Do not send passwords, access keys, identity documents or financial account data. Setting marketingConsent requires an explicit opt-in.","tags":["Leads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadRequest"},"examples":{"inquiry":{"summary":"Authorized inquiry without marketing opt-in","value":{"name":"Maria","email":"maria@example.com","whatsapp":"+15555550123","locale":"pt","interest":"formation","source":"agent-authorized-inquiry","pagePath":"/abrir-empresa-nos-eua"}}}}}},"responses":{"200":{"description":"Inquiry accepted by the CRM or local mock mode.","headers":{"Api-Version":{"$ref":"#/components/headers/ApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadSuccess"}}}},"400":{"description":"Malformed JSON request.","headers":{"Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The request did not satisfy the typed schema.","headers":{"Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded for this endpoint.","headers":{"Api-Version":{"$ref":"#/components/headers/ApiVersion"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server failure.","headers":{"Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The CRM could not accept the request after retries.","headers":{"Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/agent-content":{"get":{"operationId":"getSofePageAsMarkdown","summary":"Retrieve a public page as Markdown","description":"Returns the same public information available on a Sofe Capital page in a compact Markdown representation. Canonical page URLs also support Accept: text/markdown negotiation.","tags":["Agent content"],"parameters":[{"name":"path","in":"query","required":true,"description":"Absolute site path beginning with a slash.","schema":{"type":"string","pattern":"^/","examples":["/sobre"]}}],"responses":{"200":{"description":"Markdown representation of the requested page.","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Markdown recovery page with links to the sitemap, llms.txt and docs.","content":{"text/markdown":{"schema":{"type":"string"}}}},"422":{"description":"The path parameter is missing or invalid.","headers":{"Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/webhooks/ghl":{"post":{"operationId":"receiveGoHighLevelWebhook","summary":"Receive a signed GoHighLevel event","description":"Reserved for GoHighLevel callbacks. Generic agents should not call this operation.","tags":["Webhooks"],"security":[{"SofeWebhookSignature":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Event accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OkResponse"}}}},"400":{"description":"Malformed JSON event.","headers":{"Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid webhook signature.","headers":{"Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/openapi.json":{"get":{"operationId":"getSofeOpenApiDocument","summary":"Retrieve this API contract","description":"Returns the OpenAPI 3.1 document for Sofe Capital in JSON.","tags":["Agent content"],"responses":{"200":{"description":"OpenAPI document.","headers":{"Api-Version":{"$ref":"#/components/headers/ApiVersion"}},"content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"headers":{"ApiVersion":{"description":"Dated contract version (YYYY-MM-DD) implemented by this response. See x-versioning-policy for the deprecation timeline.","schema":{"type":"string","example":"2026-09-01"}},"RateLimitLimit":{"description":"Maximum number of requests allowed in the current window.","schema":{"type":"integer","example":20}},"RateLimitRemaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer","example":19}},"RateLimitReset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":60}},"RetryAfter":{"description":"Seconds to wait before retrying, present only on 429 responses.","schema":{"type":"integer","example":31}}},"securitySchemes":{"SofeWebhookSignature":{"type":"apiKey","in":"header","name":"x-sofe-signature","description":"Shared webhook secret configured only in the server environment."}},"schemas":{"LeadRequest":{"type":"object","additionalProperties":false,"required":["name","email","whatsapp"],"properties":{"name":{"type":"string","minLength":2,"maxLength":100,"description":"First name or preferred name."},"lastName":{"type":"string","maxLength":100},"email":{"type":"string","format":"email","maxLength":254},"whatsapp":{"type":"string","minLength":8,"maxLength":30,"description":"Contact number including country code."},"source":{"type":"string","maxLength":80},"locale":{"type":"string","enum":["pt","en","es"]},"interest":{"type":"string","enum":["formation","operations","accounting_compliance","banking","wealth_planning","succession","general"]},"journey":{"type":"string","enum":["new_company","existing_company","evaluating"]},"message":{"type":"string","maxLength":2000},"country":{"type":"string","maxLength":100},"company":{"type":"string","maxLength":150},"language":{"type":"string","enum":["pt","en","es"]},"timeframe":{"type":"string","enum":["immediate","within_3_months","within_6_months","researching"]},"revenue":{"type":"string","enum":["pre_revenue","under_100k","100k_500k","over_500k"]},"consent":{"oneOf":[{"type":"boolean","const":true},{"type":"string","const":"accepted"}]},"marketingConsent":{"oneOf":[{"type":"boolean","const":true},{"type":"string","const":"accepted"}],"description":"Send only after explicit marketing opt-in."},"pagePath":{"type":"string","maxLength":300},"utmSource":{"type":"string","maxLength":200},"utmMedium":{"type":"string","maxLength":200},"utmCampaign":{"type":"string","maxLength":200}}},"LeadSuccess":{"type":"object","additionalProperties":false,"required":["ok"],"properties":{"ok":{"type":"boolean","const":true},"mock":{"type":"boolean"}}},"OkResponse":{"type":"object","additionalProperties":false,"required":["ok"],"properties":{"ok":{"type":"boolean","const":true}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"required":["code","message","resolution"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"resolution":{"type":"string","description":"Actionable recovery guidance."},"details":{"description":"Optional structured validation details."}}}}}}},"x-agent-guidance":{"whenToUse":["Retrieve authoritative Sofe Capital service information.","Compare published company formation and compliance scopes.","Submit a service inquiry only after the person explicitly authorizes transmission of their contact details."],"constraints":["Never infer marketing consent.","Never send passwords, private keys, identity documents or financial account data.","Do not represent educational content as legal, tax or investment advice."]}}