Gerar token JWT de acesso
/v1/auth/tokenPorta de entrada da API. Envie client_id e client_secret em JSON; a API troca no Keycloak (client_credentials) e devolve um token JWT (validade ~2h).
Formato: corpo application/json com client_id e client_secret. Use o access_token retornado como Authorization: Bearer <token> nas demais chamadas. Único endpoint que não exige token prévio.
No console desta página, cole somente o token no campo de autorização, sem escrever Bearer na frente: o prefixo já é adicionado.
Request Body
application/jsonrequired
Ver schema bruto / exemplo JSON
{
"client_id": "mds-client",
"client_secret": "<seu client_secret>"
}Responses
Token gerado com sucesso (resposta do Keycloak).
Ver schema bruto / exemplo JSON
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 7200
}Requisição malformada (campos obrigatórios ausentes/ inválidos).
Estrutura padronizada de erro.
Código HTTP do erro.
Código interno do erro.
Descrição legível do erro.
items
Crítica devolvida pela operadora. Em bloqueante: true rejeita (corrija e reenvie), false é aviso e a movimentação segue (ex. 2401), null a operadora não classificou.
client_id/client_secret inválidos. O corpo segue o schema Erro, com o motivo do provedor de identidade em codigo (ex. invalid_client).
Estrutura padronizada de erro.
Código HTTP do erro.
Código interno do erro.
Descrição legível do erro.
items
Crítica devolvida pela operadora. Em bloqueante: true rejeita (corrija e reenvie), false é aviso e a movimentação segue (ex. 2401), null a operadora não classificou.
Corpo da requisição acima do limite aceito pela fachada: 1 MB nas rotas de dados, 12 MB em POST /v1/faturas/interpretacoes, que recebe o PDF em base64.
Não há limite de ITENS no lote: o teto é de bytes, e existe para que um corpo gigante não derrube o processo. Lote grande que estoure o limite deve ser dividido em requisições; cada uma é independente na operadora.
Estrutura padronizada de erro.
Código HTTP do erro.
Código interno do erro.
Descrição legível do erro.
items
Crítica devolvida pela operadora. Em bloqueante: true rejeita (corrija e reenvie), false é aviso e a movimentação segue (ex. 2401), null a operadora não classificou.
Não foi possível concluir a operação junto à operadora.
Em consulta, sem repetir no corpo a falha pode ser transitória e nova tentativa é segura.
Em escrita (POST, PATCH, DELETE) o corpo traz repetir: false, e o desfecho é indeterminado: a operadora pode ter processado e só a resposta ter se perdido. Não reenvie. Se o corpo trouxer protocolo, consulte-o em GET /v1/movimentacoes/{protocolo}; se não, confira o beneficiário pelo CPF antes de tentar de novo.
Erro gerado pela própria API, antes ou depois de falar com a operadora. Formato distinto do Erro, que é usado quando o desfecho vem da operadora.
Motivo resumido.
Detalhe técnico, quando existe.
Quando false, não reenvie. Em consulta significa que repetir devolve o mesmo resultado; em escrita significa que o desfecho é indeterminado, porque a operadora pode ter processado e só a resposta ter se perdido. Ausente quando a falha pode ser transitória, o que só ocorre em consulta.
Protocolo da movimentação, quando a operadora devolveu um antes de falhar. **Em escrita com 502, consulte este protocolo em GET /v1/movimentacoes/{protocolo} em vez de reenviar.**
Caminho chamado na operadora, sem host. Para diagnóstico.
Resposta da operadora, para diagnóstico. Formato variável.
Outro status de transporte, repassado da operadora como veio (ex. 403, 404, 409, 429).
Não são desfecho de negócio. Rejeição da operadora chega em HTTP 200 com criticas; ausência de registro também é 200. Um status aqui indica problema de integração, não de cadastro, e vale acionar o suporte.
Estrutura padronizada de erro.
Código HTTP do erro.
Código interno do erro.
Descrição legível do erro.
items
Crítica devolvida pela operadora. Em bloqueante: true rejeita (corrija e reenvie), false é aviso e a movimentação segue (ex. 2401), null a operadora não classificou.
Gerar token JWT de acesso
/v1/auth/tokenPorta de entrada da API. Envie client_id e client_secret em JSON; a API troca no Keycloak (client_credentials) e devolve um token JWT (validade ~2h).
Formato: corpo application/json com client_id e client_secret. Use o access_token retornado como Authorization: Bearer <token> nas demais chamadas. Único endpoint que não exige token prévio.
No console desta página, cole somente o token no campo de autorização, sem escrever Bearer na frente: o prefixo já é adicionado.
Request Body
application/jsonrequired
Ver schema bruto / exemplo JSON
{
"client_id": "mds-client",
"client_secret": "<seu client_secret>"
}Responses
Token gerado com sucesso (resposta do Keycloak).
Ver schema bruto / exemplo JSON
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 7200
}Requisição malformada (campos obrigatórios ausentes/ inválidos).
Estrutura padronizada de erro.
Código HTTP do erro.
Código interno do erro.
Descrição legível do erro.
items
Crítica devolvida pela operadora. Em bloqueante: true rejeita (corrija e reenvie), false é aviso e a movimentação segue (ex. 2401), null a operadora não classificou.
client_id/client_secret inválidos. O corpo segue o schema Erro, com o motivo do provedor de identidade em codigo (ex. invalid_client).
Estrutura padronizada de erro.
Código HTTP do erro.
Código interno do erro.
Descrição legível do erro.
items
Crítica devolvida pela operadora. Em bloqueante: true rejeita (corrija e reenvie), false é aviso e a movimentação segue (ex. 2401), null a operadora não classificou.
Corpo da requisição acima do limite aceito pela fachada: 1 MB nas rotas de dados, 12 MB em POST /v1/faturas/interpretacoes, que recebe o PDF em base64.
Não há limite de ITENS no lote: o teto é de bytes, e existe para que um corpo gigante não derrube o processo. Lote grande que estoure o limite deve ser dividido em requisições; cada uma é independente na operadora.
Estrutura padronizada de erro.
Código HTTP do erro.
Código interno do erro.
Descrição legível do erro.
items
Crítica devolvida pela operadora. Em bloqueante: true rejeita (corrija e reenvie), false é aviso e a movimentação segue (ex. 2401), null a operadora não classificou.
Não foi possível concluir a operação junto à operadora.
Em consulta, sem repetir no corpo a falha pode ser transitória e nova tentativa é segura.
Em escrita (POST, PATCH, DELETE) o corpo traz repetir: false, e o desfecho é indeterminado: a operadora pode ter processado e só a resposta ter se perdido. Não reenvie. Se o corpo trouxer protocolo, consulte-o em GET /v1/movimentacoes/{protocolo}; se não, confira o beneficiário pelo CPF antes de tentar de novo.
Erro gerado pela própria API, antes ou depois de falar com a operadora. Formato distinto do Erro, que é usado quando o desfecho vem da operadora.
Motivo resumido.
Detalhe técnico, quando existe.
Quando false, não reenvie. Em consulta significa que repetir devolve o mesmo resultado; em escrita significa que o desfecho é indeterminado, porque a operadora pode ter processado e só a resposta ter se perdido. Ausente quando a falha pode ser transitória, o que só ocorre em consulta.
Protocolo da movimentação, quando a operadora devolveu um antes de falhar. **Em escrita com 502, consulte este protocolo em GET /v1/movimentacoes/{protocolo} em vez de reenviar.**
Caminho chamado na operadora, sem host. Para diagnóstico.
Resposta da operadora, para diagnóstico. Formato variável.
Outro status de transporte, repassado da operadora como veio (ex. 403, 404, 409, 429).
Não são desfecho de negócio. Rejeição da operadora chega em HTTP 200 com criticas; ausência de registro também é 200. Um status aqui indica problema de integração, não de cadastro, e vale acionar o suporte.
Estrutura padronizada de erro.
Código HTTP do erro.
Código interno do erro.
Descrição legível do erro.
items
Crítica devolvida pela operadora. Em bloqueante: true rejeita (corrija e reenvie), false é aviso e a movimentação segue (ex. 2401), null a operadora não classificou.