Perguntas Frequentes sobre a API do ERP Spalla

É a porta de entrada oficial para que outros programas conversem com o seu ERP, de forma automática e sem intervenção humana.

Na prática: em vez de alguém exportar uma planilha, conferir e digitar em outro sistema, o outro sistema pede a informação diretamente ao Spalla e recebe a resposta na hora. O mesmo vale no sentido inverso — um pedido feito na sua loja virtual pode entrar no ERP sozinho, no momento em que o cliente finaliza a compra.

É um recurso do próprio ERP — não um produto separado que roda por fora. Comercialmente, a API é um módulo do Spalla, contratado à parte: você o habilita quando decide integrar, e ele passa a trabalhar sobre a mesma base e as mesmas regras do sistema que a sua equipe já usa.

Os usos mais comuns entre nossos clientes:

• Loja virtual e marketplace — pedidos entram no ERP automaticamente; estoque e preços saem do ERP para a loja.
• Painéis de indicadores e BI — a ferramenta de análise lê os dados direto da fonte, sempre atualizados.
• Força de vendas — o aplicativo do representante consulta o catálogo e registra pedidos em campo.
• Automações internas — rotinas que conferem, classificam ou lançam informação sem ninguém digitar.
• Agentes de inteligência artificial — assistentes que consultam e, quando autorizados, registram informação no ERP.

O que essas situações têm em comum é a eliminação da digitação intermediária, que é onde o erro costuma nascer.

Não há troca de sistema. A API conversa com a mesma base de dados que a sua equipe já usa todos os dias — não existe cópia, sincronização noturna ou banco paralelo. O que a API mostra é o que está no ERP naquele instante.

O que existe é a habilitação do módulo de API — contratá-lo à parte e definir quais informações serão expostas, para quem, e com quais permissões. É uma conversa de configuração, não um projeto de substituição.

Valem, e este é um dos pontos mais importantes desta página.

As regras do ERP Spalla não estão na tela — estão no servidor. A tela apresenta a informação e conduz o operador, mas quem decide se uma operação é válida é o núcleo do sistema, uma camada abaixo de qualquer interface.

A consequência é direta: um pedido que entra pela API passa exatamente pelas mesmas verificações de um pedido digitado por um funcionário. Controle de estoque, saldo de conta, limite de crédito, travas de segurança, cálculos e consistências — tudo idêntico. Não existe um caminho mais permissivo por ser "de fora".

Não. A API não cria uma porta nova para os seus dados: ela usa o mesmo núcleo de segurança do ERP em que a sua equipe já confia todos os dias. Nada fica exposto por estar "na API".

Três pontos sustentam essa tranquilidade:

• Você decide o que compartilhar. Cada integração enxerga apenas as informações que você liberou para ela, com as permissões que você definiu — nem um campo além.
• Cada parceiro tem a sua própria chave. O acesso é identificado a cada requisição, e você corta o de um parceiro a qualquer momento, na hora, sem afetar os demais.
• A comunicação é protegida. O tráfego com a API ocorre por conexão segura (HTTPS), como o de um banco on-line.

Essa é a situação normal de operação, e o sistema foi construído para ela.

Todos os caminhos de entrada — o ERP no computador, o aplicativo web e os serviços de API — convergem para o mesmo servidor, e as requisições são tratadas de forma centralizada e serializada. Não são três sistemas conversando e tentando se acertar depois: é um só, recebendo de três portas.

O controle de estoque é o exemplo mais fácil de visualizar. Imagine a última unidade de um produto sendo disputada, no mesmo segundo, por um vendedor digitando no ERP, por um cliente finalizando compra no aplicativo web e por um pedido chegando de um marketplace pela API. Não há ambiguidade sobre "quem chegou primeiro", e não há duas reservas do mesmo saldo: o servidor ordena as operações e aplica o controle uma a uma. Quem não puder ser atendido recebe a recusa correspondente, com o motivo.

Nem volume nem velocidade contornam o controle. Uma integração que dispara centenas de requisições por minuto é submetida às mesmas verificações de um operador digitando devagar. Não existe atalho por pressa.

Sua empresa decide, sempre. A definição é feita dentro do ERP, pela pessoa que administra a API na sua operação — não pelo integrador, e não pela empresa que desenvolveu o software dele.

O integrador recebe uma chave de acesso e passa a enxergar exatamente aquilo que foi liberado para ela. Ele não consegue ampliar o próprio acesso, nem descobrir o que existe além do que lhe foi concedido.

Cada integração recebe uma chave de acesso própria, que acompanha toda requisição. É o equivalente ao crachá: quem apresenta a chave é identificado, e o sistema sabe imediatamente de qual integração se trata.

