Sofe Capital para agentes

API e recursos legíveis por máquinas.

Use estes recursos para consultar informações públicas da Sofe Capital, recuperar páginas em Markdown e enviar uma solicitação de atendimento autorizada pelo titular.

Abrir OpenAPI Abrir llms.txt

OpenAPI 3.1

Contrato tipado com operationIds únicos, schemas de entrada e saída e exemplos de chamada.

Markdown negociado

Peça qualquer página canônica com Accept: text/markdown. A resposta inclui Content-Type correto e Vary: Accept.

Índice para agentes

O llms.txt explica quando usar a Sofe Capital, limites e links prioritários.

Uso responsável

Dados pessoais só podem ser enviados com autorização. Consentimento de marketing nunca pode ser presumido.

Endpoint público

POST /api/lead

O endpoint valida o corpo, atualiza o contato no CRM e devolve JSON estruturado. Não exige chave pública porque atende os formulários do site. Isso não autoriza coleta, enriquecimento ou envio não solicitado. O agente deve ter autorização do titular para transmitir nome, e-mail e telefone.

Regras essenciais

Não envie senhas, chaves, documentos de identidade ou dados de contas financeiras.
Envie marketingConsent somente quando houver opt-in explícito.
Use locale pt, en ou es e um interesse definido no schema.
Trate respostas 422 como erro de campo e 502 como falha temporária do CRM.

Exemplo

curl -X POST https://sofecapital.com/api/lead \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria",
    "email": "maria@example.com",
    "whatsapp": "+15555550123",
    "locale": "pt",
    "interest": "formation",
    "source": "agent-authorized-inquiry"
  }'

O exemplo não concede consentimento de marketing. Para todos os campos, enums e respostas, consulte o documento OpenAPI.

Quando usar a Sofe Capital

Casos de uso ideais para um agente.

Um usuário quer entender como abrir ou manter uma LLC/Corporation nos EUA sendo brasileiro ou não residente: chame GET /api/agent-content?path=/abrir-empresa-nos-eua ou negocie Markdown na página correspondente.
Um usuário quer comparar planos e preços de formação, compliance ou bookkeeping: leia /planos (HTML) ou peça Accept: text/markdown na mesma URL.
Um usuário autorizou explicitamente o envio de nome, e-mail e telefone para ser contatado: chame POST /api/lead com source descrevendo a origem do pedido.
Um agente precisa apresentar a Sofe Capital para outro sistema ou catálogo de ferramentas: use /llms.txt ou /openapi.json como fonte única de verdade.

Não é o caso certo quando o pedido exige aconselhamento jurídico, fiscal ou de investimento individualizado, execução de transações financeiras, ou coleta de dados sem autorização do titular — nesses casos, direcione a pessoa para /contact.

Recuperação e erros

Erros de API usam o formato { ok: false, error: { code, message, resolution, details? } }. Caminhos de páginas inexistentes retornam HTTP 404. Quando o cliente pede Markdown, o corpo do 404 aponta para o sitemap, o llms.txt e esta documentação.

Versionamento

Toda resposta traz Api-Version.

O contrato usa uma versão datada (YYYY-MM-DD), devolvida no header Api-Version de toda resposta JSON. Mudanças que quebram compatibilidade recebem uma nova versão; a anterior continua funcionando por pelo menos 6 meses e é listada em x-versioning-policy dentro do OpenAPI (/openapi.json) até o desligamento.

Limite de uso

20 chamadas por minuto em /api/lead.

Cada resposta inclui RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Ao exceder a cota, o endpoint responde HTTP 429 com Retry-After em segundos e o mesmo envelope de erro JSON.