Ogmma Revenue

API pública · v1

API do Miydas

Elegibilidade, autorização, faturamento e retornos com operadoras de saúde, num contrato só. Como o Miydas fala com cada operadora — webservice, portal ou arquivo — é problema nosso: a chamada e a resposta são as mesmas em todas.

Coleção importável: miydas.postman_collection.json — 78 requisições, agrupadas na ordem do ciclo. Importa no Postman, Insomnia, Bruno, Hoppscotch e Thunder Client. Ponha a sua chave na variável apiKey; ela não vem dentro do arquivo, de propósito.

Esta página é gerada da própria API. Especificação OpenAPI: https://api.miydas.com.br/v1/openapi.json

Começar

Base: https://api.miydas.com.br/v1. Chave: cada clínica emite a sua para o produto, no Miydas; envie em Authorization: Bearer myd_live_…. A chave carrega a empresa — não há parâmetro de clínica.

Testar sem pedido real. A clínica também pode emitir uma chave de teste, myd_test_…, na mesma URL: ela opera só na homologação da operadora, e o que cria vem com teste: true e só aparece para chaves de teste. Operadora sem homologação configurada responde AMBIENTE_TESTE_INDISPONIVEL.

Recursos, não chamadas. O POST de elegibilidade ou autorização cria o recurso e responde 202 com ele; processamento.status diz o andamento com a operadora (PENDENTE, PROCESSANDO, CONCLUIDO, FALHOU). Com Prefer: wait=20 a resposta espera até 20 s e vem 200 se a operadora responder a tempo. Depois disso, leia o recurso ou assine eventos.

Repetir sem duplicar. Escritas aceitam Idempotency-Key: a mesma chave com o mesmo corpo, em 24 h, devolve o mesmo recurso sem novo pedido à operadora.

Onde está o detalhe de cada rota. Cada operação tem página própria em /docs/api/{operacao}, com os parâmetros do pedido, os campos da resposta — o que cada um é, não só de que tipo —, exemplo de chamada, exemplo de retorno e os erros dela. A lista está em Referência.

Um formato de erro. Toda falha vem como { "error": "CODIGO", "message": "…", "details": { … } }. error é estável e serve para lógica; message é para gente e pode mudar. Campo desconhecido no corpo é recusado, não ignorado.

Sandbox — experimente antes de ter chave

Toda operação que devolve JSON responde também em https://api.miydas.com.br/v1/sandbox/{id}, sem autenticação. O corpo é o mesmo que a operação real devolve — o exemplo sai deste catálogo, e um teste na API o amarra ao mapper de verdade, então ele não envelhece em relação ao contrato.

Experimente agora

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

A lista do que dá para experimentar, com a URL de cada operação, está em https://api.miydas.com.br/v1/sandbox. A resposta vem com o cabeçalho Miydas-Sandbox: true.

Não confunda com a chave de teste. A chave myd_test_… opera na homologação da operadora e serve para quem vai escrever — pedir autorização, mandar lote. Para quem vai ler ela não ajuda: a empresa de teste não tem demonstrativo nenhum, e a resposta é uma lista vazia. O sandbox existe justamente para você ver o formato antes de ter credencial de operadora, convênio configurado e varredura rodada.

Nenhum dado de empresa passa pelo sandbox: ele devolve o exemplo documentado, não a base de ninguém.

Operadoras suportadas

A lista não é mantida à mão, e por isso dá para confiar nela. Ela é gerada do registro de conectores: cada conector declara o que faz, o que não faz e por quê — e "rodou em produção" fica verde sozinho quando a operação executa com sucesso. Motivo vazio não passa no CI.

Matriz de operadoras e operações → Operação na linha, operadora na coluna, sem chave nenhuma — o corte para decidir se dá para integrar um fluxo. A matriz por canal mostra a mesma coisa webservice por webservice e robô por robô, com as notas de cada operadora.

Pela API, com a sua chave, são três leituras:

  • GET /v1/conectores/matriz — a matriz inteira: o que cada operadora faz, não faz e por quê.
  • GET /v1/operadoras/{registroANS}/capacidades — as operações de uma operadora só.
  • GET /v1/operadoras/disponiveis — as que a clínica pode habilitar.

