Ogmma Revenue

Demonstrativos

POST/v1/demonstrativos/leituras

Lê um arquivo TISS e devolve o demonstrativo

O Miydas é dono do parser TISS; quem integra é dono do arquivo. Esta rota existe para quem recebeu o demonstrativo por fora do portal (e-mail, download manual) e não quer escrever um segundo parser. NÃO fala com a operadora: é POST porque carrega corpo, não porque executa — não gasta cota, não cria execução e não aceita Prefer: wait. NÃO persiste: lê e devolve. O acervo é GET /v1/demonstrativos, e gravar aqui duplicaria o documento que já veio do portal, com dois ids para o mesmo protocolo. Buscar documento NOVO é POST /v1/retornos/sincronizacoes.

Escopo:
retorno:ler
Resposta:
200

Pedido

Esta rota não recebe parâmetro nenhum — só a chave.

Exemplo de chamada

curl -X POST https://api.miydas.com.br/v1/demonstrativos/leituras \
  -H "Authorization: Bearer $MIYDAS_CHAVE"

Resposta 200

dataLeituraDeArquivoO recurso. Os campos estão na tabela abaixo.

O resultado de ler um arquivo. Nada foi gravado: o acervo e GET /v1/demonstrativos.

Campos de LeituraDeArquivo

CampoTipoO que é
arquivoobjetoO arquivo de onde o dado veio.
nometextoNome do arquivo de onde o dado veio, como a operadora o nomeou.
formatotexto
um de: XML, ZIP
O involucro. Num ZIP, cada XML interno foi lido.
bytesinteiroTamanho do arquivo recebido.
demonstrativoslista de objetosUm por documento encontrado no arquivo. Um ZIP com varios XML devolve varios; um XML, normalmente um.
tipotexto
um de: ANALISE, PAGAMENTO
ANALISE: o julgamento da conta — o que a operadora reconheceu e o que glosou. PAGAMENTO: o caixa — o que ela creditou. Duas respostas distintas, quase sempre em meses distintos.
numeroDemonstrativotextoO número que a operadora deu ao demonstrativo. NÃO identifica o documento: ele se repete entre operadoras e entre competências. A identidade de um retorno é o protocolo mais a data.
protocolotextoO protocolo que a operadora devolveu ao receber. É o número que prova a entrega e por onde se consulta o andamento depois.
competenciatextoYYYY-MM, como o documento a declara.
operadoratextoO nome da operadora como o documento o escreve — nao e o catalogo ANS.
emitidoEmtextoData que o documento declara como de emissão. Cuidado: em documento de portal, é o dia do download.
creditoEmtextoData do credito. So em documento de pagamento.
valoresobjetoAusência é null, nunca "0.00": zero é valor que a operadora declarou.
informadotextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
processadotextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
liberadotextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
glosatextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
valorPagotextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
guiaslista de objetosAs guias do documento.
numeroGuiaPrestadortextoO número que VOCÊ deu à guia. O TISS não deixa repetir dentro do prestador, e é por ele que você reencontra a guia aqui.
numeroGuiaOperadoratextoO número que a OPERADORA deu à guia. Só existe depois que ela respondeu, e é o número que vale numa discussão com ela.
senhatextoA senha de autorização que a operadora concedeu. É ela que autoriza a execução.
beneficiariotextoO nome do beneficiário, como a operadora o devolveu. Pode divergir do seu cadastro, e em boa parte dos documentos nem vem — a carteirinha é que identifica.
carteiratextoNúmero da carteirinha do beneficiário na operadora, como está no cartão. Sem máscara nem separador.
atendimentoEmtextoData de realizacao do atendimento, como o documento a declara.
valoresobjetoAusência é null, nunca "0.00": zero é valor que a operadora declarou.
informadotextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
processadotextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
liberadotextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
glosatextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
glosaslista de objetosGlosas de nivel GUIA — as de item estao em itens[].glosas.
codigotextoCodigo da glosa na tabela 38 do TISS, como o documento o trouxe.
descricaotextoO significado do codigo. Preenchido da tabela 38 quando o documento manda so o codigo.
valortextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
itenslista de objetosProcedimentos e despesas da guia, como o documento os lista.
tipotexto
um de: PROCEDIMENTO, DESPESA
PROCEDIMENTO: a tabela de procedimentos. DESPESA: material, medicamento, taxa, diaria, OPME.
sequencialtextoA ordem do registro dentro do documento, como a operadora a numerou.
codigoProcedimentotextoCódigo do procedimento na tabela declarada em codigoTabela.
codigoDespesatextoSo em item de despesa.
descricaotextoDescrição do item, como a fonte a informou.
quantidadetextoQuantas unidades, como o documento declarou. Vem em texto porque a operadora às vezes manda fracionado (1,5) e arredondar aqui mudaria o valor da conta.
valoresobjetoAusência é null, nunca "0.00": zero é valor que a operadora declarou.
informadotextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
processadotextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
liberadotextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
glosatextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
glosaslista de objetosAs glosas deste item — o nivel em que o recurso e montado, porque no TISS ele e item a item.
codigotextoCodigo da glosa na tabela 38 do TISS, como o documento o trouxe.
descricaotextoO significado do codigo. Preenchido da tabela 38 quando o documento manda so o codigo.
valortextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
liquidacaoobjetoO acerto financeiro do documento. AUSENTE em documento de analise: analise nao fecha pagamento, e um bloco vazio ali diria "sem imposto" onde o certo e "este documento nao trata disso".
totalDebitostextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
totalCreditostextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
lancamentoslista de objetosLinha a linha do que foi descontado e somado ao credito.
naturezatexto
um de: DEBITO, CREDITO
Nulo quando o documento manda um indicador fora de 1 (debito) e 2 (credito): chamar credito o que e debito inverteria o sinal do dinheiro.
tipotextoO codigo do tipo de debito ou credito, como a operadora o declara.
descricaotextoO texto do lancamento (ex. "IRPJ Prod Medica").
valortextoDecimal em string. null = a fonte não informou; "0.00" = informou zero. Os dois são diferentes.
avisoslista de textoVazio quando a leitura saiu limpa. Arquivo que nao produziu demonstrativo nenhum devolve demonstrativos: [] COM aviso — nunca 204, que o integrador leria como sucesso silencioso.

