Fluxo de Contas a Pagar/Receber — Documentação Complementar

https://<host>:<porta>/root/dicionario?userToken=<token>

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, na chave FL_COD (ver o Passo 11).

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, na chave TD_COD. Os tipos cadastrados na sua instância são os registros de TPDOC.

Estrutura analítica que classifica o documento por departamento, projeto ou área. O documento financeiro lançado pela API referencia um centro de custo, informado no cabeçalho.

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, na chave ST_COD.

Í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, na chave ID_COD. É um campo opcional.

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, na chave PZ_COD. Quando o integrador não envia as parcelas (chave TITULO), o Spalla usa a condição cadastrada para gerar as parcelas.

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 as parcelas no JSON do lançamento (chave TITULO).

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 na chave PT_COD de cada parcela, quando as parcelas são enviadas na chave TITULO.

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.

Um documento se vincula a processo de importação ou a processo de exportação: envie no lançamento só uma das duas chaves de rateio, CEIPROCESRATEIO para importação ou EXPRATEIO para exportação.

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

Quando o financeiro for despesa/receita de um processo de importação, o JSON do lançamento (Passo 11) leva a chave CEIPROCESRATEIO. Cada item dela grava uma linha na tabela CEIPROCESRATEIO — "Rateio de Documentos por Processo" —, que liga o documento ao processo. É por ela que o documento se relaciona com o processo: o cabeçalho do documento (DOCS) não guarda o código do processo. O rateio depende de dois cadastros:

• Processo de Importação — identifica o processo de comércio exterior a que o documento se refere (CEIPROCESCAD, código em PIM_COD). O processo pode ser incluído pela API, conforme a página Processo de Importação, ou na retaguarda do ERP, no módulo Imp → Importação → 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), com o código em TDP_COD. O tipo financeiro traz a incidência no custo (TDP_CUSTO) e o lançamento em conta corrente (TDP_REEMBOLSO) usados quando o item do rateio não os informa.

Os campos de cada item de CEIPROCESRATEIO

A chave é um array com um item por processo e tipo financeiro. Para ratear o documento entre dois processos, ou entre dois tipos financeiros do mesmo processo, envie um item para cada combinação.

Campo	Envio	Conteúdo
PIM_COD	Obrigatório	Código do processo de importação (CEIPROCESCAD.PIM_COD). É a primeira chave de cada item: a rotina reconhece o início de um item pela chave PIM_COD.
TDP_COD	Obrigatório	Código do tipo financeiro (CEIPROCESTPDOC.TDP_COD).
PIM_VALMNACIO	Sempre	Valor atribuído ao processo, em moeda nacional.
PIM_VALMDOLAR	Opcional	Valor em moeda estrangeira (contrato de câmbio). Envie 0 quando não houver.
PIM_CUSTO	Opcional	Indicativo de incidência no custo do processo. Os valores aceitos estão no dicionário oficial, no campo PIM_CUSTO de CEIPROCESRATEIO. Omitido, o servidor usa o TDP_CUSTO do tipo financeiro.
PIM_REEMBOLSO	Opcional	Lançamento em conta corrente: 0 nenhum, 1 débito, 2 crédito. Omitido, o servidor usa o TDP_REEMBOLSO do tipo financeiro.

• Envie só os campos da tabela, com valores numéricos e ponto como separador decimal.
• Não repita a combinação processo + tipo financeiro no mesmo documento: o rateio é identificado pelo documento, pelo processo e pelo tipo financeiro. Some os valores num item só.
• Envie o rateio inteiro na mesma chamada. Cada chamada ao Passo 11 cria um documento novo; os itens de CEIPROCESRATEIO enviados nela são todo o rateio desse documento.

O exemplo completo, com cabeçalho e rateio, está no Passo 11, em Cenário C.

Validações do rateio por processo de importação

As validações abaixo são executadas no servidor em cada item. Quando uma delas recusa o lançamento, a mensagem chega na coluna DOC_ERRO do retorno do Passo 11. N é o código do processo (PIM_COD) ou do documento, conforme a mensagem. A mensagem de nota fiscal de nacionalização vem precedida do prefixo interno DBMATENCAO,OPERACAO|: descarte-o ao exibir para o usuário final.