Consulte antes de integrar um fluxo. Operação que a operadora não oferece responde 409 OPERACAO_NAO_COBERTA, e repetir não muda a resposta. A matriz distingue três coisas que costumam ser confundidas: o que é tecnicamente possível, o que está homologado e o que já rodou em produção.

Jornada completa

A referência abaixo responde como chamo esta rota. Esta seção responde em que ordem — que é o que falta para faturar de verdade. Quem descobre a ordem por tentativa monta lote antes de ter autorização e perde o faturamento do mês.

  1. 1. Autenticar

    Toda chamada leva a chave da clínica. Ela carrega a empresa — não existe parâmetro de clínica.

    cURL

    curl https://api.miydas.com.br/v1/ \
      -H 'Authorization: Bearer myd_test_SUA_CHAVE'

    Comece com a chave de teste (myd_test_…): ela opera na homologação da operadora, e o que cria não se mistura com produção.

  2. 2. Ver o que a operadora faz

    Nem toda operadora oferece toda operação. A matriz diz o que cada uma faz, o que não faz e por quê.

    cURL

    curl https://api.miydas.com.br/v1/conectores/matriz \
      -H 'Authorization: Bearer myd_test_SUA_CHAVE'

    Operação que a operadora não oferece responde 409 OPERACAO_NAO_COBERTA. Não repita: a resposta não muda.

  3. 3. Configurar a conexão

    A credencial da clínica na operadora fica cifrada no Miydas. Ela nunca sai por nenhuma rota.

    cURL

    curl -X POST https://api.miydas.com.br/v1/conexoes \
      -H 'Authorization: Bearer myd_test_SUA_CHAVE' \
      -H 'content-type: application/json' \
      -d '{"registroANS":"334561","connectorId":"unimed-blumenau-soap"}'

    Com chave de teste, a conexão nasce em homologação. O escopo conexao:gerenciar é o mais sensível da API — quem o tem escreve o login da clínica na operadora.

  4. 4. Conferir elegibilidade

    Antes do atendimento: esta carteirinha vale hoje?

    cURL

    curl -X POST https://api.miydas.com.br/v1/elegibilidades \
      -H 'Authorization: Bearer myd_test_SUA_CHAVE' \
      -H 'content-type: application/json' \
      -H 'Prefer: wait=15' \
      -H 'X-Correlation-Id: pedido-8821' \
      -d '{"registroANS":"334561","carteira":"00000000000000000"}'

    Com Prefer: wait=N a resposta espera a operadora até N segundos e vem 200. Sem ele, vem 202 e o resultado chega por webhook. Na recepção, use wait.

  5. 5. Pedir autorização

    Quando o procedimento exige. Devolve senha e validade.

    cURL

    curl -X POST https://api.miydas.com.br/v1/autorizacoes \
      -H 'Authorization: Bearer myd_test_SUA_CHAVE' \
      -H 'content-type: application/json' \
      -H 'Idempotency-Key: 5f2c1a9e-...' \
      -d '{"registroANS":"334561","beneficiario":{"carteira":"000..."},"procedimentos":[{"tabela":"22","codigo":"40304361","quantidade":1}]}'

    PARCIAL é o caso que mais aparece: a operadora autoriza menos do que se pediu. Leia quantidadeAutorizada por procedimento, não só a situação da guia.

  6. 6. Montar o lote

    Você descreve o faturamento; o Miydas monta a mensagem TISS e valida no esquema oficial. NÃO transmite.

    cURL

    curl -X POST https://api.miydas.com.br/v1/lotes \
      -H 'Authorization: Bearer myd_test_SUA_CHAVE' \
      -H 'content-type: application/json' \
      -d '{"referenciaExterna":"fatura-2026-09-0042","operadora":"Unimed Blumenau","registroANS":"334561","competencia":"2026-09","prestador":{...},"guias":[{...}]}'

    Confira conformidade.xsdValido na resposta. Lote inválido é recusado na transmissão — a operadora recusaria de todo jeito. referenciaExterna é a sua chave de idempotência: repetir o POST devolve o mesmo lote.

  7. 7. Transmitir

    Agora sim o lote vai para a operadora, e volta com protocolo.

    cURL

    curl -X POST https://api.miydas.com.br/v1/lotes/LOTE_ID/envios \
      -H 'Authorization: Bearer myd_test_SUA_CHAVE'

    É idempotente por estado: lote já transmitido devolve o que tem, sem falar com a operadora. Repetir depois de um timeout SEU é seguro.

  8. 8. Quando a resposta não chega

    Se a transmissão sair e a confirmação se perder, o lote fica INDETERMINADO e o reenvio é bloqueado.

    cURL

    curl -X POST https://api.miydas.com.br/v1/lotes/LOTE_ID/resolucoes \
      -H 'Authorization: Bearer myd_test_SUA_CHAVE' \
      -H 'content-type: application/json' \
      -d '{"chegou":true,"protocolo":"PROTO-18700001","nota":"protocolo localizado no portal em 20/10"}'

    Este é o passo que separa cobrar uma vez de cobrar duas. O Miydas não consegue confirmar sozinho: sem protocolo não existe consulta de protocolo. Alguém precisa olhar o portal.

  9. 9. Acompanhar o protocolo

    Perguntar à operadora em que pé está o processamento do lote.

    cURL

    curl -X POST https://api.miydas.com.br/v1/lotes/consultas \
      -H 'Authorization: Bearer myd_test_SUA_CHAVE' \
      -H 'content-type: application/json' \
      -d '{"registroANS":"334561","protocolo":"PROTO-18700001"}'
  10. 10. Buscar retornos e glosas

    Os demonstrativos de análise e de pagamento da competência, já normalizados.

    cURL

    curl -X POST https://api.miydas.com.br/v1/retornos/sincronizacoes \
      -H 'Authorization: Bearer myd_test_SUA_CHAVE' \
      -H 'content-type: application/json' \
      -d '{"registroANS":"334561","de":"2026-09-01","ate":"2026-09-30"}'

    O Miydas lê PDF, XLS, CSV, JSON de portal e XML TISS, e acomoda tudo no mesmo recurso. O arquivo original fica como comprovante.

