API 2.0.0 • ENGINE 1.10.0 • ESTÁVEL

Documentos fiscais transformados em dados estruturados

API para identificação e extração de informações de PDFs fiscais e contábeis, preparada para automações com n8n, Microsoft 365 e sistemas internos do grupo P&S2B.

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

DISPONIBILIDADE

Status da API

Abrir health check

StatusConsultando...

Versão2.0.0

Tempo de respostaConsultando...

Engine documental1.10.0

Última verificação: aguardando...

INTEGRAÇÃO

Primeiros passos

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

Solicite uma API Key à P&S2B.

Prepare o arquivo PDF que será processado.

Envie um POST multipart para /api/v1/pdf/extract.

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

Utilize os dados estruturados retornados na automação.

ENDEREÇO

URL base

https://document.pes2b.com

SEGURANÇA

Autenticação

Os endpoints de 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 código-fonte, GitHub, prints ou workflows exportados.

MONITORAMENTO

Health checks

GET/api/v1/healthPúblico

GET/api/v1/infoPúblico

GET/openapi.jsonPúblico

OBSERVABILIDADE

Diagnóstico operacional

GET/api/v1/diagnosticsAPI Key

Retorna métricas acumuladas desde o último início do serviço, incluindo volume, sucesso, falhas, confiança, parsers ativos e tempo médio de processamento.

curl -X GET \
  'https://document.pes2b.com/api/v1/diagnostics' \
  -H 'X-API-Key: SUA_CHAVE'

Campo	Significado
`processedDocuments`	Total de documentos contabilizados.
`successfulDocuments`	Documentos processados com sucesso.
`failedDocuments`	Documentos com falha.
`successRate`	Taxa de sucesso entre 0 e 1.
`blockedByConfidence`	Parsers bloqueados por confiança inferior ao mínimo.
`unknownDocuments`	Documentos não identificados.
`rejectedUploads`	Uploads rejeitados antes do processamento.
`averageProcessingMs`	Tempo médio de processamento em milissegundos.
`byDocumentType`	Quantidade processada por tipo documental.
`byConfidenceLevel`	Quantidade nos níveis HIGH, MEDIUM e LOW.

{
  "success": true,
  "message": "Diagnóstico operacional do serviço.",
  "requestId": "a1cb5279-4b56-442d-876c-bf4b1ae23aca",
  "data": {
    "service": "pes2b-document-service",
    "environment": "production",
    "engineVersion": "1.10.0",
    "uptimeSeconds": 104,
    "processedDocuments": 0,
    "successfulDocuments": 0,
    "failedDocuments": 0,
    "successRate": 1,
    "blockedByConfidence": 0,
    "unknownDocuments": 0,
    "rejectedUploads": 0,
    "averageProcessingMs": 0,
    "parsers": { "total": 6, "active": 6, "inactive": 0 },
    "byDocumentType": {},
    "byConfidenceLevel": { "HIGH": 0, "MEDIUM": 0, "LOW": 0 }
  },
  "errors": [],
  "warnings": [
    "As métricas são mantidas em memória e reiniciadas quando o serviço é reiniciado."
  ]
}

Limitação atual: as métricas são mantidas em memória. Reinícios e novos deploys zeram os contadores.

ENDPOINT PRINCIPAL

Processar PDF

POST/api/v1/pdf/extractAPI Key

Recebe um arquivo PDF no campo multipart file, identifica o tipo documental e devolve os dados encontrados em JSON.

Envie o arquivo como multipart/form-data. O nome do campo deve ser exatamente file.

PROCESSAMENTO EM LOTE

Processar vários PDFs

POST/api/v1/pdf/extract-batchAPI Key

Processa até 10 arquivos por requisição. Envie os PDFs no campo multipart files.

ENTRADA

Exemplo de requisição

curl -X POST \
  'https://document.pes2b.com/api/v1/pdf/extract' \
  -H 'X-API-Key: SUA_CHAVE' \
  -F 'file=@documento.pdf;type=application/pdf'