Exemplo de retorno

{
  "data": {
    "arquivo": {
      "nome": "demonstrativo-pagamento-202609.xml",
      "formato": "XML",
      "bytes": 184320
    },
    "demonstrativos": [
      {
        "tipo": "PAGAMENTO",
        "numeroDemonstrativo": "000000187",
        "protocolo": "PROTO-18700001",
        "competencia": "2026-09",
        "operadora": "UNIMED REGIONAL",
        "emitidoEm": "2026-10-05",
        "creditoEm": "2026-10-10",
        "valores": {
          "informado": "1200.00",
          "processado": "1200.00",
          "liberado": "1050.00",
          "glosa": "150.00"
        },
        "valorPago": "1050.00",
        "guias": [
          {
            "numeroGuiaPrestador": "88120",
            "numeroGuiaOperadora": "2026000188120",
            "senha": null,
            "beneficiario": "BENEFICIARIO DE EXEMPLO",
            "carteira": "00000000000000000",
            "atendimentoEm": "2026-09-18",
            "valores": {
              "informado": "1200.00",
              "processado": "1200.00",
              "liberado": "1050.00",
              "glosa": "150.00"
            },
            "glosas": [],
            "itens": [
              {
                "tipo": "PROCEDIMENTO",
                "sequencial": "1",
                "codigoProcedimento": "40304361",
                "codigoDespesa": null,
                "descricao": "Hemograma com contagem de plaquetas",
                "quantidade": "1",
                "valores": {
                  "informado": "150.00",
                  "processado": "150.00",
                  "liberado": "0.00",
                  "glosa": "150.00"
                },
                "glosas": [
                  {
                    "codigo": "1308",
                    "descricao": "Procedimento nao consta no rol contratado",
                    "valor": "150.00"
                  }
                ]
              }
            ]
          }
        ],
        "liquidacao": {
          "totalDebitos": "48.30",
          "totalCreditos": "0.00",
          "lancamentos": [
            {
              "natureza": "DEBITO",
              "tipo": "1",
              "descricao": "IRPJ Prod Medica",
              "valor": "15.75"
            },
            {
              "natureza": "DEBITO",
              "tipo": "3",
              "descricao": "ISS",
              "valor": "32.55"
            }
          ]
        }
      }
    ],
    "avisos": []
  }
}

Experimente sem chave

O sandbox devolve este mesmo corpo, sem autenticação e sem tocar na base de ninguém.

curl https://api.miydas.com.br/v1/sandbox/demonstrativos_leituras

O sandbox responde sempre em GET, mesmo para uma operação POST: ele devolve a forma da resposta, não executa nada.

A chave de teste myd_test_… é outra coisa: ela opera na homologação da operadora e serve para escrever. Para ver o formato antes de ter credencial, convênio e varredura, é este sandbox.

Erros

CódigoHTTPQuandoO que fazer
ARQUIVO_AUSENTE400A leitura foi pedida sem arquivo, com mais de um arquivo, ou com o arquivo em outro campo.Envie multipart/form-data com um arquivo só, no campo arquivo.
ARQUIVO_GRANDE413O arquivo passa do teto de leitura. details.limiteMb diz qual é.Se for um ZIP com muitos documentos, divida-o e leia em partes.
FORMATO_NAO_LIDO415A extensão está fora da leitura estruturada (hoje .xml e .zip). PDF, imagem e planilha não viram dado.Recusado de propósito, em vez de devolver lista vazia: use o arquivo XML que a operadora disponibiliza.

Toda falha tem o mesmo formato: { "error": "CODIGO", "message": "…", "details": { … } }. error é estável e serve para lógica; message é para gente e pode mudar. Erros comuns a toda rota com chave (lista completa) não se repetem aqui.