Essa chave está vinculada a um usuário de integração criado no ERP para aquela finalidade. Não é o usuário pessoal de ninguém: é um usuário próprio, com as permissões que aquela integração precisa ter e nada além.

Como consequência, tudo o que acontece pela API é rastreável até a integração que executou.

Não. O acesso funciona por lista de liberação, e não por exclusão: nada é acessível até ser explicitamente liberado para aquela integração.

Na prática, a empresa monta a lista do que aquele parceiro precisa — por exemplo, apenas produtos e preços, para uma loja virtual. Todo o resto do ERP simplesmente não existe do ponto de vista daquela chave. O parceiro não vê, não consulta e não descobre que existe.

Um segundo parceiro, no mesmo ERP, pode ter uma lista completamente diferente, sem nenhuma relação com a primeira.

Sim, e essa é uma das configurações mais usadas. A liberação é feita em dois níveis: o que a integração alcança e o que ela pode fazer com cada item dessa lista.

Um exemplo comum: um painel de indicadores recebe permissão de consulta sobre vendas e estoque, e nenhuma permissão de gravação. Ele lê o que precisa e é incapaz de alterar qualquer coisa — ainda que alguém tente, por engano ou de propósito.

Outro exemplo: uma loja virtual pode receber permissão de criar pedidos, mas não de excluir pedidos existentes.

É possível ocultar informações pontuais dentro de algo que, no restante, está liberado.

O caso clássico é exatamente esse: a loja virtual precisa do cadastro de produtos — descrição, unidade, código de barras, preço de venda — mas não deve enxergar o custo de compra nem a margem. A informação sensível é ocultada, e o parceiro recebe o cadastro sem ela. Do lado dele, é como se aquele dado não existisse.

Isso evita a alternativa ruim, que seria negar o cadastro inteiro por causa de dois campos.

A requisição é recusada, com uma mensagem clara informando que aquele item não está entre as opções daquela integração.

Dois pontos importantes: a recusa acontece no servidor, e não depende de nenhum cuidado do programa que está chamando; e a mensagem não revela o que existe além do permitido — ela apenas informa que aquilo não faz parte daquela integração.

Substituindo ou desativando a chave daquela integração, dentro do ERP. A partir daquele momento, toda requisição feita com a chave antiga passa a ser recusada.

Não é preciso avisar o parceiro com antecedência, mexer em configuração de rede, nem envolver a equipe que desenvolveu o sistema dele. O corte é imediato e vale só para aquela integração — as demais continuam funcionando normalmente.

Não. Ela foi desenhada para integrações que rodam sem ninguém por perto — de madrugada, em servidor, sem supervisão — e por isso não expira por tempo. Ela vale até ser substituída ou revogada.

Existe também uma forma de autenticação temporária, por sessão, usada quando há login de pessoa com usuário e senha. Para integração automática, a chave permanente é o caminho recomendado.

Sim, e é um uso que tem crescido rápido: o agente consulta o ERP para responder perguntas, montar análises ou executar tarefas repetitivas, sempre pela API.

Para o ERP, um agente de IA é mais uma integração. Ele recebe a própria chave, a própria lista de liberação e as próprias permissões, exatamente como um sistema de terceiros receberia.

Nenhum. Esta talvez seja a resposta mais importante desta página.

A inteligência artificial não recebe um acesso diferenciado, não contorna regra alguma e não "conversa direto com o banco de dados". Ela entra pela mesma porta que qualquer outro sistema, apresentando uma chave, e está sujeita às mesmas verificações — a lista do que pode alcançar, o que pode fazer com cada item, os campos ocultos e as permissões do usuário vinculado à chave.

Há um segundo limite, ainda mais forte que as permissões: as regras de negócio do sistema continuam valendo para o agente. Mesmo que ele receba permissão de gravação, não consegue registrar nada que a tela do ERP recusaria — não pode furar o controle de estoque, ignorar um limite de crédito ou lançar um valor que não fecha. A validação acontece no servidor, e o agente está do lado de fora dela como qualquer outro sistema.

Pelos mesmos controles das demais integrações, e a recomendação é começar restritivo.

O ponto de partida saudável é uma chave somente de consulta, alcançando apenas as informações que o agente precisa ler. Com isso, o pior cenário possível é o agente responder algo errado — nunca alterar um documento, um saldo ou um cadastro.

Quando houver confiança e necessidade comprovada, a gravação é liberada de forma pontual: para um tipo específico de registro, e só para a operação que faz sentido. Não é necessário — nem recomendável — abrir tudo de uma vez.

