Instruções para Utilização da API de acesso aos dados do ERP Spalla

1. INTRODUÇÃO

Esta documentação tem como finalidade prover informações sobre a forma de acesso aos dados do SPALLA por meio da API e integração.

2. URL BASE

A API deve ser instalada no servidor do cliente como um serviço do SPALLA, para isto deve-se atribuir as configurações da BASE DE DADOS de integração, a Porta de Comunicação e o Tipo de Protocolo de Transferência a ser utilizado nas requisições sendo eles HTTP ou HTTPS.

A Url Base da API possui a seguinte estrutura

Exemplo de URL Base da API:

Estrutura da URL:

# Formato Geral
https://api.apelido.spalla.app:55002/root

# URL Base (sem o path /root)
https://api.apelido.spalla.app:443

# Observação:
# - Quando a porta é 443 (HTTPS padrão) ou 80 (HTTP padrão), ela não aparece na URL
# - Exemplos: https://api.apelido.spalla.app/root (porta 443 implícita)

3. ENDPOINTS COM AUTENTICAÇÃO

A API Spalla oferece duas formas independentes de autenticação. Escolha apenas uma; elas não são combinadas na mesma requisição.

A seguir, a documentação detalhada de cada uma.

clientNonce

Este endPoint fornece um ID único para que seja executada uma comunicação direta com os dados a aplicação SPALLA, ele deve ser executado sempre antes da autenticação para que seja possível obter o ID único de Autenticação que será utilizado no login.

O ClientNonce é um hash único gerado a partir de um valor aleatório e do login do usuário, ele é utilizado para garantir a segurança da comunicação entre o cliente e o servidor.

Exemplo:

# Exemplo de Requisição para Geração do ClientNonce

https://api.apelido.spalla.app:443/root/clientNonce?UserName=SUPORTE

Response:

{
    "result": "66f4966d5b78de54f0ffdcb9fd5b4db5c1a1e4012ebfb81ef343929e42b2c512"
}

SessionSignature

O SessionSignature é o método de autenticação da API, ele é gerado a partir do ClientNonce e do Password do usuário, ele é utilizado para assinar a sessão do usuário garantindo assim a autenticação do mesmo para a utilização dos demais endPoints.

A sessão de usuário assinada com o SessionSignature tem um tempo de expiração de 5 minutos em caso de inatividade, após este tempo é necessário gerar um novo SessionSignature.

Exemplo:

# Exemplo de Requisição para Geração do SessionSignature

https://api.apelido.spalla.app:443/Auth?UserName=SUPORTE&PassWord=123456&ClientNonce=66f4966d5b78de54f0ffdcb9fd5b4db5c1a1e4012ebfb81ef343929e42b2c512

Response:

{
    "usuario": "SUPORTE",
    "timeout": 60,
    "session_signature": "00021d4a4142ffd2993007e514df8005685ce05f6aae641e3df54ed7055ace6adc6a2a11"
}

3. ENDPOINTS COM CHAVE DE INTEGRAÇÃO

Para uma integração com aplicações de forma mais prática também disponibilizamos um endPoint um pouco mais simples que exige apenas o parâmetro userToken, este endPoint possui todos os recursos já disponibilizados porém existe apenas uma chave de acesso única que deve ser cadastrada para o usuário. Esta chave de acesso está vinculada a um usuário que será liberado para o integrador e estará vinculada a um conjunto de recursos que atender ao escopo da integração

O userToken pode ser informado tanto como QueryParam na requisição quanto no HEADER, sendo que caso exista a informação como QueryParam ela ignora o HEADER, e caso não exista ai ela passa a buscar pelo HEADER

4. MÉTODOS

Como Funciona a Estrutura de Requisições

A API utiliza um conceito diferente do padrão REST tradicional. O método HTTP informado no cabeçalho da requisição não determina a operação que será executada no banco de dados. Em vez disso, a operação real é definida pelo campo "method" dentro do corpo JSON da requisição.

Estrutura Geral das Requisições:

Exemplo Visual da Arquitetura:

# EXEMPLO 1: Consulta de dados (leitura)
# O método HTTP padrão é PATCH. Para leitura, POST ou GET podem ser usados como alternativa

Requisição HTTP:
    Método HTTP: PATCH (padrão) ou POST/GET (alternativa para leitura)
    URL: https://api.apelido.spalla.app:443/root/integrador
    Header: userToken: <SEU_TOKEN_AQUI>
    Body: {
        "method": "GET",              <-- Método SQL (operação real)
        "objectType": "TABLE",
        "objectName": "CLIFOR"
    }

# EXEMPLO 2: Inserção de dados (gravação)
# Para gravação, o método HTTP PATCH é obrigatório

Requisição HTTP:
    Método HTTP: PATCH (obrigatório para gravação)
    URL: https://api.apelido.spalla.app:443/root/integrador
    Header: userToken: <SEU_TOKEN_AQUI>
    Body: {
        "method": "POST",             <-- Método SQL (operação real)
        "objectType": "TABLE",
        "objectName": "CLIFOR",
        "dataFields": [...]
    }