Referência

78 operações em 12 famílias. Cada uma tem página própria, com os parâmetros do pedido, os campos da resposta, exemplo de chamada, exemplo de retorno e os erros que ela pode devolver.

O que cada objeto de resposta carrega, campo a campo, fica em Objetos.

Eventos

EventoQuandoEscopo para receber
autorizacao.atualizadaA autorização mudou: a operadora respondeu o pedido, uma consulta trouxe situação ou senha novas (inclusive as que o Miydas faz sozinho enquanto a guia está pendente — a cada 30 min a 6 h, por até 30 dias, nas operadoras que oferecem consulta de situação), ou a guia foi cancelada. Também sai quando uma operação pedida pela API sobre a autorização falha de vez.autorizacao:ler
elegibilidade.concluidaA operadora respondeu a elegibilidade.elegibilidade:ler
elegibilidade.falhouA operadora não respondeu a elegibilidade depois das tentativas.elegibilidade:ler
teste.pingEnviado sob demanda por POST /v1/assinaturas/{id}/teste, para conferir URL e assinatura.—

Recebendo eventos

Cada evento chega num POST à URL da assinatura. O corpo não leva nome de paciente: tipo, id, situação e onde consultar o recurso completo. Responda 2xx em até 15 s. Outra resposta é tentada de novo em 1, 5, 15, 60, 120 min; depois disso, a entrega fica como falha em /v1/assinaturas/{id}/entregas.

  • miydas-evento — Nome do evento
  • miydas-entrega — Id da entrega — o mesmo em cada nova tentativa; use para não processar duas vezes
  • miydas-timestamp — Milissegundos desde 1970, no momento do envio
  • miydas-assinatura — HMAC-SHA256 (hex) de ${timestamp}.${corpo} com o segredo da assinatura

Corpo

{
  "evento": "autorizacao.atualizada",
  "ocorridoEm": "2026-09-27T13:02:14.000Z",
  "recurso": {
    "tipo": "Autorizacao",
    "id": "cmf3k2x9a0001aut",
    "situacao": "AUTORIZADA",
    "senha": "18700001",
    "validadeSenha": "2026-10-27",
    "numeroGuiaPrestador": "000123"
  },
  "consultarEm": "/v1/autorizacoes/cmf3k2x9a0001aut",
  "entrega": "cmf3k2x9a0004ent"
}

