SPAAPI — Fluxo de Contas a Pagar/Receber

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 e cadastros para realizar o ciclo completo de lançamento e baixa de títulos financeiros (contas a pagar e contas a receber), identificando em cada passo se a ação é realizada via API ou na retaguarda do ERP.

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 compreende três blocos lógicos, executados em ordem:

Preparar os cadastros de retaguarda — conjunto de tabelas auxiliares do ERP (empresa, tipo de operação, centro de custo, condição de pagamento, carteira de cobrança, conta corrente, forma de pagamento, etc.) que precisam existir antes que qualquer documento financeiro possa ser lançado. Esses cadastros são feitos pela operação dentro do próprio ERP.
Cadastrar a pessoa (cliente ou fornecedor) via API — a pessoa associada ao documento pode ser criada e mantida via API REST sobre o objeto pessoa do ERP, desde que os verbos de escrita tenham sido previamente liberados na retaguarda.
Executar o lançamento e a baixa do título — chamada à procedure de inclusão (APW_PRC_FINDOCADD) seguida, quando o título for liquidado, da chamada à procedure de baixa (APW_PRC_FINDOCADDBAIXA).

4. Diagrama de execução

Convenção visual: azul (Retaguarda do ERP) · verde (Via API).

5. Aviso sobre cadastro de pessoa via API

Atenção — liberação necessária na retaguarda.

O cadastro de pessoa (cliente ou fornecedor) via API é realizado por chamadas REST padrão (POST, PUT, DELETE) sobre o objeto pessoa do ERP. Esses verbos de escrita, no entanto, 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 o objeto pessoa não serão aceitas.

Antes de iniciar a integração, confirme com a equipe responsável que os verbos de escrita necessários foram habilitados para a sua chave de API. A lista de verbos efetivamente liberados para a sua instância aparece no dicionário oficial.

Define a entidade jurídica (empresa) e, quando aplicável, a filial sobre a qual o título financeiro será lançado. É o ponto de partida do cabeçalho do documento.

Onde cadastrar no ERP: módulo Cad → Cadastros → Empresa.

Tabela referenciada: FILIAL.

Como referenciar nas chamadas da API: o código da empresa/filial é informado no cabeçalho do lançamento. O nome exato da chave e o tipo de dado estão no dicionário oficial da sua API.

Tipo de operação financeira (por exemplo, duplicata, boleto, nota de débito), conforme cadastro interno do ERP. Determina regras operacionais aplicadas ao título.

Onde cadastrar no ERP: módulo Cad → Configurações → Ver mais → Tipo de Operação.

Tabela referenciada: TPDOC.

Como referenciar nas chamadas da API: o código do tipo de operação é informado no cabeçalho do lançamento. A lista de tipos válidos para a sua instância está no dicionário oficial.

Estrutura analítica que permite classificar e ratear o valor do documento entre diferentes departamentos, projetos ou áreas. O documento financeiro referencia um centro de custo principal no cabeçalho e, opcionalmente, pode distribuir o valor entre vários centros de custo por meio do bloco de rateio.

Onde cadastrar no ERP: módulo Cad → Cadastros → Centro de Custo.

Tabela referenciada: SETOR (denominação interna; equivale a Centro de Custo no domínio funcional).

Como referenciar nas chamadas da API: o código é informado no cabeçalho do lançamento e, quando há rateio, também em cada item do bloco opcional de rateio por centro de custo. O nome exato das chaves está no dicionário oficial.

Índice ou cotação aplicado ao documento financeiro para conversão de valores. Relevante quando o documento contém valores expressos em referência distinta da padrão configurada para a operação.

Onde cadastrar no ERP: módulo Fin → Configurações Financeiras → Ver mais → Índices.

Tabela referenciada: INDICES.

Como referenciar nas chamadas da API: o código do índice pode ser informado no cabeçalho do lançamento. É um campo opcional — consulte o dicionário oficial para o nome da chave e as regras aplicáveis.

