{"openapi":"3.0.3","info":{"title":"MedPontual · API de agendamento","version":"1.0.0","description":"Contrato da API de agendamento da MedPontual e do conector ExpressChat."},"servers":[{"url":"https://sandbox.medpontual.com.br","description":"Ambiente de teste com clínica fictícia"}],"paths":{"/api/booking/v1":{"post":{"summary":"Executar uma ação da API de agendamento","operationId":"executarAgendamentoMedPontual","security":[{"medpontualBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CatalogRequest"},{"$ref":"#/components/schemas/AvailabilityRequest"},{"$ref":"#/components/schemas/BookRequest"}]},"examples":{"unidades":{"summary":"Unidades públicas","value":{"action":"catalog","kind":"units","page":0}},"modalidades":{"summary":"Modalidades da unidade","value":{"action":"catalog","kind":"modalities","selection":{"unit":"VALOR_DA_UNIDADE"},"page":0}},"especialidades":{"summary":"Especialidades por unidade e modalidade","value":{"action":"catalog","kind":"specialties","selection":{"unit":"VALOR_DA_UNIDADE","modality":"in_person"},"page":0}},"convenios":{"summary":"Convênios e particular","value":{"action":"catalog","kind":"plans","selection":{"unit":"VALOR_DA_UNIDADE","modality":"in_person","specialty":"VALOR_DO_ATENDIMENTO"},"page":0}},"profissionais":{"summary":"Profissionais disponíveis para a combinação","value":{"action":"catalog","kind":"professionals","selection":{"unit":"VALOR_DA_UNIDADE","modality":"in_person","specialty":"VALOR_DO_ATENDIMENTO","plan":"particular"},"page":0}},"horarios":{"summary":"Horários de uma data elegível","value":{"action":"availability","date":"2026-11-20","selection":{"unit":"VALOR_DA_UNIDADE","modality":"in_person","specialty":"VALOR_DO_ATENDIMENTO","plan":"particular","professional":""},"page":0}},"agendamento":{"summary":"Modelo com aceite explícito já obtido","value":{"action":"book","quote":"VALOR_OPACO_DO_HORARIO","requestId":"ID_ESTAVEL_DA_SOLICITACAO","patient":{"name":"Paciente fictício de homologação","cpf":"CPF_FICTICIO_VALIDO","phone":"DDD_E_NUMERO_FICTICIO","email":"paciente@example.test","acceptedTerms":true}}}}}}},"responses":{"200":{"description":"Resposta correspondente à ação. Em book, informe o status devolvido.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CatalogResponse"},{"$ref":"#/components/schemas/AvailabilityResponse"},{"$ref":"#/components/schemas/BookResponse"}]}}}},"400":{"description":"JSON, dados, data, carteirinha ou aceite inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Token ausente, inválido, revogado, substituído ou expirado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permissão insuficiente, provedor inativo, agenda indisponível ou oferta de outro contexto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Endereço desconhecido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Vaga, oferta ou regra alterada, CPF com agendamento ativo ou conflito com pedido anterior.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Corpo JSON acima de 30.000 bytes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de 180 chamadas por minuto por token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno. Se o resultado for incerto, repita com o mesmo ID, a mesma oferta e os mesmos dados enquanto a oferta estiver válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/integrations/expresschat/v1":{"post":{"summary":"Consultar catálogo, verificar horários ou solicitar um agendamento","operationId":"executarAgendamentoExpressChat","security":[{"expresschatBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CatalogRequest"},{"$ref":"#/components/schemas/AvailabilityRequest"},{"$ref":"#/components/schemas/BookRequest"}]},"examples":{"unidades":{"summary":"Unidades públicas","value":{"action":"catalog","kind":"units","page":0}},"modalidades":{"summary":"Modalidades da unidade","value":{"action":"catalog","kind":"modalities","selection":{"unit":"VALOR_DA_UNIDADE"},"page":0}},"especialidades":{"summary":"Especialidades por unidade e modalidade","value":{"action":"catalog","kind":"specialties","selection":{"unit":"VALOR_DA_UNIDADE","modality":"in_person"},"page":0}},"convenios":{"summary":"Convênios e particular","value":{"action":"catalog","kind":"plans","selection":{"unit":"VALOR_DA_UNIDADE","modality":"in_person","specialty":"VALOR_DO_ATENDIMENTO"},"page":0}},"profissionais":{"summary":"Profissionais disponíveis para a combinação","value":{"action":"catalog","kind":"professionals","selection":{"unit":"VALOR_DA_UNIDADE","modality":"in_person","specialty":"VALOR_DO_ATENDIMENTO","plan":"particular"},"page":0}},"horarios":{"summary":"Horários de uma data elegível","value":{"action":"availability","date":"2026-11-20","selection":{"unit":"VALOR_DA_UNIDADE","modality":"in_person","specialty":"VALOR_DO_ATENDIMENTO","plan":"particular","professional":""},"page":0}},"agendamento":{"summary":"Modelo com aceite explícito já obtido","value":{"action":"book","quote":"VALOR_OPACO_DO_HORARIO","requestId":"ID_ESTAVEL_DA_SOLICITACAO","patient":{"name":"Paciente fictício de homologação","cpf":"CPF_FICTICIO_VALIDO","phone":"DDD_E_NUMERO_FICTICIO","email":"paciente@example.test","acceptedTerms":true}}}}}}},"responses":{"200":{"description":"Resposta correspondente à ação. Em book, informe o status devolvido.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CatalogResponse"},{"$ref":"#/components/schemas/AvailabilityResponse"},{"$ref":"#/components/schemas/BookResponse"}]}}}},"400":{"description":"JSON, dados, data, carteirinha ou aceite inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Token ausente, inválido, revogado, substituído ou expirado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permissão insuficiente, provedor inativo, agenda indisponível ou oferta de outro contexto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Endereço desconhecido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Vaga, oferta ou regra alterada, CPF com agendamento ativo ou conflito com pedido anterior.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Corpo JSON acima de 30.000 bytes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de 180 chamadas por minuto por token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno. Se o resultado for incerto, repita com o mesmo ID, a mesma oferta e os mesmos dados enquanto a oferta estiver válida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"expresschatBearer":{"type":"http","scheme":"bearer","description":"Chave mp_expresschat_ válida por 24 horas."},"medpontualBearer":{"type":"http","scheme":"bearer","description":"Chave mp_api_ válida por 24 horas."}},"schemas":{"Option":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"value":{"type":"string"},"description":{"type":"string"}},"required":["id","title","value","description"]},"Selection":{"type":"object","properties":{"unit":{"type":"string","maxLength":80},"modality":{"type":"string","enum":["in_person","online"]},"specialty":{"type":"string","maxLength":100},"plan":{"type":"string","maxLength":80,"description":"Use o valor recebido do catálogo. Particular usa particular."},"professional":{"type":"string","maxLength":80,"description":"Valor recebido do catálogo ou string vazia sem preferência."}}},"CatalogRequest":{"type":"object","properties":{"action":{"type":"string","enum":["catalog"]},"kind":{"type":"string","enum":["units","modalities","specialties","plans","professionals"]},"page":{"type":"integer","minimum":0,"maximum":100,"default":0},"selection":{"$ref":"#/components/schemas/Selection"}},"required":["action","kind"]},"AvailabilityRequest":{"type":"object","properties":{"action":{"type":"string","enum":["availability"]},"date":{"type":"string","format":"date"},"selection":{"$ref":"#/components/schemas/Selection"},"page":{"type":"integer","minimum":0,"maximum":100,"default":0}},"required":["action","date","selection"],"description":"Informe unit, specialty e plan. Informe a modalidade explicitamente, inclusive para vídeo. Use uma data elegível no horário de Brasília."},"Patient":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"cpf":{"type":"string","maxLength":30,"description":"CPF válido, como texto."},"phone":{"type":"string","maxLength":30,"description":"DDD e 10 ou 11 dígitos no total."},"email":{"type":"string","format":"email","maxLength":160},"insuranceCardNumber":{"type":"string","maxLength":60,"description":"Obrigatória para convênio. Preserve zeros à esquerda. Omita para particular."},"acceptedTerms":{"type":"boolean","enum":[true],"description":"True apenas depois de aceite explícito, após apresentar resumo, authorization.text, termsUrl e privacyUrl."}},"required":["name","cpf","phone","email","acceptedTerms"],"additionalProperties":false},"BookRequest":{"type":"object","properties":{"action":{"type":"string","enum":["book"]},"quote":{"type":"string","maxLength":3000,"description":"Valor opaco retornado em availability.data[].value."},"requestId":{"type":"string","minLength":1,"maxLength":160,"description":"ID exclusivo e estável por solicitação. Mantenha-o com a mesma quote e o mesmo patient em uma repetição de resultado incerto."},"patient":{"$ref":"#/components/schemas/Patient"}},"required":["action","quote","requestId","patient"]},"CatalogResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/Option"}},"count":{"type":"integer","minimum":0,"maximum":10,"description":"Quantidade de itens na página atual."},"nextPage":{"type":"integer","nullable":true,"description":"Número da página seguinte, ou null ao fim da lista."},"clinic":{"type":"string"},"authorization":{"type":"object","properties":{"text":{"type":"string"},"version":{"type":"string"},"termsUrl":{"type":"string","format":"uri"},"privacyUrl":{"type":"string","format":"uri"}},"required":["text","version","termsUrl","privacyUrl"]}},"required":["success","data","count","nextPage","clinic","authorization"]},"AvailabilityResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/Option"}},"count":{"type":"integer","minimum":0,"maximum":10,"description":"Quantidade de itens na página atual."},"nextPage":{"type":"integer","nullable":true,"description":"Número da página seguinte, ou null ao fim da lista."},"expiresIn":{"type":"integer","enum":[600]}},"required":["success","data","count","nextPage","expiresIn"]},"BookResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"id":{"type":"string"},"status":{"type":"string","enum":["pending","confirmed"]},"repeated":{"type":"boolean","enum":[true]},"confirmationPolicy":{"type":"object","description":"Metadados da regra de confirmação."}},"required":["ok","id","status"]},"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"next":{"type":"object","nullable":true,"description":"Informações complementares quando disponíveis."}},"required":["error"]}}}}