Mensagem	Causa	Ação
O processo N está CANCELADO, é necessário alterar o Status do Processo para permitir quaisquer alterações	O status do processo do item é do tipo Cancelado.	Confira o PIM_COD. Para lançar no processo, o status dele precisa voltar a um status do tipo Ativo, pela API (Processo de Importação, Passo 8) ou na retaguarda do ERP.
O processo N está ENCERRADO, é necessário alterar o Status do Processo para permitir quaisquer alterações	O status do processo do item é do tipo Encerrado.	Confira o PIM_COD. Para lançar no processo, o status dele precisa voltar a um status do tipo Ativo, pela API (Processo de Importação, Passo 8) ou na retaguarda do ERP.
Somente é permitido rateio entre processos, quando não houver Incidência de Custo de Entrada!	O documento é rateado entre dois ou mais processos, e algum item tem incidência no custo de entrada contábil (PIM_CUSTO igual a 1, 2, 5 ou 8, informado ou herdado do tipo financeiro).	Lance um documento para cada processo, ou use nos itens tipos financeiros sem incidência no custo de entrada.
Nota Fiscal de Nacionalização já foi gerada no Documento N	Item com PIM_CUSTO 1 ou 2 (informado ou herdado) em processo cuja nota fiscal de nacionalização já foi emitida.	Confirme com a retaguarda do ERP a incidência no custo a usar em despesa lançada depois da nacionalização.

O status do processo está em CEIPROCESCAD.PIM_STATUS, e o tipo de cada status (Ativo, Encerrado ou Cancelado), em CEISTATUSPROCESSO.

Previsões financeiras do processo

Conferência do vínculo

Depois do lançamento, o rateio gravado é lido com GET em CEIPROCESRATEIO, filtrando por PIM_COD (todos os documentos do processo) ou pela chave do documento (FL_COD, CF_TIPO e FT_COD, devolvidos pelo Passo 11). Confirme no dicionário da sua instância se CEIPROCESRATEIO está disponível para o seu token; se faltar, peça ao gestor do ERP a revisão do cadastro de API.

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

Quando o financeiro for despesa/receita de um processo de exportação, o JSON do lançamento leva a chave EXPRATEIO. Cada item grava uma linha 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".

Cada item de EXPRATEIO começa pela chave EXP_COD, o código do processo de exportação, e leva os campos abaixo. O processo de exportação precisa ser da mesma filial do documento (FL_COD do cabeçalho).

• EXP_DATMOV — data da movimentação, com hora, no formato "AAAA-MM-DD HH:MM:SS";
• EXP_VALMNACIO — valor em moeda nacional;
• EXP_VALMDOLAR — valor em moeda estrangeira (contrato de câmbio);
• EXP_REEMBOLSO — valor a ser reembolsado: 0 não, 1 sim.

Como no rateio de importação, envie todos os itens de EXPRATEIO na mesma chamada que cria o documento.

Trecho do JSON do lançamento, junto com as chaves do cabeçalho do Passo 11:

{
    "EXPRATEIO": [
        {
            "EXP_COD": 12
            ,"EXP_DATMOV": "2026-10-05 00:00:00"
            ,"EXP_VALMNACIO": 1250.00
            ,"EXP_VALMDOLAR": 0
            ,"EXP_REEMBOLSO": 0
        }
    ]
}

Valores ilustrativos. Os códigos e valores dos exemplos desta página são ilustrativos. Use os cadastros da sua instância. A lista completa e autoritativa de campos de cada objeto está no dicionário oficial.

Diferença entre os dois cenários

Aspecto	Importação	Exportação
Chave do JSON usada	CEIPROCESRATEIO	EXPRATEIO
Primeira chave de cada item	PIM_COD	EXP_COD
Cadastros prévios 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 as chaves CEIPROCESRATEIO e EXPRATEIO 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 é gravado em duas tabelas:

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

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.

Procedure responsável por incluir um documento financeiro — tanto a pagar quanto a receber. O tipo de movimento é definido pela chave CF_TIPO do cabeçalho: "F" para documento de fornecedor (recebido, a pagar) e "C" para documento de cliente (emitido, a receber).

Forma de entrada

A procedure recebe um único parâmetro, pRawJson: uma string contendo um JSON serializado. Monte o objeto JSON, converta-o em texto e envie o texto como valor do parâmetro. A rotina é executada como PROCEDURE RESULT, com "method": "GET" no corpo e verbo HTTP PATCH. Apesar do GET, ela grava o documento: o tipo diz só que o retorno chega estruturado. Cada chamada bem-sucedida cria um documento novo, por isso não a repita para conferir: consulte o documento com a chave devolvida, pelas views de Consulta dos dados gerados. O objeto tem quatro partes:

