Olá, como podemos ajudar você?

Tutoriais, dúvidas frequentes e configurações do USE em um só lugar.

DS Connect
23 min
Criado por Vitoria Hellen Ferreira Silva Nunes em 10/11/2026 17:59
Atualizado por Vitoria Hellen Ferreira Silva Nunes em 10/11/2026 18:00


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

ItemInformação
SistemaDS Connect Portal do Cliente
Área / MóduloIntegrações API
Produtos atendidosFit, Smart, Exact e Premium
Processo de ativaçãoGS-REQ-060 — Ativação DS Connect (SLA: 2 dias úteis)
Item de catálogo no MovideskAtivação DS Connect
CobrançaR$ 50 por loja/mês, com 10.000 tokens por loja/mês
NegociaçãoTime de Opcionais/Farmer
Atualizado em10/11/2026
⚠️ Atenção: o Suporte não ativa nem configura o DS Connect. Cliente interessado deve ser direcionado conforme o tipo de conta: SMB → Opcionais/Farmer (telefone (19) 97123-8203) e Grandes Contas → time de Grandes Contas. Veja a seção 2.
Nesta página:
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
Legenda
SIM Faz / disponível
NÃO Não faz / não disponível
Sob liberação Requer liberação específica

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.

RecursoDS 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 escolhidasSIM
Portal do Cliente com chaves ativas, consumo do mês e alertas de consumoSIM
Teste da chave pelo navegador (tela Testar API Key), sem programarSIM
Download do openapi.json com as rotas da chave (para Postman, Insomnia ou assistente de IA)SIM
Gravar ou alterar dados no ERPNÃO
Aceitar chamadas vindas de fora do BrasilNÃO
Desenvolver dashboards, relatórios ou aplicações para o clienteNÃO
Rota de Log de operaçõesSob liberação
💡 Encerrar uma chave não derruba as demais. Como cada aplicação ou parceiro tem a sua, o cliente pode cortar o acesso de um parceiro sem afetar os outros.

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.

1Cliente demonstra interesse.

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.

2(Grandes Contas) Atendimento e envio das rotas.

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.

3Opcionais/Farmer registra o ticket e apresenta a proposta.

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.

4Contratação registrada e ticket encaminhado à Implantação.

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.

5Implantação cadastra o usuário, libera as rotas e treina o cliente.

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.

⚠️ Atenção: a chave de acesso aparece uma única vez, na criação, e o cliente aceita um termo de responsabilidade. Se o cliente perder a chave, não é possível recuperá-la — é preciso emitir uma nova.

3. Como o cliente começa a usar

1Guardar a chave recebida.

A chave é emitida pela Data System com as lojas e rotas definidas na contratação.

2Enviar a chave no cabeçalho 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.

3Testar a chave.

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.

4Importar as rotas.

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:

teste_ds_connect.sh
# 1) Confirma se a chave funciona (rede, prefixo da chave e lojas)
curl "https://ep-api-ash2aqb7eva6b0br.z01.azurefd.net/api/v1/me" \
  -H "X-Api-Key: SUA_CHAVE_AQUI"

# 2) Primeira chamada de dados
curl "https://ep-api-ash2aqb7eva6b0br.z01.azurefd.net/api/v1/clientes" \
  -H "X-Api-Key: SUA_CHAVE_AQUI"

4. Regras e limites da API

RegraComo funciona
Somente leituraTodas as rotas são GET. Nenhuma chamada altera dado no ERP.
Só tráfego do BrasilChamadas 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 chamadas100 requisições por minuto, por IP de saída. Se todo o escritório sai pelo mesmo IP, o limite é compartilhado.
URL oficialA chamada precisa vir pela URL base oficial; outro endereço é bloqueado.
Período máximoConsultas por período aceitam até 90 dias. Acima disso, quebrar em janelas menores.
PaginaçãoListas vêm paginadas (itensPorPagina e pagina, até 1.000 itens por página). Cada página é uma chamada.
Escopo da chaveCada chave só alcança as lojas e as rotas liberadas para ela.
Escopo das rotas
EscopoSignificado
Toda a redeCadastros comuns a todas as lojas (produtos, marcas, coleções etc.).
Por lojaDados apenas das lojas liberadas na chave.
Por região de preçoPreços conforme a região de preço de cada loja.
Sob liberaçãoDisponível só mediante liberação específica (ex.: Log de operações).

5. Áreas e rotas disponíveis