Conferindo a assinatura (Node)

import { createHmac, timingSafeEqual } from 'node:crypto';

// corpo: o texto CRU recebido, antes de qualquer JSON.parse
function assinaturaValida(corpo, cabecalhos, segredo) {
  const ts = cabecalhos['miydas-timestamp'];
  if (Math.abs(Date.now() - Number(ts)) > 5 * 60_000) return false; // replay
  const esperada = createHmac('sha256', segredo).update(`${ts}.${corpo}`).digest('hex');
  const recebida = cabecalhos['miydas-assinatura'] ?? '';
  return esperada.length === recebida.length &&
    timingSafeEqual(Buffer.from(esperada), Buffer.from(recebida));
}

Erros

Os erros sem HTTP não são resposta de pedido: aparecem em processamento.erro quando a operação foi aceita e falhou depois.

CódigoHTTPQuandoO que fazer
CHAVE_AUSENTE401O pedido veio sem Authorization: Bearer … nem X-API-Key.Envie a chave.
CHAVE_INVALIDA401Chave desconhecida, revogada, expirada, ou de produto revogado.Peça uma chave nova a quem administra a clínica no Miydas.
ESCOPO_INSUFICIENTE403A chave não tem o escopo da rota. details.faltando diz qual.Peça o escopo na concessão; não repita o pedido.
VALIDATION_ERROR400O pedido não segue o formato (corpo, filtro ou cabeçalho). details.campos traz cada campo e o motivo. Campo desconhecido também é recusado.Corrija os campos apontados.
RECURSO_NAO_ENCONTRADO404O id não existe — ou é de outra empresa, o que a API não distingue de propósito. Também a rota inexistente na v1.Confira o id.
LOTE_JA_TRANSMITIDO409Já existe um lote com esta referenciaExterna e ele foi transmitido (ou está indeterminado). Lote transmitido é imutável.Para corrigir, crie um lote NOVO com outra referenciaExterna. details traz o protocolo e a data do original.
LOTE_VAZIO400O lote não tem nenhum procedimento.Inclua ao menos um procedimento em alguma guia.
LOTE_XSD_INVALIDO409A transmissão foi pedida para um lote que não passou no esquema oficial.Veja conformidade.erros no lote e crie um lote novo corrigido. A operadora recusaria.
LOTE_REGRA_DA_OPERADORA422O lote é válido no esquema oficial, mas viola uma regra MEDIDA desta operadora — ela o recusaria na importação. Recusado aqui, antes de transmitir, porque transmitir é irreversível e gasta um protocolo.Leia detalhes.violacoes: cada item traz o que corrigir e o código da crítica que a operadora devolveu quando isso passou. Corrija e repita o POST — nada foi transmitido.
LOTE_RECUSADO422A operadora respondeu recusando o lote, com código e descrição TISS. O lote NÃO entrou.Leia a mensagem, corrija o faturamento e crie um lote novo. Reenviar o mesmo terá o mesmo desfecho.
AMBIENTE_SEM_ENVIO409Uma chave de teste (myd_test_) pediu a transmissão de um lote. Chave de teste opera só na homologação da operadora, e a homologação ainda não é alcançável por esta rota.Monte e valide o lote com a chave de teste — isso não toca a operadora. Para transmitir, use uma chave de produção.
LOTE_TRANSMITINDO409A transmissão deste lote já está em curso no portal da operadora. Envio por portal é assíncrono, diferente do envio por webservice.Aguarde e consulte o lote — o desfecho chega sem nova ação. Não repita o pedido: abriria uma segunda transmissão da mesma guia.
LOTE_SEM_PROTOCOLO409Pediu-se o retorno de um lote que ainda não tem protocolo — ele foi montado, não transmitido.Transmita em POST /v1/lotes/{id}/envios: o protocolo é a chave com que a operadora identifica o lote do lado dela.
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.
LOTE_SEM_ANS400O lote não tem registro ANS, então não há como resolver a operadora.Informe registroANS ao criar o lote.
LOTE_INDETERMINADO409A transmissão deste lote começou e a resposta da operadora não chegou. Ela PODE ter recebido.NÃO reenvie. Confirme no portal da operadora se o lote entrou e registre o resultado em POST /v1/lotes/{id}/resolucoes. Reenviar sem confirmar cobra a mesma guia duas vezes.
LOTE_NAO_INDETERMINADO409Pediu-se resolução de um lote que não está indeterminado.Não há o que resolver; veja a situação atual do lote.
PROTOCOLO_OBRIGATORIO400Marcou-se chegou: true sem informar o protocolo.Informe o protocolo que a operadora deu — é por ele que status e demonstrativo são consultados depois.
CONECTOR_SEM_SUBMIT400O conector desta operadora não envia lote.Veja o que ela faz em GET /v1/operadoras/{registroANS}/capacidades.
OPERADORA_NAO_CONFIGURADA422A operadora do lote não tem conexão com credencial configurada.Configure a conexão em POST /v1/conexoes e grave a credencial.
OPERADORA_NAO_ENCONTRADA404A empresa não tem essa operadora (registro ANS) cadastrada.Veja as operadoras em GET /v1/operadoras.
OPERACAO_NAO_COBERTA422A operadora não oferece esta operação. details.operacoesDisponiveis lista o que ela oferece.Não repita: a resposta não muda.
CREDENCIAL_AUSENTE422A empresa não cadastrou a credencial desta operadora.Cadastre a credencial no Miydas e repita.
CBO_OBRIGATORIO422O canal que atende esta operadora exige o CBO-S do profissional solicitante e o pedido veio sem profissionalSolicitante.cbo. Nem toda operadora exige: GET /v1/capacidades diz quais, em pedidoExige.Mande o CBO-S de seis dígitos do solicitante. Ele também é necessário no faturamento, então vale guardá-lo no cadastro do médico.
REFAZ_ITEM_INVALIDO422Algum procedimentos[].refazItem não aponta para um procedimento desta empresa, ou aponta para o outro ambiente — a chave de teste não enxerga o que é de produção, e o contrário.Use o id que veio em procedimentos[].id da autorização anterior. Na primeira tentativa, omita o campo.
GUIA_JA_ENVIADA409A guia já saiu para a operadora. O TISS proíbe repetir o numeroGuiaPrestador, inclusive depois de negativa — reenviar a mesma guia é recusado pela própria operadora (glosa 1601).Para pedir de novo, refaça: uma guia nova, com número novo, já preenchida com o que havia. A antiga fica no histórico com o motivo.
EXAME_AUTORIZADO_REMOVIDO422A execução declarada deixou de fora um exame que a operadora autorizou. details.itens diz quais.Mande o item com quantidade: 0 em vez de omiti-lo. Zero diz "não executei" sem apagar o lastro do que foi autorizado — e é por esse lastro que o faturamento se defende de glosa depois.
ITEM_DE_OUTRA_GUIA422A execução declarou um id de item que não pertence a esta guia.Use os id que vêm em procedimentos desta guia, ou omita o id para acrescentar um exame novo.
GUIA_COM_DESFECHO409A guia já tem desfecho da operadora — autorizada, autorizada em parte ou cancelada — e por isso não se corrige mais: o documento passou a ser dela, e mudar só o nosso lado faria os dois discordarem sobre a mesma guia.Cancele na operadora e peça uma guia nova com o que precisa mudar. Guia ainda não autorizada continua corrigível por PATCH /autorizacoes/{id}.
SOLICITANTE_INVALIDO422A correção deixaria o profissional solicitante num estado que a operadora recusa: conselho fora de dm_conselhoProfissional, UF inexistente, CBO fora de seis dígitos ou número em branco. details.erros traz cada problema em uma frase.Corrija o que a mensagem aponta. Recusar aqui é de propósito: passando, o erro só apareceria no envio, como TISS_CONSELHO_INVALIDO, depois de a guia ir à fila e voltar.
ENVIO_EM_ANDAMENTO409Já existe um envio desta guia em voo. A trava é a troca de situação, feita em condição: dois envios simultâneos mandariam dois pedidos reais da mesma guia à operadora.Espere o desfecho do envio corrente — ele responde pelo mesmo recurso. Guia presa porque o worker caiu é destravada sozinha no envio seguinte.
LIMITE_DE_PROCEDIMENTOS422A operadora aceita menos procedimentos por pedido do que os enviados (o padrão TISS não limita; algumas operadoras sim). details.maximo diz quantos.Divida em mais de um pedido.
AMBIENTE_TESTE_INDISPONIVEL422A chave é de teste (myd_test_…) e o pedido não cabe na homologação: a empresa não tem homologação configurada para esta operadora; ou a operação grava dado de produção (lote, retorno, recurso de glosa, cancelamento por número, anexos, documentos, cadastro de convênio); ou tenta trocar o endereço, o conector ou a agenda da conexão de homologação. A chave de teste nunca opera em produção.Configure a homologação da operadora no Miydas; para autorização e elegibilidade use /v1/autorizacoes e /v1/elegibilidades; o resto, com a chave de produção.
GUIA_JA_SOLICITADA409O numeroGuiaPrestador já foi usado nesta operadora, no mesmo ambiente (teste ou produção) — o padrão TISS proíbe repetir. details.autorizacaoId aponta a autorização existente, quando ela é conhecida.Use outro número; para saber do anterior, consulte a autorização apontada.
IDEMPOTENCIA_CONFLITO422A mesma Idempotency-Key veio com um pedido diferente.Use uma chave nova para um pedido novo.
IDEMPOTENCIA_EM_ANDAMENTO409Um pedido com esta Idempotency-Key ainda está sendo criado.Repita em instantes com a mesma chave: vem a mesma resposta.
LIMITE_EXCEDIDO429Muitas operações em andamento para esta operadora nesta empresa.Espere e repita — com a mesma Idempotency-Key, se for escrita.
CANCELAMENTO_IMPOSSIVEL422A autorização não tem número de guia com que a operadora a identifique.Não há o que cancelar por aqui.
EXECUCAO_SEM_AUTORIZACAO422A guia ainda não foi liberada pela operadora (EM_ANALISE, NEGADA, CANCELADA ou sem desfecho). Nada foi enviado.Consulte a situação e execute depois que ela estiver AUTORIZADA ou PARCIALMENTE_AUTORIZADA.
EXECUCAO_SEM_GUIA_DA_OPERADORA422A autorização não tem numeroGuiaOperadora, que é o número pelo qual a operadora identifica o que executar.Consulte a autorização primeiro: a operadora devolve o número dela junto do desfecho.
EXECUCAO_SEM_PROCEDIMENTO422A autorização não tem procedimento com código para executar.Não há o que executar por aqui.
DESTINO_NAO_PERMITIDO400A URL da assinatura não resolve para um endereço público.Use uma URL https pública.
OPERADORA_INDISPONIVEL—A operadora não respondeu, ou respondeu fora do padrão.Se podeRepetir for true, repita depois. Se for false (escrita), consulte antes de repetir — o pedido pode ter chegado.
PEDIDO_RECUSADO—A operadora recusou o pedido antes de analisar (ex.: código de procedimento que ela não aceita). A mensagem traz o motivo dela.Corrija o pedido conforme o motivo e peça de novo — nada foi autorizado.
PEDIDO_INCOMPLETO—Falta um dado que esta operadora exige (ex.: indicação clínica na Bradesco). Nada foi enviado.Complete o pedido e repita.
OPERADORA_OCUPADA—O acesso da empresa à operadora estava em uso por outra pessoa no momento. Nada foi enviado.Repita em alguns minutos.
CONEXAO_INCOMPLETA—Falta um dado obrigatório na conexão da empresa com a operadora (ex.: nome do contratado). Nada foi enviado à operadora.Complete a conexão no Miydas e repita — a mensagem diz o que falta.
CREDENCIAL_RECUSADA—A operadora recusou a credencial cadastrada.Atualize a credencial no Miydas.
DADOS_RECUSADOS—A operadora — ou a validação do Miydas antes do envio — recusou os dados do pedido. message diz qual dado quando isso se sabe: o conselho do profissional, o registro ANS na credencial da operadora, procedimentos acima do limite, o cadastro do prestador na operadora (a conexão sem o nome do contratado sai como CONEXAO_INCOMPLETA). Recusado antes do envio, nada chegou à operadora e podeRepetir é true; recusado pela operadora numa escrita, podeRepetir é false, como em toda escrita que chegou lá.Corrija o dado apontado — no pedido ou na credencial da operadora no Miydas — e faça um pedido novo: repetir igual dá a mesma recusa. Solicitação de autorização que não chegou à operadora (a mensagem diz) pode ser refeita com o mesmo numeroGuiaPrestador.
ERRO_INTERNO500Falha do Miydas.Reporte com o horário e o id do recurso.

