> ## Documentation Index > Fetch the complete documentation index at: https://developers.sults.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Convenções da API v1 do SULTS > As regras que valem para a API inteira: URLs base, formato JSON, datas em UTC, campos sem máscara e paginação API v1 Esta página reúne as convenções que valem para **todos os endpoints** da API do SULTS. Aprenda uma vez, use em qualquer módulo. ## URLs base A API responde em `https://api.sults.com.br`, com duas bases de caminho conforme o módulo: | Módulos | Base | Exemplo | | - | - | - | | Unidades (empresas e colaboradores) | `/v1` | `GET /v1/empresas` | | Chamados, Checklist, Compras, Implantação, Projetos e Expansão | `/api/v1` | `GET /api/v1/chamado/ticket` | 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çalho `Authorization`. 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](/v1/autenticacao). ## Formato A API fala **JSON**: envie `Content-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: | Regra | Valor | | - | - | | Formato | `yyyy-MM-ddTHH:mm:ssZ` (UTC ISO 8601) | | Exemplo | `2026-07-20T14:30:00Z` | | Fuso horário | Sempre **UTC**, na resposta e nos filtros de data | Gere e compare datas sempre em UTC para evitar deslocamentos de fuso, inclusive nos cursores de [sincronização](#como-manter-os-dados-atualizados). ## Máscaras Campos com máscara são retornados **sem máscara**, apenas dígitos: | Campo | Como vem | | - | - | | CNPJ | `00000000000000` | | CEP | `38026000` | | Celular | `11987654321` | ## Paginação Os endpoints de listagem são paginados por dois parâmetros de consulta: | Parâmetro | Descrição | | - | - | | `start` | Número da página, a partir de `0`. | | `limit` | Registros por página. **Máximo 100.** | A resposta paginada vem em um envelope: | Campo | Descrição | | - | - | | `data` | Lista com os registros da página. | | `start` | Página retornada. | | `limit` | Registros por página solicitados. | | `totalPage` | Quantidade de páginas disponíveis. | | `size` | Quantidade de registros nesta página. | ```json theme={"theme":{"light":"github-dark","dark":"github-dark"}} { "data": [ { "id": 1, "titulo": "Exemplo 1" }, { "id": 2, "titulo": "Exemplo 2" } ], "start": 0, "limit": 2, "totalPage": 5, "size": 2 } ``` 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. Para varrer todos os registros, incremente `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](/geral/limites). ## 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: 1. Guarde um **cursor**: a data e hora (UTC) da última sincronização que deu certo. 2. 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. 3. Percorra todas as páginas, com `limit=100`. 4. Grave criando ou atualizando pelo `id`, porque a margem de 5 minutos pode trazer registros repetidos. 5. Só avance o cursor quando a execução inteira terminar sem erro. Nem todo endpoint tem filtro de data. Use o melhor que cada módulo oferece: | Módulo | Endpoint | Filtro de data | Como acompanhar | | - | - | - | - | | Chamados | `GET /api/v1/chamado/ticket` | `ultimaAlteracaoStart` / `ultimaAlteracaoEnd` | Pela última alteração: pega criações, interações e mudanças de situação numa consulta só. | | Checklist | `GET /api/v1/checklist/avaliacao` | `dtFimStart` / `dtFimEnd` | Pela data de término, para avaliações finalizadas. | | Compras (pedidos) | `GET /api/v1/comercial/pedido` | `dtPedidoStart` / `dtPedidoEnd` e `canceladoEmStart` / `canceladoEmEnd` | Um cursor para pedidos novos e outro para cancelamentos (com `cancelado=true`). | | Compras (produtos) | `GET /api/v1/comercial/produto` | `publicadoStart` / `publicadoEnd` | Pela data de publicação. Edições não têm filtro: consulte por `id` quando precisar. | | Projetos e Implantação | `GET /api/v1/projeto` e `GET /api/v1/implantacao/projeto` | `dtInicio` / `dtFim` e `concluido` | Projetos novos pela data de início; encerramentos com `concluido=true`. Tarefas: consulte por projeto ativo. | | Unidades | `GET /v1/empresas` e `GET /v1/pessoas` | Nenhum | Varredura completa, comparando `dtUltimaAlteracao` com o seu cursor. Use `ativo=false` para ver inativações. | | Expansão | `GET /api/v1/expansao/negocio` | Nenhum | Varredura por funil e etapa, comparando `dtCadastro` e `dtConclusao`. | Nas varreduras, deixe cerca de 500 ms entre as páginas para respeitar o [limite de requisições](/geral/limites). ## Glossário Os termos do SULTS aparecem assim na API e nesta documentação: | Termo | O que é | Em inglês | | - | - | - | | Unidade | A empresa ou franquia que compõe a rede | Unit | | Colaborador | Pessoa vinculada a uma unidade | Employee | | Chamado | Solicitação de atendimento entre unidades e a central | Ticket | | Avaliação | Aplicação de um checklist em uma unidade | Assessment | | Negócio | Lead ou oportunidade no funil da Expansão | Deal | | Etiqueta | Marcador de organização (tags) | Tag | ## 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](/v1/autenticacao). ## 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. ``` Expansão > Parâmetros > Equipe > Equipe de Expansão ``` Tela Equipe de Expansão, com as listas de administradores e vendedores e o código de cada pessoa destacado antes do nome ### 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. ``` Expansão > Parâmetros > Funis > Etapas ``` Tela Etapas do Funil no módulo de Expansão, com o código #4 destacado antes do nome da primeira etapa ### Origem Para obter o ID de uma origem, acesse a tela de cadastro de origens. ``` Expansão > Parâmetros > Origens de Negócio ``` Tela Origens de Negócio no módulo de Expansão, com o código #1 destacado antes do nome da origem Facebook ### Campanha Para obter o ID de uma campanha, acesse a tela de cadastro de campanhas. ``` Expansão > Parâmetros > Campanhas ``` Tela Campanhas no módulo de Expansão, com o código #17 destacado antes do nome da campanha Redes Sociais ### Situação A situação do negócio pode ser descrita através dos seguintes valores: | Valor | Situação | | - | - | | 1 | Aberto | | 2 | Ganho | | 3 | Perdido | ### Motivo de perda Para obter o ID de um motivo de perda, acesse a tela de motivos de perda. ``` Expansão > Parâmetros > Motivos de Perda ``` Tela Motivos de perda no módulo de Expansão, com o código #6 destacado antes do motivo Cliente fora do perfil ### 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. ``` Expansão > Parâmetros > Modelos de Email ``` Tela Modelos de Email no módulo de Expansão, com o código #1 destacado na coluna ID do modelo Primeiro Contado ## Próximos passos Como a API sinaliza falhas e boas práticas de tratamento. Os endpoints dos 7 módulos, com playground. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.