La API de Meevia

La API le abre a tu sistema las partes de la clínica que tiene sentido automatizar: la agenda, el catálogo de profesionales y procedimientos, y la ficha básica del paciente. Lo que haces a través de ella sigue las mismas reglas que valen para quien opera la clínica dentro de la plataforma.

Es HTTP con JSON, sin biblioteca obligatoria y sin SDK que instalar. Si tu entorno sabe hacer una petición y leer una respuesta, ya sabe hablar con Meevia.

Casos habituales

• Una web o una app propia donde el paciente elige la hora y reserva por su cuenta.
• Un sistema que la clínica ya usa y que necesita ver la agenda del día sin que nadie teclee dos veces.
• Automatización interna: un panel propio, un informe, una rutina que confirma la asistencia.

Qué necesita tener la clínica

El acceso a la API forma parte del plan de la clínica. Si el plan actual no lo incluye, la primera llamada ya vuelve rechazada, y eso no lo arregla ningún cambio en tu código: es una conversación con el equipo comercial.

Qué no está aquí todavía

Esta versión lee y escribe agenda, y lee catálogo y paciente. Que Meevia avise a tu sistema cuando pasa algo en la clínica, la facturación y los pagos no forman parte de ella.

La clave nace en el panel de desarrollador, que está en developers.meevia.app y tiene carcasa propia, fuera del sistema de la clínica. Es así porque quien integra muchas veces no es de la clínica. No hay ningún camino por la API para crear una clave. La interfaz del panel está en portugués de Brasil, así que los nombres de pestaña y de permiso que se citan abajo son exactamente los que vas a leer en pantalla.

Abrir el panel de desarrollador

1. 1Abre el panel de desarrolladorLa dirección es developers.meevia.app. Quien ya trabaja dentro del sistema de la clínica llega al mismo sitio por Integrações (Integraciones), en la tarjeta API e Webhooks, que es una puerta al panel.
2. 2Entra con tu cuenta, o pide una invitaciónQuien administra la clínica entra directo. Quien viene de fuera necesita invitación: en la pestaña Acessos (Accesos), quien administra el panel invita por correo y elige entre Somente ver (solo ver), que consulta y no actúa, y Pode administrar (puede administrar), que además emite claves. Pedir la invitación es mejor que pedir la clave ya hecha, porque una clave que viaja por mensaje ya se ha filtrado.
3. 3Elige la clínicaEl panel atiende todas las clínicas a las que tienes acceso, y la que elijas arriba es la dueña de todo lo que muestran las pestañas. Si trabajas para varias, aquí es donde cambias.
4. 4En la pestaña Chaves (Claves), crea una clave nuevaPonle un nombre que diga dónde se va a usar. Seis meses después, ese nombre es la única forma de revocar la clave correcta sin tumbar la integración equivocada.
5. 5Elige el modo y los ámbitosEl modo decide si la clave toca la clínica de verdad o el entorno de prueba. Los ámbitos deciden qué puede hacer. Marca solo lo que la integración necesita.
6. 6Copia la clave antes de cerrar la ventanaLa clave completa aparece una sola vez, en el momento de emitirla. Meevia guarda el trozo que la identifica y nunca la parte secreta, así que cerrar sin copiar no tiene recuperación: revoca la clave y emite otra.

Una clave, una clínica

La clave vale para la clínica que la emitió, y solo para ella. Si atiendes a varias clínicas, son varias claves, cada una guardada por separado y sustituible sin tocar las demás. No existe una clave que vea más de una clínica.

Cuándo revocar

Revocar vale al instante y no tiene vuelta atrás: la clave deja de funcionar y sus llamadas pasan a ser rechazadas. Hazlo al cambiar de proveedor, al apagar una integración y a la mínima sospecha de filtración.

Quién puede qué

El permiso Pode administrar del panel abre las dos cosas que cambian algo: emitir y revocar claves, y reiniciar el entorno de prueba. Se recibe por invitación y vale por clínica, así que quien viene de fuera hace las dos sin depender de nadie. Reiniciar tiene un segundo camino: quien administra la clínica también reinicia. Quien solo tiene Somente ver ve las claves y no emite ninguna; el panel lo avisa en pantalla, en vez de esconder el botón.