Glossário do contrato

O que cada palavra significa nesta API: qual campo carrega cada valor e onde a leitura ingênua do contrato leva a integração para o buraco. Quem não distingue reconhecido de liberado constrói a tela financeira errada e descobre em produção.

O vocabulário do domínio — RCM, TISS, tipos de glosa, prazos regulatórios — fica no Glossário de domínio (RCM, TISS, tipos de glosa, prazos). Não repetimos aqui para não ter duas definições da mesma palavra.

Cobrado
O valor que foi informado à operadora no envio do lote.
Cuidado: É o que NÓS mandamos. Quando o lote de envio não é conhecido, o Miydas usa a maior declaração da operadora — e diz de onde veio.
Reconhecido
O valor que a operadora processou e aceitou como devido.
Cuidado: Reconhecido não é pago. Entre um e outro ainda cabe glosa.
Liberado
O valor aprovado para pagamento pela operadora.
Cuidado: Liberado zero DECLARADO é resposta ("não pagamos nada"), diferente de campo ausente ("não disseram"). O Miydas trata os dois como coisas distintas.
Glosado
O valor recusado pela operadora, com motivo e código da Tabela 38.
Cuidado: Cada operadora declara a glosa em um ponto diferente da cadeia. O Miydas devolve a perda medida (cobrado − liberado) e também a declarada — a diferença entre as duas é glosa silenciosa.
Pago
O valor efetivamente creditado, conforme o demonstrativo de pagamento.
Glosa silenciosa
Pagamento a menor SEM glosa declarada. No contrato, é a diferença entre a perda medida (cobrado − liberado) e o valor que a operadora declarou ter cortado.
Cuidado: É invisível em qualquer relatório que só some o campo de glosa da operadora. Por isso devolvemos os dois.
processamento.status
Estado TÉCNICO: a plataforma terminou de falar com a operadora? PENDENTE, EXECUTANDO, AGUARDANDO_ACAO, CONCLUIDO, FALHOU.
Cuidado: Não confunda com o estado de NEGÓCIO. Uma autorização pode ter processamento CONCLUIDO e situacao NEGADA: sucesso técnico, negativa de negócio.
situacao
Estado de NEGÓCIO do recurso: o que a operadora decidiu. AUTORIZADA, NEGADA, PARCIAL; no lote, PRONTO, TRANSMITIDO, RECUSADO, INDETERMINADO.
referenciaExterna
O id do recurso no SEU sistema. Opcional na maioria das rotas, obrigatório no lote — onde é também a chave de idempotência.
Cuidado: Use-a e você reencontra aqui o que criou sem guardar os nossos ids.
Prefer: wait=N
Pede que a resposta espere a operadora até N segundos. Cabendo no prazo, vem 200 com o resultado; senão, 202 e o resultado chega por webhook.
Cuidado: Na recepção, com o paciente na frente, use wait. Em processamento em lote, não use.
AGUARDANDO_ACAO
A execução parou e NÃO sai sozinha: depende de alguém agir (no portal da operadora, em geral).
Cuidado: Quem faz polling precisa tratar este estado: esperar mais não resolve.
Competência
Mês de referência do faturamento, no formato YYYY-MM.
Cuidado: A regra de qual mês uma guia pertence varia por operadora. Não presuma que é o mês da execução.
Protocolo
O comprovante de que a operadora recebeu o lote. É por ele que se consulta o andamento depois.
Elegibilidade
A resposta a "esta carteirinha vale hoje, para este atendimento?".
Autorização
A liberação, pela operadora, de UM procedimento específico — com senha e validade.
Cuidado: Autorização negada é sucesso técnico e negativa de negócio: processamento CONCLUIDO com situacao NEGADA. Não trate como erro.
Indeterminado
Um lote foi transmitido e a resposta da operadora não chegou. Ela pode ter recebido.
Cuidado: É o estado mais importante desta lista. NÃO reenvie: confirme no portal e registre em POST /v1/lotes/{id}/resolucoes. Reenviar cobra a mesma guia duas vezes.

