@anpdgovbr/sei-client

Cliente TypeScript para chamadas SOAP RPC/encoded ao Web Service do SEI (SeiWS.php) — sem dependência de framework, .env ou runtime específico além de Node.js 22+. A aplicação consumidora resolve configuração, cache, autorização, logging e persistência.

A API segue o contrato do SEI 5.0.4 e cobre consultas, criação de processos e documentos, tramitação, blocos, marcadores, controle de prazo, anotações, publicações, e-mail e ouvidoria.

O guia operacional fica em ../../doc/sei-client.md.

Sumário

• Instalação
• Uso
• Métodos principais
• Tratamento de erros
• Conteúdo de documentos
• Blocos
• Marcadores e controle de prazo
• Upload em partes
• Responsabilidades do consumidor

Instalação

npm install @anpdgovbr/sei-client
# ou
yarn add @anpdgovbr/sei-client
# ou
pnpm add @anpdgovbr/sei-client
Copy

Uso

import { createSeiClient } from "@anpdgovbr/sei-client"

const sei = createSeiClient({
  endpointUrl: "https://sei.orgao.gov.br/sei/ws/SeiWS.php",
  siglaSistema: process.env.SEI_SIGLA_SISTEMA!,
  identificacaoServico: process.env.SEI_IDENTIFICACAO_SERVICO!,
  requestTimeoutMs: 30_000,
})

// Consultas (somente leitura)
const unidades = await sei.consultas.listarUnidades()
const proc = await sei.consultas.consultarProcedimento({
  idUnidade: "110000001",
  protocoloProcedimento: "00000.000001/2026-01",
})

// Operações (alteram estado)
const retorno = await sei.operacoes.gerarProcedimento({
  idUnidade: "110000001",
  procedimento: {
    idTipoProcedimento: "100000101",
    especificacao: "Integração via sei-client",
    assuntos: [{ codigoEstruturado: "06.01.01" }],
    interessados: [],
    nivelAcesso: "0",
  },
})
Copy

O pacote não lê variáveis de ambiente. SiglaSistema e IdentificacaoServico são cadastrados no SEI (Administração → Sistemas) e devem ser tratados como segredos server-side.

Métodos principais

A fachada SeiClient agrupa dois subclients: consultas (SeiConsultasClient, somente leitura) e operacoes (SeiOperacoesClient, escrita). Os métodos mais comuns também existem como atalhos na raiz.

Consultas (sei.consultas.*)

Operações (sei.operacoes.*)

A lista completa, com parâmetros e tipos, está na documentação TypeDoc do monorepo.

Tratamento de erros

Todas as falhas de comunicação viram SeiSoapError, com operation, status HTTP (408 em timeout) e fault quando o SEI retorna SOAP Fault:

import { SeiSoapError } from "@anpdgovbr/sei-client"

try {
  await sei.consultas.consultarProcedimento({ ... })
} catch (error) {
  if (error instanceof SeiSoapError) {
    console.error(error.operation, error.status, error.fault)
  }
}
Copy

Conteúdo de documentos

O SEI espera Documento.Conteudo e Documento.ConteudoSecoes[].Conteudo em Base64. Use encodeSeiBase64 para HTML/texto:

import { encodeSeiBase64 } from "@anpdgovbr/sei-client"

await sei.operacoes.incluirDocumento({
  idUnidade: "110000036",
  documento: {
    tipo: "G",
    protocoloProcedimento: "00261.000000/2026-00",
    idSerie: "5",
    nivelAcesso: "0",
    conteudoSecoes: [
      {
        nome: "Corpo do Texto",
        conteudo: encodeSeiBase64("<p>Conteúdo do documento</p>"),
      },
    ],
  },
})
Copy

Blocos

O SEI diferencia tipos de bloco: A (assinatura), R (reunião) e I (interno). Documento pode ser incluído em bloco de assinatura (Tipo=A), mas processo não: para incluirProcessoBloco/retirarProcessoBloco, use bloco interno ou outro tipo compatível. Essa restrição vem do SEI e não do cliente TypeScript.

Marcadores e controle de prazo

definirMarcador registra marcador em processo e não possui operação par de remoção no Web Service do SEI. Já controles de prazo têm ciclo explícito: definirControlePrazo, concluirControlePrazo e removerControlePrazo.

Upload em partes

adicionarArquivo inicia um anexo temporário usando tamanho total em bytes, MD5 hexadecimal do arquivo completo e a primeira parte em Base64. adicionarConteudoArquivo envia partes adicionais em Base64 até completar o tamanho declarado. O ID retornado é usado em documento.idArquivo.

Responsabilidades do consumidor

• Carregar e proteger siglaSistema/identificacaoServico (segredos).
• Definir timeout, retry e circuit breaker conforme o ambiente.
• Tratar SeiSoapError e mapear mensagens para o usuário final.
• Cache, auditoria, autorização e persistência ficam na aplicação.