Define a condição de pagamento (também referida internamente como prazo de pagamento) — quantidade de parcelas, intervalos e regras aplicáveis quando o título for parcelado automaticamente pelo ERP. É a fonte do comportamento padrão de parcelamento.

Onde cadastrar no ERP: módulo Fin → Configurações Financeiras → Ver mais → Condição de Pagamento.

Tabela referenciada: PRAZO.

Como referenciar nas chamadas da API: o código da condição de pagamento é informado no cabeçalho do lançamento. Quando o integrador não envia o bloco de parcelas manualmente, o Spalla usa a condição cadastrada para gerar as parcelas. Detalhes no dicionário oficial.

Carteira de cobrança (também referida como portador de cobrança ou portador do título) — conjunto de regras que define como cada parcela será cobrada/paga: conta corrente associada, forma de pagamento padrão, relatório de boleto, percentuais de juros e multa, entre outros. É referenciada em cada parcela quando o integrador envia manualmente o bloco de parcelas no JSON do lançamento.

Onde cadastrar no ERP: módulo Fin → Configurações Financeiras → Ver mais → Contas → Carteira de Cobrança.

Tabela referenciada: PORTA (denominação interna; equivale a Carteira de Cobrança no domínio funcional).

Como referenciar nas chamadas da API: o código da carteira é informado em cada item do bloco de parcelas, quando esse bloco é enviado. Confira a chave exata no dicionário oficial.

Conta corrente (também referida como banco) — conta bancária da empresa onde o pagamento ou recebimento será efetivado. Obrigatória no momento da baixa do título.

Onde cadastrar no ERP: módulo Fin → Configurações Financeiras → Ver mais → Contas → Conta Corrente.

Tabela referenciada: BANCO (denominação interna; equivale a Conta Corrente no domínio funcional).

Como referenciar nas chamadas da API: o código da conta corrente é informado no momento da baixa do título. A nomenclatura exata do parâmetro está no dicionário oficial.

Meio de pagamento utilizado na liquidação do título (por exemplo, dinheiro, cheque, cartão, transferência), conforme cadastro do ERP. Obrigatório no momento da baixa.

Onde cadastrar no ERP: módulo Fin → Configurações Financeiras → Ver mais → Forma de Pagamento.

Tabela referenciada: FORPAG.

Como referenciar nas chamadas da API: o código da forma de pagamento é informado no momento da baixa. Veja o dicionário oficial para a lista de formas habilitadas na sua instância.

Este passo é opcional e só se aplica quando o documento financeiro está vinculado a uma operação de comércio exterior — ou seja, quando se trata de uma despesa/receita relacionada a um processo de importação ou a um processo de exportação. Para operações financeiras comuns (sem vínculo com comércio exterior), pule este passo.

Os dois cenários são excludentes — um mesmo documento se vincula a processo de importação ou a processo de exportação, nunca aos dois simultaneamente. Os blocos de rateio enviados no JSON do lançamento são distintos para cada caso.

A) Vínculo com Processo de Importação

Quando o financeiro for despesa/receita de um processo de importação, o lançamento usa o bloco de rateio por processo de importação no JSON. Esse bloco grava registros na tabela de rateio interna, que exige dois cadastros prévios na retaguarda:

Processo de Importação — identifica o processo de comércio exterior a que o documento se refere.
Onde cadastrar no ERP: módulo Imp → Importação → Processo de Importação.
Tabela referenciada: CEIPROCESCAD — "Processo de Importação".
Tipo Financeiro do Processo de Importação — classifica a natureza do gasto/receita dentro do processo (fretes, seguros, despachante, tributos, etc.).
Onde cadastrar no ERP: módulo Imp → Configurações do Importação → Ver mais → Tipo Financeiro.
Tabela referenciada: CEIPROCESTPDOC (denominação interna; equivale a Tipo Financeiro do Processo de Importação no domínio funcional).

