L'API di Meevia

L'API apre al tuo sistema le parti della clinica che ha senso automatizzare: l'agenda, il catalogo di professionisti e prestazioni, e l'anagrafica di base del paziente. Quello che fai attraverso di essa segue le stesse regole che valgono per chi manda avanti la clinica dentro la piattaforma.

È HTTP con JSON, senza librerie obbligatorie e senza SDK da installare. Se il tuo ambiente sa fare una richiesta e leggere una risposta, sa già parlare con Meevia.

Casi ricorrenti

• Un sito o un'app tua, dove il paziente sceglie l'orario e prenota da solo.
• Un sistema che la clinica già usa e che deve vedere l'agenda del giorno senza che nessuno digiti due volte.
• Automazione interna: un cruscotto tuo, un report, una routine che conferma le presenze.

Cosa deve avere la clinica

L'accesso all'API fa parte del piano della clinica. Se il piano attuale non lo comprende, già la prima chiamata torna rifiutata, e questo non lo risolve nessuna modifica al tuo codice: è una conversazione con il commerciale.

Cosa non c'è ancora

Questa versione legge e scrive l'agenda, e legge catalogo e paziente. Che sia Meevia ad avvisare il tuo sistema quando in clinica succede qualcosa, insieme alla fatturazione e ai pagamenti, non ne fa parte.

La chiave nasce nel pannello sviluppatore, che sta su developers.meevia.app e ha un guscio suo, fuori dal sistema della clinica. È così perché chi realizza l'integrazione spesso non è della clinica. Non esiste alcuna strada, passando dall'API, per creare una chiave. L'interfaccia del pannello è in portoghese brasiliano, quindi i nomi di scheda e di permesso citati qui sotto sono esattamente quelli che leggerai a schermo.

Apri il pannello sviluppatore

1. 1Apri il pannello sviluppatoreL'indirizzo è developers.meevia.app. Chi già lavora dentro il sistema della clinica arriva allo stesso posto da Integrações (Integrazioni), nel riquadro API e Webhooks, che è una porta verso il pannello.
2. 2Entra con il tuo account, oppure chiedi un invitoChi amministra la clinica entra subito. Chi viene da fuori va invitato: nella scheda Acessos (Accessi), chi amministra il pannello invita per e-mail e sceglie tra Somente ver (sola visualizzazione), che consulta e non agisce, e Pode administrar (può amministrare), che emette anche chiavi. Chiedere l'invito è meglio che chiedere la chiave già pronta, perché una chiave che viaggia per messaggio è già uscita.
3. 3Scegli la clinicaIl pannello serve tutte le cliniche a cui hai accesso, e quella scelta in alto è la padrona di tutto ciò che le schede mostrano. Se lavori per più di una, è qui che cambi.
4. 4Nella scheda Chaves (Chiavi), crea una chiave nuovaDalle un nome che dica dove verrà usata. Sei mesi dopo, quel nome è l'unico modo di revocare la chiave giusta senza far cadere l'integrazione sbagliata.
5. 5Scegli il modo e gli ambitiIl modo decide se la chiave tocca la clinica vera o l'ambiente di prova. Gli ambiti decidono cosa può fare. Spunta solo ciò che serve all'integrazione.
6. 6Copia la chiave prima di chiudere la finestraLa chiave completa appare una volta sola, al momento dell'emissione. Meevia conserva il pezzo che la identifica e mai la parte segreta, quindi chiudere senza copiare non ha recupero: revoca la chiave ed emettine un'altra.

Una chiave, una clinica

La chiave vale per la clinica che l'ha emessa, e solo per quella. Se segui più cliniche, sono più chiavi, ciascuna custodita a parte e sostituibile senza toccare le altre. Non esiste una chiave che veda più di una clinica.

Quando revocare

Revocare vale all'istante e non si torna indietro: la chiave smette di funzionare e le sue chiamate iniziano a tornare rifiutate. Fallo quando cambi fornitore, quando spegni un'integrazione e al minimo sospetto di fuga.

Chi può fare cosa

Il ruolo Pode administrar nel pannello apre le due cose che cambiano qualcosa: emettere e revocare chiavi, e riavviare l'ambiente di prova. Si riceve per invito e vale per clinica, quindi chi viene da fuori fa entrambe senza dipendere da nessuno. Riavviare ha una seconda strada: anche chi amministra la clinica riavvia. Chi ha solo Somente ver vede le chiavi e non ne emette nessuna; il pannello lo dice a schermo, invece di nascondere il pulsante.