ÁreaRotasO que entrega
Clientes5Cadastro de clientes, busca por CPF/CNPJ e consulta do que mudou
Produtos e preços9Catálogo com grade, marca, coleção, fotos e preços por loja ou região
Estoque6Saldos, movimentações, entradas de mercadoria e estoque mínimo
Vendas e pedidos5Vendas com itens e pagamentos, pré-vendas do PDV e pedidos omnichannel
Financeiro2Contas a pagar e a receber
Compras e fornecedores2Pedidos de compra e cadastro de fornecedores
Logística entre lojas6Distribuições, transferências e sugestões de transferência
Trocas e qualidade2Registro de defeitos
Cadastros da rede7Lojas, equipe, coleções, departamentos, marcas, modelos e log de operações
Lista completa de rotas

Trechos entre chaves, como {loja}, são preenchidos com o valor desejado na chamada. A coluna Tokens indica o custo por chamada.

ÁreaRotaO que entregaEscopoTokens
ClientesGET /api/v1/clientesLista de clientes por loja, paginada e ordenável—1
ClientesGET /api/v1/clientes/cpfCnpj/{cpfCnpj}Cliente pelo CPF ou CNPJ—1
ClientesGET /api/v1/clientes/datultaltClientes alterados no período (incremental)—1
ClientesGET /api/v1/clientes/loja/{lojaCliente}/codigo/{codigoCliente}Cliente por loja e código—1
ClientesGET /api/v1/clientes/{lojaCliente}/{codigoCliente}Cliente por loja e código (endereço curto)—1
Produtos e preçosGET /api/v1/produtosCatálogo completo: classe, coleção, cor, grade, marca, modelo e códigos de barrasToda a rede1
Produtos e preçosGET /api/v1/produtos-data-ultima-alteracaoProdutos alterados no período (incremental)Toda a rede1
Produtos e preçosGET /api/v1/produtos/descricao/{descricao}Busca de produtos pela descriçãoToda a rede1
Produtos e preçosGET /api/v1/produtos/fotos/{data}Fotos por grade alteradas a partir de uma dataToda a rede1
Produtos e preçosGET /api/v1/produtos/loja/{loja}/codigo/{codigo}Produto por loja e códigoToda a rede1
Produtos e preçosGET /api/v1/produtos/loja/{loja}/referencia/{referencia}/cor/{cor}/tamanho/{tamanhodes}Produto e saldo na loja por referência, cor e tamanhoPor loja1
Produtos e preçosGET /api/v1/produtos/marcas/{marcas}Produtos das marcas informadasToda a rede1
Produtos e preçosGET /api/v1/produtos/precoPreços e promoções por loja ou regiãoPor região de preço1
Produtos e preçosGET /api/v1/produtos/{loja}/{codigo}Produto por loja e código (endereço curto)Toda a rede1
EstoqueGET /api/v1/saldosSaldo por produto, grade e lojaPor loja1
EstoqueGET /api/v2/saldosSaldo de estoque — versão 2 (contrato mais recente)Por loja1
EstoqueGET /api/v1/saldos/movimentadosSaldos que movimentaram a partir de data/hora (incremental)Por loja1
EstoqueGET /api/v1/produtos/movimentacoes/loja/{loja}Movimentações de estoque da loja no períodoPor loja1
EstoqueGET /api/v1/entradas-estoqueEntradas de mercadoria com itens, fornecedor e operaçãoPor loja1
EstoqueGET /api/v1/produtos/estoque-minimoProdutos com saldo e estoque mínimo por lojaPor loja1
Vendas e pedidosGET /api/v1/vendasVendas com itens, cliente, pagamentos, vendedor, voucher e NFPor loja5
Vendas e pedidosGET /api/v1/vendas/loja/{loja}/codigo/{codigo}Venda por loja e códigoPor loja1
Vendas e pedidosGET /api/v1/vendas-exceto-crediario/cpf/{cpf}Compras do cliente pelo CPF nos últimos 24 meses (exceto crediário)Por loja1
Vendas e pedidosGET /api/v1/pedidos-vendaPré-vendas do PDV (janelas de até 90 dias)Por loja1
Vendas e pedidosGET /api/v1/omnichannelPedidos omnichannel por número, status e períodoPor loja1
FinanceiroGET /api/v1/contas-a-pagarTítulos a pagar com fornecedor, centro de custo, vencimento e pagamentoPor loja5
FinanceiroGET /api/v1/contas-a-receberTítulos a receber com pagamentosPor loja5
Compras e fornecedoresGET /api/v1/pedidos-comprasPedidos de compra com itens, fornecedor e recebimentosPor loja1
Compras e fornecedoresGET /api/v1/fornecedorCadastro de fornecedores (busca por CNPJ)Toda a rede1
Logística entre lojasGET /api/v1/distribuicoesEnvios do CD para as lojasPor loja5
Logística entre lojasGET /api/v1/distribuicoes/{loja}/{codigo}Detalhe de uma distribuição com itensPor loja1
Logística entre lojasGET /api/v1/transferenciasTransferências entre lojasPor loja5
Logística entre lojasGET /api/v1/transferencias/{loja}/{codigo}Detalhe de uma transferência com itensPor loja1
Logística entre lojasGET /api/v1/sugestoes-transferenciaSugestões de transferência entre lojasPor loja5
Logística entre lojasGET /api/v1/sugestoes-transferencia/{loja}/{codigo}Detalhe de uma sugestão com itensPor loja1
Trocas e qualidadeGET /api/v1/defeitosDefeitos por período, status e finalizaçãoPor loja1
Trocas e qualidadeGET /api/v1/defeitos/{loja}/{codigo}Detalhe do defeito: itens, fornecedor, responsável e fotosPor loja1
Cadastros da redeGET /api/v1/lojasCadastro das lojas (código, CNPJ e dados)Toda a rede1
Cadastros da redeGET /api/v1/funcionarioFuncionários das lojas liberadasPor loja1
Cadastros da redeGET /api/v1/colecoesColeçõesToda a rede1
Cadastros da redeGET /api/v1/departamentosDepartamentosToda a rede1
Cadastros da redeGET /api/v1/marcasMarcas com markup inicial—1
Cadastros da redeGET /api/v1/modelosModelosToda a rede1
Cadastros da redeGET /api/v1/logLog de operações do ERP (usuário, tipo e descrição)Sob liberação1