Métodos SQL Disponíveis (Campo "method" no Body)

Abaixo segue a documentação dos métodos SQL que podem ser especificados no campo "method" do corpo JSON para acesso aos dados do SPALLA:

Tipos de Dados e Formatação de Valores

Regras para formatar os valores enviados em dataFields, params, where e having nos métodos POST, PUT, DELETE e PATCH. A API converte internamente todos os valores recebidos em texto antes de aplicar ao banco de dados.

GET

A requisição do tipo GET é utilizada para consultas de dados, ela é feita por meio de um Script JSON que é enviado no corpo da requisição BODY e é interpretada pela API.

O Script JSON é composto por um conjunto de parâmetros que são utilizados para a consulta dos dados, abaixo segue a documentação dos parâmetros.

Através do método GET é possível realizar consultas nos seguintes Objetos

Exemplo:

{
    // *** Método a Ser Executado
    // Nome do método invocado no SQL
    "method": "GET"

    // *** Tipo do Objeto
    // Tipo do Objeto do Select [ TABLE, VIEW, FUNCTION, PROCEDURE RESULT ]
    ,"objectType": "PROCEDURE RESULT"

    // *** Nome do Objeto
    // Nome do Objeto do Select
    ,"objectName": "PRC_RES_CLIFOR1"

    // *** Limit / QUantidade de Registros
    // Quantidade de Registros por resultado
    ,"limit": 5

    // *** Offset / Paginação
    // Registros a pular ( Qtde informada x Limit )
    // Ex: Limit: 5 e Offset : 1 apresentaria os registros de 1 a 5
    // Ex: Limit: 5 e Offset : 2 apresentaria os registros de 6 a 10
    ,"offset": 1

    // *** Campos do Select
    ,"fields": [
        "CF_COD",
        "CF_RSOCIAL",
        "CF_CPFCGC",
        "CF_STATUS"
    ]

    // *** Campos a Ignorar
    // Ignora apenas os campos informados e retorna todos os outros
    // Utilizar apenas um dos grupo "fields" ou "fieldsIgnore" nunca os dois juntos
    // Informar os campos de forma individual separados por vírgula
    ,"fieldsIgnore": [ "CF_RSOCIAL" ]

    // *** Campos Calculados
    // Campos com Expressões SQL, campos fabricados com base nos dados da tabela
    // Informar os campos de forma individual separados por vírgula
    ,"calculatedFields" : [
        "1 AS calculatedFields1",
        "2 AS calculatedFields2",
        "3 AS calculatedFields3"
    ]

    // *** Parâmetros
    // Lista de parâmetros e valores a aplicar na procedure antes do WHERE
    ,"params" : [
        // Parâmetros da Função ou da Procedure com Result
        {
            "name" : "pCF_COD",
            "value": "8"
        }
    ]

    // *** where
    // Expressões de filtros aplicadas no WHERE do SQL
    ,"where": [
        // Campos da Tabela
        {
          "type": "Field",
          "name": "CF_STATUS",
          "value": 1
        }

        // Campos calculados
        ,{
          "type": "Field",
          "name": "calculatedFields3",
          "value": 3
        }

        // Expressões SQL
        ,{
          "type": "Expression",
          "value": "CF_COD > 0"
        }
    ]

    // Group By
    // Campos a Agrupar no resultado do SQL
    // Informar os campos de forma individual separados por vírgula
    ,"groupBy" : [
        "CF_COD",
        "CF_RSOCIAL",
        "CF_CPFCGC",
        "CF_STATUS"
    ]

    // *** Having
    // Lista de condições a aplicar depois do SQL pronto
    // Estes filtros são aplicados após os filtros do WHERE onde podemos filtrar um COUNT por exemplo, ou uma condição além do WHERE
    // Informar os campos de forma individual separados por vírgula
    // Aqui podemos utilizar os campos calculados como filtros
    ,"Having" : [
        // Campos da Tabela
        {
          "type": "Field",
          "name": "CF_STATUS",
          "value": 1
        }

        // Campos calculados
        ,{
          "type": "Field",
          "name": "calculatedFields1",
          "value": 1
        }

        // Expressões SQL
        ,{
          "type": "Expression",
          "value": "CF_COD > 0"
        }
    ]

    // *** Order By
    // Campos de ordenação dos resultados
    // Informar os campos de forma individual separados por vírgula com ou sem as clausulas "ASC" e "DESC"
    ,"orderBy": [
        "CF_COD ASC",
        "CF_RSOCIAL DESC"
    ]
}

POST

Através do método POST é possível realizar consultas nos seguintes Objetos

Exemplo:

{
    // method
    // Nome do método invocado no SQL
    "method": "POST"

    // objectType
    // Tipo do Objeto do Select
    ,"objectType": "TABLE"

    // objectName
    // Nome do Objeto do Select
    ,"objectName": "TESTEAPI"

    // Campos para Insert na Tabela
    ,"dataFields": [
        // Campo 1: Codigo
        {
          "name": "CODIGO",
          "value": 1
        }

        // Campo 2: Nome
        ,{
          "name": "NOME",
          "value": "MARIA DA SILVA"
        }
    ]
}