Toda llamada va autenticada. La clave viaja en la cabecera de autorización, con el esquema que muestra el ejemplo, y no hay más: no hay inicio de sesión, ni sesión, ni token que caduque a mitad de camino.

curl -X GET \
  -H "Authorization: Bearer mv_live_a1b2c3d49f8e7d6c5b4a39281706f5e4d3c2b1a0" \
  "https://wnricobmssysbwfhbmsm.supabase.co/functions/v1/api-v1/v1/practitioners"

La clave es un valor único, y es ese valor entero el que viaja en la cabecera. Tiene tres trozos pegados: el prefijo dice en qué modo está la clave, el trozo del medio la identifica y es el que aparece en la pestaña Chaves del panel, y el último es la parte secreta. Esa última Meevia no la guarda nunca en claro, así que ni el soporte puede leer la tuya. Envía siempre la clave completa: mandar solo la parte secreta es el descuido que más rechazos de autorización produce.

Dos modos

El modo se decide al emitir la clave y no cambia después. En la práctica mantienes las dos claves y cambias la variable de entorno para pasar de un lado al otro.

Cada ámbito abre una parte de la API, y la clave solo hace lo que sus ámbitos permiten. La falta de un ámbito aparece en la primera llamada que lo necesita, no al emitir la clave.

Concede el mínimo. Una integración que solo muestra la agenda en una pantalla grande no tiene por qué poder reservar citas. Y una clave escueta es un destrozo pequeño el día en que se filtre.

Los ámbitos no se editan después de emitir la clave. Ampliarlos es emitir una clave nueva con lo que falta, cambiarla en tu entorno y revocar la antigua.

La clínica recibe un entorno de prueba solo para ella, aislado de la clínica real. La primera clave de prueba que se emite ya crea ese entorno, así que no hay nada que aprovisionar ni que pedir.

Qué viene ya dentro

Viene un paciente, un procedimiento y un profesional de ejemplo. Ninguno de ellos existe en la clínica de verdad. Las listas de profesionales y de procedimientos devuelven los identificadores de esos dos, así que consultar catálogo y horarios libres funciona en la primera sesión. Dar de alta es de la clínica: por la API, lo que se crea son citas.

Qué no se puede probar aquí

La API escribe en tres lugares: crear una cita, cambiar su situación y cancelarla. Hoy no se puede ejercitar ninguno de los tres aquí, y el motivo viene en cadena. Crear necesita el identificador del paciente, que no sale en pantalla ni vuelve de ninguna consulta, porque no hay listado de pacientes. Cambiar la situación y cancelar necesitan el identificador de una cita, y solo existiría si crear hubiera funcionado: la lista de citas nace vacía aquí. Quien necesite probar la escritura lo hace en la clínica de verdad, con el cuidado que eso pide: reserva en un hueco vacío y cancela en cuanto confirmes que funcionó.

Cómo reiniciarlo

La pestaña Ambiente de teste (Entorno de prueba) del panel tiene un botón que descarta el entorno actual y entrega otro, limpio, con los mismos datos iniciales. Las claves de prueba ya emitidas siguen valiendo: están ligadas a la clínica, no al entorno que se descartó.

Reiniciar es de quien tiene Pode administrar en el panel o administra la clínica. Quien viene de fuera con ese permiso lo reinicia por su cuenta, sin tener a quién pedírselo.

Toda llamada sale hacia la misma dirección, y es una sola para todo el mundo. No hay una dirección por clínica: lo que separa una clínica de otra es la clave, nunca la URL.

https://wnricobmssysbwfhbmsm.supabase.co/functions/v1/api-v1

Vas a ver un trozo que parece repetido en mitad del camino. Está bien así. Uno es de la infraestructura que aloja la API y el otro es de la versión de la nuestra. Copia la dirección exactamente como aparece aquí; quitar la parte que parece sobrar devuelve una respuesta de dirección inexistente.

Lleva cinco minutos, contando desde el inicio de sesión. Hazlo en modo de prueba: si algo sale distinto de lo esperado, quien lo paga es un paciente inventado.

