1. Introdução
Esta página é uma documentação complementar ao dicionário automático da API do ERP Spalla. Seu propósito é descrever a ordem operacional em que o integrador externo deve executar as chamadas para realizar o ciclo completo de manutenção de pessoas (clientes e fornecedores) e dos contatos vinculados a elas — inclusão, alteração, exclusão e consulta, via API REST.
Os dados de pessoa residem em duas tabelas distintas do banco:
CLIFOR1— cadastro principal da pessoa (dados básicos, fiscais, comerciais, financeiros).CLIFOR3— cadastro de contatos vinculados à pessoa (responsáveis, telefones, e-mails, autorizações).
Esta página não substitui o dicionário oficial da sua instância. Todos os detalhes técnicos — parâmetros aceitos, tipos de dados, regras de obrigatoriedade, estrutura de retorno, lista de objetos exportados — estão no dicionário oficial e devem ser consultados lá. Quando algum detalhe desse tipo for necessário, esta página orienta o leitor a abrir o dicionário oficial na entrada correspondente.
2. Onde encontrar o dicionário oficial da sua API
Cada empresa que opera o ERP Spalla expõe o seu próprio dicionário automático em um endereço próprio. Para acessá-lo, abra no navegador a URL no formato abaixo, substituindo os placeholders pelos valores da sua instância:
https://<host>:<porta>/root/dicionario?userToken=<token>
<host>— endereço do servidor que hospeda a API.<porta>— porta de comunicação configurada no servidor.<token>— token de identificação fornecido pela equipe responsável pela API.
O dicionário oficial é a fonte autoritativa para parâmetros, tipos, obrigatoriedade, exemplos completos e lista de objetos liberados para a sua API.
3. Visão geral do fluxo
O ciclo completo de manutenção de pessoas compreende três blocos lógicos, executados em ordem:
- Verificar pré-requisitos de retaguarda — cadastros auxiliares (Cidade e País) que precisam existir no ERP antes que uma pessoa possa ser registrada como cadastro completo.
- Incluir a pessoa via API REST — obter o próximo código livre, definir tipo e natureza, preparar os campos obrigatórios e enviar a requisição de criação em
CLIFOR1. Em seguida, criar os contatos emCLIFOR3(quando aplicável). - Manter a pessoa via API REST — alterações posteriores (PUT), exclusões (DELETE) sujeitas às restrições de integridade referencial, e consultas (GET) para auditoria ou sincronização.
Toda criação e alteração via API passa pelas mesmas regras de validação aplicadas quando a operação é feita pela interface do ERP — essas regras residem no backend (banco de dados) e atuam em todos os canais de entrada.
4. Diagrama de execução
Convenção visual: azul (Retaguarda do ERP) · verde (Via API REST).
5. Aviso sobre liberação na retaguarda
Atenção — liberação necessária na retaguarda.
O cadastro de pessoas (e dos contatos) via API REST utiliza os verbos padrão sobre os objetos do ERP. Os verbos de escrita (POST, PUT, DELETE) não vêm habilitados por padrão em todas as instalações do Spalla. A liberação é controlada na retaguarda do ERP pela operação responsável pela API. Sem essa liberação prévia, as requisições de escrita sobre os objetos de pessoa e contato não serão aceitas.
Antes de iniciar a integração, confirme com a equipe responsável que os verbos necessários foram habilitados para a sua chave de API. A lista de verbos efetivamente liberados aparece no próprio dicionário oficial da sua instância.
Antes de uma pessoa poder ser registrada como cadastro completo (sem ficar como pré-cadastro), dois cadastros auxiliares precisam existir no ERP, porque são obrigatoriamente referenciados pelo cadastro principal:
- Cidade (campo
CID_COD) — código da cidade do endereço padrão da pessoa. - País (campo
PS_COD) — código do país do endereço padrão. O ERP preenche automaticamente com o código do Brasil quando o estado não for "EX" (exterior) e o valor enviado for zero ou nulo.
Esses dois cadastros são mantidos pela operação dentro do próprio ERP. Existem ainda cadastros opcionais que podem ser referenciados pela pessoa quando aplicável — vendedor, carteira de cobrança, condição e forma de pagamento, grupo de clientes, plano de rota, entre outros — mas não são obrigatórios para que a pessoa seja registrada como cadastro completo.
Para conhecer os objetos exatos expostos pela API para esses cadastros e as chaves de referência aceitas, consulte o dicionário oficial da sua instância.
O código identificador da pessoa (CF_COD) é a chave primária da tabela CLIFOR1 e deve ser informado pelo integrador no momento da criação. O ERP não gera esse código automaticamente em uma sequence dedicada — a regra de negócio é simples: o próximo código livre é o maior código existente mais 1.
Como descobrir o próximo código
Antes de cada inclusão, o integrador faz uma consulta prévia via API REST sobre o objeto CLIFOR1 (verbo GET), recuperando o maior valor da coluna CF_COD atualmente cadastrado. O próximo código a ser enviado no POST é esse valor incrementado em 1:
próximo CF_COD = MAX(CF_COD na tabela CLIFOR1) + 1
A forma exata de pedir esse agregado — campos, filtros, parâmetros de ordenação ou de seleção (fields, where, orderBy, etc.) — está descrita no dicionário oficial da sua API, na entrada do objeto CLIFOR1.
Cuidado com concorrência. Em cenários com múltiplos integradores criando pessoas simultaneamente, há risco de dois processos obterem o mesmo "próximo código" e o segundo POST falhar por violação de chave primária. Garanta que a sequência consultar o próximo código → enviar o POST seja serializada por processo, ou esteja preparado para tratar o erro de chave duplicada e tentar novamente com o próximo código.
Mesma regra para contatos
O cadastro de contatos em CLIFOR3 usa uma chave composta por CF_COD (a pessoa) e CT_COD (número de ordem do contato dentro da pessoa). O próximo CT_COD livre para uma pessoa segue a mesma lógica, restrita àquela pessoa:
próximo CT_COD para a pessoa = MAX(CT_COD em CLIFOR3 onde CF_COD = pessoa) + 1
Duas decisões precisam ser tomadas antes de montar o corpo da requisição: qual o tipo de relacionamento da pessoa com a empresa, e qual a natureza jurídica.
Tipo (campo CF_TIPO) — obrigatório
| Valor | Significado |
|---|---|
C | Cliente — a pessoa figura como contraparte de operações de venda (títulos a receber, pedidos, orçamentos). |
F | Fornecedor — a pessoa figura como contraparte de operações de compra (títulos a pagar). |
A | Ambos — a pessoa atua simultaneamente como cliente e como fornecedor. |
Natureza (campo CF_NATURA)
| Valor | Significado |
|---|---|
F | Pessoa física — o documento esperado em CF_CPFCGC é o CPF. |
J | Pessoa jurídica — o documento esperado em CF_CPFCGC é o CNPJ. |
A natureza define a validação aplicada ao campo CF_CPFCGC (CPF para natureza física, CNPJ para natureza jurídica) e influencia a regra da Inscrição Estadual descrita no Passo 4.
Para que a pessoa seja registrada como cadastro completo (e não como pré-cadastro), o integrador precisa enviar explicitamente o campo de controle de pré-cadastro como zero e preencher os campos básicos exigidos pelo banco. Caso contrário, o ERP marca automaticamente o registro como pré-cadastro e ele fica indisponível para muitas operações posteriores.
Campo de controle do pré-cadastro. Envie CF_PRECADASTRO = 0 no corpo da requisição para que a pessoa seja gravada como cadastro completo. Se esse campo for omitido ou enviado nulo, o ERP atribui automaticamente o valor 1 (pré-cadastro), e a pessoa fica com cadastro incompleto.
Campos obrigatórios
| Campo | Descrição | Observação |
|---|---|---|
CF_COD | Código da pessoa | Obtido no Passo 2. |
CF_TIPO | Tipo (C, F ou A) | Definido no Passo 3. |
CF_NATURA | Natureza (F ou J) | Definida no Passo 3. Direciona a validação do documento e da inscrição estadual. |
CF_PRECADASTRO | Indicador de pré-cadastro | Enviar 0 para cadastro completo. |
CF_RSOCIAL | Razão social ou nome completo | Obrigatório. |
CF_CPFCGC | CPF ou CNPJ | Obrigatório. Tipo e formato validados conforme CF_NATURA. |
CF_INSEST | Inscrição estadual | Obrigatório. Quando a pessoa é física (CF_NATURA = F) ou é jurídica sem registro estadual, preencher com o texto literal ISENTO. |
CF_END | Logradouro (endereço padrão) | Obrigatório. |
CF_NUMERO | Número do endereço padrão | Obrigatório. |
CF_BAIRRO | Bairro do endereço padrão | Obrigatório. |
CID_COD | Código da cidade | Obrigatório. Referencia o cadastro de cidades (Passo 1). |
CF_ESTADO | UF do endereço padrão | Obrigatório. Convertido automaticamente para maiúsculas. Use EX para endereços fora do Brasil. |
PS_COD | Código do país | Obrigatório. Referencia o cadastro de países (Passo 1). |
CF_CEP | CEP do endereço padrão | Obrigatório. |
CF_DDD + CF_1FONE | DDD e telefone principal | Obrigatórios apenas quando o ERP estiver configurado para exigir telefone no cadastro. |
CF_EMAIL | Endereço de e-mail | Obrigatório apenas quando o ERP estiver configurado para exigir e-mail no cadastro. |
Regra do campo CF_INSEST. Esse campo aceita ou um número de inscrição estadual válido, ou o texto literal ISENTO. Use ISENTO nestes dois cenários:
- Quando a pessoa for pessoa física (
CF_NATURA = F). - Quando a pessoa for pessoa jurídica que não possui inscrição estadual.
Em ambos os casos, enviar o texto ISENTO mantém o cadastro completo sem disparar a validação de inscrição estadual.
Outros campos do CLIFOR1 (mais de uma centena, agrupados em endereço de cobrança, endereço de entrega, dados de crédito, dados fiscais, dados bancários, retenções, configurações de comércio exterior, entre outros) são opcionais e não impedem o cadastro completo. Para a lista exaustiva, tipos e regras específicas, consulte o dicionário oficial da sua API na entrada do objeto CLIFOR1.
Independentemente do canal (interface do ERP, API REST ou procedure), o banco aplica um conjunto de validações em toda operação de inclusão ou alteração de pessoa. Essas regras residem no backend e não podem ser contornadas pelo integrador.
Formato do documento (CPF/CNPJ)
O conteúdo de CF_CPFCGC é validado quanto ao formato segundo a natureza:
CF_NATURA = F→ aplicação das regras de CPF (tamanho, dígitos verificadores).CF_NATURA = J→ aplicação das regras de CNPJ (tamanho, dígitos verificadores).
Documentos com formato inválido são rejeitados.
Duplicidade de pessoa
O banco verifica a existência de outra pessoa com o mesmo CF_CPFCGC no mesmo contexto (mesmo estado, mesma natureza). Cadastros duplicados são rejeitados, com mensagem indicando o código já existente. Antes de enviar a inclusão, faça um GET com filtro por CF_CPFCGC para verificar se a pessoa já existe.
Inscrição estadual
Quando CF_INSEST contiver um valor diferente de ISENTO, o banco aplica a rotina de validação de inscrição estadual conforme a UF informada em CF_ESTADO. A regra varia por estado e segue a tabela oficial.
Pessoa do exterior
Quando o endereço for fora do Brasil (CF_ESTADO = 'EX'), o banco aciona uma rotina específica que valida os campos pertinentes para pessoa estrangeira. Consulte o dicionário oficial para a lista de campos adicionais aplicáveis nesse cenário.
Paridade de regras — API e interface. As validações descritas neste passo são exatamente as mesmas aplicadas quando o cadastro é feito diretamente pela tela do ERP. Elas residem no backend (banco de dados) e atuam em todas as operações de inclusão (POST), alteração (PUT) e exclusão (DELETE), independentemente do canal de origem. Mensagens de erro retornadas pela API são idênticas às geradas pelo banco quando a mesma regra é violada na operação direta pelo ERP.
Com o código livre obtido (Passo 2), o tipo e a natureza decididos (Passo 3) e os campos obrigatórios preparados (Passo 4), o cadastro principal é incluído por uma requisição POST sobre o objeto CLIFOR1 exposto pela API REST.
Estrutura da requisição
A estrutura exata da requisição — endpoint, método HTTP, body JSON, formato dos campos, parâmetros aceitos e payload de retorno — está descrita no dicionário oficial da sua API, na entrada do objeto CLIFOR1. Cada cliente do Spalla possui o seu próprio dicionário, refletindo a configuração e as liberações específicas da sua instância.
Campos preenchidos automaticamente pelo backend
Alguns campos não precisam ser enviados pelo integrador. O banco os preenche automaticamente no momento da inclusão:
CF_USERCTRL— usuário que executou a inclusão.CF_CPFCGCFORMAT— versão formatada do CPF/CNPJ informado emCF_CPFCGC.CF_DTATU— data e hora da última atualização do cadastro.CF_CODADIANTAMENTO— quando não informado, recebe o próprioCF_COD.CF_TIPEMPeCF_TIPEMP2— quando não informados, recebem os valores padrão configurados em parâmetros do sistema.PS_COD— quando não informado e o estado não forEX, recebe automaticamente o código do Brasil.CF_ESTADO— convertido para maiúsculas.
Pré-requisitos cumpridos antes deste passo
Cadastros de Cidade e País (Passo 1) e código livre obtido (Passo 2). Os demais campos obrigatórios (Passo 4) e as regras de validação (Passo 5) devem estar atendidos no corpo da requisição.
Retorno
A API devolve a confirmação do registro criado, com a chave da pessoa (CF_COD) que servirá de referência para o cadastro de contatos (Passo 7) e para todas as operações financeiras subsequentes (lançamento de títulos, baixa, etc.). A estrutura exata do retorno está descrita no dicionário oficial.
Os contatos vinculados a uma pessoa (responsáveis, sócios, funcionários, contatos de cobrança, contatos para envio de notas fiscais) são gravados na tabela CLIFOR3 e expostos pela API como um objeto REST separado. Cada contato pertence a uma única pessoa e é identificado pelo par (CF_COD, CT_COD).
Pré-requisito
A pessoa principal precisa existir em CLIFOR1. O CF_COD do contato deve apontar para uma pessoa já cadastrada.
Obtenção do próximo CT_COD
Antes do POST, o integrador faz um GET sobre CLIFOR3 filtrado pelo CF_COD da pessoa, obtém o maior CT_COD existente para aquela pessoa e usa esse valor + 1.
Campos obrigatórios
| Campo | Descrição |
|---|---|
CF_COD | Código da pessoa principal (chave do CLIFOR1). |
CT_COD | Número de ordem do contato dentro da pessoa. |
CT_NOME | Nome do contato. |
CT_STATUS | Status do contato. Quando não informado, o ERP assume o valor padrão 1 (ativo). |
Demais campos — cargo, data de nascimento, telefones, e-mail, endereço, autorizações para download de XML, indicadores de contato de cobrança / NF-e / NFS-e, dados de portal de usuário — são opcionais. Para a relação completa, tipos e regras, consulte o dicionário oficial da sua API na entrada do objeto CLIFOR3.
Alterações em pessoa ou em contato são feitas por requisições PUT sobre o objeto correspondente (CLIFOR1 para a pessoa, CLIFOR3 para o contato), identificando o registro pela sua chave.
Regras aplicadas
Toda alteração passa pelas mesmas validações descritas no Passo 5 — formato de CPF/CNPJ, inscrição estadual, regras de pessoa do exterior. Adicionalmente, a alteração pode ser bloqueada quando viola regras específicas de transição de estado, por exemplo:
- Reverter cadastro completo para pré-cadastro (definir
CF_PRECADASTRO = 1em uma pessoa que estava com0) é bloqueado quando a pessoa já foi referenciada em orçamentos, pedidos ou documentos financeiros. - Alteração do prefixo de processo de importação (campo
CF_PREFIXOPROCESSO) é bloqueada quando já existe processo de importação cadastrado para a pessoa. - Alteração em campos específicos — como percentual de desconto de venda ou fator de risco — pode exigir permissões de usuário adicionais no ERP.
Mensagens de erro retornadas pela API descrevem a regra violada de forma direta. A lista completa de regras de transição está descrita no dicionário oficial e na documentação interna do ERP.
Campos recomendados na requisição
A API aceita requisições PUT com apenas os campos que serão efetivamente alterados, identificando o registro pela chave primária (CF_COD para pessoa, CF_COD + CT_COD para contato). A estrutura exata do PUT está descrita no dicionário oficial da sua API.
A exclusão de pessoa ou de contato é feita por requisição DELETE sobre o objeto correspondente, identificando o registro pela chave.
Integridade referencial. O ERP Spalla mantém integridade referencial entre os registros. Uma pessoa (cliente ou fornecedor) que já foi utilizada em qualquer documento operacional — orçamento, pedido, nota fiscal, título financeiro, processo de importação, entre outros — não pode ser excluída. A exclusão é rejeitada pelo banco para preservar a consistência do histórico de movimentos.
A mesma restrição se aplica aos contatos: um contato referenciado por outras tabelas do sistema (por exemplo, contatos com usuário de portal vinculado) também permanece bloqueado para exclusão enquanto a referência existir.
Estratégia alternativa — inativação
Quando o objetivo é "remover" uma pessoa que já tem movimentos, a estratégia operacional do ERP é a inativação: alterar o status do cadastro para o valor que indica registro inativo, em vez de tentar a exclusão. Os valores de status disponíveis e o significado de cada um estão descritos no dicionário oficial, na entrada do objeto CLIFOR1.
Quando a exclusão é possível
A exclusão direta funciona apenas para cadastros que nunca foram referenciados por nenhum documento ou processo do ERP. Em ambientes em produção, esse cenário é raro — tipicamente envolve apenas cadastros recém-criados que ainda não foram utilizados em nenhuma operação.
A consulta de pessoas e de contatos é feita por requisições GET sobre os objetos CLIFOR1 e CLIFOR3. O verbo GET é geralmente liberado mesmo nos cenários em que os verbos de escrita estão restritos, por ser leitura.
Os parâmetros aceitos na consulta — filtros (where), seleção de campos (fields), ordenação (orderBy), agrupamento, paginação (limit, offset) — estão descritos no dicionário oficial. A estrutura completa de retorno também está no dicionário, na entrada de cada objeto.
Casos típicos de consulta
- Verificação de duplicidade antes da inclusão — consultar por
CF_CPFCGCantes de chamar oPOSTevita erro de duplicidade. - Obtenção do próximo código livre (Passo 2) — recuperar o maior
CF_CODatual. - Listagem de contatos de uma pessoa — consultar
CLIFOR3com filtro porCF_COD. - Sincronização periódica — recuperar pessoas alteradas a partir de uma data, usando
CF_DTATUcomo filtro. - Auditoria — conferência de dados cadastrais após sincronizações ou importações.
Validações e erros
As validações aplicadas às operações de cadastro de pessoa e de contato são as regras de negócio do banco de dados do ERP Spalla — restrições de integridade referencial, regras das triggers e dos próprios corpos das procedures. Quando alguma dessas regras é violada, a mensagem original gerada pelo banco é retornada no corpo da resposta da API.
O integrador deve tratar a mensagem de erro retornada e exibi-la ou registrá-la conforme a necessidade da integração. As mensagens são definidas pela instalação do ERP e podem variar entre clientes; por isso, esta página não lista mensagens específicas.
Dica — identificar a tabela e o campo a partir da interface do ERP
Atalho para inspeção visual. Ao operar qualquer tela do ERP Spalla diretamente pela interface (Cadastro de Pessoa, Cadastro de Contato ou qualquer outra), pressione a combinação Ctrl + Alt + Shift + H. O sistema altera o título da janela indicando que o modo de identificação está ativo. A partir desse momento, ao parar o mouse sobre qualquer campo da tela, aparece um hintbox mostrando o nome da tabela e da coluna do banco às quais aquele campo da interface está vinculado. É um recurso prático para mapear visualmente, durante o uso do ERP, qual tabela e qual coluna correspondem a cada campo da tela — e assim correlacionar essas referências com as chaves do JSON utilizadas na API.
Relação com o fluxo financeiro
As pessoas cadastradas em CLIFOR1 são as contrapartes obrigatórias de todo lançamento de título financeiro — contas a pagar (quando a pessoa é fornecedor) ou contas a receber (quando a pessoa é cliente). O código retornado pela API após a criação da pessoa (CF_COD) é referenciado no cabeçalho da chamada de lançamento de título.
Existe uma documentação complementar específica sobre o fluxo de lançamento e baixa de títulos financeiros (contas a pagar e contas a receber). Consulte essa documentação para entender como integrar o cadastro de pessoas que esta página cobre com o ciclo financeiro completo — lançamento de títulos, baixa, consulta de contas em aberto e de contas liquidadas.
Onde aprofundar
Esta página é um guia operacional — descreve o que fazer e em que ordem. Para como exatamente chamar cada objeto da API (nomes de chaves, tipos de dado, obrigatoriedade, exemplos completos de payload de requisição e de retorno, parâmetros de consulta), a fonte autoritativa é o dicionário oficial da sua instância, em https://<host>:<porta>/root/dicionario?userToken=<token>.
O dicionário oficial é gerado dinamicamente a partir do banco de dados da própria instalação, refletindo sempre o estado atual da API liberada para aquela chave. Manter o consumo da API baseado nele garante que a integração permaneça alinhada com a versão exata do ERP em produção.