Documentação Funcional — ecosif-automations¶
Público-alvo: Clientes / Negócio / Operação
Módulo: ecosif-automations
1. Objetivo do Módulo¶
O ecosif-automations automatiza a importação de lançamentos contábeis a partir de ficheiros .IPL e do ficheiro mestre CT32.LD: valida formato e dados (empresa e filial), resolve o mapeamento do fundo via CT32, envia os lançamentos para fila de processamento e organiza os ficheiros em pastas de sucesso ou erro. Em produção (AWS), o fluxo é acionado pelo upload para S3 e processado em fila (SQS); localmente, pode ser testado com scripts e pasta local.
Em linguagem de negócio:
- O que é: O “motor” que recebe ficheiros de importação gerados por sistemas externos (ou enviados manualmente), valida e grava os lançamentos no eCosif.
- Para que serve: Reduzir trabalho manual e erros na carga de lançamentos e manter rasto de ficheiros processados e com falha.
- Quem se beneficia: Contabilidade, back-office e sistemas que alimentam o eCosif com ficheiros padrão IPL/CT32.
2. Tipos de Ficheiros e Layouts Suportados¶
2.1 Ficheiro .IPL (Lançamentos)¶
- Extensão:
.IPL(maiúscula ou minúscula). - Nome esperado: NNNNNN_YYYYMMDD.IPL
- Exemplo:
123456_20240101.IPL - NNNNNN = código do fundo (6 dígitos).
- YYYYMMDD = data de referência do ficheiro (8 dígitos).
- Formato: Ficheiro de texto, uma linha por lançamento, cada linha com exatamente 156 caracteres (incluindo espaços). Linhas em branco ou que pareçam cabeçalho (contendo "dt", "lot", "lanc", "code", "desc", "valor") são ignoradas.
Layout por posição (156 caracteres):
| Posições | Conteúdo | Exemplo / Observação |
|---|---|---|
| 0–6 | Data (YYMMDD) | 240101 = 2024-01-01 |
| 6–12 | Lote | 000001 |
| 12–17 | Número do lançamento | 00001 |
| 17 | Tipo (1=crédito, 2=débito) | 1 ou 2 |
| 18 | Espaço | — |
| 19–26 | Conta contábil | 8 caracteres |
| 26–30 | Código do histórico | 4 caracteres |
| 30–80 | Descrição do histórico | 50 caracteres |
| 80–87 | Conta contrapartida | 8 caracteres |
| 87–91 | Código histórico contrapartida | 4 caracteres |
| 91–140 | Descrição histórico contrapartida | 49 caracteres |
| 140–157 | Valor (numérico, vírgula ou ponto decimal) | 17 caracteres |
Qualquer linha com comprimento diferente de 156 ou com tipo diferente de 1/2 é considerada erro de parse; se houver erros, o ficheiro inteiro falha e é movido para a pasta de erro com CSV de diagnóstico.
2.2 Ficheiro .CT32.LD (Mestre de mapeamento)¶
- Nome esperado: chave fixa no bucket/pasta, configurada por
CT32_MASTER_KEY(default:CT32.LD). - Papel: ficheiro mestre e permanente no diretório de importação. Pode ter muitas linhas (milhares).
- Formato: CSV com múltiplas linhas de dados (além de eventual cabeçalho).
- Campos (5 colunas, separador vírgula):
source_name, company_code, branch_code, fund_code, description
| Ordem | Campo | Descrição |
|---|---|---|
| 1 | source_name | Nome da base/ambiente (ex.: ecosif_prod) |
| 2 | company_code | Código da empresa |
| 3 | branch_code | Código da filial |
| 4 | fund_code | Código do fundo (deve coincidir com o prefixo do IPL) |
| 5 | description | Descrição (ex.: do ficheiro ou período) |
O CT32.LD é usado para resolver empresa + filial a partir do fundo do nome do IPL:
- o sistema extrai
NNNNNNdeNNNNNN_YYYYMMDD.IPL; - procura no CT32 linha com
fund_code = NNNNNN; - usa
company_codeebranch_codedessa linha para validação no masterdata e para o processamento seguinte.
Se o CT32 não existir, estiver inválido, tiver duplicidade de fund_code ou não contiver o fundo do IPL, a importação falha.
2.3 Resumo¶
| Tipo | Nome | Formato | Uso |
|---|---|---|---|
| .IPL | NNNNNN_YYYYMMDD.IPL | Texto, linhas fixas de 156 caracteres | Lançamentos contábeis (data, lote, conta, histórico, valor, tipo crédito/débito). |
| .CT32.LD | CT32.LD (ou chave em CT32_MASTER_KEY) |
CSV, 5 campos, multi-linha | Mapeamento fundo → empresa/filial para validação e contexto. |
Não são suportados outros formatos (ex.: Excel, XML) nem outros layouts de .IPL no código atual.
3. O Que Fazer Quando uma Importação Falha¶
3.1 Confirmar que falhou¶
- S3: Verificar se o .IPL foi movido para a pasta importError/ e se existe um ficheiro ERRO_<nome_do_ipl>.csv (ex.:
ERRO_123456_20240101.csv). - Local: Ver a pasta local_data/importError/ e os ERRO_*.csv.
- Logs: Consultar os logs do Lambda (CloudWatch) ou a saída do script local; a mensagem de erro é registada e, no CSV de erro, aparece na terceira coluna (separador
;).
3.2 Ler o CSV de erro¶
O CSV de erro tem o formato (exemplo):
timestamp;nome_do_ficheiro;mensagem_de_erro;estado_do_ct32;ERROR
- timestamp: Data/hora do erro.
- nome_do_ficheiro: Nome do .IPL.
- mensagem_de_erro: Motivo da falha (ex.: "Company not found: XXX", "Invalid IPL filename format", "CT32.LD file not found", "IPL file has N validation errors").
- estado_do_ct32: Indica se o CT32 foi verificado ou não (ex.: "CT32.LD FILE NOT FOUND", "CT32.LD FILE OK").
3.3 Ações por tipo de erro¶
| Mensagem típica | Causa provável | O que fazer |
|---|---|---|
| Invalid IPL filename format | Nome do ficheiro não segue NNNNNN_YYYYMMDD.IPL | Renomear o ficheiro para o padrão (6 dígitos + _ + 8 dígitos + .IPL). |
| CT32.LD file not found | Não existe o ficheiro mestre na chave configurada | Criar/enviar o CT32 na chave definida em CT32_MASTER_KEY (default CT32.LD). |
| Company not found: <code> | Código de empresa do CT32 não existe no masterdata | Cadastrar a empresa no eCosif (ecosif-masterdata) ou corrigir o campo company_code no .CT32.LD. |
| Branch not found: <company>/<branch> | Filial não existe no masterdata | Cadastrar a filial para essa empresa no eCosif ou corrigir branch_code no .CT32.LD. |
| Fund code not found in CT32: <code> | Fundo do nome do IPL não existe no CT32 mestre | Incluir/corrigir linha no CT32 com esse fund_code. |
| CT32 has duplicate fund code mappings | Mesmo fundo aparece em duas linhas do CT32 | Corrigir o CT32 para manter um único mapeamento por fund_code. |
| IPL file has N validation errors | Linhas com tamanho diferente de 156 ou tipo inválido (não 1/2) | Revisar o ficheiro .IPL: garantir 156 caracteres por linha e tipo 1 ou 2 na posição 17. Corrigir o ficheiro na origem ou manualmente e reenviar. |
| Failed to parse CT32 file | CSV do CT32 com menos de 5 campos ou formato inválido | Garantir que o CT32 tem linhas com 5 campos (source_name,company_code,branch_code,fund_code,description). |
3.4 Depois de corrigir¶
- S3: Colocar os ficheiros corrigidos novamente no bucket (no prefixo de “entrada” que está configurado para disparar o Lambda). O processamento será acionado de novo pelo evento S3.
- Local: Colocar os ficheiros em local_data/input/ e executar de novo o script de import (ex.:
python scripts/test_local_import.py local_data/input/123456_20240101.IPL).
Não é necessário apagar manualmente o ficheiro da pasta de erro; o sistema apenas move os que falham para importError/. Os relatórios de sucesso ficam em imported/reports/ (S3) ou local_data/imported/reports/ (local).
4. Glossário¶
| Termo | Significado |
|---|---|
| .IPL | Ficheiro de importação de lançamentos contábeis (layout fixo 156 caracteres por linha). |
| .CT32.LD | Ficheiro mestre de mapeamento fundo → empresa/filial em formato CSV. |
| Importação | Processo de validação do .IPL, resolução de empresa/filial no CT32, validação no masterdata e envio para fila de processamento. |
| Pasta de erro / importError | Pasta onde são movidos os .IPL (e CSV de erro) quando a validação ou o parse falham. |
| Pasta importada / imported | Pasta onde são movidos os ficheiros processados com sucesso após a API de import responder. |
| Relatório de processamento | Ficheiro CSV (ex.: <fileName>.report.csv) com total de lançamentos e quantidade importada, gerado após sucesso na API. |
Para detalhes técnicos dos fluxos e da integração com moviments/masterdata, ver architecture/arquitetura.md. Para variáveis de ambiente, pastas e monitorização, ver deploy/operacao.md.