Campo	Tipo	Obrigatório	Descrição
`file`	PDF	Sim	Documento a ser identificado e processado.

SAÍDA

Resposta de sucesso

{
  "success": true,
  "documentType": "DECLARACAO_PGDAS",
  "engine": {
    "version": "1.10.0",
    "family": "SIMPLES_NACIONAL",
    "detector": "simples.detector",
    "parser": "declaracao",
    "parserVersion": "1.0.0",
    "schemaVersion": "1.0",
    "confidence": 1,
    "confidenceLevel": "HIGH",
    "minimumConfidence": 0.8,
    "parserExecuted": true,
    "parserBlocked": false
  },
  "pages": 2,
  "data": {
    "identificacao": {
      "empresa": "EMPRESA EXEMPLO LTDA.",
      "cnpj": "12.345.678/0001-90",
      "competencia": "06/2026"
    }
  },
  "warnings": [],
  "errors": [],
  "requestId": "00000000-0000-4000-8000-000000000001"
}

O objeto engine permite auditar detector, parser, versão, confiança e eventual bloqueio de segurança. Os campos de data variam conforme o documento.

Níveis de confiança: HIGH a partir de 0,90; MEDIUM a partir de 0,75; LOW abaixo de 0,75. O parser somente executa quando a confiança atinge o limite definido no registry.

MÓDULO FISCAL

Relatório do Simples Nacional

Para relatórios de apuração do Domínio Sistemas, a API pode retornar o resumo mensal, as apurações individuais e a consolidação por anexo.

Resumo mensal

Receita da competência, RBT12, faixa, valor do Simples e carga tributária efetiva.

Apurações

Atividade, anexo, seção, tratamento tributário, receita, alíquota efetiva e tributo.

Consolidação

Agrupamento das receitas e tributos por anexo, com alíquota média efetiva.

{
  "resumo": {
    "receitaBrutaMesNumero": 10238.00,
    "rbt12Numero": 122916.51,
    "faixaEnquadramento": "0,00 a 180.000,00",
    "valorSimplesRecolherNumero": 332.78,
    "cargaTributariaTotalNumero": 3.2504
  },
  "consolidacaoPorAnexo": [
    {
      "anexo": "I",
      "descricaoAnexo": "Comércio",
      "receitaTributadaNumero": 8378.00,
      "valorSimplesNumero": 221.18,
      "aliquotaMediaNumero": 2.64
    }
  ]
}

IDENTIFICAÇÃO

Documentos reconhecidos

A API identifica automaticamente o tipo do PDF e seleciona o parser correspondente. Os campos variam conforme o documento e a qualidade do conteúdo extraído.

Tipo	Identificador	Dados principais
Declaração PGDAS-D	`DECLARACAO_PGDAS`	Competência, receitas, débito, número da declaração, recibo e tipo original/retificadora.
Recibo PGDAS-D	`RECIBO_PGDAS`	Número do recibo, transmissão, CNPJ, competência, receita e débitos.
Guia DAS	`DAS`	Empresa, CNPJ, competência, número do documento, valor e vencimento.
Extrato PGDAS-D	`EXTRATO_PGDAS`	Identificação do documento; parser detalhado ainda em evolução.
Relatório do Simples	`RELATORIO_SIMPLES`	Resumo, RBT12, apurações, consolidação por anexo e carga tributária.
Declaração de faturamento	`DECLARACAO_FATURAMENTO`	Período, faturamento mensal, total, emissão, responsável e validações.
Declaração + recibo no mesmo PDF	`COMBINADO_DECLARACAO_RECIBO_PGDAS`	Separação automática em dois documentos estruturados.
Documento não reconhecido	`NAO_IDENTIFICADO`	Metadados técnicos e indicação para conferência manual.

REFERÊNCIA PRÁTICA

Exemplos de JSON por documento