Sim. Não há limite prático de integrações simultâneas, e cada uma é independente das outras.

É comum separar assim: uma chave de consulta, ampla, para análises e relatórios; e uma chave de operação, estreita, alcançando poucos tipos de registro e usada apenas nas rotinas que realmente precisam gravar. Se um dia a chave de operação precisar ser revogada, a de consulta continua funcionando — e o inverso também vale.

A mesma lógica serve para separar ambientes de teste e produção, ou para dar a cada parceiro a sua própria chave em vez de compartilharem uma.

Porque a configuração não está no endereço, e sim na chave.

Todas as integrações chamam o mesmo endereço. Ao receber a requisição, o ERP identifica a chave, carrega o perímetro daquela integração — a lista de liberação, as operações permitidas, os campos ocultos — e aplica o perímetro do usuário vinculado. Duas requisições idênticas, com chaves diferentes, produzem resultados diferentes: uma pode ser atendida e a outra recusada.

A vantagem prática é grande: mudar o que um parceiro pode fazer é uma alteração de configuração no ERP, que entra em vigor na requisição seguinte. Ninguém precisa publicar versão nova, reiniciar serviço ou alterar programa.

Não. Um único serviço atende todos os integradores, cada um com o seu perímetro. Não há custo de infraestrutura por parceiro adicional, nem instalação nova a cada integração.

Isso também simplifica a manutenção: quando o ERP é atualizado, todos os integradores passam a contar com as novidades ao mesmo tempo, sem migração individual.

O ERP gera, para cada chave, um dicionário próprio: um documento que lista exatamente os itens liberados para aquela integração, com os campos disponíveis, os tipos de cada informação, as operações permitidas e exemplos prontos de requisição.

Esse dicionário é gerado a partir da configuração real, no momento em que é aberto — ele não é um manual escrito à mão que pode ficar desatualizado. Duas integrações diferentes abrem o mesmo endereço e recebem documentos diferentes, cada um refletindo o seu próprio perímetro.

Ela segue um modelo próximo do REST, porém com uma diferença importante: em vez de um endereço distinto para cada recurso, existe um endereço único, e a operação desejada é declarada dentro do corpo da requisição, junto com o item a ser acessado.

A consequência prática é boa para quem integra: não é preciso descobrir e manter uma lista de endereços, nem ajustar o programa quando um item novo é liberado. O programa aponta sempre para o mesmo lugar, e o que muda é o conteúdo da requisição.

Os formatos de envio e de resposta são os usuais do mercado, e qualquer linguagem de programação atual consegue consumir a API sem biblioteca especial.

No servidor, de forma centralizada — e não em cada aplicação que consome o sistema. Existe uma única implementação das regras de negócio, compartilhada por todos os canais de entrada. A API não tem uma segunda versão dessas regras.

Três consequências práticas para quem vai integrar:

As integrações existentes continuam funcionando. Campo novo não quebra quem já consome a API: ele passa a estar disponível, e quem não o utiliza segue igual.

O dicionário da integração reflete a mudança automaticamente, porque é gerado a partir da estrutura real e da configuração vigente. O desenvolvedor do parceiro abre o documento e vê o que passou a existir, sem depender de um comunicado.

Itens novos, no entanto, só ficam acessíveis depois de liberados explicitamente para aquela integração. A atualização do ERP não amplia sozinha o perímetro de ninguém.

O caminho mais rápido é levantar três coisas com a área que vai integrar:

1. Quais informações precisam ir e vir — normalmente cabem em uma lista curta.
2. Em que sentido cada uma flui: só leitura, só gravação, ou os dois.
3. Com que frequência: em tempo real a cada evento, ou em lotes periódicos.

Com isso definido, a habilitação da API costuma ser a parte mais curta do projeto — o tempo se concentra do lado do sistema que vai consumir. Fluxos mais comuns, como cadastro de pessoas, cadastro de produtos, pedidos e financeiro, já têm roteiros completos documentados, com a ordem das operações e as validações de cada etapa.

A documentação técnica completa — cada item liberado, cada campo, tipos, obrigatoriedade, retorno e exemplos prontos de requisição — fica no dicionário da sua própria instalação, e é disponibilizada junto com a habilitação da API. Ela é gerada sob medida para o seu ambiente: por isso não existe versão pública, e não faria sentido existir — o conteúdo é diferente para cada empresa e para cada chave.

Para avançar, o caminho é falar com o gestor do ERP Spalla da sua empresa ou com o nosso time comercial. A habilitação inclui a criação do usuário de integração, a definição do perímetro de acesso junto com vocês, e a entrega do endereço, da chave e do acesso à documentação detalhada.