URLs base
A API responde emhttps://api.sults.com.br, com duas bases de caminho conforme o módulo:
O caminho exato de cada endpoint está na página dele, na aba Referência da API.
Autenticação
Toda requisição leva o token no cabeçalhoAuthorization. A geração, as diferenças entre tokens v1 e v2 e as práticas de guarda segura estão em Autenticação e tokens.
Formato
A API fala JSON: envieContent-Type: application/json nas requisições com corpo e espere JSON em toda resposta. A API manipula solicitações CORS, mas mantenha as chamadas no seu backend para não expor o token.
Datas
Todos os campos de data seguem um único formato:
Gere e compare datas sempre em UTC para evitar deslocamentos de fuso, inclusive nos cursores de sincronização.
Máscaras
Campos com máscara são retornados sem máscara, apenas dígitos:Paginação
Os endpoints de listagem são paginados por dois parâmetros de consulta:
A resposta paginada vem em um envelope:
Alguns endpoints retornam a lista diretamente, sem o envelope (por exemplo,
GET /v1/empresas). A página de cada endpoint indica o formato exato da resposta.start até totalPage ou até a página vir vazia, sempre com limit=100.
Limites de requisição
O limite é de 2 requisições por segundo, por IP, e vale igual nas duas versões da API. O tratamento correto, com backoff exponencial e o ritmo das varreduras, está em Limites de requisição.Como manter os dados atualizados
A API não oferece webhooks: o seu sistema consulta os endpoints de tempos em tempos e busca só o que mudou. O padrão que funciona em qualquer módulo:- Guarde um cursor: a data e hora (UTC) da última sincronização que deu certo.
- A cada execução, busque o que mudou desde o cursor com o filtro de data do endpoint, começando 5 minutos antes dele para não perder registros na fronteira.
- Percorra todas as páginas, com
limit=100. - Grave criando ou atualizando pelo
id, porque a margem de 5 minutos pode trazer registros repetidos. - Só avance o cursor quando a execução inteira terminar sem erro.
Nas varreduras, deixe cerca de 500 ms entre as páginas para respeitar o limite de requisições.
Glossário
Os termos do SULTS aparecem assim na API e nesta documentação:Permissões do token
O token da v1 acessa todos os endpoints, incluindo os 7 de escrita. Não há escopo por token nesta versão; o detalhe está em Autenticação.Registros e IDs
Esses são os registros usados para a criação do negócio: os responsáveis, origens, campanhas, etapas e situações da Expansão. Os IDs abaixo são informados nos campos do endpoint de criação de negócio.Responsável
Para obter o ID do responsável, é necessário visualizar as pessoas que estão na equipe de Expansão.
O ID da pessoa aparece antes do nome, com #
Etapa
Cada funil possui uma lista de etapas. Para obter o ID de uma etapa, acesse a lista de funis, abra o funil desejado e encontre a etapa.
O ID da etapa aparece antes do nome, com #
Origem
Para obter o ID de uma origem, acesse a tela de cadastro de origens.
O ID da origem aparece antes do nome, com #
Campanha
Para obter o ID de uma campanha, acesse a tela de cadastro de campanhas.
O ID da campanha aparece antes do nome, com #
Situação
A situação do negócio pode ser descrita através dos seguintes valores:Motivo de perda
Para obter o ID de um motivo de perda, acesse a tela de motivos de perda.
O ID do motivo de perda aparece antes do nome, com #
Modelos de e-mail
Modelos de e-mail são templates usados para enviar uma mensagem a um lead. Para obter o ID de um modelo de e-mail, acesse a tela de modelos de e-mail.
O ID do modelo de e-mail fica na coluna ID
Próximos passos
Erros
Como a API sinaliza falhas e boas práticas de tratamento.
Referência da API
Os endpoints dos 7 módulos, com playground.