Todos os exemplos abaixo utilizam dados fictícios e anonimizados. O envelope técnico real inclui também success, engine, pages, warnings, errors, text e requestId.

Declaração PGDAS-DDECLARACAO_PGDAS

{
  "success": true,
  "documentType": "DECLARACAO_PGDAS",
  "pages": 4,
  "data": {
    "identificacao": {
      "empresa": "EMPRESA EXEMPLO LTDA.",
      "cnpj": "12.345.678/0001-90",
      "competencia": "06/2026",
      "numeroDeclaracao": "12345678202606001"
    },
    "documento": {
      "tipo": "DECLARACAO_PGDAS",
      "tipoDeclaracao": "ORIGINAL",
      "ehRetificadora": false,
      "numeroRecibo": "01.23.45678.9012345-6"
    },
    "resumo": {
      "receitaBrutaMesNumero": 45000.00,
      "totalDebitoDeclaradoNumero": 2187.50
    }
  },
  "warnings": [],
  "errors": [],
  "requestId": "00000000-0000-4000-8000-000000000001"
}

Recibo PGDAS-DRECIBO_PGDAS

{
  "success": true,
  "documentType": "RECIBO_PGDAS",
  "data": {
    "identificacao": {
      "empresa": "EMPRESA EXEMPLO LTDA.",
      "cnpj": "12.345.678/0001-90",
      "competencia": "06/2026"
    },
    "documento": {
      "tipo": "RECIBO_PGDAS",
      "numeroDeclaracao": "12345678202606001",
      "numeroRecibo": "01.23.45678.9012345-6",
      "tipoDeclaracao": "ORIGINAL",
      "ehRetificadora": false
    },
    "datas": {
      "dataTransmissao": "15/07/2026",
      "horaTransmissao": "14:32:10",
      "dataTransmissaoISO": "2026-07-15T17:32:10.000Z"
    },
    "valores": {
      "receitaBrutaNumero": 45000.00,
      "totalDebitoDeclaradoNumero": 2187.50,
      "totalDebitoExigivelNumero": 2187.50
    }
  },
  "requestId": "00000000-0000-4000-8000-000000000002"
}

Guia DASDAS

{
  "success": true,
  "documentType": "DAS",
  "data": {
    "identificacao": {
      "empresa": "EMPRESA EXEMPLO LTDA.",
      "cnpj": "12.345.678/0001-90",
      "competencia": "06/2026"
    },
    "documento": {
      "tipo": "DAS",
      "numeroDocumento": "07.16.26123.4567890-1"
    },
    "datas": {
      "vencimento": "20/07/2026"
    },
    "valores": {
      "valorDocumento": "2.187,50"
    },
    "extras": {}
  },
  "requestId": "00000000-0000-4000-8000-000000000003"
}

Extrato PGDAS-DEXTRATO_PGDAS

{
  "success": true,
  "documentType": "EXTRATO_PGDAS",
  "data": {
    "identificacao": {},
    "documento": {
      "tipo": "EXTRATO_PGDAS"
    },
    "datas": {},
    "valores": {},
    "extras": {
      "mensagem": "Parser ainda não implementado."
    }
  },
  "warnings": [],
  "requestId": "00000000-0000-4000-8000-000000000004"
}

Transparência: o extrato já é reconhecido, mas a extração detalhada ainda não está implementada na versão atual.

Relatório do Simples NacionalRELATORIO_SIMPLES

