Como integrar o webservice TISS da operadora: tutorial passo a passo

Se a sua clínica ainda envia lotes pelo portal da operadora copiando e colando XML, é hora de evoluir. A integração via webservice TISS automatiza o envio, devolve o protocolo em segundos e elimina o erro humano de upload manual. Neste tutorial você vai entender — em linguagem simples — como funciona o webservice e o que precisa fazer para ligar sua clínica nele.
O que é o webservice TISS?
Webservice TISS é uma API SOAP definida pela ANS (veja a documentação oficial em gov.br/ans) que permite que sistemas conversem entre si — sua clínica envia o XML do lote e a operadora responde com protocolo, status e retorno financeiro.
Cada operadora publica o WSDL com seus endpoints. Os mais usados são envioLoteGuias, verificaElegibilidade e solicitacaoStatusProtocolo.
Quais pré-requisitos você precisa antes de integrar o webservice TISS?
Antes de codar qualquer integração, organize:
- Contrato ativo com a operadora e código de prestador.
- Credenciais do webservice (login, senha ou certificado A1).
- URL do WSDL homologação e produção.
- Um XML TISS válido — comece testando no validador TISS online para garantir que o arquivo passa no XSD antes de enviar.
Passo 1 — Como fazer a autenticação no webservice TISS?
A maioria das operadoras usa autenticação WS-Security com usuário e senha no header SOAP, ou certificado digital ICP-Brasil A1. Veja nosso guia detalhado em assinatura digital ICP-Brasil no TISS.
Passo 2 — Como enviar o lote pelo webservice TISS?
Monte o envelope SOAP envolvendo o XML do lote. Calcule o hash MD5 do conteúdo (veja o tutorial completo em como calcular o hash MD5) e chame o método envioLoteGuias. A resposta traz o número do protocolo.
Passo 3 — Como consultar o retorno pelo webservice TISS?
Depois de alguns minutos (ou horas, depende da operadora), consulte solicitacaoStatusProtocolo. O retorno traz as guias aceitas, em análise ou rejeitadas. Use a diferença entre rejeição e glosa para tratar cada caso corretamente.
Quais são os erros comuns na primeira integração com o webservice?
Os problemas que mais aparecem em produção:
- Versão de TISS divergente entre cliente e operadora (veja guia de migração para TISS 4.03).
- Hash MD5 calculado sobre o XML formatado em vez do canônico.
- Certificado A1 expirado ou cadeia incompleta.
- Tags fora da ordem definida no XSD — algo que o validador TISS mostra antes de você enviar.
Onde encontrar vídeos para aprofundar em integração webservice TISS?
Para ver na prática o consumo de webservices SOAP, pesquise no YouTube: consumir webservice SOAP tutorial.
Perguntas frequentes
Posso testar o webservice antes de produção?
Sim. Praticamente toda operadora oferece ambiente de homologação. Use-o exaustivamente — envie lotes vazios, lotes com erro proposital e observe os códigos de retorno.
Preciso de certificado digital para usar o webservice?
Depende da operadora. Algumas exigem ICP-Brasil A1 para autenticar, outras aceitam usuário e senha. Confirme no manual técnico de cada uma.
E se o webservice estiver fora do ar?
Mantenha sempre o portal manual como plano B e implemente fila de reenvio automático no seu sistema.
Conclusão
Integrar com webservice TISS economiza horas por semana e reduz drasticamente a glosa por envio fora do prazo. Comece validando seu XML no validador TISS, evolua para o ambiente de homologação e só depois suba para produção. E para gerar os arquivos com a estrutura certa, use o gerador de guias TISS.
Continue lendo
- Tutoriais
Tutorial do Faturamento TISS no TISS Manager: atendimento, lote validado, glosa e relatórios
Aprenda o fluxo de 4 etapas do Faturamento TISS — Atendimentos, Lotes, Glosas e Relatórios — com XML validado contra o schema oficial da ANS antes do envio.
- Tutoriais
Como converter XML TISS para a 4.03.00 e validar no Validador TISS: tutorial completo
Passo a passo para converter arquivos TISS antigos para a versão 4.03.00 e confirmar no Validador TISS que o XML está pronto para a operadora.
- Tutoriais
Validador TISS em lote: como validar vários XMLs de uma vez e acompanhar no Histórico
Passo a passo para validar vários arquivos XML TISS de uma vez, corrigir os problemas e guardar cada validação no Histórico do TISS Manager.