• Cabeçalho — as chaves do documento, diretamente na raiz do objeto (sem chave que as agrupe). Obrigatório.
• TITULO — array com as parcelas a serem geradas. Opcional. Quando omitido, o Spalla gera as parcelas automaticamente a partir da condição de pagamento informada no cabeçalho. Quando enviado, o Spalla substitui as parcelas geradas pelas descritas pelo integrador.
• CEIPROCESRATEIO — array com o rateio do documento por processo de importação. Opcional — aplicável apenas a operações vinculadas a processos de importação. Campos e regras no Passo 9.
• EXPRATEIO — array com o rateio do documento por processo de exportação. Opcional. Campos no Passo 9.

Chaves do cabeçalho

Chave	Envio	Conteúdo
FL_COD	Obrigatório	Empresa/filial (Passo 1).
CF_TIPO	Obrigatório	"F" a pagar, "C" a receber.
TD_COD	Obrigatório	Tipo de operação (Passo 2).
ST_COD	Obrigatório	Centro de custo (Passo 3).
CF_COD	Obrigatório	Pessoa: o fornecedor ou o cliente do documento (Passo 10).
MD_COD	Obrigatório	Código da moeda.
PZ_COD	Obrigatório	Condição de pagamento (Passo 5).
FT_VAL	Sempre	Valor do documento, com ponto decimal.
FT_BRUTO	Sempre	Valor bruto do documento, com ponto decimal.
FT_NUM	Opcional	Número do documento. Omitido ou 0: se o tipo de operação tem série, o servidor usa o próximo número da série; sem série, o documento a pagar ("F") recebe o próprio FT_COD como número. No documento a receber ("C") de tipo sem série, envie o número. Com série protegida no tipo de operação, o servidor numera mesmo que você envie FT_NUM.
FT_NR2	Opcional	Outro número do documento, em texto (até 20 caracteres).
FT_EMI	Opcional	Data de emissão, com hora, no formato "AAAA-MM-DD HH:MM:SS". Omitida, vale a data atual. O documento guarda só a data.
FT_DAT	Opcional	Data de movimento, no mesmo formato e com a mesma regra de FT_EMI.
ID_COD	Opcional	Índice / cotação (Passo 4).

O código do documento (FT_COD) não é enviado: o servidor o numera e o devolve no retorno.

Campos de cada parcela em TITULO

Campo	Envio	Conteúdo
PT_COD	Obrigatório	Carteira de cobrança (Passo 6). É a primeira chave de cada parcela: a rotina reconhece o início de uma parcela pela chave PT_COD.
TT_DVC	Obrigatório	Data de vencimento, com hora, no formato "AAAA-MM-DD HH:MM:SS".
TT_VAL	Sempre	Valor da parcela, em moeda nacional.
TT_VALMEST	Opcional	Valor da parcela em moeda estrangeira. Envie 0 quando não houver.
TT_HIS	Opcional	Histórico da parcela (até 250 caracteres).
TT_PJR	Opcional	Percentual de juros de mora.
TT_PMT	Opcional	Percentual de multa.
TT_PDC	Opcional	Percentual de desconto.

As parcelas são numeradas na ordem do array (TT_ORD 1, 2, 3…). Envie só os campos da tabela.

Cenário A — parcelas geradas automaticamente pelo Spalla

Quando TITULO é omitido, o Spalla utiliza a condição de pagamento referenciada no cabeçalho (PZ_COD) para calcular automaticamente a quantidade de parcelas, datas de vencimento e valores. É o caminho mais simples. O JSON antes da serialização:

{
    "FL_COD": 1
    ,"CF_TIPO": "F"
    ,"TD_COD": 5132
    ,"ST_COD": 58
    ,"CF_COD": 3326
    ,"FT_NR2": "NF 4512"
    ,"FT_EMI": "2026-10-01 00:00:00"
    ,"FT_DAT": "2026-10-01 00:00:00"
    ,"MD_COD": 1
    ,"PZ_COD": 2246
    ,"FT_VAL": 1500.00
    ,"FT_BRUTO": 1500.00
}

O mesmo JSON, serializado no parâmetro pRawJson da requisição:

{
    "method": "GET"
    ,"objectType": "PROCEDURE RESULT"
    ,"objectName": "APW_PRC_FINDOCADD"
    ,"params": [
        {
            "name": "pRawJson"
            ,"value": "{\"FL_COD\":1,\"CF_TIPO\":\"F\",\"TD_COD\":5132,\"ST_COD\":58,\"CF_COD\":3326,\"FT_NR2\":\"NF 4512\",\"FT_EMI\":\"2026-10-01 00:00:00\",\"FT_DAT\":\"2026-10-01 00:00:00\",\"MD_COD\":1,\"PZ_COD\":2246,\"FT_VAL\":1500.00,\"FT_BRUTO\":1500.00}"
        }
    ]
}