Ogni chiamata parte autenticata. La chiave viaggia nell'intestazione di autorizzazione, con lo schema che mostra l'esempio, e non c'è altro: niente login, niente sessione, nessun token che scade a metà strada.

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

La chiave è un valore unico, ed è quel valore intero a viaggiare nell'intestazione. Ha tre pezzi incollati: il prefisso dice in che modo sta la chiave, il pezzo centrale la identifica ed è quello che compare nella scheda Chaves del pannello, e l'ultimo è la parte segreta. Quest'ultima Meevia non la conserva mai in chiaro, quindi nemmeno l'assistenza riesce a leggere la tua. Manda sempre la chiave completa: mandare solo la parte segreta è la svista che produce più rifiuti di autorizzazione.

Due modi

Il modo si decide all'emissione e dopo non cambia. In pratica tieni le due chiavi e cambi la variabile d'ambiente per passare da un lato all'altro.

Ogni ambito apre una parte dell'API, e la chiave fa solo quello che i suoi ambiti permettono. La mancanza di un ambito si vede alla prima chiamata che ne ha bisogno, non all'emissione.

Concedi il minimo. Un'integrazione che mostra soltanto l'agenda su uno schermo in sala non ha motivo di poter prenotare appuntamenti. E una chiave essenziale è un danno piccolo il giorno in cui esce.

Gli ambiti non si modificano dopo l'emissione. Allargarli vuol dire emettere una chiave nuova con quello che manca, sostituirla nel tuo ambiente e revocare la vecchia.

La clinica riceve un ambiente di prova tutto suo, isolato dalla clinica vera. La prima chiave di prova emessa lo crea già, quindi non c'è niente da predisporre né da chiedere.

Cosa c'è già dentro

C'è un paziente, una prestazione e un professionista di esempio. Nessuno dei tre esiste nella clinica vera. Gli elenchi di professionisti e di prestazioni restituiscono gli identificativi di quei due, quindi consultare catalogo e orari liberi funziona già alla prima seduta. L'anagrafica è della clinica: dall'API, quello che si crea sono appuntamenti.

Cosa non si riesce a provare qui

L'API scrive in tre punti: creare un appuntamento, cambiarne la situazione e annullarlo. Oggi nessuno dei tre si riesce a esercitare qui, e il motivo arriva a catena. Creare ha bisogno dell'identificativo del paziente, che non compare a schermo né torna da nessuna consultazione, perché non c'è un elenco di pazienti. Cambiare la situazione e annullare hanno bisogno dell'identificativo di un appuntamento, ed esisterebbe solo se creare avesse funzionato: la lista degli appuntamenti qui nasce vuota. Chi deve provare la scrittura lo fa nella clinica vera, con la cura che questo richiede: prenota in un orario vuoto e annulla appena hai visto che ha funzionato.

Come riavviarlo

La scheda Ambiente de teste (Ambiente di prova) del pannello ha un pulsante che butta via l'ambiente attuale e ne consegna un altro, pulito, con gli stessi dati iniziali. Le chiavi di prova già emesse restano valide: sono legate alla clinica, non all'ambiente che è stato buttato via.

Riavviare è di chi ha Pode administrar nel pannello o amministra la clinica. Chi viene da fuori con quel ruolo riavvia da solo, senza dover chiedere a nessuno.

Ogni chiamata parte verso lo stesso indirizzo, ed è uno solo per tutti. Non esiste un indirizzo per clinica: a separare una clinica dall'altra è la chiave, mai l'URL.

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

Noterai un pezzo che sembra ripetuto a metà percorso. È giusto così. Uno è dell'infrastruttura che ospita l'API e l'altro è della versione della nostra. Copia l'indirizzo esattamente come compare qui; togliere la parte che sembra di troppo restituisce una risposta di indirizzo inesistente.

Ci vogliono cinque minuti, contando dall'accesso. Fallo in modo di prova: se qualcosa esce diverso dall'atteso, a pagare è un paziente inventato.

