CompensacaoCarteira (FINA450)

Verbo no path (Tier 3). O endpoint usa POST com verbo explícito na URL (_compensar, _estornar) em vez do CRUD convencional. Motivo: o FINA450 não opera sobre uma chave natural de SE1 ou SE2 — compensar age sobre conjuntos de chaves passadas via AUTARECCHAVE/AUTAPAGCHAVE; estornar exige um SE2 posicionado. POST + verbo torna a intenção explícita sem ambiguidade de payload.

Compensação apenas TOTAL. A rotina automática FINA450 compensa o valor total dos títulos selecionados. Não há caminho para compensação parcial — se a somatória dos SE1 não bate com a somatória dos SE2, o título de maior valor permanece em aberto com saldo residual. Para compensar parcialmente, é necessário criar títulos auxiliares antes da chamada.

Mesmo clifor em cliente e fornecedor. O FINA450 mapeia AUTCCLI450 e AUTCFOR450 com o mesmo código de clifor/loja — o par precisa existir simultaneamente em SA1 e SA2. Cenário típico: empresa que é cliente e fornecedor da mesma matriz (compensação entre carteiras de um único parceiro comercial).

Multi-filial via afilcomp. Quando os títulos vêm de filiais diferentes, o servidor coleta as filiais durante a montagem das chaves e envia AUTAFILCOMP populado para o FINA450. Para forçar uma filial específica (ou para desambiguar quando há múltiplas), informe afilcomp no payload (formato: string única do TamSX3 de E1_FILIAL/E2_FILIAL).

Trilha SE5 com E5_TIPODOC=CP. Cada compensação gera 2 ou mais lançamentos em SE5 (um por par SE1/SE2 envolvido), todos com E5_TIPODOC="CP". O /_list aplica esse filtro implicitamente. Use /_byid para inspecionar um lançamento específico via recno.

Estorno requer chave SE2 do título de compensação. O /_estornar não desfaz a operação via "compensação id": requer as 5 partes da chave do SE2 gerado pela compensação (prefixo, numero, tipo, clifor, loja). O endpoint faz DbSeek + FINA450 op=5.

Compensação apenas TOTAL. O FINA450 não suporta compensação parcial — se a somatória dos SE1 não bate exatamente com a somatória dos SE2, o título de maior valor permanece em aberto com saldo residual. Para compensar parcialmente, é necessário criar títulos auxiliares antes da chamada. Não há plano de implementar partição automática enquanto a rotina automática não expuser o caminho oficial.

Estorno por chave SE2, não por compensação id. O /_estornar exige as 5 partes da chave do SE2 gerado pela compensação — não há "id da operação" rastreável. Consumidores devem persistir a chave (prefixo, numero, tipo, clifor, loja) no momento do /_compensar para usar depois.

Mesmo clifor em SA1 + SA2. O FINA450 mapeia cliente e fornecedor com o mesmo código. Se a base tem cadastros separados (cliente com código X, fornecedor com código Y), a compensação não funciona via este endpoint — só serve para entidades duplas (cliente + fornecedor da mesma matriz).

Multi-filial: detecção automática vs explícita. Quando os títulos vêm de filiais diferentes, o servidor detecta automaticamente e popula AUTAFILCOMP. Em casos ambíguos (ex.: titulares espalhados por 3+ filiais com regras de matriz), a detecção pode não escolher o que o usuário espera — preferir o campo afilcomp explícito no payload.

Sentinela do smoke test depende de cadastro FIN001. O test-compensacao-carteira.sh usa o cliente FIN001 da documentação oficial da TDN. Em ambientes que não têm esse cadastro duplicado em SA1+SA2, substituir por entidade real da base antes de rodar. Documentado no README do endpoint.

Bloqueio MSBLQL/MSBLQD não aplicado. A SE1/SE2 não expõem MSBLQL/MSBLQD no cabeçalho do título; o bloqueio relevante está em SA1/SA2 (cliente/fornecedor) e é enforced pelo próprio FINA450. Não há contrato adicional a aplicar no endpoint.