API 1.1.0 • PRODUÇÃO • ESTÁVEL

Planilhas contábeis transformadas em dados validados e importáveis

API do grupo P&S2B para análise, diagnóstico e importação de arquivos contábeis XLSX/XLS de grande volume, preparada para automações com n8n e PostgreSQL.

Começar integração Baixar documentação

DISPONIBILIDADE

Status da API

Abrir health check

StatusConsultando...

Versão1.1.0

Tempo de respostaConsultando...

FormatosXLSX / XLS

Última verificação: aguardando...

INTEGRAÇÃO

Primeiros passos

O consumo básico da API pode ser concluído em cinco etapas.

Solicite ou utilize uma API Key válida da P&S2B.

Prepare a planilha contábil em XLSX ou XLS.

Envie o arquivo como multipart/form-data.

Informe a chave no cabeçalho X-API-Key.

Use /v1/analyze, /v1/diagnose-unbalanced ou /v1/process conforme a finalidade.

ENDEREÇO

URL base

https://contabil-parser.pes2b.com

SEGURANÇA

Autenticação

Os endpoints de análise e processamento exigem uma API Key válida no cabeçalho X-API-Key.

X-API-Key: SUA_CHAVE

Importante: armazene a chave em credenciais do n8n ou em variáveis de ambiente. Nunca publique a chave em GitHub, prints ou workflows exportados.

MONITORAMENTO

Health check

GET/healthPúblico

Confirma que o serviço está ativo e informa o nome da aplicação e o ambiente.

curl 'https://contabil-parser.pes2b.com/health'

{
  "success": true,
  "service": "PES2B Contábil Parser",
  "environment": "production"
}

ANÁLISE SEM GRAVAÇÃO

Analisar planilha

POST/v1/analyzeAPI Key

Analisa a planilha sem criar importação no banco. Retorna hash, volume, totais, período, tipos, quantidade de movimentos financeiros e quantidade de lotes desbalanceados.

curl -X POST \
  'https://contabil-parser.pes2b.com/v1/analyze' \
  -H 'X-API-Key: SUA_CHAVE' \
  -F 'file=@comercio2026.xlsx' \
  -F 'batch_size=1000'

Campo	Descrição
`file`	Arquivo XLSX ou XLS. Obrigatório.
`batch_size`	Opcional. Entre 100 e 10.000. Padrão definido no serviço.

Este endpoint é ideal para pré-validação e auditoria. Não grava dados no PostgreSQL.

DIAGNÓSTICO CONTÁBIL

Diagnosticar arquivo desbalanceado

POST/v1/diagnose-unbalancedAPI Key

Localiza os grupos id_movim_finan responsáveis pelo desbalanceamento do arquivo e devolve as linhas originais de cada grupo, sem gravar dados no banco.

curl -X POST \
  'https://contabil-parser.pes2b.com/v1/diagnose-unbalanced' \
  -H 'X-API-Key: SUA_CHAVE' \
  -F 'file=@comercio2026.xlsx'

Exemplo de resposta

{
  "success": true,
  "diagnostico": "ARQUIVO_DESBALANCEADO",
  "nome_arquivo": "comercio2026.xlsx",
  "resumo": {
    "total_linhas": 253933,
    "total_movimentos_financeiros": 84820,
    "total_debito": 8480733.30,
    "total_credito": 8676943.30,
    "diferenca": -196210.00,
    "quantidade_grupos_desbalanceados": 10,
    "total_batches": 254
  },
  "grupos_desbalanceados": [
    {
      "id_movim_finan": 6998523,
      "data": "2026-01-15",
      "total_debito": 0,
      "total_credito": 35000,
      "diferenca": -35000,
      "quantidade_linhas": 1,
      "descricao_origem": "Num Trâns Giga Com Seg receber de Internet",
      "historico_origem": "TRANSF INTERNET SICO - COMERCIO SICO (REPASSE)",
      "linhas": [
        {
          "linha_origem": 174,
          "tipo_origem": "A",
          "id_conta": 61996,
          "id_planejamento": 329,
          "descricao_origem": "Num Trâns Giga Com Seg receber de Internet",
          "valor_debito": 0,
          "valor_credito": 35000,
          "historico_origem": "TRANSF INTERNET SICO - COMERCIO SICO (REPASSE)"
        }
      ]
    }
  ]
}

Uso recomendado: gerar relatórios de divergências para correção pelo cliente antes de uma nova tentativa de importação.

IMPORTAÇÃO

Processar e gravar planilha

POST/v1/processAPI Key

Valida o arquivo, resolve a empresa pelo código Domínio, impede duplicidade indevida, grava movimentos em batches e finaliza a importação somente após validar quantidade e totais gravados.

