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_listarA 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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.
Elegibilidade
Autorização
- POST
/v1/autorizacoesSolicita autorização de procedimentos (guia SP/SADT) - GET
/v1/autorizacoesAutorizações — filtre por situação, carteira ou senhas que vencem - POST
/v1/autorizacoes/consultasTraz uma guia pedida fora do Miydas e consulta a situação - GET
/v1/autorizacoes/{id}Uma autorização, com o histórico - POST
/v1/autorizacoes/{id}/consultasPergunta à operadora a situação atual - POST
/v1/autorizacoes/{id}/envioTransmite uma guia que já existe e ainda não saiu - PATCH
/v1/autorizacoes/{id}Corrige a guia que ainda não foi autorizada - POST
/v1/autorizacoes/{id}/cancelamentoCancela a guia na operadora - GET
/v1/autorizacoes/{id}/guia.pdfA guia de SP/SADT em PDF, para imprimir - PUT
/v1/autorizacoes/{id}/executadosGrava o que foi executado, sem falar com a operadora - POST
/v1/autorizacoes/{id}/execucaoRegistra na operadora que o exame foi feito
Faturamento
- POST
/v1/lotesMonta o lote: gera a mensagem TISS e valida no esquema oficial. NÃO transmite - GET
/v1/lotesLotes da clínica, por operadora, período, protocolo e situação - GET
/v1/lotes/{id}Um lote: se chegou à operadora, e o que ela fez com ele - POST
/v1/lotes/{id}/enviosTransmite o lote à operadora e registra o protocolo - POST
/v1/lotes/{id}/retornosBusca na operadora o retorno deste lote - POST
/v1/lotes/{id}/resolucoesRegistra o que foi apurado na operadora sobre um lote indeterminado - POST
/v1/itens-faturaveisManda os exames realizados, para conferir antes de faturar - GET
/v1/itens-faturaveisO que foi realizado e ainda não foi cobrado - GET
/v1/lotes-importadosOs lotes que o prestador importou — a camada de envio - GET
/v1/lotes-importados/{id}/guiasAs guias do lote, com os itens de cada uma - GET
/v1/lotes/{id}/mensagemA mensagem TISS que foi transmitida, em bytes - POST
/v1/lotes/consultasConsulta a situação de um protocolo de lote - POST
/v1/anexosEnvia lote de anexos (situação inicial, radio, quimio, OPME)
Demonstrativos
- POST
/v1/demonstrativos/leiturasLê um arquivo TISS e devolve o demonstrativo - GET
/v1/demonstrativosO retorno da operadora como acervo — análise de conta e pagamento - GET
/v1/demonstrativos/{id}O documento inteiro: protocolos, guias, glosas e liquidação - GET
/v1/demonstrativos/{id}/arquivos/{arquivoId}O documento original, em bytes - GET
/v1/demonstrativos/{id}/itensO que a operadora declarou item a item, com o motivo da recusa junto - GET
/v1/retornos-sem-vinculoO julgamento da operadora que não casou com guia nenhuma - GET
/v1/retornos-sem-vinculo/resumoQuanto está solto, e onde - POST
/v1/retornos/sincronizacoesBusca demonstrativos e retornos de um período
Eventos
- GET
/v1/eventosOs eventos que podem ser assinados - POST
/v1/assinaturasAssina eventos numa URL. Devolve o segredo de assinatura UMA vez - GET
/v1/assinaturasAssinaturas ativas desta chave - GET
/v1/assinaturas/{id}Uma assinatura - DELETE
/v1/assinaturas/{id}Remove a assinatura (o histórico de entregas fica) - POST
/v1/assinaturas/{id}/segredoTroca o segredo de assinatura - GET
/v1/assinaturas/{id}/entregasAs últimas 50 entregas, com o que o destino respondeu - POST
/v1/assinaturas/{id}/testeManda umteste.pingagora e diz o que o destino respondeu
| Evento | Quando | Escopo para receber |
|---|---|---|
| autorizacao.atualizada | A 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.concluida | A operadora respondeu a elegibilidade. | elegibilidade:ler |
| elegibilidade.falhou | A operadora não respondeu a elegibilidade depois das tentativas. | elegibilidade:ler |
| teste.ping | Enviado sob demanda por POST /v1/assinaturas/{id}/teste, para conferir URL e assinatura. | — |
Retenções
Glosas
- GET
/v1/glosasGlosas com o significado oficial da Tabela 38 da ANS - GET
/v1/glosas/resumoO retrato agregado: quanto, em que nível, e quanto sem motivo - GET
/v1/glosas/motivosO catálogo do que esta clínica recebeu, traduzido e ordenado por valor - GET
/v1/glosas/silenciosasPago a menor sem glosa declarada - GET
/v1/glosas/{id}Uma glosa, com significado e evidência - POST
/v1/recursos-glosaEnvia recurso contra glosas - POST
/v1/recursos-glosa/consultasConsulta a situação de um recurso
Beneficiário
- GET
/v1/beneficiariosBusca por carteirinha ou nome - GET
/v1/beneficiarios/{carteira}O histórico de uma carteirinha - GET
/v1/beneficiarios/{carteira}/guiasToda guia da carteirinha, em toda competência - GET
/v1/beneficiarios/{carteira}/glosasO que foi cortado desta carteirinha, e por quê - GET
/v1/beneficiarios/{carteira}/elegibilidadesO histórico de consultas de elegibilidade - GET
/v1/beneficiarios/{carteira}/autorizacoesSenhas, validades e situações desta carteirinha - GET
/v1/beneficiarios/{carteira}/linha-do-tempoTudo da carteirinha em ordem, de trás para frente - POST
/v1/utilizacoesConsulta o histórico de atendimentos do beneficiário na operadora - POST
/v1/comunicacoes-beneficiarioComunica internação ou alta de beneficiário
Referências
- GET
/v1/operadoras/{registroANS}/codigosDe-para do código próprio da operadora para a TUSS - GET
/v1/operadoras/{registroANS}/documentosO que a operadora publica, e se conseguimos ler - GET
/v1/referencias/tussTerminologia TUSS — 54.497 termos, o vigente por padrão - GET
/v1/referencias/operadoras-ansOperadoras registradas na ANS — ache o registroANS pelo CNPJ - GET
/v1/referencias/cnesEstabelecimentos de saúde no CNES — 140.937 unidades
Recebimento
- GET
/v1/documentos-recebidosTudo que chegou — e o que não virou dado - GET
/v1/documentos-recebidos/resumoDe tudo que chegou, quanto virou dado - GET
/v1/documentos-recebidos/{id}Um documento recebido, com o motivo de ter parado - GET
/v1/execucoes/{id}/passosOnde o robô esteve e onde parou - POST
/v1/documentosEnvia laudo, pedido ou comprovante
Guias
- GET
/v1/guiasA guia pelas três camadas: envio, análise e pagamento - GET
/v1/guias/{id}Uma guia, com as três camadas e os cinco valores - GET
/v1/guias/{id}/procedenciaDe onde veio cada número desta guia - GET
/v1/guias/{id}/itensO item pelas três camadas, com o veredito da conciliação - POST
/v1/guias/cancelamentosCancela guia autorizada ou lote enviado
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 eventomiydas-entrega— Id da entrega — o mesmo em cada nova tentativa; use para não processar duas vezesmiydas-timestamp— Milissegundos desde 1970, no momento do enviomiydas-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ódigo | HTTP | Quando | O que fazer |
|---|---|---|---|
| CHAVE_AUSENTE | 401 | O pedido veio sem Authorization: Bearer … nem X-API-Key. | Envie a chave. |
| CHAVE_INVALIDA | 401 | Chave desconhecida, revogada, expirada, ou de produto revogado. | Peça uma chave nova a quem administra a clínica no Miydas. |
| ESCOPO_INSUFICIENTE | 403 | A 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_ERROR | 400 | O 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_ENCONTRADO | 404 | O 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_TRANSMITIDO | 409 | Já 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_VAZIO | 400 | O lote não tem nenhum procedimento. | Inclua ao menos um procedimento em alguma guia. |
| LOTE_XSD_INVALIDO | 409 | A 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_OPERADORA | 422 | O 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_RECUSADO | 422 | A 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_ENVIO | 409 | Uma 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_TRANSMITINDO | 409 | A 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_PROTOCOLO | 409 | Pediu-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_AUSENTE | 400 | A 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_GRANDE | 413 | O 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_LIDO | 415 | A 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_ANS | 400 | O lote não tem registro ANS, então não há como resolver a operadora. | Informe registroANS ao criar o lote. |
| LOTE_INDETERMINADO | 409 | A 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_INDETERMINADO | 409 | Pediu-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_OBRIGATORIO | 400 | Marcou-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_SUBMIT | 400 | O conector desta operadora não envia lote. | Veja o que ela faz em GET /v1/operadoras/{registroANS}/capacidades. |
| OPERADORA_NAO_CONFIGURADA | 422 | A 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_ENCONTRADA | 404 | A empresa não tem essa operadora (registro ANS) cadastrada. | Veja as operadoras em GET /v1/operadoras. |
| OPERACAO_NAO_COBERTA | 422 | A operadora não oferece esta operação. details.operacoesDisponiveis lista o que ela oferece. | Não repita: a resposta não muda. |
| CREDENCIAL_AUSENTE | 422 | A empresa não cadastrou a credencial desta operadora. | Cadastre a credencial no Miydas e repita. |
| CBO_OBRIGATORIO | 422 | O 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_INVALIDO | 422 | Algum 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_ENVIADA | 409 | A 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_REMOVIDO | 422 | A 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_GUIA | 422 | A 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_DESFECHO | 409 | A 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_INVALIDO | 422 | A 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_ANDAMENTO | 409 | Já 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_PROCEDIMENTOS | 422 | A 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_INDISPONIVEL | 422 | A 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_SOLICITADA | 409 | O 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_CONFLITO | 422 | A mesma Idempotency-Key veio com um pedido diferente. | Use uma chave nova para um pedido novo. |
| IDEMPOTENCIA_EM_ANDAMENTO | 409 | Um pedido com esta Idempotency-Key ainda está sendo criado. | Repita em instantes com a mesma chave: vem a mesma resposta. |
| LIMITE_EXCEDIDO | 429 | Muitas operações em andamento para esta operadora nesta empresa. | Espere e repita — com a mesma Idempotency-Key, se for escrita. |
| CANCELAMENTO_IMPOSSIVEL | 422 | A 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_AUTORIZACAO | 422 | A 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_OPERADORA | 422 | A 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_PROCEDIMENTO | 422 | A autorização não tem procedimento com código para executar. | Não há o que executar por aqui. |
| DESTINO_NAO_PERMITIDO | 400 | A 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_INTERNO | 500 | Falha 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