1. 1Emite una clave de pruebaSigue el camino descrito en Cómo conseguir una clave, marcando el modo de prueba y el ámbito de lectura del catálogo. Copia la clave.
2. 2Guarda la clave en una variable de entornoAsí la clave no queda en el historial del terminal ni pegada en mitad del comando que le vas a mandar a un compañero.
3. 3Pide la lista de profesionalesEs la llamada más sencilla de aquí: no recibe ningún parámetro, y el entorno de prueba ya viene con un profesional dentro. Si responde, tu clave, tu ámbito y tu dirección están bien de una sola vez.
4. 4Mira lo que volvióUna respuesta con éxito trae al profesional de prueba. De ahí en adelante la receta es la misma para el resto: cambia la dirección, la cabecera sigue igual.

curl -X GET \
  -H "Authorization: Bearer mv_live_a1b2c3d49f8e7d6c5b4a39281706f5e4d3c2b1a0" \
  "https://wnricobmssysbwfhbmsm.supabase.co/functions/v1/api-v1/v1/practitioners"

{
  "data": [
    {
      "id": "1f6d5c84-3b92-4a07-8e15-d6c3f9b204ae",
      "name": "Dra. Helena Costa",
      "specialty": "Dermatologia"
    }
  ]
}

Si no vino lo que esperabas

Compara lo que volvió con el catálogo de rechazos de esta página, que dice qué pasó y qué hacer en cada caso. Vale la pena mirar también la pestaña Requisições (Peticiones) del panel, que muestra la dirección llamada, la respuesta y la hora de cada llamada recibida. Solo guarda ese resumen, nunca el contenido que enviaste.

Las respuestas vienen envueltas siempre igual, y cada llamada muestra el formato de lo que devuelve. Programa contra el envoltorio e ignora lo que no conozcas: con el tiempo aparece información nueva, y la integración que ignora lo que no espera sobrevive a eso sin necesitarte.

Los envoltorios

• Un solo registro, dentro del envoltorio estándar.data
• Una lista, dentro de ese mismo envoltorio.data
• Una lista en páginas, junto al marcador que pide la siguiente.datanext_cursorPuede venir sin valor
• Esta respuesta se sale del patrón de las demás: trae el día consultado al lado de los horarios.dateslots
• El formato de todo rechazo, en cualquier llamada.error

Listas largas

Las listas vienen en páginas. La respuesta trae un marcador de continuación: mientras venga con valor, manda ese mismo marcador en la llamada siguiente para pedir la página siguiente. Cuando venga vacío, se acabó. No intentes adivinar el total ni montar la paginación por tu cuenta.

Qué lleva cada respuesta

Cada una trae lo que recibe, lo que devuelve y un ejemplo listo para pegar en el terminal. Cambia los identificadores del ejemplo por los tuyos.

Lista las citas de un periodo, en páginas.

Ámbito exigido

appointments:readLeer la agenda

Repetición

No se aplica

Respuesta

Citadatanext_cursorPuede venir sin valor

Rechazos posibles

unauthorizedplan_requiredscope_requirednot_foundmethod_not_allowedvalidation_failedrate_limitedsandbox_not_readyinternal_error

curl -X GET \
  -H "Authorization: Bearer mv_live_a1b2c3d49f8e7d6c5b4a39281706f5e4d3c2b1a0" \
  "https://wnricobmssysbwfhbmsm.supabase.co/functions/v1/api-v1/v1/appointments?from=2026-10-01&to=2026-10-31&limit=2"

