TissManager
Testar grátis
Tutoriais

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

Equipe TISS Manager30 de maio de 20269 min de leitura
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.

Pré-requisitos antes de começar

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 — Autenticação

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 — Envio do lote

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 — Consulta do retorno

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.

Erros comuns na primeira integração

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.

Vídeos para aprofundar

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