curl -X POST \
  'https://contabil-parser.pes2b.com/v1/process' \
  -H 'X-API-Key: SUA_CHAVE' \
  -F 'codigo_dominio=469' \
  -F 'modo_importacao=NORMAL' \
  -F 'batch_size=1000' \
  -F 'file=@comercio2024.xlsx'

Campo	Obrigatório	Descrição
`codigo_dominio`	Sim	Código da empresa no Domínio Sistemas.
`modo_importacao`	Não	`NORMAL` ou `REIMPORTAR`. Padrão: NORMAL.
`batch_size`	Não	Entre 100 e 10.000.
`file`	Sim	Planilha XLSX ou XLS.

Validação contábil: se débito e crédito não fecharem, o processamento é interrompido com HTTP 422 antes da gravação definitiva.

CONTROLE DE VERSÃO

NORMAL x REIMPORTAR

Modo	Comportamento
`NORMAL`	Utilize para uma nova carga. Se o mesmo arquivo já possuir importação vigente, a API pode bloquear por conflito.
`REIMPORTAR`	Cria uma nova importação e, após a nova carga ser validada, marca a anterior como `SUBSTITUIDO`.

A importação anterior só é substituída depois que a nova carga termina e passa pela validação final.

CONTRATO DE ENTRADA

Formato da planilha

A primeira aba é processada. Os cabeçalhos são normalizados para minúsculas e devem conter, no mínimo:

Coluna obrigatória	Finalidade
`id`	Identificador da linha de origem.
`id_movim_finan`	Identificador estrutural do movimento financeiro.
`data`	Data/competência do movimento.
`id_conta`	Conta analítica da origem.
`planejamento_analitico`	Descrição analítica da origem.
`id_planejamento`	Identificador do planejamento.
`planejamento`	Descrição sugerida.
`tipo`	Tipo da origem.
`cod_planejamento`	Código/classificação sugerida.
`credito`	Valor de crédito.
`debito`	Valor de débito.

ESCALABILIDADE

Arquivos grandes

O parser foi desenhado para arquivos contábeis de grande volume. A gravação é feita em batches e o diagnóstico de XLSX utiliza leitura otimizada em streaming para evitar transportar centenas de milhares de linhas pelo n8n.

batch_size mínimo100

batch_size máximo10.000

ProcessamentoStreaming / batches

DiagnósticoSem gravação

TRATAMENTO DE FALHAS

Códigos de erro

HTTP	Situação	Exemplo
`400`	Parâmetro inválido, formato não suportado ou batch_size fora do limite.	`modo_importacao deve ser NORMAL ou REIMPORTAR.`
`401`	API Key ausente ou inválida.	Autenticação recusada.
`404`	Empresa não cadastrada para o código Domínio.	`Empresa não cadastrada.`
`409`	Conflito de importação/arquivo já existente.	Utilize REIMPORTAR quando aplicável.
`413`	Arquivo excede o limite configurado.	`Arquivo excede N MB.`
`422`	Arquivo recebido, mas inválido para processamento contábil.	`Arquivo desbalanceado: -196210.0.`

Importante: erros 422 de desbalanceamento devem ser tratados corrigindo o arquivo de origem; não é recomendado remover essa trava.

AUTOMAÇÃO

Integração com n8n

Nos workflows P&S2B, envie o arquivo como n8n Binary File no campo multipart file e guarde a API Key em Credential/Header Auth.

Receba o XLSX/XLS no Form Trigger ou outro fluxo.

Use HTTP Request com POST e multipart/form-data.

Parameter Type: n8n Binary File; Name: file.

Trate HTTP 422 separadamente para mostrar o motivo ao usuário.

Para arquivos desbalanceados, chame /v1/diagnose-unbalanced e gere o relatório de divergências.

DESENHO DO SERVIÇO

Arquitetura e segurança

FrameworkFastAPI

LeituraStreaming / batches

PersistênciaPostgreSQL

ControleHash + status

Segredos: APP_API_KEY e credenciais PostgreSQL pertencem somente ao serviço do parser. Nunca devem ser expostos no portal de documentação.

RECURSOS

Downloads

Documentação MarkdownReferência completa para consulta e versionamento. Collection PostmanChamadas prontas para os principais endpoints. OpenAPI JSONContrato da API utilizado pelo Swagger UI. Swagger UIExplore os endpoints e schemas em interface interativa.

VERSÃO

Versionamento

Versão	Alteração principal
1.1.0	Adição de `/v1/diagnose-unbalanced` com retorno dos grupos e linhas originais responsáveis pelo desbalanceamento.
1.0.0	Versão inicial com health, análise e processamento/persistência.

BOAS PRÁTICAS

Segurança

Utilize HTTPS, mantenha a API Key apenas em credenciais seguras e nunca encaminhe credenciais PostgreSQL ao cliente ou ao portal de documentação. Arquivos temporários processados pela API são removidos após a requisição.