{
  "data": [
    {
      "id": "9c1f4b2a-7e83-4d61-b0a5-2f8c6d31e4a7",
      "status": "agendado",
      "starts_at": "2026-10-03T14:30:00",
      "ends_at": "2026-10-03T15:30:00",
      "patient_id": "4d7e2c19-5a6b-4f30-9e81-c2a5b7d04f63",
      "professional_id": "1f6d5c84-3b92-4a07-8e15-d6c3f9b204ae",
      "procedure_ids": [
        "2a9f8b31-6c74-4e05-9d28-a3f1e7b5c06d"
      ],
      "created_at": "2026-09-28T11:04:22.517Z"
    },
    {
      "id": "5e0b7a94-1d62-4c38-97af-8b41d2e6c03f",
      "status": "confirmado",
      "starts_at": "2026-10-03T16:00:00",
      "ends_at": "2026-10-03T16:45:00",
      "patient_id": "4d7e2c19-5a6b-4f30-9e81-c2a5b7d04f63",
      "professional_id": "1f6d5c84-3b92-4a07-8e15-d6c3f9b204ae",
      "procedure_ids": [
        "2a9f8b31-6c74-4e05-9d28-a3f1e7b5c06d"
      ],
      "created_at": "2026-09-28T11:04:22.517Z"
    }
  ],
  "next_cursor": "MjAyNi0xMC0wM3wxNDozMDowMHw5YzFmNGIyYS03ZTgzLTRkNjEtYjBhNS0yZjhjNmQzMWU0YTc="
}

curl -X GET \
  -H "Authorization: Bearer mv_live_a1b2c3d49f8e7d6c5b4a39281706f5e4d3c2b1a0" \
  "https://wnricobmssysbwfhbmsm.supabase.co/functions/v1/api-v1/v1/appointments?from=2026-10-01&to=2026-10-31&limit=2&cursor=MjAyNi0xMC0wM3wxNDozMDowMHw5YzFmNGIyYS03ZTgzLTRkNjEtYjBhNS0yZjhjNmQzMWU0YTc%3D"

{
  "data": [],
  "next_cursor": null
}

Reserva una cita para un paciente, con un profesional, a una hora.

Ámbito exigido

appointments:writeTocar la agenda

Repetición

Exige valor de repetición

Respuesta

Citadata

Rechazos posibles

unauthorizedplan_requiredscope_requirednot_foundmethod_not_allowedvalidation_failedrate_limitedidempotency_conflictsandbox_not_readyinternal_error

curl -X POST \
  -H "Authorization: Bearer mv_live_a1b2c3d49f8e7d6c5b4a39281706f5e4d3c2b1a0" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3c05a1-9b24-4e6d-8c17-0a5f3d92b4e8" \
  -d '{
  "patient_id": "4d7e2c19-5a6b-4f30-9e81-c2a5b7d04f63",
  "professional_id": "1f6d5c84-3b92-4a07-8e15-d6c3f9b204ae",
  "procedure_ids": [
    "2a9f8b31-6c74-4e05-9d28-a3f1e7b5c06d"
  ],
  "starts_at": "2026-10-03T14:30:00",
  "status": "agendado"
}' \
  "https://wnricobmssysbwfhbmsm.supabase.co/functions/v1/api-v1/v1/appointments"

{
  "data": {
    "id": "9c1f4b2a-7e83-4d61-b0a5-2f8c6d31e4a7",
    "status": "agendado",
    "starts_at": "2026-10-03T14:30:00",
    "ends_at": "2026-10-03T15:30:00",
    "patient_id": "4d7e2c19-5a6b-4f30-9e81-c2a5b7d04f63",
    "professional_id": "1f6d5c84-3b92-4a07-8e15-d6c3f9b204ae",
    "procedure_ids": [
      "2a9f8b31-6c74-4e05-9d28-a3f1e7b5c06d"
    ],
    "created_at": "2026-09-28T11:04:22.517Z"
  }
}

curl -X POST \
  -H "Authorization: Bearer mv_live_a1b2c3d49f8e7d6c5b4a39281706f5e4d3c2b1a0" \
  -H "Content-Type: application/json" \
  -d '{
  "patient_id": "4d7e2c19-5a6b-4f30-9e81-c2a5b7d04f63",
  "professional_id": "1f6d5c84-3b92-4a07-8e15-d6c3f9b204ae",
  "procedure_ids": [
    "2a9f8b31-6c74-4e05-9d28-a3f1e7b5c06d"
  ],
  "starts_at": "2026-10-03T14:30:00"
}' \
  "https://wnricobmssysbwfhbmsm.supabase.co/functions/v1/api-v1/v1/appointments"