1. 1Emetti una chiave di provaSegui la strada descritta in Come ottenere una chiave, spuntando il modo di prova e l'ambito di lettura del catalogo. Copia la chiave.
2. 2Metti la chiave in una variabile d'ambienteCosì la chiave non resta nella cronologia del terminale né incollata in mezzo al comando che stai per mandare a un collega.
3. 3Chiedi l'elenco dei professionistiÈ la chiamata più semplice di qui: non riceve nessun parametro, e l'ambiente di prova arriva già con un professionista dentro. Se risponde, la tua chiave, il tuo ambito e il tuo indirizzo sono giusti in un colpo solo.
4. 4Guarda cosa è tornatoUna risposta andata a buon fine porta il professionista di prova. Da lì in poi la ricetta è la stessa per tutto il resto: cambia l'indirizzo, l'intestazione resta uguale.

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"
    }
  ]
}

Se non è arrivato quello che ti aspettavi

Confronta quello che è tornato con il catalogo dei rifiuti di questa pagina, che dice cosa è successo e cosa fare in ogni caso. Vale la pena guardare anche la scheda Requisições (Richieste) del pannello, che mostra l'indirizzo chiamato, la risposta e l'orario di ogni chiamata ricevuta. Conserva solo quel riepilogo, mai il contenuto che hai mandato.

Le risposte arrivano incartate sempre allo stesso modo, e ogni chiamata mostra il formato di ciò che restituisce. Programma contro l'involucro e ignora quello che non conosci: col tempo compaiono informazioni nuove, e l'integrazione che ignora ciò che non si aspetta sopravvive a questo senza aver bisogno di te.

Gli involucri

• Un solo record, dentro l'involucro standard.data
• Un elenco, dentro lo stesso involucro.data
• Un elenco a pagine, accompagnato dal marcatore che chiede la successiva.datanext_cursorPuò arrivare senza valore
• Questa risposta esce dallo schema delle altre: porta il giorno consultato accanto agli orari.dateslots
• Il formato di ogni rifiuto, in qualunque chiamata.error

Elenchi lunghi

Gli elenchi arrivano a pagine. La risposta porta un marcatore di continuazione: finché arriva pieno, manda quello stesso marcatore nella chiamata successiva per prendere la pagina dopo. Quando arriva senza valore, è finita. Non provare a indovinare il totale né a costruirti la paginazione per conto tuo.

Cosa porta ogni risposta

Ognuna porta quello che riceve, quello che restituisce e un esempio pronto da incollare nel terminale. Sostituisci gli identificativi dell'esempio con i tuoi.

Elenca gli appuntamenti di un periodo, a pagine.

Ambito richiesto

appointments:readLeggere l'agenda

Ripetizione

Non si applica

Risposta

Appuntamentodatanext_cursorPuò arrivare senza valore

Rifiuti possibili

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
}

Prenota un appuntamento per un paziente, con un professionista, a un orario.

Ambito richiesto

appointments:writeToccare l'agenda

Ripetizione

Richiede il valore di ripetizione

Risposta

Appuntamentodata

Rifiuti possibili

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."
  }
}

Apre un appuntamento preciso.

Ambito richiesto

appointments:readLeggere l'agenda

Ripetizione

Non si applica

Risposta

Appuntamentodata

Rifiuti possibili

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 lo stato di un appuntamento, entro quanto è permesso.

Ambito richiesto

appointments:writeToccare l'agenda

Ripetizione

Sicuro ripeterla

Risposta

Appuntamentodata

Rifiuti possibili

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"
    }
  }
}

Annulla un appuntamento.

Ambito richiesto

appointments:writeToccare l'agenda

Ripetizione

Sicuro ripeterla

Risposta

Appuntamentodata

Rifiuti possibili

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"
  }
}

Apre l'anagrafica di base di un paziente.

Ambito richiesto

patients:readLeggere il paziente

Ripetizione

Non si applica

Risposta

Pazientedata

Rifiuti possibili

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"
  }
}

Elenca i professionisti della clinica.

Ambito richiesto

catalog:readLeggere il catalogo

Ripetizione

Non si applica

Risposta

Professionistadata

Rifiuti possibili

unauthorizedplan_requiredscope_requirednot_foundmethod_not_allowedrate_limitedsandbox_not_readyinternal_error

Questa chiamata non riceve parametri.

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"
    }
  ]
}

Elenca le prestazioni del catalogo.

Ambito richiesto

catalog:readLeggere il catalogo

Ripetizione

Non si applica

Risposta

Prestazionedata

Rifiuti possibili

unauthorizedplan_requiredscope_requirednot_foundmethod_not_allowedrate_limitedsandbox_not_readyinternal_error

