{"openapi":"3.1.0","info":{"title":"Wellbhook API","version":"1.0.0","description":"Consulta de check-ins e eventos. Academia e ambiente são impostos pela chave revogável. Período padrão: hoje e os 29 dias anteriores no fuso de cada unidade. from/to são inclusivos. O parâmetro legado environment é ignorado e nunca altera o ambiente da chave. Filtros desconhecidos são ignorados. Provedores reais dependem de habilitação e homologação."},"servers":[{"url":"https://wellbhook.com.br"}],"externalDocs":{"url":"https://wellbhook.com.br/docs/agents","description":"Skills, plugins e MCP"},"paths":{"/api/v1/checkins":{"get":{"operationId":"listCheckins","summary":"Consultar check-ins","description":"Retorna apenas dados mínimos. APPROVED não comprova passagem por catraca. Mantenha filtros e datas ao paginar; o cursor por ID não é um cursor incremental de sincronização.","tags":["Consulta"],"security":[{"apiKey":[]}],"parameters":[{"name":"unitId","in":"query","required":false,"schema":{"description":"ID da unidade desta academia. Omita para todas as unidades autorizadas.","type":"string","minLength":1,"maxLength":128}},{"name":"provider","in":"query","required":false,"schema":{"type":"string","enum":["WELLHUB","TOTALPASS"]}},{"name":"status","in":"query","required":false,"schema":{"description":"Estado atual do check-in, inclusive para filtrar eventos.","type":"string","enum":["RECEIVED","VALIDATING","APPROVED","REJECTED","EXPIRED","INCONCLUSIVE"]}},{"name":"from","in":"query","required":false,"schema":{"description":"Data inicial inclusiva YYYY-MM-DD no fuso de cada unidade. Padrão: há 29 dias.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"schema":{"description":"Data final inclusiva YYYY-MM-DD no fuso de cada unidade. Padrão: hoje. Período máximo de 367 dias.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"description":"nextCursor da página anterior, mantendo os mesmos filtros.","type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Página de registros autorizados, ordenada por ID ascendente. nextCursor=null indica fim da consulta, sem garantia de snapshot.","headers":{"Cache-Control":{"schema":{"type":"string","const":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Checkin"}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"]}}}},"400":{"description":"Filtros inválidos ou intervalo superior a 367 dias.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida ou revogada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unidade não pertence à academia da chave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite compartilhado REST/MCP de 120 requisições por minuto por chave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","const":60},"description":"Segundos antes da próxima tentativa."}}},"500":{"description":"Falha temporária. Faça retentativas limitadas com atraso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/events":{"get":{"operationId":"listEvents","summary":"Consultar eventos registrados","description":"from/to e status filtram o check-in relacionado, pelo horário de ocorrência e estado atual. Não filtram data ou tipo do evento. Evento registrado não comprova entrega HTTP. Use webhooks para sincronização e consultas por período para reconciliação.","tags":["Consulta"],"security":[{"apiKey":[]}],"parameters":[{"name":"unitId","in":"query","required":false,"schema":{"description":"ID da unidade desta academia. Omita para todas as unidades autorizadas.","type":"string","minLength":1,"maxLength":128}},{"name":"provider","in":"query","required":false,"schema":{"type":"string","enum":["WELLHUB","TOTALPASS"]}},{"name":"status","in":"query","required":false,"schema":{"description":"Estado atual do check-in, inclusive para filtrar eventos.","type":"string","enum":["RECEIVED","VALIDATING","APPROVED","REJECTED","EXPIRED","INCONCLUSIVE"]}},{"name":"from","in":"query","required":false,"schema":{"description":"Data inicial inclusiva YYYY-MM-DD no fuso de cada unidade. Padrão: há 29 dias.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"schema":{"description":"Data final inclusiva YYYY-MM-DD no fuso de cada unidade. Padrão: hoje. Período máximo de 367 dias.","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"description":"nextCursor da página anterior, mantendo os mesmos filtros.","type":"string","minLength":1,"maxLength":128}}],"responses":{"200":{"description":"Página de registros autorizados, ordenada por ID ascendente. nextCursor=null indica fim da consulta, sem garantia de snapshot.","headers":{"Cache-Control":{"schema":{"type":"string","const":"no-store"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"nextCursor":{"type":["string","null"]}},"required":["data","nextCursor"]}}}},"400":{"description":"Filtros inválidos ou intervalo superior a 367 dias.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida ou revogada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unidade não pertence à academia da chave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite compartilhado REST/MCP de 120 requisições por minuto por chave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer","const":60},"description":"Segundos antes da próxima tentativa."}}},"500":{"description":"Falha temporária. Faça retentativas limitadas com atraso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"checkinEvent":{"post":{"summary":"Evento enviado ao destino HTTPS configurado pela academia","description":"Entrega pelo menos uma vez, sem ordem garantida. Deduplicate pelo ID. Valide HMAC-SHA256 sobre timestamp.corpoOriginal antes de parsear JSON, com tolerância de 300 segundos e comparação em tempo constante. Persista antes de responder. Timeout de 10 segundos; até seis tentativas: imediata e intervalos de 1min, 5min, 30min, 2h, 12h. Falha de entrega não desfaz aprovação.","parameters":[{"name":"X-Wellbhook-Signature","in":"header","required":true,"schema":{"type":"string","pattern":"^t=[0-9]+,v1=[a-f0-9]{64}$"}},{"name":"X-Wellbhook-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Wellbhook-Delivery-Id","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEnvelope"}}}},"responses":{"2XX":{"description":"Evento persistido ou duplicata já persistida."},"4XX":{"description":"Evento recusado; Wellbhook tentará novamente até o limite."},"5XX":{"description":"Falha temporária; Wellbhook tentará novamente até o limite."}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"whk_","description":"Chave de consulta gerada no painel. Escopo fixo de academia e ambiente. Não é o segredo HMAC."}},"schemas":{"Checkin":{"type":"object","properties":{"id":{"type":"string"},"unitId":{"type":"string"},"provider":{"type":"string","enum":["WELLHUB","TOTALPASS"]},"environment":{"type":"string","enum":["DEMO","LIVE"]},"personId":{"type":"string"},"personName":{"type":"string"},"status":{"type":"string","enum":["RECEIVED","VALIDATING","APPROVED","REJECTED","EXPIRED","INCONCLUSIVE"]},"reason":{"type":["string","null"]},"occurredAt":{"type":"string","format":"date-time"},"validatedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","unitId","provider","environment","personId","personName","status","reason","occurredAt","validatedAt"]},"WebhookEnvelope":{"type":"object","properties":{"id":{"type":"string"},"version":{"type":"string","const":"1"},"type":{"type":"string","enum":["checkin.received","checkin.approved","checkin.rejected","checkin.expired","checkin.validation_failed"]},"created_at":{"type":"string","format":"date-time"},"environment":{"type":"string","enum":["demo","live"]},"unit_id":{"type":"string"},"provider":{"type":"string","enum":["wellhub","totalpass"]},"data":{"type":"object","properties":{"checkin_id":{"type":"string"},"external_id":{"type":"string"},"person":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"status":{"type":"string","enum":["received","validating","approved","rejected","expired","inconclusive"]},"occurred_at":{"type":"string","format":"date-time"},"validated_at":{"type":["string","null"],"format":"date-time"},"reason":{"type":["string","null"]}},"required":["checkin_id","external_id","person","status","occurred_at","validated_at","reason"]}},"required":["id","version","type","created_at","environment","unit_id","provider","data"]},"Event":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["checkin.received","checkin.approved","checkin.rejected","checkin.expired","checkin.validation_failed"]},"payload":{"$ref":"#/components/schemas/WebhookEnvelope"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","type","payload","createdAt"]},"Error":{"type":"object","properties":{"ok":{"type":"boolean","const":false},"code":{"type":"string","enum":["INVALID_REQUEST","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","CONFLICT","GONE","RATE_LIMITED","REQUEST_FAILED","INTERNAL_ERROR"]},"error":{"type":"string"},"message":{"type":"string"}},"required":["ok","code","error","message"]}}},"x-mcp":{"url":"https://wellbhook.com.br/api/mcp","transport":"streamable-http","authentication":"Bearer API key; no OAuth","tools":["list_checkins","list_events","get_integration_guide"]}}