Este guia se aplica aos clientes SEI e SIP. Use o guia SEI, o contrato SEI, o guia SIP e o contrato SIP para os detalhes de cada serviço.
| Camada | O que determina | Exemplo |
|---|---|---|
| Servidor e contrato WS | Operações expostas, dados retornados, regras de negócio e acesso | O SOAP SEI não oferece listagem geral de processos por unidade |
| Cliente de integração | Tipos, envelopes, transporte, timeout e normalização | consultarProcedimento exige protocolo e normaliza unidades abertas |
| Aplicação consumidora | Configuração, autorização final, cache, persistência e composição | Consultar protocolos conhecidos e filtrar pela unidade |
Operação existente no WSDL sem método de domínio é uma possível lacuna do cliente. Operação ausente do WSDL exige outra capacidade do servidor; XML de baixo nível não cria essa capacidade. Operação existente mas não liberada no cadastro é um problema de habilitação/acesso. Essas situações exigem soluções diferentes.
O SIP fornece cadastros e permissões vinculadas ao sistema alvo. Uma permissão no SIP não garante acesso a todo processo do SEI nem substitui os critérios do serviço de integração. A autorização do usuário final continua na aplicação.
! nos
exemplos TypeScript não valida valores em runtime.requestTimeoutMs é obrigatório e limita cada chamada, não o fluxo inteiro..env, carrega WSDL dinamicamente, implementa paginação
automática, cache ou retry. Use somente filtros e paginação presentes no
tipo da operação; não há paginação universal.Date.consultas, embora grave dados. Autorize por operação e efeito real.| Situação | Interpretação e tratamento |
|---|---|
| Lista vazia | Nenhum item retornado para aquele contexto; não prova inexistência global |
DTO null |
Mapper não produziu objeto; não equivale automaticamente a “não encontrado” |
| SOAP Fault | Verificar operation, status, fault e mensagem; pode indicar regra de negócio ou acesso |
| HTTP fora de 2xx | Verificar endpoint, proxy e servidor; status é preservado |
Timeout (status === 408) |
Limite local atingido; não confirma que o servidor cancelou o processamento |
| Erro de rede, parsing ou mapeamento | Pode propagar erro fora de SeiSoapError/SipSoapError; preservar causa no tratamento |
Os mappers têm padrões por campo. Coleções podem virar [], textos podem virar
"", campos anuláveis podem virar null e alguns objetos recebem valores
padrão. Consulte os tipos e mappers, sem inferir presença no XML só pela presença
no DTO.
Não registre envelopes ou credenciais indiscriminadamente. Ao diagnosticar, preserve nome da operação, status e contexto mínimo, com dados sensíveis removidos.
Não há retry automático nem garantia geral de idempotência. Se uma escrita expirar ou perder a resposta, ela pode já ter produzido efeito no servidor. Reconcilie o estado antes de repetir criação de processo/documento, envio de e-mail, tramitação, replicação ou outra alteração.
Grave os identificadores retornados para acompanhamento. Fluxos com várias chamadas não são uma transação única: mantenha resultados parciais e falhas por item. Limite concorrência em consultas em lote. Cache de permissões ou estado de processos deve ter política de atualização definida pelo consumidor.
Tipos e testes com fixtures verificam o comportamento do cliente, não a habilitação de um serviço na instalação de destino. Build e TypeDoc também não validam acesso real ao SEI/SIP.
Uma validação em homologação se aplica à operação, aos parâmetros e ao ambiente exercitados. Métodos marcados como Experimental na referência de API ainda exigem validação de ponta a ponta. A versão do contrato de referência não é uma garantia irrestrita para versões, módulos e configurações diferentes.
Para relatar um problema, informe versão do pacote, versão do servidor, operação, parâmetros anonimizados, status/erro e comportamento esperado. Identifique se a operação existe no WSDL, se está liberada e se o comportamento diverge do contrato ou da normalização documentada.