{
  "success": true,
  "documentType": "RELATORIO_SIMPLES",
  "data": {
    "identificacao": {
      "empresa": "EMPRESA EXEMPLO LTDA.",
      "cnpj": "12.345.678/0001-90",
      "competencia": "06/2026"
    },
    "documento": {
      "tipo": "RELATORIO_SIMPLES"
    },
    "resumo": {
      "receitaBrutaMesNumero": 45000.00,
      "rbt12Numero": 480000.00,
      "faixaEnquadramento": "360.000,01 a 720.000,00",
      "valorSimplesRecolherNumero": 2187.50,
      "cargaTributariaTotalNumero": 4.8611
    },
    "apuracoes": [
      {
        "ordem": 1,
        "anexo": "III",
        "descricaoAnexo": "Prestação de Serviços",
        "receitaTributadaNumero": 45000.00,
        "aliquotaEfetivaNumero": 4.8611,
        "valorSimplesNumero": 2187.50
      }
    ],
    "consolidacaoPorAnexo": [
      {
        "anexo": "III",
        "receitaTributadaNumero": 45000.00,
        "valorSimplesNumero": 2187.50,
        "quantidadeApuracoes": 1,
        "aliquotaMediaNumero": 4.8611
      }
    ]
  },
  "requestId": "00000000-0000-4000-8000-000000000005"
}

Declaração de faturamentoDECLARACAO_FATURAMENTO

{
  "success": true,
  "documentType": "DECLARACAO_FATURAMENTO",
  "data": {
    "identificacao": {
      "empresa": "EMPRESA EXEMPLO LTDA.",
      "cnpj": "12.345.678/0001-90",
      "competencia": "06/2026"
    },
    "documento": {
      "tipo": "DECLARACAO_FATURAMENTO",
      "finalidade": "COMPROVACAO_FATURAMENTO_12_MESES"
    },
    "periodo": {
      "inicio": "07/2025",
      "fim": "06/2026"
    },
    "faturamento": {
      "meses": [
        { "competencia": "07/2025", "valorNumero": 38000.00 },
        { "competencia": "08/2025", "valorNumero": 40500.00 }
      ],
      "quantidadeMeses": 12,
      "totalNumero": 480000.00,
      "totalConfere": true
    },
    "emissao": {
      "data": "16/07/2026",
      "municipio": "Porto Alegre/RS"
    },
    "responsavel": {
      "nome": "RESPONSÁVEL EXEMPLO",
      "cpf": "***.***.***-**"
    },
    "assinatura": {
      "necessaria": true,
      "assinada": false,
      "tipoEsperado": "PADES"
    },
    "warnings": []
  },
  "requestId": "00000000-0000-4000-8000-000000000006"
}

Declaração e recibo combinadosCOMBINADO_DECLARACAO_RECIBO_PGDAS

{
  "success": true,
  "documentType": "COMBINADO_DECLARACAO_RECIBO_PGDAS",
  "compound": true,
  "documents": [
    {
      "role": "DECLARACAO",
      "suggestedSuffix": "DECLARACAO",
      "documentType": "DECLARACAO_PGDAS",
      "pages": 4,
      "data": { "documento": { "tipo": "DECLARACAO_PGDAS" } },
      "file": {
        "mimeType": "application/pdf",
        "extension": "pdf",
        "size": 182400,
        "base64": "JVBERi0xLjQKLi4u"
      }
    },
    {
      "role": "RECIBO",
      "suggestedSuffix": "RECIBO",
      "documentType": "RECIBO_PGDAS",
      "pages": 1,
      "data": { "documento": { "tipo": "RECIBO_PGDAS" } },
      "file": {
        "mimeType": "application/pdf",
        "extension": "pdf",
        "size": 48320,
        "base64": "JVBERi0xLjQKLi4u"
      }
    }
  ],
  "requestId": "00000000-0000-4000-8000-000000000007"
}

EVOLUÇÃO DO PARSER

Como incluir um novo tipo de documento

Adicionar um documento não significa apenas criar uma expressão regular. O processo completo inclui amostras reais, regra de identificação, contrato de saída, parser, testes, documentação e validação no fluxo consumidor.

Exemplo: para incluir um Recibo de entrega do SPED, primeiro precisamos receber PDFs reais e anonimizados. O texto e o leiaute podem variar conforme o módulo — ECD, ECF, EFD ICMS/IPI, EFD-Contribuições ou outro — e também conforme a versão do programa.

Visão geral do processo