Changelog

Campo novo em resposta e rota nova são compatíveis e entram sem aviso — mas sem aviso não significa sem registro. Quebra incompatível não aparece aqui: ela vira /v2.

2026-10-25

  • melhoriaCada rota ganhou página própria em /docs/api/{operacao}, com os parâmetros do pedido, os campos da resposta, exemplo de chamada, exemplo de retorno e os erros dela. O {operacao} da URL é o mesmo id do sandbox.
  • melhoriaTodo campo do contrato agora diz o que é, e não só de que tipo é — 979 campos, dos quais 758 não tinham definição nenhuma. Vale para o openapi.json e para GET /v1/catalogo, não só para a página.
  • novoO envelope das listas virou objeto documentado (Paginacao): total, limite, deslocamento e temMais. Ele já saía em quinze rotas e não estava em schema nenhum.
  • novoOs parâmetros de caminho ({id}, {carteira}, {registroANS}…) passam a vir declarados no catálogo, com definição — antes a documentação mostrava /v1/guias/{id} sem dizer qual id.

2026-10-20

  • novoFaturamento na API: POST /v1/lotes monta a mensagem TISS e valida no esquema oficial sem transmitir; POST /v1/lotes/{id}/envios transmite e devolve o protocolo. Escopo novo lote:gerenciar, separado de lote:enviar.
  • novoEstado INDETERMINADO para lote transmitido sem confirmação, com o reenvio bloqueado e POST /v1/lotes/{id}/resolucoes para registrar o que foi apurado no portal.
  • melhoriaPOST /v1/lotes/{id}/envios é idempotente por estado: lote já transmitido devolve o que tem, sem falar com a operadora de novo.
  • melhoriaX-Request-Id e X-Correlation-Id são aceitos e devolvidos em toda chamada. Mande o seu e reencontre, nos nossos registros, tudo o que aquele fluxo produziu.
  • atençãoA operação POST /v1/lotes que criava execução com conteúdo vazio (declarada PARCIAL) foi substituída pelo recurso de lote. Ela não transmitia nada de útil; quem a chamava precisa passar a montar o lote pelo contrato novo.