Esses dois códigos alimentam, respectivamente, as chaves de identificação do processo e do tipo financeiro em cada item do bloco de rateio por processo de importação no JSON do lançamento (tabela CEIPROCESRATEIO — "Rateio de Documentos por Processo"). Os nomes exatos das chaves do JSON estão no dicionário oficial.

B) Vínculo com Processo de Exportação

Quando o financeiro for despesa/receita de um processo de exportação, o lançamento usa o bloco de rateio por exportação no JSON. Esse bloco grava registros na tabela EXPRATEIO — "Rateio de Contas (Exportação)" — que possui FK para o processo de exportação na tabela EXPPROCES. Por isso, é necessário um único cadastro prévio na retaguarda:

Processo de Exportação — identifica o processo de comércio exterior.
Onde cadastrar no ERP: módulo Exp → Exportação → Processo de Exportação.
Tabela referenciada: EXPPROCES — "Processos de Exportação".

O código do processo de exportação alimenta a chave de identificação do processo em cada item do bloco de rateio por exportação no JSON do lançamento. O nome exato da chave está no dicionário oficial.

Diferença entre os dois cenários

Aspecto	Importação	Exportação
Bloco do JSON usado	Rateio por processo de importação	Rateio por exportação
Cadastros de retaguarda exigidos	`CEIPROCESCAD` + `CEIPROCESTPDOC`	`EXPPROCES`
Tabela de rateio que recebe os registros	`CEIPROCESRATEIO`	`EXPRATEIO`
Tipificação financeira por item	Obrigatória (TDP_COD)	Não se aplica

Quando não usar: em todas as operações financeiras que não têm vínculo com comércio exterior, este passo é dispensado. O integrador simplesmente omite os blocos de rateio correspondentes no JSON do lançamento.

Toda movimentação financeira está vinculada a uma pessoa — um cliente (quando o título é a receber) ou um fornecedor (quando é a pagar). Esse cadastro pode ser criado, alterado e removido via API REST, usando os verbos padrão sobre o objeto pessoa do ERP.

O cadastro de pessoas é controlado diretamente em duas tabelas do banco:

CLIFOR1 — cadastro principal da pessoa (dados básicos, fiscais, comerciais e financeiros).
CLIFOR3 — cadastro de contatos vinculados à pessoa (responsáveis, telefones, e-mails associados a cada contato).

A API expõe esses dois cadastros como objetos REST separados. Os nomes exatos dos objetos e a relação entre eles estão descritos no dicionário oficial da sua instância.

Liberação prévia na retaguarda. Os verbos de escrita (POST, PUT, DELETE) sobre os objetos de pessoa e de contato precisam ter sido habilitados na retaguarda do ERP para a chave de API que será usada. Verbos não liberados resultam em rejeição da requisição.

Onde encontrar a definição do objeto: no dicionário oficial da sua API, na entrada do objeto pessoa. Lá estão os campos aceitos, tipos de dado, regras de obrigatoriedade e exemplos de payload completos.

Verbos típicos do ciclo de vida:

GET — consultar pessoas existentes (geralmente liberado para integração).
POST — cadastrar uma nova pessoa (exige liberação na retaguarda).
PUT — alterar dados de uma pessoa existente (exige liberação na retaguarda).
DELETE — remover/inativar uma pessoa (exige liberação na retaguarda).

A lista de verbos efetivamente liberados para a sua chave aparece no próprio dicionário oficial da sua instância.

