DS Connect — Guia do Suporte
O DS Connect é a plataforma que entrega os dados do ERP Data System (somente leitura) para dashboards, relatórios, BI e aplicações criadas com IA. Cada aplicação ou parceiro recebe uma chave de acesso própria, com as lojas e as rotas liberadas para ela, e o consumo é acompanhado no Portal do Cliente. Consulte este artigo para orientar clientes interessados, explicar como a API funciona e identificar os erros mais comuns.
Palavras-chave: DS Connect · API · Integração · X-Api-Key · Chave de acesso · Rotas · Tokens · Créditos · Portal do Cliente · openapi.json
| Item | Informação |
|---|---|
| Sistema | DS Connect Portal do Cliente |
| Área / Módulo | Integrações API |
| Produtos atendidos | Fit, Smart, Exact e Premium |
| Processo de ativação | GS-REQ-060 — Ativação DS Connect (SLA: 2 dias úteis) |
| Item de catálogo no Movidesk | Ativação DS Connect |
| Cobrança | R$ 50 por loja/mês, com 10.000 tokens por loja/mês |
| Negociação | Time de Opcionais/Farmer |
| Atualizado em | 10/11/2026 |
1. O que é o DS Connect · 2. Como o cliente contrata (fluxo de ativação) · 3. Como o cliente começa a usar · 4. Regras e limites da API · 5. Áreas e rotas disponíveis · 6. Consumo de tokens · 7. Erros mais comuns · 8. Perguntas frequentes
1. O que é o DS Connect
A simples liberação de uma API entrega o dado; o DS Connect entrega o dado e o controle: mostra quem está conectado, o que cada aplicação consulta e quanto consome. São 44 rotas em 9 áreas do negócio, todas de leitura.
| Recurso | DS Connect |
|---|---|
| Libera os dados do ERP para consulta (cadastros, estoque, vendas, financeiro, logística) | SIM |
| Uma chave de acesso para cada aplicação ou parceiro, com lojas e rotas escolhidas | SIM |
| Portal do Cliente com chaves ativas, consumo do mês e alertas de consumo | SIM |
| Teste da chave pelo navegador (tela Testar API Key), sem programar | SIM |
Download do openapi.json com as rotas da chave (para Postman, Insomnia ou assistente de IA) | SIM |
| Gravar ou alterar dados no ERP | NÃO |
| Aceitar chamadas vindas de fora do Brasil | NÃO |
| Desenvolver dashboards, relatórios ou aplicações para o cliente | NÃO |
| Rota de Log de operações | Sob liberação |
2. Como o cliente contrata (fluxo de ativação)
Processo GS-REQ-060 — Ativação DS Connect. Sistemas envolvidos: DS Connect (API), Portal do Cliente, plataforma de cadastro, Movidesk e Sankhya.
SMB: o Suporte ou o CS informa o número do time de Opcionais/Farmer, (19) 97123-8203, para o cliente falar direto com eles.
Grandes Contas: o atendimento é feito pelo time de Grandes Contas.
O time de Grandes Contas responde às dúvidas técnicas e envia o Catálogo de APIs do DS Connect. Com o interesse confirmado, direciona o ticket para Opcionais/Farmer.
Registra o ticket no Movidesk com a categoria “Ativação DS Connect”, apresenta o produto, envia a proposta comercial e conduz a negociação (R$ 50 por loja/mês, com franquia de 10.000 tokens por loja/mês), e define com o cliente as lojas, as aplicações ou parceiros e as rotas de cada um. Se o cliente recusar, a recusa é registrada e o ticket encerrado.
Com a proposta aprovada, a contratação e a quantidade de lojas são registradas no Sankhya. O ticket segue para Implantação/Opcionais com as lojas, as aplicações/parceiros e as rotas de cada chave.
Cadastra o usuário com acesso ao Portal do Cliente e libera lojas e rotas por chave. No treinamento, mostra a tela Testar API Key, o acompanhamento de consumo, o download do openapi.json e o uso do cabeçalho X-Api-Key. Em seguida, o ticket é encerrado.
3. Como o cliente começa a usar
A chave é emitida pela Data System com as lojas e rotas definidas na contratação.
X-Api-Key.Não é no cabeçalho Authorization nem na URL (query string). Toda rota começa com /api/v1/ (ou /api/v2/ no saldo v2) e deve ser chamada pela URL base oficial.
A rota /api/v1/me devolve a rede, o prefixo da chave e o escopo de lojas. É a melhor chamada para saber se o problema é a chave ou a rota. Sem terminal, o cliente pode usar a tela Testar API Key do Portal do Cliente.
No portal, o cliente baixa o openapi.json (OpenAPI 3.0) e importa no Postman, Insomnia ou no gerador de cliente da linguagem. Se for construir com IA, basta entregar esse arquivo e o catálogo ao assistente. Rotas não liberadas vêm marcadas e respondem 403.
Exemplo de teste da chave e de primeira chamada de dados:
4. Regras e limites da API
| Regra | Como funciona |
|---|---|
| Somente leitura | Todas as rotas são GET. Nenhuma chamada altera dado no ERP. |
| Só tráfego do Brasil | Chamadas de fora do país são bloqueadas na borda, antes de chegar à chave. Servidor hospedado em outra região não funciona. |
| Limite de chamadas | 100 requisições por minuto, por IP de saída. Se todo o escritório sai pelo mesmo IP, o limite é compartilhado. |
| URL oficial | A chamada precisa vir pela URL base oficial; outro endereço é bloqueado. |
| Período máximo | Consultas por período aceitam até 90 dias. Acima disso, quebrar em janelas menores. |
| Paginação | Listas vêm paginadas (itensPorPagina e pagina, até 1.000 itens por página). Cada página é uma chamada. |
| Escopo da chave | Cada chave só alcança as lojas e as rotas liberadas para ela. |
| Escopo | Significado |
|---|---|
| Toda a rede | Cadastros comuns a todas as lojas (produtos, marcas, coleções etc.). |
| Por loja | Dados apenas das lojas liberadas na chave. |
| Por região de preço | Preços conforme a região de preço de cada loja. |
| Sob liberação | Disponível só mediante liberação específica (ex.: Log de operações). |
5. Áreas e rotas disponíveis
| Área | Rotas | O que entrega |
|---|---|---|
| Clientes | 5 | Cadastro de clientes, busca por CPF/CNPJ e consulta do que mudou |
| Produtos e preços | 9 | Catálogo com grade, marca, coleção, fotos e preços por loja ou região |
| Estoque | 6 | Saldos, movimentações, entradas de mercadoria e estoque mínimo |
| Vendas e pedidos | 5 | Vendas com itens e pagamentos, pré-vendas do PDV e pedidos omnichannel |
| Financeiro | 2 | Contas a pagar e a receber |
| Compras e fornecedores | 2 | Pedidos de compra e cadastro de fornecedores |
| Logística entre lojas | 6 | Distribuições, transferências e sugestões de transferência |
| Trocas e qualidade | 2 | Registro de defeitos |
| Cadastros da rede | 7 | Lojas, equipe, coleções, departamentos, marcas, modelos e log de operações |
Trechos entre chaves, como {loja}, são preenchidos com o valor desejado na chamada. A coluna Tokens indica o custo por chamada.
| Área | Rota | O que entrega | Escopo | Tokens |
|---|---|---|---|---|
| Clientes | GET /api/v1/clientes | Lista de clientes por loja, paginada e ordenável | — | 1 |
| Clientes | GET /api/v1/clientes/cpfCnpj/{cpfCnpj} | Cliente pelo CPF ou CNPJ | — | 1 |
| Clientes | GET /api/v1/clientes/datultalt | Clientes alterados no período (incremental) | — | 1 |
| Clientes | GET /api/v1/clientes/loja/{lojaCliente}/codigo/{codigoCliente} | Cliente por loja e código | — | 1 |
| Clientes | GET /api/v1/clientes/{lojaCliente}/{codigoCliente} | Cliente por loja e código (endereço curto) | — | 1 |
| Produtos e preços | GET /api/v1/produtos | Catálogo completo: classe, coleção, cor, grade, marca, modelo e códigos de barras | Toda a rede | 1 |
| Produtos e preços | GET /api/v1/produtos-data-ultima-alteracao | Produtos alterados no período (incremental) | Toda a rede | 1 |
| Produtos e preços | GET /api/v1/produtos/descricao/{descricao} | Busca de produtos pela descrição | Toda a rede | 1 |
| Produtos e preços | GET /api/v1/produtos/fotos/{data} | Fotos por grade alteradas a partir de uma data | Toda a rede | 1 |
| Produtos e preços | GET /api/v1/produtos/loja/{loja}/codigo/{codigo} | Produto por loja e código | Toda a rede | 1 |
| Produtos e preços | GET /api/v1/produtos/loja/{loja}/referencia/{referencia}/cor/{cor}/tamanho/{tamanhodes} | Produto e saldo na loja por referência, cor e tamanho | Por loja | 1 |
| Produtos e preços | GET /api/v1/produtos/marcas/{marcas} | Produtos das marcas informadas | Toda a rede | 1 |
| Produtos e preços | GET /api/v1/produtos/preco | Preços e promoções por loja ou região | Por região de preço | 1 |
| Produtos e preços | GET /api/v1/produtos/{loja}/{codigo} | Produto por loja e código (endereço curto) | Toda a rede | 1 |
| Estoque | GET /api/v1/saldos | Saldo por produto, grade e loja | Por loja | 1 |
| Estoque | GET /api/v2/saldos | Saldo de estoque — versão 2 (contrato mais recente) | Por loja | 1 |
| Estoque | GET /api/v1/saldos/movimentados | Saldos que movimentaram a partir de data/hora (incremental) | Por loja | 1 |
| Estoque | GET /api/v1/produtos/movimentacoes/loja/{loja} | Movimentações de estoque da loja no período | Por loja | 1 |
| Estoque | GET /api/v1/entradas-estoque | Entradas de mercadoria com itens, fornecedor e operação | Por loja | 1 |
| Estoque | GET /api/v1/produtos/estoque-minimo | Produtos com saldo e estoque mínimo por loja | Por loja | 1 |
| Vendas e pedidos | GET /api/v1/vendas | Vendas com itens, cliente, pagamentos, vendedor, voucher e NF | Por loja | 5 |
| Vendas e pedidos | GET /api/v1/vendas/loja/{loja}/codigo/{codigo} | Venda por loja e código | Por loja | 1 |
| Vendas e pedidos | GET /api/v1/vendas-exceto-crediario/cpf/{cpf} | Compras do cliente pelo CPF nos últimos 24 meses (exceto crediário) | Por loja | 1 |
| Vendas e pedidos | GET /api/v1/pedidos-venda | Pré-vendas do PDV (janelas de até 90 dias) | Por loja | 1 |
| Vendas e pedidos | GET /api/v1/omnichannel | Pedidos omnichannel por número, status e período | Por loja | 1 |
| Financeiro | GET /api/v1/contas-a-pagar | Títulos a pagar com fornecedor, centro de custo, vencimento e pagamento | Por loja | 5 |
| Financeiro | GET /api/v1/contas-a-receber | Títulos a receber com pagamentos | Por loja | 5 |
| Compras e fornecedores | GET /api/v1/pedidos-compras | Pedidos de compra com itens, fornecedor e recebimentos | Por loja | 1 |
| Compras e fornecedores | GET /api/v1/fornecedor | Cadastro de fornecedores (busca por CNPJ) | Toda a rede | 1 |
| Logística entre lojas | GET /api/v1/distribuicoes | Envios do CD para as lojas | Por loja | 5 |
| Logística entre lojas | GET /api/v1/distribuicoes/{loja}/{codigo} | Detalhe de uma distribuição com itens | Por loja | 1 |
| Logística entre lojas | GET /api/v1/transferencias | Transferências entre lojas | Por loja | 5 |
| Logística entre lojas | GET /api/v1/transferencias/{loja}/{codigo} | Detalhe de uma transferência com itens | Por loja | 1 |
| Logística entre lojas | GET /api/v1/sugestoes-transferencia | Sugestões de transferência entre lojas | Por loja | 5 |
| Logística entre lojas | GET /api/v1/sugestoes-transferencia/{loja}/{codigo} | Detalhe de uma sugestão com itens | Por loja | 1 |
| Trocas e qualidade | GET /api/v1/defeitos | Defeitos por período, status e finalização | Por loja | 1 |
| Trocas e qualidade | GET /api/v1/defeitos/{loja}/{codigo} | Detalhe do defeito: itens, fornecedor, responsável e fotos | Por loja | 1 |
| Cadastros da rede | GET /api/v1/lojas | Cadastro das lojas (código, CNPJ e dados) | Toda a rede | 1 |
| Cadastros da rede | GET /api/v1/funcionario | Funcionários das lojas liberadas | Por loja | 1 |
| Cadastros da rede | GET /api/v1/colecoes | Coleções | Toda a rede | 1 |
| Cadastros da rede | GET /api/v1/departamentos | Departamentos | Toda a rede | 1 |
| Cadastros da rede | GET /api/v1/marcas | Marcas com markup inicial | — | 1 |
| Cadastros da rede | GET /api/v1/modelos | Modelos | Toda a rede | 1 |
| Cadastros da rede | GET /api/v1/log | Log de operações do ERP (usuário, tipo e descrição) | Sob liberação | 1 |
6. Consumo de tokens
Cada chamada consome tokens, que no Portal do Cliente aparecem com o nome de créditos.
| Item | Valor |
|---|---|
| Mensalidade | R$ 50 por loja, por mês |
| Franquia inclusa | 10.000 tokens por loja, por mês |
| Exemplo | Rede com 10 lojas: R$ 500 por mês e 100 mil tokens |
| Excedente | Acima da franquia, cada crédito custa R$ 0,0050 (conforme Portal do Cliente) |
- Cada rota tem seu custo: a maioria custa 1 token; listas pesadas (vendas, contas a pagar/receber, distribuições, transferências e sugestões de transferência) custam 5.
- Cada página conta: cada página de uma lista é uma chamada e consome o custo da rota.
- Retorno grande custa mais: respostas grandes geram tokens extras conforme o tamanho.
7. Erros mais comuns e como resolver
O corpo da resposta sempre traz um campo error com o código do problema.
7.1 Chave não enviada ou inválida
O que o cliente vê: 401 api_key_required ou 401 invalid_api_key.
Causa mais comum: a chave não foi enviada no cabeçalho X-Api-Key, foi digitada errada, ou foi encerrada/expirada no portal.
O que verificar:
- Se a chave está no cabeçalho
X-Api-Key(e não emAuthorizationou na URL). - Se a chave está ativa no Portal do Cliente. Testar pela tela Testar API Key ou pela rota
/api/v1/me.
/api/v1/me devolve a rede, o prefixo da chave e o escopo de lojas.7.2 Rota ou loja sem acesso
O que o cliente vê: 403 route_not_in_allowlist.
Causa mais comum: a chave existe, mas a rota (ou a loja) não foi liberada para ela na configuração. Liberar novas rotas é uma alteração de escopo: direcionar para Opcionais/Farmer (SMB) ou Grandes Contas.
7.3 Acesso bloqueado
O que o cliente vê: 403 origin_bypass_blocked, 429 ou chamada bloqueada sem chegar à API.
Causa mais comum: chamada fora da URL oficial, servidor fora do Brasil, ou mais de 100 requisições por minuto no mesmo IP de saída.
7.4 Tabela completa de erros
| HTTP | Código (error) | O que houve | O que fazer |
|---|---|---|---|
| 401 | api_key_required | Requisição sem o cabeçalho X-Api-Key. | Enviar a chave no cabeçalho correto. |
| 401 | invalid_api_key | Chave inexistente, expirada ou revogada. | Conferir a chave no portal; se perdida, emitir nova. |
| 403 | route_not_in_allowlist | A chave não cobre essa rota. | Solicitar liberação da rota (alteração de escopo). |
| 403 | write_not_allowed | Tentativa de escrita; a chave é somente leitura. | Escrita precisa de solicitação específica. |
| 403 | origin_bypass_blocked | A chamada não veio pela URL oficial. | Usar exatamente a URL base oficial. |
| 400 | missing_required_field | Faltou parâmetro obrigatório (o campo vem em field). | Informar o parâmetro indicado. |
| 400 | invalid_date_range | dataFim anterior a dataInicio. | Corrigir as datas. |
| 400 | date_range_too_wide | Período maior que 90 dias. | Quebrar em janelas de até 90 dias. |
| 429 | — | Mais de 100 requisições por minuto no mesmo IP de saída. | Reduzir a frequência ou espaçar as chamadas. |
7.5 Consumo acima da franquia
Causa mais comum: consultas sem filtro, listas pesadas (rotas de 5 tokens) chamadas com muita frequência, muitas páginas ou retornos grandes. Orientar conforme as dicas da seção 6; para volume maior, direcionar ao time de Opcionais/Farmer, responsável pela negociação.
8. Perguntas frequentes
O DS Connect permite gravar dados no ERP?
Não. Todas as rotas são de leitura. Escrita exige solicitação específica.
O cliente perdeu a chave. Dá para ver de novo?
Não. A chave aparece uma única vez, na criação. É preciso emitir uma nova chave.
O servidor do cliente está fora do Brasil. Vai funcionar?
Não. Só é aceito tráfego vindo do Brasil; chamadas de outras regiões são bloqueadas.
Quanto custa e quem negocia?
R$ 50 por loja/mês, com franquia de 10.000 tokens por loja/mês. Toda negociação (proposta, volume extra, condições) é feita pelo time de Opcionais/Farmer.
Quem desenvolve o dashboard ou a aplicação?
O próprio cliente ou o parceiro dele. A Data System entrega os dados, as chaves e o portal, mas não desenvolve as aplicações.
Como o cliente testa sem saber programar?
Pela tela Testar API Key do Portal do Cliente, que faz a mesma chamada da rota /api/v1/me pelo navegador.
“Créditos” e “tokens” são a mesma coisa?
Sim. No catálogo aparece “token”; no Portal do Cliente, “crédito”.
O cliente quer liberar mais rotas, lojas ou um novo parceiro. Para onde direcionar?
SMB: Opcionais/Farmer, (19) 97123-8203. Grandes Contas: time de Grandes Contas.
error da resposta e a rota chamada antes de escalar — nunca peça a chave completa.