Faturamento
/v1/lotes/{id}/retornosBusca na operadora o retorno deste lote
O recorte por lote da varredura: em vez de varrer um período e filtrar do lado de fora, pergunta à operadora o que ela respondeu sobre ESTE protocolo. Responde 202 e nunca 200 — a busca leva segundos a minutos no portal da operadora, e o retorno normalizado sai em GET /v1/execucoes/{id}/retornos. Traz o demonstrativo de ANÁLISE. O de PAGAMENTO é indexado por data de crédito, não por protocolo: a operadora não sabe responder "o pagamento do lote X" — para ele, use POST /v1/retornos/sincronizacoes.
- Escopo:
- retorno:ler
- Resposta:
- 202
Pedido
Caminho
| {id}* | Identificador do recurso no Miydas. Opaco e estável — NÃO é o número que a operadora ou o seu sistema usam para a mesma coisa. Guarde-o como veio e não derive significado do formato. |
Exemplo de chamada
curl -X POST https://api.miydas.com.br/v1/lotes/cmf3k2x9a0001aut/retornos \
-H "Authorization: Bearer $MIYDAS_CHAVE"Resposta 202
| data | Aceita | O recurso. Os campos estão na tabela abaixo. |
Exemplo de retorno
{
"data": {
"execucaoId": "exec_cmf3k2x9a0001",
"status": "PENDENTE",
"operacao": "FETCH_RETURNS",
"operadora": {
"registroANS": "334561"
},
"lote": {
"id": "lote_cmf3k2x9a0001",
"protocolo": "PROTO-18700001",
"competencia": "2026-09"
},
"consultarEm": "/v1/execucoes/exec_cmf3k2x9a0001/retornos",
"ressalva": "Traz o demonstrativo de ANALISE do protocolo. O de PAGAMENTO e indexado por data de credito: busque-o em POST /v1/retornos/sincronizacoes."
}
}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/lotes_retornosO 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ódigo | HTTP | Quando | O que fazer |
|---|---|---|---|
| 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_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. |
| 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. |
| 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. |
| 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. |
| LIMITE_EXCEDIDO | 429 | Muitas operações em andamento para esta operadora nesta empresa. | Espere e repita — com a mesma Idempotency-Key, se for escrita. |
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.