Reunir amostras. Separar preferencialmente de 3 a 5 PDFs do mesmo documento, incluindo variações de período, empresa e versão.

Definir o contrato de saída. Listar exatamente quais campos devem retornar e seus formatos.

Analisar o texto extraído. Verificar como o pdf-parse entrega títulos, rótulos e valores.

Criar a detecção. Incluir uma regra específica no detector, antes de regras mais genéricas.

Implementar o parser. Extrair e normalizar os campos sem misturar identificação com regra de negócio do n8n.

Registrar o parser. Associar o novo documentType ao módulo criado.

Criar testes automatizados. Validar identificação, campos obrigatórios, variações e documentos parecidos.

Atualizar contrato e documentação. OpenAPI, Swagger, exemplos JSON, Markdown e changelog.

Publicar e homologar. Executar testes, fazer deploy e validar uma chamada real antes de alterar o fluxo do n8n.

Arquivos normalmente alterados

Arquivo	Finalidade
`src/document/detectors/familias/<familia>.detector.js`	Reconhece o tipo documental pelas marcas textuais do PDF.
`src/document/parsers/<grupo>/<documento>/parser.js`	Extrai os campos e monta o objeto `data`.
`src/document/parsers/registry.js`	Liga o identificador retornado pelo detector ao parser correspondente.
`src/document/helpers/`	Funções reutilizáveis para CNPJ, competência, datas, valores e normalização.
`test/<documento>.test.js`	Garante que futuras mudanças não quebrem o documento já suportado.
`docs/openapi.json` e `docs-site/openapi.json`	Documentam schemas, exemplos e respostas no Swagger.
`docs-site/index.html` e Markdown	Explicam o novo documento para quem integra com a API.

Exemplo: Recibo de entrega do SPED

O identificador deve ser específico para o módulo. Um nome possível seria RECIBO_SPED_ECD. Não é recomendável usar apenas RECIBO_SPED se os campos e marcas textuais forem diferentes entre ECD, ECF e EFD.

// document.detector.js — exemplo ilustrativo
if (
  normalized.includes('RECIBO DE ENTREGA DE ESCRITURAÇÃO CONTÁBIL DIGITAL') &&
  normalized.includes('IDENTIFICAÇÃO DO ARQUIVO') &&
  normalized.includes('HASH DA ESCRITURAÇÃO')
) {
  return 'RECIBO_SPED_ECD';
}

// registry.js
RECIBO_SPED_ECD: require(
  path.join(__dirname, 'sped', 'recibo-ecd')
)

// src/document/parsers/sped/recibo-ecd/parser.js
exports.parse = (text) => ({
  identificacao: {
    empresa: extrairEmpresa(text),
    cnpj: extrairCnpj(text),
    periodo: extrairPeriodo(text)
  },
  documento: {
    tipo: 'RECIBO_SPED_ECD',
    numeroRecibo: extrairNumeroRecibo(text),
    hashEscrituracao: extrairHash(text)
  },
  transmissao: {
    dataHora: extrairDataHora(text),
    situacao: extrairSituacao(text)
  },
  extras: {}
});

Contrato JSON sugerido

{
  "success": true,
  "documentType": "RECIBO_SPED_ECD",
  "pages": 1,
  "data": {
    "identificacao": {
      "empresa": "EMPRESA EXEMPLO LTDA.",
      "cnpj": "12.345.678/0001-90",
      "periodo": {
        "inicio": "01/01/2025",
        "fim": "31/12/2025"
      }
    },
    "documento": {
      "tipo": "RECIBO_SPED_ECD",
      "numeroRecibo": "ECD-EXEMPLO-000001",
      "hashEscrituracao": "HASH_ANONIMIZADO"
    },
    "transmissao": {
      "dataHora": "30/06/2026 18:42:10",
      "situacao": "RECEBIDA"
    },
    "extras": {}
  },
  "warnings": [],
  "errors": [],
  "requestId": "00000000-0000-4000-8000-000000000100"
}