{
  "error": {
    "code": "validation_failed",
    "message": "Cabeçalho Idempotency-Key é obrigatório para criar agendamento."
  }
}

Abre una cita concreta.

Ámbito exigido

appointments:readLeer la agenda

Repetición

No se aplica

Respuesta

Citadata

Rechazos posibles

unauthorizedplan_requiredscope_requirednot_foundmethod_not_allowedrate_limitedsandbox_not_readyinternal_error

curl -X GET \
  -H "Authorization: Bearer mv_live_a1b2c3d49f8e7d6c5b4a39281706f5e4d3c2b1a0" \
  "https://wnricobmssysbwfhbmsm.supabase.co/functions/v1/api-v1/v1/appointments/9c1f4b2a-7e83-4d61-b0a5-2f8c6d31e4a7"

{
  "data": {
    "id": "9c1f4b2a-7e83-4d61-b0a5-2f8c6d31e4a7",
    "status": "agendado",
    "starts_at": "2026-10-03T14:30:00",
    "ends_at": "2026-10-03T15:30:00",
    "patient_id": "4d7e2c19-5a6b-4f30-9e81-c2a5b7d04f63",
    "professional_id": "1f6d5c84-3b92-4a07-8e15-d6c3f9b204ae",
    "procedure_ids": [
      "2a9f8b31-6c74-4e05-9d28-a3f1e7b5c06d"
    ],
    "created_at": "2026-09-28T11:04:22.517Z"
  }
}

Cambia el estado de una cita, dentro de lo permitido.

Ámbito exigido

appointments:writeTocar la agenda

Repetición

Seguro repetir

Respuesta

Citadata

Rechazos posibles

unauthorizedplan_requiredscope_requirednot_foundmethod_not_allowedvalidation_failedrate_limitedstatus_transition_not_allowedsandbox_not_readyinternal_error

curl -X PATCH \
  -H "Authorization: Bearer mv_live_a1b2c3d49f8e7d6c5b4a39281706f5e4d3c2b1a0" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "confirmado"
}' \
  "https://wnricobmssysbwfhbmsm.supabase.co/functions/v1/api-v1/v1/appointments/9c1f4b2a-7e83-4d61-b0a5-2f8c6d31e4a7/status"

{
  "data": {
    "id": "9c1f4b2a-7e83-4d61-b0a5-2f8c6d31e4a7",
    "status": "confirmado",
    "starts_at": "2026-10-03T14:30:00",
    "ends_at": "2026-10-03T15:30:00",
    "patient_id": "4d7e2c19-5a6b-4f30-9e81-c2a5b7d04f63",
    "professional_id": "1f6d5c84-3b92-4a07-8e15-d6c3f9b204ae",
    "procedure_ids": [
      "2a9f8b31-6c74-4e05-9d28-a3f1e7b5c06d"
    ],
    "created_at": "2026-09-28T11:04:22.517Z"
  }
}

curl -X PATCH \
  -H "Authorization: Bearer mv_live_a1b2c3d49f8e7d6c5b4a39281706f5e4d3c2b1a0" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "realizado"
}' \
  "https://wnricobmssysbwfhbmsm.supabase.co/functions/v1/api-v1/v1/appointments/9c1f4b2a-7e83-4d61-b0a5-2f8c6d31e4a7/status"

{
  "error": {
    "code": "status_transition_not_allowed",
    "message": "Transição de status não permitida por esta API.",
    "details": {
      "from": "agendado",
      "to": "realizado"
    }
  }
}

Cancela una cita.

Ámbito exigido

appointments:writeTocar la agenda

Repetición

Seguro repetir

Respuesta

Citadata

Rechazos posibles

unauthorizedplan_requiredscope_requirednot_foundmethod_not_allowedrate_limitedstatus_transition_not_allowedsandbox_not_readyinternal_error

curl -X POST \
  -H "Authorization: Bearer mv_live_a1b2c3d49f8e7d6c5b4a39281706f5e4d3c2b1a0" \
  "https://wnricobmssysbwfhbmsm.supabase.co/functions/v1/api-v1/v1/appointments/9c1f4b2a-7e83-4d61-b0a5-2f8c6d31e4a7/cancel"

