O que é uma API e como utilizá-la no Sienge Plataforma?
Uma API (Interface de Programação de Aplicações) é como um acordo entre sistemas: ela define uma forma segura e padronizada para que diferentes softwares conversem entre si.
Pense nela como um cardápio de restaurante:
Você vê o que pode pedir (ações),
Aprende como pedir (método),
E sabe o que vai receber em troca (resposta).
Como funciona na prática?
Endpoints: são os “endereços” que expõem recursos, como Clientes ou Títulos a Receber.
Cada recurso permite ações típicas:
GET: buscar dados (ex.: obter um cliente)
POST: criar (ex.: cadastrar um novo cliente)
PUT: atualizar (ex.: editar informações de um cliente)
DELETE: excluir (ex.: remover um cliente)
Um recurso (como Clientes ou Credores) é, portanto, o conjunto de ações possíveis sobre aquele tema.
O que você encontra na documentação da API?
Como ler endpoints → o caminho para cada ação (ex.: /clientes/{id}).
Métodos HTTP (GET, POST, PUT, DELETE) → o tipo de operação que pode ser feita.
Autenticação → como comprovar que você tem permissão para usar a API.
Boas práticas → orientações para integrar de forma segura, estável e padronizada.
Por que isso é importante?
Integrações mais rápidas e confiáveis.
Menos retrabalho por erros de formato ou permissão.
As mesmas regras do sistema também valem para a integração.
Onde acessar?
A documentação de APIs é dinâmica e pode sofrer atualizações frequentes. Você pode consultá-la sempre pelo link: Documentação das APIs do Sienge Plataforma;
Visão Geral – Nova API de Transferências de Estoque
A API de Transferências de Estoque permite integrar o estoque do Sienge Plataforma com ferramentas externas, registrando transferências em tempo real com segurança, integridade e conformidade dos dados.
Com as novas validações e regras de negócio, apenas movimentos válidos — de acordo com as mesmas regras aplicadas nas telas do Sienge — são aceitos. Isso evita retrabalho, inconsistências e divergências de saldo.
- Problema que atendemos: falta de um meio seguro e consistente para registrar transferências de estoque via integração, respeitando saldos, apropriações e cadastros.
- Ganhos no dia a dia: redução de erros, bloqueio de duplicidades, garantia de saldos, trilha de auditoria e aceleração do fluxo operacional de transferência entre obras/centros.
- Como acessar: documentação técnica e endpoints no Portal de Desenvolvedores do Sienge em: Plataforma > APIs > Suprimentos > Estoque > Transferências.
- Contexto funcional: as mesmas regras do Sienge (telas de Estoque) são aplicadas aos movimentos via API. Referência funcional: Suprimentos > Estoque > Movimentos de Estoque.
O que foi entregue (incrementos)
A API valida automaticamente todas as informações enviadas no POST de transferências, garantindo dados válidos e consistentes:
- Campos obrigatórios: documento, data do movimento, tipo de movimento (ativo e do tipo “Transferência”), centro de custo de origem e destino, e pelo menos um insumo.
- Validação de valores informados: documento, centro de custo, insumo, unidade de movimento, detalhe e marca conforme restrições e cadastros do Sienge.
- Regras de data e quantidade: validação de data do movimento; verificação de quantidade informada.
Tipo de movimento: precisa existir e estar ativo.
Prevenção de duplicidade: impede cadastro quando documento + número já existir.
Geração automática: número do movimento quando não informado; preço do insumo para itens de saída conforme regra de custo vigente.
- Parâmetros 506 e 293: validação e tratamento conforme regras atuais do Sienge.
- Estoque e reservas: consome estoque nos itens de saída e adiciona nos itens de entrada; bloqueia se saldo insuficiente (considerando reservas).
- Auditoria: geração de logs para todas as tabelas envolvidas.
- Documentação técnica: endpoints, parâmetros, exemplos de requisição e resposta, regras de validação e mensagens de erro disponíveis no Portal de Desenvolvedores.
Regras de negócio principais
- Itens obrigatórios: pelo menos um insumo no payload.
- Mesma tabela de referência: insumo deve manter o mesmo código, detalhe e marca.
- Tabelas de referência diferentes entre obras: insumos de origem e destino podem ser diferentes, mas devem ser do mesmo tipo; a API não cadastra automaticamente insumo na tabela de destino (se não existir, retorna erro).
- Níveis de apropriação: é permitido transferir entre itens com diferentes níveis de apropriação; quando houver validação de apropriação, o nível do item precisa ser compatível com o nível da obra.
- Unidade de movimento: deve existir e ser válida para o item de origem.
- Estado dos cadastros: marca, detalhe, unidade construtiva e insumos precisam existir; insumos de origem e destino não podem estar inativos.
- Obra/Contrato: não é permitido movimentar estoque para obras que não estejam em andamento.
- Itens duplicados: não é permitido repetir o mesmo item no payload.
- Financeiro: geração de movimentos de entrada e saída em Caixas e Bancos quando aplicável ao cenário de negócio.
- Multi-itens: é permitido criar um movimento com mais de um insumo.
Códigos de status e mensagens (exemplos)
400 – Requisição inválida
Nenhum item informado no payload.
422 – Erro de validação
- Quantidade superior ao saldo disponível na origem (considerando reservas).
- Para mesma tabela de referência: identificadores diferentes (código/detalhe/marca) entre origem e destino.
- Itens repetidos no payload.
- Documento + número já existente. Mensagem exibida no Sienge: “Operação não foi realizada pois já existe um registro cadastrado com este código em: Movimentos de Estoques.”
- Unidade de movimento inexistente para o item de origem.
- Percentual das apropriações diferente de 100%.
- Item de orçamento sem quantidade apropriada.
- Nível do item de apropriação diferente do nível da obra (quando aplicável).
- Marca inexistente.
- Detalhe não encontrado.
- Unidade construtiva não encontrada.
- Insumo de origem ou destino inativo.
- Para obras com tabelas diferentes: insumos de origem e destino de tipos diferentes, ou insumo de destino inexistente (não será cadastrado automaticamente).
201 – Sucesso
Movimento criado com sucesso (com número gerado automaticamente, se não informado).
409 – Conflito de concorrência (opcional, dependendo do contrato da API)
Tentativas simultâneas de transferência no mesmo item/obra.
Nota! As mensagens de erro detalhadas constam na documentação técnica com códigos internos e caminhos de correção sugeridos.
Casos cobertos pela API
- Transferência entre itens da mesma obra:
- Bloqueio quando quantidade excede saldo.
- Bloqueio de itens repetidos.
- Validação de unidade, detalhe, marca, apropriação e nível da obra.
- Permite mais de um insumo no mesmo movimento.
- Transferência entre obras de tabelas de referência diferentes:
- Permite informar insumos distintos entre origem e destino, desde que do mesmo tipo.
- Retorna erro quando insumo de destino não existe (não cria automaticamente).
- Transferência com apropriações diferentes:
- Permitida quando na mesma tabela de referência, respeitando regras de apropriação e percentuais.
Como começar (passo a passo)
Obtenha credenciais de API no seu ambiente DC.
Revise parametrizações relevantes (ex.: parâmetros 506 e 293) com seu administrador.
Consulte a documentação no Portal de Desenvolvedores em: Plataforma > APIs > Suprimentos > Estoque > Transferências.
Implemente chamadas ao endpoint de POST de transferências conforme o contrato.
Valide cenários de saldo, apropriações e cadastros em sandbox antes de ir para produção.
Monitore respostas 4xx/5xx e trate os erros conforme retorno da API.
Ative logs e auditoria no seu conector para rastreabilidade ponta a ponta.
Para quem é recomendada esta API
Empresas que usam ERPs satélites, WMS, sistemas de canteiro ou apps móveis de campo.
Times de TI e parceiros que precisam registrar transferências com a mesma governança do Sienge.
Permissões e pré-requisitos
Perfil com permissão para Estoque e acesso às obras/centros de custo.
Cadastros de insumo, detalhe, marca, unidade e unidade construtiva válidos e ativos.
Obras em andamento.
Parâmetros 506 e 293 configurados conforme regras do Sienge.
FAQ
Preciso informar o número do movimento?
Não. Se não for informado, o Sienge gera automaticamente.
A API cria insumo na obra de destino?
Não. Para tabelas diferentes, o insumo precisa existir e ser do mesmo tipo.
Posso transferir entre apropriações diferentes?
Sim, respeitando regras de apropriação e percentuais (total = 100%).
Existe trilha de auditoria?
Sim. Todas as tabelas envolvidas geram registros de auditoria.
Dica! Suporte
Precisa de ajuda para habilitação, documentação ou comportamento da API? Abra um chamado no Ajuda Sienge informando:
Ambiente (DC).
Obras e centros de custo envolvidos.
Payload da requisição.
Response (incluindo status e body).
Prints, quando possível.
Disponibilidade e quem pode usar as APIs do Sienge?
APIs do Sienge estão disponíveis para clientes na versão Data Center (DC).
Clientes em servidor local não têm acesso às APIs.
Para informações detalhadas sobre disponibilidade de recursos e planos, acesse o artigo: Quais clientes podem utilizar APIs e quais recursos do sistema estão disponíveis? – Sienge Plataforma
Esperamos que este artigo tenha ajudado!