Dica — descobrir a tabela e o campo a partir da interface do ERP. Ao operar qualquer tela do ERP Spalla diretamente pela interface (Cadastro de Pessoa 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.

Regras de validação e integridade referencial. As regras de validação aplicadas ao cadastro de pessoa via API são exatamente as mesmas que o ERP aplica quando o cadastro é feito diretamente pela operação na interface do sistema. Essas regras de negócio 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 — interface gráfica do ERP, API REST ou procedure.

O sistema mantém integridade referencial entre os registros. Por isso, por exemplo, uma pessoa (cliente ou fornecedor) que já foi utilizada em um documento financeiro não pode ser excluída — a exclusão é rejeitada para preservar a consistência do histórico de movimentos. Restrições análogas se aplicam aos demais cadastros: qualquer registro referenciado por outro documento permanece bloqueado para exclusão enquanto a referência existir.

A mesma garantia vale para os passos de lançamento (APW_PRC_FINDOCADD) e baixa (APW_PRC_FINDOCADDBAIXA): todas as validações de negócio do banco são aplicadas integralmente, qualquer que seja o canal de entrada. Mensagens de erro retornadas pela API são as mesmas geradas pelo banco quando a mesma regra é violada na operação direta pelo ERP.

Procedure responsável por incluir um documento financeiro — tanto a pagar quanto a receber. O tipo de movimento (a pagar ou a receber) é definido por uma chave do cabeçalho que identifica se o documento é de cliente (emitido / a receber) ou de fornecedor (recebido / a pagar). A consulta ao dicionário oficial mostra o nome exato dessa chave e os valores aceitos.

Forma de entrada

A procedure recebe um único parâmetro: uma string contendo um JSON serializado. Esse JSON é composto por quatro seções:

Cabeçalho — identificação do documento (empresa, tipo, pessoa, datas, valor total, etc.). Obrigatório.
Bloco de parcelas — lista das parcelas a serem geradas. Opcional. Quando omitido, o Spalla gera as parcelas automaticamente a partir do prazo informado no cabeçalho. Quando enviado, o Spalla usa exatamente as parcelas descritas pelo integrador.
Bloco de rateio por processo de importação — lista de processos de comércio exterior com valores rateados. Opcional — aplicável apenas a operações vinculadas a processos de importação.
Bloco de rateio por exportação — rateio específico para operações de exportação. Opcional.

Para a lista completa de chaves aceitas em cada bloco, com nome, tipo, obrigatoriedade e regras de validação, consulte o dicionário oficial da sua API na entrada APW_PRC_FINDOCADD.

Cenário A — parcelas geradas automaticamente pelo Spalla

Quando o bloco de parcelas é omitido, o Spalla utiliza o prazo de pagamento referenciado no cabeçalho para calcular automaticamente a quantidade de parcelas, datas de vencimento e valores. É o caminho mais simples.

{
  "cabecalho": {
    // identificação do documento, pessoa, datas, valor total, prazo
    // (consulte o dicionário oficial para a lista completa de chaves)
  }
  // sem o bloco de parcelas: o Spalla parcela conforme o prazo cadastrado
}

Cenário B — parcelas controladas manualmente pelo integrador

Quando o bloco de parcelas é enviado, o Spalla ignora qualquer parcelamento automático e grava exatamente as parcelas descritas. Use este cenário quando precisar de controle total sobre datas, valores, históricos individuais e regras de juros/multa/desconto por parcela.

{
  "cabecalho": {
    // identificação do documento, pessoa, datas, valor total
  },
  "parcelas": [
    { /* parcela 1 */ },
    { /* parcela 2 */ }
    // ... uma entrada por parcela
  ],
  "rateioCentroCusto": [
    // opcional: lista de itens de rateio por centro de custo
  ],
  "rateioExportacao": [
    // opcional: lista de itens de rateio para operações de exportação
  ]
}

Os nomes reais das chaves (em maiúsculas, conforme o padrão das procedures do Spalla) e a estrutura interna de cada item dos arrays estão documentados no dicionário oficial da sua API.

Retorno

A procedure devolve a chave de identificação de cada parcela gerada. Essa chave é o que permite, posteriormente, registrar a baixa do título. Os campos exatos do retorno estão no dicionário oficial da sua API na entrada desta procedure.

Pré-requisitos cumpridos antes deste passo

Todos os cadastros de retaguarda relevantes para o cabeçalho e para os blocos opcionais (passos 1 a 9) e o cadastro da pessoa (passo 10) precisam estar concluídos.

Procedure responsável por registrar o pagamento (no caso de contas a pagar) ou o recebimento (no caso de contas a receber) de um título previamente lançado. A diferenciação entre baixa de título a pagar e baixa de título a receber é feita pelo mesmo indicador de tipo de movimento usado no lançamento.

Forma de entrada

A procedure recebe um conjunto de parâmetros distintos para identificar o título (chave devolvida pelo lançamento) e descrever a baixa (data de pagamento, valor, forma de pagamento, conta corrente, histórico, e os valores complementares de desconto, juros, multa e acréscimo).

Para a assinatura completa, com nome de cada parâmetro, tipo, obrigatoriedade e ordem, consulte o dicionário oficial da sua API na entrada APW_PRC_FINDOCADDBAIXA.

Pré-requisito obrigatório

O título precisa existir antes da baixa. A baixa é executada sobre uma parcela já gravada por APW_PRC_FINDOCADD (passo 11) ou já existente no ERP. A chave de identificação devolvida pelo lançamento é o que conecta a baixa ao título correto.

Retorno

A procedure devolve a confirmação da baixa registrada. Os campos exatos do retorno e o comportamento em caso de baixa parcial estão descritos no dicionário oficial.

Validações e erros

As validações aplicadas ao lançamento e à baixa 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 procedure.

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.

Consulta dos dados gerados

Após o lançamento e a baixa, os títulos ficam disponíveis para consulta pelo módulo financeiro do ERP Spalla. Para que o integrador também possa consumir esses dados via API, o Spalla disponibiliza quatro views de leitura, expostas como objetos REST (verbo GET). Cada uma representa um recorte específico do ciclo do título:

View	Conteúdo	Quando consultar
`SPA_CONTASAPAGAR`	Títulos a pagar — em aberto	Listar obrigações financeiras pendentes com fornecedores (despesas ainda não liquidadas).
`SPA_CONTASPAGAS`	Títulos pagos — histórico	Auditar pagamentos já efetuados a fornecedores, com data, valor e forma de pagamento.
`SPA_CONTASARECEBER`	Títulos a receber — em aberto	Listar valores a receber de clientes (receitas ainda não liquidadas).
`SPA_CONTASRECEBIDAS`	Títulos recebidos — histórico	Auditar recebimentos já efetuados de clientes, com data, valor e forma de pagamento.

As quatro views consolidam dados do cabeçalho do documento (empresa, pessoa, tipo de operação, datas, valores) e da parcela (vencimento, número da parcela, status). As views SPA_CONTASPAGAS e SPA_CONTASRECEBIDAS incluem ainda os dados da baixa (data do pagamento, forma e banco), permitindo a reconciliação completa do ciclo lançamento → baixa.

Liberação na retaguarda. A consulta sobre cada uma dessas views precisa estar habilitada na retaguarda do ERP para a chave de API utilizada. Sem essa liberação, a view não aparece no dicionário da sua instância nem responde a requisições.

Como consultar: a forma exata de chamar cada view via API — endpoint, método HTTP, estrutura do corpo da requisição, parâmetros aceitos (filtros, limites, ordenação, seleção de campos) e exemplo de payload de retorno — está descrita no dicionário oficial da sua API, nas entradas correspondentes a cada uma das quatro views. 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. Consulte-o sempre que precisar da especificação detalhada de uma consulta — esta documentação complementar não duplica essas informações para evitar conflito com o que está publicado no dicionário oficial.

Onde aprofundar

Esta página é um guia operacional — descreve o que fazer e em que ordem. Para como exatamente chamar cada procedure (nomes de chaves, tipos de dado, obrigatoriedade, exemplos completos de payload e de retorno), 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.