API Pública da Soft CS

A API Pública da Soft CS permite que aplicações externas se integrem com a sua operação de Customer Success de forma segura, padronizada e orientada a clientes.

Com ela, integrações podem consultar e manter dados essenciais da jornada do cliente:

Clientes e contatos
Tickets e oportunidades
Tarefas e planos de sucesso
Contratos, cobranças e recebimentos
Health scores e eventos de analytics

A API foi desenhada para permitir que sistemas externos trabalhem junto com a Soft CS sem depender de processos manuais, importações recorrentes ou integrações frágeis.

O Que Você Pode Fazer

Com a API Pública, sua aplicação pode:

Listar, criar, atualizar e excluir clientes
Gerenciar contatos vinculados a clientes
Criar e acompanhar tickets
Registrar oportunidades comerciais
Criar e atualizar tarefas
Gerenciar planos de sucesso, objetivos e tarefas relacionadas
Consultar e manter contratos
Registrar alterações de contrato (upsell, cross-sell, cancelamento)
Registrar cobranças e recebimentos
Enviar e consultar health scores
Registrar eventos de analytics relacionados à jornada do cliente

Estrutura de Recursos

Todas as entidades relacionadas a um cliente são acessadas a partir do próprio cliente:

/api/public/v1/clients/{clientId}/tickets
/api/public/v1/clients/{clientId}/contracts
/api/public/v1/clients/{clientId}/analytics-events

Essa estrutura deixa claro o contexto dos dados e evita operações soltas sem vínculo com o cliente.

Como A API Funciona

Versionamento: A API é versionada. A versão atual é a V1: /api/public/v1

Autenticação: Todas as requisições protegidas usam OAuth 2.0 com Authorization Code + PKCE. O acesso é concedido por um usuário da Soft CS, com permissões explícitas, e a integração recebe um token para agir em nome desse usuário.

Depois de autorizado, o token deve ser enviado no header:

Authorization: Bearer <access_token>

Escopos: Cada token possui escopos que definem exatamente o que a integração pode fazer:

clients:read
tickets:write
contracts:read
analytics-events:write

Se o token não tiver o escopo necessário para uma operação, a API retorna erro de permissão.

Premissas Da API

A API Pública segue algumas premissas importantes:

Versionamento explícito: mudanças relevantes são organizadas por versão
Segurança por OAuth 2.0 + PKCE: integrações acessam dados apenas após autorização do usuário
Permissões por escopo: cada grupo de endpoints exige permissões específicas
Recursos relacionados por cliente: entidades como tickets, contratos e tarefas ficam sempre abaixo de /clients/{clientId}
Paginação por limit e offset: listagens retornam páginas simples e previsíveis
Filtros amplos: endpoints de listagem aceitam filtros para facilitar sincronizações e buscas incrementais
Tokens de curta duração: o access_token expira rapidamente; use refresh_token quando autorizado com offline_access
Respostas JSON: requests e responses usam JSON, exceto endpoints OAuth de token/revogação, que usam application/x-www-form-urlencoded

Próximos Passos

Para começar uma integração:

Cadastre um cliente OAuth na Soft CS
Implemente o fluxo Authorization Code com PKCE
Solicite os escopos necessários para sua aplicação
Troque o code por tokens
Use o access_token para chamar os endpoints da V1
Use o refresh_token para renovar o acesso quando necessário

A partir daí, sua aplicação poderá operar sobre os dados autorizados da Soft CS de forma segura e consistente.