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.

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)

2. 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": "CLAUDNEY"
        }
    ]
}

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": "CLAUDNEY SARTI SESSA"
        }

        // 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. 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.

6. 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.