Escopos

A chave só alcança o que os escopos concedidos permitem. Quem concede é a clínica.

elegibilidade:executar
Consultar elegibilidade de beneficiário
elegibilidade:ler
Ler elegibilidades já feitas
autorizacao:executar
Solicitar autorização de procedimento
autorizacao:ler
Consultar situação de autorização
guia:cancelar
Cancelar guia ou lote
lote:gerenciar
Montar lotes de faturamento — sem transmitir
lote:ler
Ver lotes de faturamento e a situação de protocolos
lote:enviar
Enviar lote de faturamento
retorno:ler
Buscar demonstrativos e retornos
webhook:gerenciar
Assinar eventos (webhooks)
retencao:ler
Ver imposto retido pela operadora — ISS, PIS, INSS, COFINS
glosa:ler
Ver glosas com o significado oficial da ANS, resumo e motivos
beneficiario:ler
Ver o histórico de uma carteirinha — guias, glosas, elegibilidades e autorizações. Expõe dado de paciente identificado: conceder é decisão, não padrão
operadora:ler
Ver operadoras atendidas, conectores e capacidades
faturavel:registrar
Mandar ao Miydas os exames realizados, para conferir antes de faturar
faturavel:ler
Ver o que o laboratório realizou e ainda não cobrou
execucao:ler
Acompanhar execuções e seus resultados
guia:ler
Ver a guia pelas três camadas — envio, análise e pagamento — e a procedência de cada número
utilizacao:ler
Consultar histórico de atendimentos do beneficiário — inclui atendimentos feitos em outros prestadores da operadora
recurso:enviar
Enviar recurso contra glosas
recurso:ler
Consultar situação de recurso de glosa
anexo:enviar
Enviar anexos
documento:enviar
Enviar laudo, pedido ou comprovante
comunicacao:enviar
Comunicar internação ou alta
credencial:verificar
Testar credenciais de uma conexão