Cenário B — parcelas controladas manualmente pelo integrador

Quando TITULO é enviado, o Spalla descarta o 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 percentuais de juros, multa e desconto por parcela.

{
    "FL_COD": 1
    ,"CF_TIPO": "F"
    ,"TD_COD": 5132
    ,"ST_COD": 58
    ,"CF_COD": 3326
    ,"FT_EMI": "2026-10-01 00:00:00"
    ,"FT_DAT": "2026-10-01 00:00:00"
    ,"MD_COD": 1
    ,"PZ_COD": 2246
    ,"FT_VAL": 1500.00
    ,"FT_BRUTO": 1500.00
    ,"TITULO": [
        {
            "PT_COD": 1001
            ,"TT_VAL": 750.00
            ,"TT_VALMEST": 0
            ,"TT_DVC": "2026-10-31 00:00:00"
            ,"TT_HIS": "Parcela 1 de 2"
            ,"TT_PJR": 1
            ,"TT_PMT": 2
            ,"TT_PDC": 0
        }
        ,{
            "PT_COD": 1001
            ,"TT_VAL": 750.00
            ,"TT_VALMEST": 0
            ,"TT_DVC": "2026-11-30 00:00:00"
            ,"TT_HIS": "Parcela 2 de 2"
            ,"TT_PJR": 1
            ,"TT_PMT": 2
            ,"TT_PDC": 0
        }
    ]
}

Cenário C — lançamento vinculado a processo de importação

Despesa de um processo de importação: o cabeçalho, com ou sem TITULO, mais a chave CEIPROCESRATEIO. No exemplo, o documento é atribuído a dois tipos financeiros do mesmo processo; PIM_CUSTO e PIM_REEMBOLSO foram omitidos e vêm do tipo financeiro. Os campos e as validações do rateio estão no Passo 9.

{
    "FL_COD": 1
    ,"CF_TIPO": "F"
    ,"TD_COD": 5132
    ,"ST_COD": 58
    ,"CF_COD": 3326
    ,"FT_EMI": "2026-10-01 00:00:00"
    ,"FT_DAT": "2026-10-01 00:00:00"
    ,"MD_COD": 1
    ,"PZ_COD": 2246
    ,"FT_VAL": 1500.00
    ,"FT_BRUTO": 1500.00
    ,"CEIPROCESRATEIO": [
        {
            "PIM_COD": 6
            ,"TDP_COD": 254
            ,"PIM_VALMNACIO": 1200.00
            ,"PIM_VALMDOLAR": 0
        }
        ,{
            "PIM_COD": 6
            ,"TDP_COD": 260
            ,"PIM_VALMNACIO": 300.00
            ,"PIM_VALMDOLAR": 0
        }
    ]
}

Retorno

A procedure devolve uma linha com as colunas abaixo.

Coluna	Conteúdo
FL_COD, CF_TIPO, FT_COD	Chave do documento. Pode vir preenchida também na recusa: use-a só quando DOC_ERRO estiver vazio.
DOC_RETORNO	Texto com um array JSON, um item por parcela gravada, com FL_COD, CF_TIPO, FT_COD, TT_ORD (número da parcela) e TT_ORDEM (número de identificação único da parcela).
DOC_ERRO	Vazio quando o lançamento é gravado. Na recusa, traz a mensagem do servidor, e DOC_RETORNO fica vazio.
DOC_JSON	O JSON recebido em pRawJson.

Conteúdo de DOC_RETORNO de um documento com duas parcelas, depois de convertido de texto para JSON:

[
    { "FL_COD": 1, "CF_TIPO": "F", "FT_COD": 7037, "TT_ORD": 1, "TT_ORDEM": 124583 }
    ,{ "FL_COD": 1, "CF_TIPO": "F", "FT_COD": 7037, "TT_ORD": 2, "TT_ORDEM": 124584 }
]

Guarde FL_COD, CF_TIPO, FT_COD e TT_ORD de cada parcela: são eles que identificam a parcela na baixa (Passo 12). Verifique DOC_ERRO em toda resposta: é ali que chega a recusa do lançamento.

Pré-requisitos cumpridos antes deste passo

Todos os cadastros relevantes para o cabeçalho e para as chaves opcionais de rateio (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

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.