PUT

Através do método PUT é possível realizar consultas nos seguintes Objetos

Exemplo:

{
    // method
    // Nome do método invocado no SQL
    "method": "PUT"

    // objectType
    // Tipo do Objeto
    ,"objectType": "TABLE"

    // objectName
    // Nome da Tabela
    ,"objectName": "TESTEAPI"

    // Campos para Update da Tabela
    // NÃO informar campos de Chave Primária aqui
    // Formatos: numeric = número ou string com ponto decimal; date = "YYYY-MM-DD"; timestamp = "YYYY-MM-DDTHH:MM:SS" (ISO-8601)
    ,"dataFields": [
        // String
        {
          "name": "NOME",
          "value": "MARIA DA SILVA"
        }

        // Numeric / Decimal
        ,{
          "name": "VALOR",
          "value": "1234.56"
        }

        // Date (somente data)
        ,{
          "name": "DATA_VENCIMENTO",
          "value": "2026-04-21"
        }

        // Timestamp (ISO-8601)
        ,{
          "name": "DATA_EMISSAO",
          "value": "2026-04-21T12:05:13"
        }
    ]

    // Condições para o Update
    // Ao menos um item deve conter "key": true indicando a chave primária
    ,"where": [
        {
          "type": "field",
          "name": "CODIGO",
          "key": true,
          "value": 1
        }
    ]
}

DELETE

Através do método DELETE é possível realizar consultas nos seguintes Objetos

Exemplo:

{
    // method
    // Nome do método invocado no SQL
    "method": "DELETE"

    // objectType
    // Tipo do Objeto do Select
    ,"objectType": "TABLE"

    // objectName
    // Nome do Objeto do Select
    ,"objectName": "TESTEAPI"

    // Condições para a Exclusão
    ,"where": [
        // Deve-se informar a chave primária da tabela para condição de exclusão
        {
          "type": "field",
          "name": "CODIGO",
          "value": 1
        }
    ]
}

PATCH

Através do método PATCH é possível realizar consultas nos seguintes Objetos

Exemplo:

{
    // method
    // Nome do método invocado no SQL
    "method": "PATCH"

    // objectType
    // Tipo do Objeto do Select
    ,"objectType": "PROCEDURE"

    // objectName
    // Nome do Objeto do Select
    ,"objectName": "PRC_TESTEAPI"

    ,"params" : [
        {
            "name" : "pPARAMETRO",
            "value": "TESTE"
        }
    ]
}

5. SPALLA API TOOLKIT

O que é

O Spalla API Toolkit — o toolkit de API para uso de IA do ERP Spalla — é um conjunto de ferramentas que ensina um agente de inteligência artificial a integrar com esta API. Com ele instalado, o agente deixa de depender de o integrador descrever a API a cada conversa: passa a conhecer o contrato das requisições, os objetos que a sua integração alcança e as regras de cada módulo do ERP.

Funciona com Claude Code, Claude Cowork e OpenAI Codex, e é composto de duas peças independentes entre si — um servidor que expõe a API como ferramentas para o agente, e um conjunto de conhecimento sobre como cada módulo espera ser integrado, que funciona mesmo sem o servidor.

Recursos

Vantagens

• Menos tempo até a primeira requisição correta. O agente descobre sozinho os nomes de campo, os tipos e a chave primária de cada objeto, em vez de você conferir tudo no dicionário antes de escrever a primeira chamada.
• Menos erro de contrato. Os pontos em que a API do Spalla difere do REST tradicional — endpoint único, operação declarada no corpo da requisição, dois envelopes de erro distintos — já estão embutidos, e são justamente os que mais consomem tempo de quem integra pela primeira vez.
• Escopo respeitado por construção. O agente enxerga apenas o que o token libera. Objeto não liberado devolve a orientação de solicitar a liberação no ERP, e não uma tentativa de contornar.
• Custo de contexto controlado. As respostas são resumidas e limitadas por padrão, de modo que uma consulta a uma tabela com centenas de colunas não consuma a conversa inteira.
• Você não repete instruções. O que foi combinado uma vez sobre a sua integração continua valendo na conversa seguinte.
• Funciona nos três agentes, com a mesma configuração e o mesmo conhecimento.

Como obter

6. INSTRUÇÕES COMPLEMENTARES

Além da referência técnica dos métodos apresentada acima, disponibilizamos guias complementares com exemplos de fluxos completos de integração para os principais módulos do ERP Spalla. Consulte os documentos abaixo para roteiros passo a passo, exemplos de requisições encadeadas e boas práticas específicas de cada área.

7. OBJETOS DISPONÍVEIS

A API do Spalla expõe quatro tipos de objetos do banco de dados do ERP. Esta seção descreve o que é cada tipo e como ele é utilizado nas requisições.