Integre sua solução à clínica

1. Peça uma chave de teste à clínica

1. O acesso master da clínica abre Sistema → Minhas integrações API e cria uma integração de teste para sua empresa.
2. Receba a chave por um canal seguro. Ela é exibida uma única vez.
3. Configure a chave no servidor da sua aplicação. Nunca no navegador, em URLs, repositórios ou aplicativos distribuídos.
4. Importe a coleção Postman, defina apiKey e execute os exemplos em ordem. A coleção usa somente teste e calcula uma data fictícia automaticamente.
5. Teste pedidos, erros, repetição, notificações e retomada antes de pedir a ativação de produção.

Base: https://api-v2.mxmed.com.br/api/integrations/v1/test. Em produção, substitua apenas test por live e use a chave de produção. Chaves e IDs de pedidos dos ambientes não se misturam.

curl 'https://api-v2.mxmed.com.br/api/integrations/v1/test/usage'   -H 'X-Api-Key: SUA_CHAVE_DE_TESTE'

Toda resposta bem-sucedida contém data e requestId. Erros contêm error.code, error.message e requestId. Guarde essa referência para diagnóstico.

2. Faça o de-para usando o catálogo da clínica

Consulte unidades, profissionais e procedimentos. Relacione seus IDs locais aos IDs retornados pelo mxMED e guarde esse vínculo por integração e ambiente. Não vincule automaticamente apenas pelo nome: pode haver homônimos ou procedimentos semelhantes.

Os IDs permanecem estáveis; nomes e disponibilidade podem mudar. Um cadastro desativado ou retirado das permissões deixa de aparecer. Nunca reutilize IDs de outra clínica. O código code do procedimento é enviado em procedureCode; o ID de catálogo serve ao seu de-para.

Paginação: ?limit=50&after=0. Use nextCursor até receber null. Sincronize o catálogo no máximo uma vez por hora, guarde os resultados e permita revisão do vínculo pelo integrador. Não é necessário sincronizar a base inteira a cada venda.

Sandbox: unidade 101, profissional 201, procedimento 301 com código 10101012 e horário 401. Todos fictícios. Não envie informações reais de pacientes.

Disponibilidade exige unitId, doctorId e date=AAAA-MM-DD. Uma data por consulta, de hoje até 30 dias à frente; até 100 horários por página. Continue com after=nextCursor. Horários estão no fuso de São Paulo, sem sufixo UTC. A consulta não reserva um horário; o checkout verifica novamente a disponibilidade.

3. Crie o pedido e direcione ao checkout

POST /api/integrations/v1/test/orders
X-Api-Key: SUA_CHAVE
Idempotency-Key: pedido-2026-001
Content-Type: application/json

{
  "externalReference": "venda-001",
  "slotId": 401,
  "unitId": 101,
  "doctorId": 201,
  "date": "AAAA-MM-DD",
  "procedureCode": "10101012"
}

Use uma referência sem dados pessoais. O preço é calculado pelo mxMED. Em produção, a resposta traz checkoutUrl, valor e validade. O link dura 15 minutos antes do início do checkout e não reserva o horário por si só. Há limite de 20 pedidos abertos por integração e ambiente.

O paciente preenche seus dados e paga no checkout da clínica, usando os meios e o provedor já configurados por ela. O integrador não recebe prontuário, lista de pacientes, CPF ou cartão. Não se cria outro vendedor ou outra conta de recebimento.

Não confirme uma venda pelo redirecionamento do navegador. Aguarde o estado CONFIRMADO no pedido ou evento. Pagamento pendente ou conciliação exigem acompanhamento. Após iniciar o checkout, mudanças de agenda e devoluções são administradas pela clínica no fluxo existente; esta API não cancela um atendimento confirmado.

Se houver timeout, repita com a mesma Idempotency-Key e o mesmo corpo. A resposta recupera o pedido, sem criar outra compra ou contar outra chamada. Uma chave ou referência reutilizada com dados diferentes retorna 409. Não gere outra referência para contornar um pagamento incerto.