6. Consumo de tokens

Cada chamada consome tokens, que no Portal do Cliente aparecem com o nome de créditos.

ItemValor
MensalidadeR$ 50 por loja, por mês
Franquia inclusa10.000 tokens por loja, por mês
ExemploRede com 10 lojas: R$ 500 por mês e 100 mil tokens
ExcedenteAcima da franquia, cada crédito custa R$ 0,0050 (conforme Portal do Cliente)
⚠️ Atenção: a negociação é feita pelo time de Opcionais/Farmer — proposta, contratação, volume maior de tokens ou condições especiais. O Suporte não negocia valores: apenas informa e direciona o cliente.
Como o token é consumido
  • 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.
💡 Como orientar o cliente a gastar menos: usar as rotas incrementais (alterados/movimentados), que trazem só o que mudou; usar a consulta direta por loja e código quando souber o código (1 token e retorno pequeno); e aplicar filtros de data, loja e status. O Portal do Cliente também tem a tela Simular consumo, que estima os créditos de uma rota sem fazer chamada.

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 em Authorization ou na URL).
  • Se a chave está ativa no Portal do Cliente. Testar pela tela Testar API Key ou pela rota /api/v1/me.
✅ Chave funcionando: /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

HTTPCódigo (error)O que houveO que fazer
401api_key_requiredRequisição sem o cabeçalho X-Api-Key.Enviar a chave no cabeçalho correto.
401invalid_api_keyChave inexistente, expirada ou revogada.Conferir a chave no portal; se perdida, emitir nova.
403route_not_in_allowlistA chave não cobre essa rota.Solicitar liberação da rota (alteração de escopo).
403write_not_allowedTentativa de escrita; a chave é somente leitura.Escrita precisa de solicitação específica.
403origin_bypass_blockedA chamada não veio pela URL oficial.Usar exatamente a URL base oficial.
400missing_required_fieldFaltou parâmetro obrigatório (o campo vem em field).Informar o parâmetro indicado.
400invalid_date_rangedataFim anterior a dataInicio.Corrigir as datas.
400date_range_too_widePerí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

⚠️ Situação: o cliente recebe alerta de consumo ou ultrapassa a franquia do mês.

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.

Observação: dúvidas comerciais, contratação, novas rotas, lojas ou chaves devem ser direcionadas a Opcionais/Farmer (SMB) ou ao time de Grandes Contas. Para erros de chamada, peça ao cliente o código HTTP, o campo error da resposta e a rota chamada antes de escalar — nunca peça a chave completa.
Este artigo foi útil para você?
Últimos artigos visitados