Critérios mínimos de aceite

O novo PDF é identificado corretamente em todas as amostras de homologação.
Documentos semelhantes não são classificados como o novo tipo por engano.
Campos obrigatórios possuem testes automatizados.
Campos ausentes retornam null, sem inventar valores.
Datas, valores, CNPJ e competência seguem o padrão já adotado pela API.
O Swagger e o Markdown exibem um exemplo anonimizado.
O workflow consumidor trata o novo documentType antes da entrada em produção.

Importante: a inclusão no parser e a inclusão no fluxo do n8n são etapas diferentes. A API pode reconhecer e devolver o JSON corretamente, mas o workflow ainda precisa decidir onde salvar o arquivo, quais campos atualizar e quais ações executar.

AUTOMAÇÃO

Integração com n8n

Use o node HTTP Request.

Método POST e URL https://document.pes2b.com/api/v1/pdf/extract.

Adicione o cabeçalho X-API-Key usando uma credencial segura.

Ative Send Body, selecione Form-Data e envie o binary no campo file.

Utilize documentType, data.identificacao.competencia e data nos próximos nodes.

ENGINE 1.10.0

Arquitetura, testes e observabilidade

A engine foi organizada para crescer por famílias documentais sem concentrar toda a lógica em um único detector ou parser.

Detecção por família

Regras ponderadas identificam o documento, registram regras encontradas e calculam confiança real.

Registry central

Cada parser declara família, versão, status, schema e confiança mínima.

Parser modular

Cada documento possui index.js, parser.js, schema.js e rules.js.

Qualidade automatizada

Fixtures anonimizadas e testes unitários, de contrato e end-to-end protegem os formatos homologados.

Logs estruturados

Eventos JSON registram requestId, documento, confiança, parser, duração e motivo de falha.

Métricas operacionais

O endpoint de diagnóstico consolida volume, taxa de sucesso, tempo médio e níveis de confiança.

Compatibilidade: o campo público documentType foi preservado. As informações novas foram acrescentadas ao objeto engine, mantendo os workflows existentes do n8n.

AUDITORIA

Rastreabilidade

Registre o requestId retornado pela API. Ele permite localizar a execução nos logs e facilita o diagnóstico de falhas.

Nos workflows do n8n, grave o identificador na lista de logs junto ao nome do arquivo, empresa, competência e tipo documental.

DIAGNÓSTICO

Códigos de erro

HTTP	Situação	Ação recomendada
`400`	Arquivo ausente, inválido ou parâmetros incorretos.	Confira o multipart e o campo `file`.
`401`	API Key ausente ou inválida.	Revise o cabeçalho `X-API-Key`.
`413`	Arquivo excede o limite permitido.	Reduza o PDF ou divida o lote.
`422`	Conteúdo não processável.	Confirme se o arquivo é PDF válido e legível.
`500`	Falha interna no processamento.	Registre o `requestId` e consulte os logs.

RECURSOS

Downloads

Arquivos oficiais para integração, testes e versionamento técnico.

MD Documentação MarkdownReferência técnica versionável. Baixar POST Collection PostmanChamadas prontas para teste. Baixar API Especificação OpenAPIContrato com schemas, exemplos e respostas. Baixar UI Swagger UIExplore e teste os endpoints. Abrir

EVOLUÇÃO

Versionamento

A API pública está na versão 2.0.0 e utiliza rotas /api/v1. A engine documental está na versão 1.10.0. Alterações incompatíveis no contrato público serão publicadas em uma nova versão de rota; melhorias internas compatíveis evoluem a versão da engine.

BOAS PRÁTICAS

Segurança

Não exponha a API Key no navegador ou em repositórios.
Use HTTPS em todas as chamadas.
Evite armazenar PDFs sensíveis fora dos ambientes autorizados.
Registre somente os dados necessários para auditoria.
Faça rotação da API Key quando houver suspeita de exposição.