Questa chiamata non riceve parametri.

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
    }
  ]
}

Mostra gli orari liberi di una giornata, e si può restringere a un professionista o a una prestazione.

Ambito richiesto

catalog:readLeggere il catalogo

Ripetizione

Non si applica

Risposta

Orario liberodateslots

Rifiuti possibili

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 rete cade in mezzo alla chiamata, il tempo scade, e tu resti senza sapere se l'appuntamento è stato creato. Ripetere per conto tuo può prenotare lo stesso paziente due volte.

Per questo ogni creazione viaggia con un valore di ripetizione inventato da te, uno per ogni operazione. Se arriva di nuovo con lo stesso contenuto, Meevia restituisce la risposta che aveva già dato, senza elaborare una seconda volta.

Idempotency-Key

Come scegliere quel valore

Genera un valore unico per operazione (un identificativo casuale va benissimo) e conservalo insieme al tuo tentativo, così da riusare esattamente lo stesso al momento di ripetere. Generarne uno nuovo a ogni tentativo equivale a non avere nessuna protezione.

La risposta conservata torna com'era, anche quando era un rifiuto. Ripetere con il valore di un tentativo andato male restituisce lo stesso errore, non un tentativo nuovo.

Riusare lo stesso valore con contenuto diverso viene rifiutato, e quel rifiuto di solito smaschera due operazioni distinte che condividono un unico valore. La stessa risposta compare quando una chiamata gemella è ancora in corso, e lì aspettare qualche istante e ripetere risolve.

Il valore vale un giorno. Dopo viene dimenticato, e una ripetizione torna a essere elaborata davvero.

Un tentativo rimasto senza risposta viene dato per perso dopo pochi minuti, e la chiamata successiva con quel valore ne prende il posto. Così una richiesta morta a metà non ti blocca fino al giorno dopo.

Cosa succede ripetendo ogni chiamata

Ogni chiave ha un tetto suo di chiamate al minuto. È per chiave e non per clinica. Due integrazioni nella stessa clinica non si contendono lo stesso limite, e quella che ha sparato troppe chiamate non fa cadere l'altra.

Il conteggio si azzera allo scoccare di ogni minuto dell'orologio, e non su una finestra che scorre. In pratica, due raffiche lanciate a cavallo dello scoccare cadono in minuti diversi, quindi un picco breve può passare anche sommando più del tetto. Non è margine su cui si possa contare: quello che regge un'integrazione è il ritmo medio.

Quando sfori, la risposta porta in un'intestazione dedicata, e non nel corpo, quanti secondi aspettare. Rispetta quel numero invece di riprovare subito. Se diventa abitudine, il problema non è il tetto: distanzia le chiamate, tieni da parte quello che cambia poco (il catalogo cambia poco) ed evita di chiedere in continuazione.

Retry-After

L'API accetta un insieme chiuso di cambi, e la tabella mostra quali: ogni stato di partenza ha le destinazioni che permette, e ciò che non è in tabella viene rifiutato. Segnare l'appuntamento come svolto e registrare un'assenza restano fuori per decisione di prodotto. Entrambi generano vendita, addebito e consumo di una seduta del pacchetto. Restano in mano a chi manda avanti la clinica.

Gli stati

pre_agendado

Prenotato, ma ancora senza conferma di nessuno. È lo stato in cui nasce un appuntamento nuovo quando non ne chiedi un altro.

agendado

È in agenda e la clinica ci conta.

confirmado

Il paziente ha confermato che viene. È quello che la reception guarda per sapere su cosa contare quel giorno.

em_espera

È in coda, in attesa che si liberi un posto. L'API non mette nessuno qui, ma legge chi c'è, e da qui l'unico cambio possibile è annullare.

cancelado

Annullato, e punto: da qui l'API non cambia più niente.

realizado

La visita è avvenuta. A registrarlo è la clinica, perché il cambio genera la vendita. L'API lo legge e non lo scrive.

faltou

Il paziente non si è presentato. Anche questo è della clinica: entra nell'addebito per mancata presenza e nel consumo di una seduta del pacchetto. L'API lo legge e non lo scrive.

Ogni rifiuto torna nello stesso formato, con un codice breve che non cambia e un messaggio in portoghese. Nel tuo programma decidi sempre in base al codice, mai in base al messaggio: il messaggio esiste per il tuo log e può essere riscritto in qualunque momento.