API de integração com o Revisão de Contas v1

CONTEÚDO

1. Visão Geral
   1. Rota
   2. Manutenção de documentos - saveDocument
   3. Inclusão de glosas - addMovementManualRestriction
   4. Remoção de glosas - removeMovementManualRestriction
   5. Validação de glosas - validateMovementRestriction
   6. Remoção de documentos - removeDocumentsByInvoice
   7. Remoção de documentos - removeDocumentsById
   8. Consulta de documentos - getDocumentById
   9. Consulta de documentos - getDocumentByInvoice
   10. Json retornado
2. Regras de Negócio Aplicadas
3. Como Validar as Informações
   
   1. Central de Movimentação de Guias TISS
      
4. Exemplo de Como Validar as Informações

01. VISÃO GERAL

O TOTVS Saúde Planos (Linha Datasul) oferece uma série de APIs para integração.

A  API Manutenção de Documentos tem o objetivo de consultar, criar, atualizar e eliminar documentos do Revisão de Contas.

O método documentsMaintenance da API fornece a opção de modificar os dados do documento e incluir, alterar ou excluir movimentos do documento, seguindo as regras de negócio explicadas na sessão 2. Regras de Negócio Aplicadas.

Com a entrada em vigência da TISS 4, a v1 desta API foi depreciada e é mantida apenas para compatibilidade pois trata apenas documentos versão TISS 3.05.00 e anteriores.

Favor considerar a utilização da última versão desta API, que trata documentos de versões mais novas da TISS além de manter a compatibilidade com documentos TISS 3.05.00 e anteriores.

a. Rota

/hrc/<versao>/documentsMaintenance/

b. saveDocument

c. addMovementManualRestriction

d. removeMovementManualRestriction

e. validateMovementRestriction

f. removeDocumentsByInvoice

Permite remover documentos passando a chave de uma fatura. Para esta funcionalidade não temos Json de entrada, os dados são passados pela URL.

Unidade/UnidadePrestadora/PrestadorPrincipal/AnoFatura/SerieFatura/Fatura

Exemplo:

http://cxs-man-dts03:8280/api/hrc/v1/documentsMaintenance/remove/fat/120/970/970/2020/970/2000G

g. removeDocumentsById

Permite remover documentos passando a chave de um documento. Para esta funcionalidade o Json de entrada possui apenas o usuário, os dados são passados pela URL.

Unidade/UnidadePrestadora/Transacao/SerieDocumento/NumeroDocumento/SequenciaDocumento

Exemplo:

http://cxs-man-dts03:8280/api/hrc/v1/documentsMaintenance/remove/doc/120/120/2/LUIS/26062181/0

{
    "parametros": [
        {
            "nomeUsuario": "user"
        }
    ]
}

h. getDocumentById

Retorna um Json contendo todos os dados de um documento. Para esta funcionalidade não temos Json de entrada, os dados são passados pela URL.

Unidade/UnidadePrestadora/Transacao/SerieDocumento/NumeroDocumento/SequenciaDocumento

Exemplo:

http://cxs-man-dts03:8280/api/hrc/v1/documentsMaintenance/doc/120/120/2/MARV/300/0

i. getDocumentByInvoice

Retorna um Json contendo todos os dados de um documento. Para esta funcionalidade não temos Json de entrada, os dados são passados pela URL.

Unidade/UnidadePrestadora/PrestadorPrincipal/AnoFatura/SerieFatura/Fatura

Exemplo:

http://cxs-man-dts03:8280/api/hrc/v1/documentsMaintenance/fat/120/970/970/2020/970/2000G

j. Json retornado

Quando o processo de modificar o documento e/ou movimentos for realizado com sucesso será retornado o código 200 e o json com a chave do documento.

Exemplo:

{
    "total": 1,
    "items": [
        {
            "cdUnidadePrestadora": 120,
            "cdUnidade": 120,
            "nrDocOriginal": 30424,
            "nrSerieDocOriginal": "TISS",
            "mensagemDetalhada": "",
            "nrDocSistema": 1,
            "tipoRegistro": "SUCCESS",
            "cdTransacao": 2
        }
    ],
    "hasNext": false
}

Quando ocorrer alguma inconsistência no processo será retornado o código 400 ou 500 e um json com as ocorrências.

O código de erro na mensagem principal é padronizado conforme a codificação abaixo. Enquanto que os códigos de erro listados na tag details são gerados pelo sistema e podem ser consultados no programa Manutenção de Mensagens (TE0110K).

Exemplo:

{
    "message": "Erro ao comunicar com API do Sistema",
    "details": [
        {
            "message": "Manutencao nao permitida em movimentos que nao estejam com status de Auditoria!",
            "detailedMessage": "",
            "code": "1",
            "type": "error"
        }
    ],
    "detailedMessage": "Erro ao executar saveDocument - api/v1/documentsMaintenance",
    "code": "100",
    "type": "error"
}

02. REGRAS DE NEGÓCIO APLICADAS 

O processo permitirá alterar os campos que são passíveis de alteração na Central de Movimentações TISS (hrc.document). Deve ser sempre informado valor nos campos editáveis, caso contrário o sistema entenderá que o valor do campo é nulo.

Pacotes

• Os campos nr-processo e nr-sequencia dos movimentos nunca podem mudar. Eles são a chave para a vinculação dos movimentos entre o que esta no Json e o que esta na base. 
• No caso do documento possuir mais de um lançamento de pacotes idênticos(mesmo código, prestador, data e hora), o sistema entende que o mesmo movimento não pode repetir dentro do mesmo pacote. Identificando assim a existência de outro pacote idêntico(mesmo código, prestador, data e hora).

Restrições:

