{"openapi":"3.1.0","info":{"title":"Mizum · API pública","version":"1.0.0","summary":"Lecturas de la recepcionista para clínicas con la API pública contratada.","description":"Extra de 19 € al mes sin IVA en Secretaria, Recepción y Max. En Secretaria expone solicitudes de cita y recados, y no escribe en la agenda: las citas responden 403. Sin el extra, la respuesta es 403. La clave va en Authorization: Bearer rci_…. Hay 60 peticiones por minuto y por clave. Las llamadas devuelven metadatos: nunca la transcripción. En psicología no sale la transcripción completa por ningún campo. Los webhooks (hasta 3) se firman con HMAC-SHA256 y se reintentan 5 veces (al momento, 60 s, 300 s, 1800 s, 7200 s). Eventos: llamada.terminada, recado.nuevo, cita.creada, cita.anulada."},"servers":[{"url":"/api/v1"}],"security":[{"claveClinica":[]}],"paths":{"/llamadas":{"get":{"summary":"Metadatos de las llamadas.","security":[{"claveClinica":[]}],"parameters":[{"name":"limite","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Resultados por página. Por defecto 50."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor de la página anterior, en el campo siguiente."},{"name":"desde","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"hasta","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"resultado","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LlamadaPagina"}}}},"401":{"description":"Clave ausente, revocada o desconocida.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"La API pública no está contratada, la clínica no está activa o, en Secretaria, se pide la agenda.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Límite de peticiones.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/llamadas/{id}":{"get":{"summary":"Metadatos de una llamada.","security":[{"claveClinica":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"El recurso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Llamada"}}}},"401":{"description":"Clave ausente, revocada o desconocida.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"La API pública no está contratada, la clínica no está activa o, en Secretaria, se pide la agenda.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"No está o no es de esta clínica.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Límite de peticiones.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/recados":{"get":{"summary":"Recados tomados por la recepcionista.","security":[{"claveClinica":[]}],"parameters":[{"name":"limite","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Resultados por página. Por defecto 50."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor de la página anterior, en el campo siguiente."},{"name":"desde","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"hasta","in":"query","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecadoPagina"}}}},"401":{"description":"Clave ausente, revocada o desconocida.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"La API pública no está contratada, la clínica no está activa o, en Secretaria, se pide la agenda.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Límite de peticiones.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/recados/{id}":{"get":{"summary":"Un recado.","security":[{"claveClinica":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"El recurso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Recado"}}}},"401":{"description":"Clave ausente, revocada o desconocida.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"La API pública no está contratada, la clínica no está activa o, en Secretaria, se pide la agenda.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"No está o no es de esta clínica.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Límite de peticiones.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/solicitudes":{"get":{"summary":"Solicitudes de cita.","security":[{"claveClinica":[]}],"parameters":[{"name":"limite","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Resultados por página. Por defecto 50."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor de la página anterior, en el campo siguiente."},{"name":"estado","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SolicitudPagina"}}}},"401":{"description":"Clave ausente, revocada o desconocida.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"La API pública no está contratada, la clínica no está activa o, en Secretaria, se pide la agenda.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Límite de peticiones.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/solicitudes/{id}":{"get":{"summary":"Una solicitud de cita.","security":[{"claveClinica":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"El recurso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Solicitud"}}}},"401":{"description":"Clave ausente, revocada o desconocida.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"La API pública no está contratada, la clínica no está activa o, en Secretaria, se pide la agenda.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"No está o no es de esta clínica.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Límite de peticiones.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/citas":{"get":{"summary":"Citas de la agenda.","security":[{"claveClinica":[]}],"parameters":[{"name":"limite","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Resultados por página. Por defecto 50."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor de la página anterior, en el campo siguiente."},{"name":"desde","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"hasta","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"estado","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Página de resultados.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CitaPagina"}}}},"401":{"description":"Clave ausente, revocada o desconocida.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"La API pública no está contratada, la clínica no está activa o, en Secretaria, se pide la agenda.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Límite de peticiones.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/citas/{id}":{"get":{"summary":"Una cita. En Secretaria responde 403: la API no escribe en la agenda.","security":[{"claveClinica":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"El recurso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cita"}}}},"401":{"description":"Clave ausente, revocada o desconocida.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"La API pública no está contratada, la clínica no está activa o, en Secretaria, se pide la agenda.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"No está o no es de esta clínica.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Límite de peticiones.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/webhooks":{"get":{"summary":"Webhooks de la clínica, sin el secreto.","security":[{"claveClinica":[]}],"responses":{"200":{"description":"Lista.","content":{"application/json":{"schema":{"type":"object","properties":{"datos":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}},"required":["datos"]}}}}}},"post":{"summary":"Da de alta un webhook. El secreto se enseña una sola vez.","security":[{"claveClinica":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"]}}}},"responses":{"201":{"description":"Creado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookNuevo"}}}},"400":{"description":"URL no válida.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/webhooks/{id}":{"delete":{"summary":"Revoca un webhook.","security":[{"claveClinica":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Revocado."},"404":{"description":"No está.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}}},"webhooks":{"llamada.terminada":{"post":{"summary":"llamada.terminada","description":"Cuerpo JSON firmado. La cabecera X-Rci-Firma es t=<unix>,v1=<hmac sha256 hex de `${t}.${cuerpo crudo}`>.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"tipo":{"type":"string","const":"llamada.terminada"},"creadoEn":{"type":"string","format":"date-time"},"datos":{"$ref":"#/components/schemas/Llamada"}},"required":["id","tipo","creadoEn","datos"]}}}},"responses":{"2XX":{"description":"Cualquier 2xx se da por entregado. 408, 429 y 5xx se reintentan."}}}},"recado.nuevo":{"post":{"summary":"recado.nuevo","description":"Cuerpo JSON firmado. La cabecera X-Rci-Firma es t=<unix>,v1=<hmac sha256 hex de `${t}.${cuerpo crudo}`>.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"tipo":{"type":"string","const":"recado.nuevo"},"creadoEn":{"type":"string","format":"date-time"},"datos":{"$ref":"#/components/schemas/Recado"}},"required":["id","tipo","creadoEn","datos"]}}}},"responses":{"2XX":{"description":"Cualquier 2xx se da por entregado. 408, 429 y 5xx se reintentan."}}}},"cita.creada":{"post":{"summary":"cita.creada","description":"Cuerpo JSON firmado. La cabecera X-Rci-Firma es t=<unix>,v1=<hmac sha256 hex de `${t}.${cuerpo crudo}`>.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"tipo":{"type":"string","const":"cita.creada"},"creadoEn":{"type":"string","format":"date-time"},"datos":{"$ref":"#/components/schemas/CitaEvento"}},"required":["id","tipo","creadoEn","datos"]}}}},"responses":{"2XX":{"description":"Cualquier 2xx se da por entregado. 408, 429 y 5xx se reintentan."}}}},"cita.anulada":{"post":{"summary":"cita.anulada","description":"Cuerpo JSON firmado. La cabecera X-Rci-Firma es t=<unix>,v1=<hmac sha256 hex de `${t}.${cuerpo crudo}`>.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"tipo":{"type":"string","const":"cita.anulada"},"creadoEn":{"type":"string","format":"date-time"},"datos":{"$ref":"#/components/schemas/CitaEvento"}},"required":["id","tipo","creadoEn","datos"]}}}},"responses":{"2XX":{"description":"Cualquier 2xx se da por entregado. 408, 429 y 5xx se reintentan."}}}}},"components":{"securitySchemes":{"claveClinica":{"type":"http","scheme":"bearer","bearerFormat":"rci_","description":"Clave de la clínica. Se guarda solo el hash. Crear y revocar se hace desde el panel del titular."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"Llamada":{"type":"object","description":"Metadatos de la llamada. No incluye la transcripción.","properties":{"id":{"type":"string"},"empezo":{"type":"string","format":"date-time"},"duracionSegundos":{"type":"integer"},"resultado":{"type":"string"},"desde":{"type":"string"},"hacia":{"type":"string"},"nombre":{"type":["string","null"]},"telefono":{"type":["string","null"]},"motivo":{"type":["string","null"]},"resumen":{"type":["string","null"]},"prioridad":{"type":"boolean"},"minutosConsumidos":{"type":"number"},"esPrueba":{"type":"boolean"},"canal":{"type":["string","null"]},"motivoCorte":{"type":["string","null"]},"enCurso":{"type":"boolean"}},"required":["id","empezo","duracionSegundos","resultado"]},"LlamadaPagina":{"type":"object","properties":{"datos":{"type":"array","items":{"$ref":"#/components/schemas/Llamada"}},"siguiente":{"type":["string","null"]}},"required":["datos","siguiente"]},"Recado":{"type":"object","properties":{"id":{"type":"string"},"nombre":{"type":["string","null"]},"telefono":{"type":["string","null"]},"motivo":{"type":["string","null"]},"prioridad":{"type":"boolean"},"empezo":{"type":"string","format":"date-time"},"resumen":{"type":["string","null"]}},"required":["id","empezo"]},"RecadoPagina":{"type":"object","properties":{"datos":{"type":"array","items":{"$ref":"#/components/schemas/Recado"}},"siguiente":{"type":["string","null"]}},"required":["datos","siguiente"]},"Solicitud":{"type":"object","properties":{"id":{"type":"string"},"nombre":{"type":"string"},"telefono":{"type":"string"},"motivo":{"type":["string","null"]},"preferencia":{"type":["string","null"]},"estado":{"type":"string"},"creadaEn":{"type":"string","format":"date-time"},"llamadaId":{"type":["string","null"]}},"required":["id","nombre","telefono","estado","creadaEn"]},"SolicitudPagina":{"type":"object","properties":{"datos":{"type":"array","items":{"$ref":"#/components/schemas/Solicitud"}},"siguiente":{"type":["string","null"]}},"required":["datos","siguiente"]},"Cita":{"type":"object","properties":{"id":{"type":"string"},"nombre":{"type":"string"},"telefono":{"type":"string"},"motivo":{"type":["string","null"]},"empieza":{"type":"string","format":"date-time"},"duracionMin":{"type":"integer"},"estado":{"type":"string"},"origen":{"type":"string"},"proveedor":{"type":["string","null"]},"externaId":{"type":["string","null"]}},"required":["id","nombre","telefono","empieza","estado"]},"CitaPagina":{"type":"object","properties":{"datos":{"type":"array","items":{"$ref":"#/components/schemas/Cita"}},"siguiente":{"type":["string","null"]}},"required":["datos","siguiente"]},"CitaEvento":{"type":"object","properties":{"id":{"type":"string"},"nombre":{"type":"string"},"telefono":{"type":"string"},"motivo":{"type":["string","null"]},"empieza":{"type":"string","format":"date-time"},"duracionMin":{"type":"integer"},"estado":{"type":"string"},"origen":{"type":"string"}},"required":["id","empieza","estado"]},"Webhook":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"activo":{"type":"boolean"},"creadoEn":{"type":"string","format":"date-time"},"revocadoEn":{"type":["string","null"]}},"required":["id","url","activo"]},"WebhookNuevo":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"secreto":{"type":"string","description":"Solo en la respuesta de alta. No se vuelve a mostrar."}},"required":["id","url","secreto"]}}}}