Sandbox não abre checkout real: checkoutUrl vem nulo. Use POST orders/ID/simulate com {"scenario":"paid"}. Cenários: paid, declined, pending e expired. Eles atualizam o pedido fictício e geram eventos.

Rotas e permissões

Configure apenas as permissões necessárias. Não existem rotas para prontuário, listagem de pacientes ou dados de cartão nesta API.

Limites, consumo e desempenho

• Use GET usage para consultar seu ambiente, permissões, chamadas consumidas, chamadas em processamento e franquia do mês. A clínica administra a capacidade autorizada para sua integração.
• Contam para o consumo respostas 2xx de catálogo, disponibilidade e novos pedidos. Erros e repetições idênticas de pedidos não contam. Consumo, eventos, acompanhamento e cancelamento pré-checkout não descontam chamadas da franquia, mas respeitam os limites de tráfego.
• Até 30 requisições/minuto por integração, 60 por clínica e 120 no conjunto da API. No máximo quatro operações externas simultâneas em todas as instâncias. Picos podem retornar 429 antes desses números por proteção de capacidade.
• Respeite Retry-After. Use espera progressiva com variação aleatória. Não mantenha consultas paralelas contínuas. Prefira eventos e consulte um pedido no máximo uma vez por minuto.
• Ao receber QUOTA_EXCEEDED, interrompa novas operações de consumo e fale com a clínica. Apenas ela pode ampliar o limite autorizado. Trocar a chave não reinicia o consumo.
• Catálogo pode usar cache de até 60 segundos e disponibilidade de até 5 segundos. A compra sempre revalida preço e horário.
• A clínica revoga chaves e escopos imediatamente nas novas requisições; revogação não desfaz operações já iniciadas. A liberação de produção é renovada em segundo plano e pode expirar em até 15 minutos se não puder ser confirmada.

Teste e produção possuem consumos separados. No sandbox, use somente dados fictícios. Para ativar produção, solicite à clínica uma credencial e as permissões necessárias.

Notificações assinadas e recuperação

A clínica cadastra sua URL HTTPS pública (porta 443, destino IPv4 público) e entrega o segredo. Cada salvamento do destino gera outro segredo. Receba POST JSON, valide a assinatura usando os bytes originais do corpo e responda 2xx rapidamente. Não redirecione a requisição.

X-MxMed-Event-Id: 123
X-MxMed-Timestamp: 1794240000
X-MxMed-Signature: sha256=...

assinatura = HMAC-SHA256(segredo, timestamp + "." + corpoOriginal)

{"id":123,"type":"order.updated","data":{
  "orderId":"...","externalReference":"venda-001",
  "status":"CONFIRMADO","amount":120,"environment":"test"
}}

Compare assinaturas em tempo constante e rejeite timestamps com diferença superior a cinco minutos. Seu relógio precisa estar sincronizado. Desduplique por ID do evento: uma entrega pode ser repetida. Os eventos não garantem ordem; use GET orders/ID para confirmar o estado mais recente.

Há até 12 tentativas automáticas, começando em 30 segundos e aumentando até seis horas entre tentativas. O painel mostra tentativas, último HTTP e permite reenvio. Se o endpoint ficar fora do ar, recupere eventos com GET events?after=ULTIMO_ID, até 50 por página, guardando o último ID recebido. Há acompanhamento automático dos pagamentos iniciados pela integração durante 60 dias; ocorrências posteriores devem ser conferidas com a clínica.

Resolva sem depender de atendimento

Antes de produção: valide revogação, permissão negada, timeout, repetição idempotente, isolamento entre empresas, 429 e falha do webhook. A documentação e a coleção são a referência de integração. Não há consultoria ou desenvolvimento para sistemas terceiros. Para falha comprovada da plataforma, a clínica pode reportar o requestId, data e código HTTP, sem enviar segredos ou dados pessoais.