• Somente será permitida a alteração de dados de um documento por requisição.
• Somente será permitida a alteração de documento com os movimentos com o status de Em Auditoria.
• O processo não permite a alteração de movimentos incluídos via pacote de intercâmbio (SISPAC);
• Ao incluir/modificar um movimento ele estará com o situação do movimento ('in-liberado-contas') 8 - Em Auditoria.
• O processo permite a inclusão de movimentos no documento, sendo que os campos que não podem ser definidos serão desconsiderados.
• O processo permite a exclusão de movimentos do documento.
• Quando da inclusão de um documento e ou movimento, os campos que não podem ser definidos serão desconsiderados. Não havendo validações se foram gravados ou se podem ser definidos pelo usuário.
• Os métodos para adicionar glosa manual (addMovementManualRestriction), remover glosa manual (removeMovementManualRestriction) e validação de glosas (validateMovementRestriction) esperam na JSON da requisição apenas um movimento por solicitação conforme os exemplos apresentados na documentação.

Alteração dos valores dos movimentos:

• Para quaisquer requisições de modificação de movimentos com valor informado nas tags vlMovimento, vlMovimentoHono, vlTaxaMovimento ou vlTaxaMovimentoHono esses valores serão considerados prioritariamente sobre quaisquer regras de valorização. Exemplo: se em uma requisição forem alterados via de acesso, quantidade de repasse e valor do movimento, o valor informado(diferente de zero e ?) nas tags vlMovimento, vlMovimentoHono, vlTaxaMovimento ou vlTaxaMovimentoHono prevalecerá, independente do valor valorizado pelo sistema.
• Se o cliente desejar que o sistema realize a valorização nos campos(vlMovimento, vlMovimentoHono, vlTaxaMovimento e vlTaxaMovimentoHono) com base nos demais campos do movimento, então as tags vlMovimento, vlMovimentoHono, vlTaxaMovimento e vlTaxaMovimentoHono deverão ser zeradas ou omitidas.
  • Se apenas algumas dessas tags forem informadas, o sistema realizará a valorização do movimento calculando o valor das demais e, ao fim do processo, gravará no movimento o valor da tag informada na requisição;
    • Exemplo1: informado na tag vlMovimento = 10  e na tag vlTaxaMovimento = 0. A api considera que o valor do movimento é 10 e a taxa será definida pela valorização do sistema;
    • Exemplo2: informado na tag vlMovimento = 0  e na tag vlTaxaMovimento = 1. A api considera que o valor do movimento será definido pela valorização do sistema e o valor da taxa será 1.
  • A valorização do movimento somente irá ocorrer caso o valor do movimento(vlMovimento) não tenha sido modificado anteriormente, seja via API, seja via interface no TOTVS. Ou seja, o sistema revaloriza apenas quando o vl-principal ou vl-auxiliar for igual ao vl-base-valor-sistema;
  • A tag vlmovimento é composta pela soma dos campos vl-principal e vl-auxiliar;
  • A tag vlTaxaMovimento é composta pela soma dos campos vl-taxa-out-uni-prin e vl-taxa-out-uni-auxi;
  • A tag vlMovimentoHono é composta pela soma dos campos vl-principal e vl-auxiliar, quando o movimento for de divisão de honorários;
  • A tag vlTaxaMovimentoHono é composta pela soma dos campos vl-taxa-out-uni-prin e vl-taxa-out-uni-auxi, quando o movimento for de divisão de honorários;
  • Através da api não podemos modificar diretamente os campos vl-base-valor-sistema, vl-honorarios-medicos, vl-operacional e vl-filme. Estes campos são de uso do sistema;
  • Maiores informações sobre valorização de movimentos podem ser consultadas em: Valorização de Procedimentos e Insumos

Inclusão/Exclusão de movimentos:

• Para inclusão de um novo movimento no documento será necessário preencher todos os campos da tag procedimentos ou insumos e da tag prestadores, somente para os movimentos que serão adicionados ou alterados. Os dados do prestador desse movimento tornam-se obrigatórios na tag prestadores. Para a inclusão de um novo movimento as tags nrProcesso e nrSeqDigitação do prestador devem ser informadas com valor zero e as tags idRegistro e idRegistroMovto não podem estar informadas com valor zero e nem com valores duplicados.
• Para realizar a inclusão de um documento com os movimentos, deve-se preencher todos os campos da tag documentos com exceção dos campos cdUnidade e nrDocOriginal, assim como pelo menos um movimento (procedimento ou insumo) e ainda os campos referente a tag prestadores do movimento com as tags nrProcesso e nrSeqDigitação zerados.
• Para a exclusão do movimento é necessário preencher a tag movimentosExcluidos, dentro da tag documentos, com as informações chave do movimento(nrProcesso e nrSeqDigitacao). Não poderá ser enviado o movimento excluído na tag de procedimentos/insumos.

Exemplo:

{
    "documentos": [
        {
            "movimentosExcluidos": [
                {"nrProcesso": 1, "nrSeqDigitacao": 1}
            ],
        }
    ]
}

03. COMO VALIDAR AS INFORMAÇÕES

Os resultados apresentados pela API podem ser validados e visualizados nos seguintes programas/relatórios:

Central de Movimentação de Guias Tiss (hrc.document)

Localize o documento que deseja consultar. 

Ao acessar o programa na tela inicial está disponível a opção de Busca Avançada:

Através da Busca Avançada é possível pesquisar o documento:

Ao informar alguns campos e clicar em buscar será retornado o documento encontrado: 

• Consultar o documento
  
        Localizando o documento, ao clicar no link do documento é possível consultar detalhes do documento. 
        
  
        Consultar glosas do documento.