{
  "data": {
    "id": "9c1f4b2a-7e83-4d61-b0a5-2f8c6d31e4a7",
    "status": "cancelado",
    "starts_at": "2026-10-03T14:30:00",
    "ends_at": "2026-10-03T15:30:00",
    "patient_id": "4d7e2c19-5a6b-4f30-9e81-c2a5b7d04f63",
    "professional_id": "1f6d5c84-3b92-4a07-8e15-d6c3f9b204ae",
    "procedure_ids": [
      "2a9f8b31-6c74-4e05-9d28-a3f1e7b5c06d"
    ],
    "created_at": "2026-09-28T11:04:22.517Z"
  }
}

Abre la ficha básica de un paciente.

Ámbito exigido

patients:readLeer paciente

Repetición

No se aplica

Respuesta

Pacientedata

Rechazos posibles

unauthorizedplan_requiredscope_requirednot_foundmethod_not_allowedrate_limitedsandbox_not_readyinternal_error

curl -X GET \
  -H "Authorization: Bearer mv_live_a1b2c3d49f8e7d6c5b4a39281706f5e4d3c2b1a0" \
  "https://wnricobmssysbwfhbmsm.supabase.co/functions/v1/api-v1/v1/patients/4d7e2c19-5a6b-4f30-9e81-c2a5b7d04f63"

{
  "data": {
    "id": "4d7e2c19-5a6b-4f30-9e81-c2a5b7d04f63",
    "name": "Ana Ribeiro",
    "phone": "+5511987654321",
    "email": "ana.ribeiro@example.com"
  }
}

Lista los profesionales de la clínica.

Ámbito exigido

catalog:readLeer el catálogo

Repetición

No se aplica

Respuesta

Profesionaldata

Rechazos posibles

unauthorizedplan_requiredscope_requirednot_foundmethod_not_allowedrate_limitedsandbox_not_readyinternal_error

Esta llamada no recibe parámetros.

curl -X GET \
  -H "Authorization: Bearer mv_live_a1b2c3d49f8e7d6c5b4a39281706f5e4d3c2b1a0" \
  "https://wnricobmssysbwfhbmsm.supabase.co/functions/v1/api-v1/v1/practitioners"

{
  "data": [
    {
      "id": "1f6d5c84-3b92-4a07-8e15-d6c3f9b204ae",
      "name": "Dra. Helena Costa",
      "specialty": "Dermatologia"
    }
  ]
}

Lista los procedimientos del catálogo.

Ámbito exigido

catalog:readLeer el catálogo

Repetición

No se aplica

Respuesta

Procedimientodata

Rechazos posibles

unauthorizedplan_requiredscope_requirednot_foundmethod_not_allowedrate_limitedsandbox_not_readyinternal_error

Esta llamada no recibe parámetros.

curl -X GET \
  -H "Authorization: Bearer mv_live_a1b2c3d49f8e7d6c5b4a39281706f5e4d3c2b1a0" \
  "https://wnricobmssysbwfhbmsm.supabase.co/functions/v1/api-v1/v1/procedures"

{
  "data": [
    {
      "id": "2a9f8b31-6c74-4e05-9d28-a3f1e7b5c06d",
      "name": "Limpeza de pele profunda",
      "price": 280,
      "duration_minutes": 60
    }
  ]
}

Muestra los horarios libres de un día, y se puede acotar a un profesional o a un procedimiento.

Ámbito exigido

catalog:readLeer el catálogo

Repetición

No se aplica

Respuesta

Horario libredateslots

Rechazos posibles

unauthorizedplan_requiredscope_requirednot_foundmethod_not_allowedvalidation_failedrate_limitedsandbox_not_readyinternal_error

curl -X GET \
  -H "Authorization: Bearer mv_live_a1b2c3d49f8e7d6c5b4a39281706f5e4d3c2b1a0" \
  "https://wnricobmssysbwfhbmsm.supabase.co/functions/v1/api-v1/v1/availability?date=2026-10-03&procedure_id=2a9f8b31-6c74-4e05-9d28-a3f1e7b5c06d"

{
  "date": "2026-10-03",
  "slots": [
    {
      "time": "09:00",
      "professional_id": "1f6d5c84-3b92-4a07-8e15-d6c3f9b204ae"
    },
    {
      "time": "10:00",
      "professional_id": "1f6d5c84-3b92-4a07-8e15-d6c3f9b204ae"
    }
  ]
}

La red se cae en mitad de la llamada, se agota el tiempo, y te quedas sin saber si la cita se creó. Repetir por tu cuenta puede reservar al mismo paciente dos veces.

Por eso toda creación viaja con un valor de repetición inventado por ti, uno para cada operación. Si vuelve a llegar con el mismo contenido, Meevia devuelve la respuesta que ya había dado, sin procesar otra vez.

Idempotency-Key

Cómo elegir ese valor

Genera un valor único por operación (un identificador aleatorio sirve) y guárdalo junto a tu intento, para reutilizar exactamente el mismo a la hora de repetir. Generar uno nuevo en cada intento es lo mismo que no tener ninguna protección.

La respuesta guardada vuelve tal como vino, incluso cuando fue un rechazo. Repetir con el valor de un intento que salió mal devuelve el mismo error, no un intento nuevo.

Reutilizar el mismo valor con contenido distinto se rechaza, y ese rechazo suele delatar dos operaciones distintas compartiendo un mismo valor. La misma respuesta aparece cuando una llamada gemela sigue en marcha, y ahí esperar unos instantes y repetir lo resuelve.

El valor vale un día. Después se olvida, y una repetición vuelve a procesarse de verdad.

Un intento que se quedó sin respuesta se da por perdido a los pocos minutos, y la llamada siguiente con ese valor ocupa su lugar. Así una petición que murió a mitad no te bloquea hasta el día siguiente.

Qué pasa al repetir cada llamada

Cada clave tiene su propio tope de llamadas por minuto. Es por clave y no por clínica. Dos integraciones en la misma clínica no se pelean por el mismo límite, y una que disparó llamadas de más no tumba a la otra.

La cuenta se pone a cero al cambiar cada minuto del reloj, y no en una ventana que se desliza. En la práctica, dos ráfagas disparadas justo en el cambio caen en minutos distintos, así que un pico corto puede pasar aunque sumado quede por encima del tope. No es holgura con la que se pueda contar: lo que sostiene una integración es el ritmo medio.

Cuando te pases, la respuesta trae en una cabecera propia, y no en el cuerpo, cuántos segundos esperar. Respeta ese número en vez de reintentar al momento. Si esto se vuelve rutina, el problema no es el tope: espacia las llamadas, guarda una copia de lo que cambia poco (el catálogo cambia poco) y deja de preguntar en bucle.

Retry-After

La API acepta un conjunto cerrado de cambios, y la tabla muestra cuáles: cada estado de origen tiene los destinos que permite, y lo que no está en la tabla se rechaza. Dar por realizada una cita y registrar una ausencia quedan fuera por decisión de producto. Los dos generan venta, cobro y consumo de sesión de bono. Siguen en manos de quien opera la clínica.

Los estados

pre_agendado

Reservada, pero todavía sin confirmación de nadie. Es el estado en el que nace una cita nueva cuando no pides otro.

agendado

Está en la agenda y la clínica cuenta con ella.

confirmado

El paciente confirmó que viene. Es lo que mira recepción para saber con qué contar ese día.

em_espera

Está en la cola, esperando a que se abra un hueco. La API no pone a nadie aquí, pero sí lee a quien está, y desde aquí el único cambio posible es cancelar.

cancelado

Cancelada, y punto final: desde aquí la API ya no cambia nada.

realizado

La consulta ocurrió. Quien lo graba es la clínica, porque el cambio genera la venta. La API lo lee y no lo escribe.

faltou

El paciente no apareció. También es de la clínica: entra en el cobro por ausencia y en el consumo de sesión de bono. La API lo lee y no lo escribe.

Todo rechazo vuelve en el mismo formato, con un código corto que no cambia y un mensaje en portugués. En tu programa, decide siempre por el código, nunca por el mensaje: el mensaje existe para tu registro y puede reescribirse en cualquier momento.