{"openapi":"3.1.0","info":{"title":"Zibox Integration API","version":"0.2.0","description":"API de integração do Zibox (kiosks, apartamentos, comandos, webhooks, chaves). Autentique com `Authorization: Bearer zint_…`. Webhooks (eventos enviados ao seu endpoint) estão documentados no campo `webhooks` deste spec; a verificação da assinatura está no quickstart e no /llms.txt."},"servers":[{"url":"https://api.zibox.com.br","description":"Production"}],"components":{"securitySchemes":{"kioskAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Kiosk API key (must be paired with X-Kiosk-Id header)"},"sessionAuth":{"type":"apiKey","in":"cookie","name":"better-auth.session_token","description":"Better Auth session cookie. Used by /v1/admin/*, /v1/morador/*, /v1/zelador/* when called from the user-facing SPA."},"botToken":{"type":"http","scheme":"bearer","description":"Static bearer token for the WhatsApp chatbot. Used by /bot/* and forwards to /v1/morador/* via the bot-resident shim."}},"schemas":{"MeResponse":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":["string","null"]},"name":{"type":["string","null"]},"role":{"type":["string","null"]},"type":{"type":"string","enum":["user","bot"]},"readOnly":{"type":"boolean"},"is_superadmin":{"type":"boolean"},"is_integrador":{"type":"boolean"},"advanced_filters":{"type":"boolean"},"has_password":{"type":"boolean"}},"required":["id","email","name","role","type","readOnly","is_superadmin","is_integrador","advanced_filters","has_password"]},"phones":{"type":"array","items":{"$ref":"#/components/schemas/MePhone"}},"kiosks":{"type":"array","items":{"$ref":"#/components/schemas/MeKiosk"}},"apartamentos":{"type":"array","items":{"$ref":"#/components/schemas/MeApto"}}},"required":["user","phones","kiosks","apartamentos"]},"SandboxSimEntregaBody":{"type":"object","properties":{"id_apto":{"type":"integer"},"torre":{"type":"string","minLength":1},"tipo":{"type":"string","default":"entrega"}},"required":["id_apto","torre"]},"SandboxSimRetiradaBody":{"type":"object","properties":{"entrega_id":{"type":"integer"}},"required":["entrega_id"]},"SandboxSimStatusBody":{"type":"object","properties":{"online":{"type":"boolean"}},"required":["online"]},"SandboxKeyCreateBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120}},"required":["name"]},"SandboxWebhookCreateBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"url":{"type":"string","maxLength":2000,"format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["entrega.criada","retirada.criada","apartamento.criado","apartamento.atualizado","apartamento.excluido","comando.atualizado","kiosk.online","kiosk.offline"]},"minItems":1}},"required":["name","url","events"]},"SandboxEntrega":{"type":"object","properties":{"id":{"type":"number"},"id_apto":{"type":"number"},"torre":{"type":"string"},"tipo":{"type":["string","null"]},"numero_porta":{"type":["number","null"]},"created_at":{"type":["string","null"]}},"required":["id","id_apto","torre","tipo","numero_porta","created_at"]},"IntegrationWebhook":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"disabled_reason":{"type":["string","null"]},"last_delivery_at":{"type":["string","null"]},"last_delivery_status":{"type":["string","null"]},"is_test":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","url","events","active","disabled_reason","last_delivery_at","last_delivery_status","is_test","created_at","updated_at"]},"IntegrationWebhookCreateBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"url":{"type":"string","maxLength":2000,"format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["entrega.criada","retirada.criada","apartamento.criado","apartamento.atualizado","apartamento.excluido","comando.atualizado","kiosk.online","kiosk.offline"]},"minItems":1}},"required":["name","url","events"]},"IntegrationWebhookCreateResponse":{"allOf":[{"$ref":"#/components/schemas/IntegrationWebhook"},{"type":"object","properties":{"secret_once":{"type":"string","description":"Segredo HMAC, mostrado APENAS na criação. Guarde — não é recuperável."}},"required":["secret_once"]}]},"IntegrationWebhookPatchBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"url":{"type":"string","maxLength":2000,"format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["entrega.criada","retirada.criada","apartamento.criado","apartamento.atualizado","apartamento.excluido","comando.atualizado","kiosk.online","kiosk.offline"]},"minItems":1},"active":{"type":"boolean"}}},"IntegrationWebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event_id":{"type":"string"},"event_type":{"type":["string","null"]},"attempt":{"type":"number"},"status_code":{"type":["number","null"]},"error":{"type":["string","null"]},"duration_ms":{"type":["number","null"]},"created_at":{"type":"string"},"delivered_at":{"type":["string","null"]},"next_retry_at":{"type":["string","null"]}},"required":["id","event_id","event_type","attempt","status_code","error","duration_ms","created_at","delivered_at","next_retry_at"]},"IntegrationKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"secret_prefix":{"type":"string"},"kiosk_ids":{"type":["array","null"],"items":{"type":"string"}},"created_at":{"type":["string","null"]},"expires_at":{"type":["string","null"]},"last_used_at":{"type":["string","null"]},"revoked_at":{"type":["string","null"]},"revoke_reason":{"type":["string","null"]}},"required":["id","name","secret_prefix","kiosk_ids","created_at","expires_at","last_used_at","revoked_at","revoke_reason"]},"IntegrationKeyCreateBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"kiosk_ids":{"type":["array","null"],"items":{"type":"string","minLength":1},"minItems":1},"expires_at":{"type":["string","null"],"format":"date-time"}},"required":["name"]},"IntegrationKeyCreateResponse":{"type":"object","properties":{"key_id":{"type":"string"},"name":{"type":"string"},"secret_once":{"type":"string","description":"Chave em claro — mostrada apenas na criação."},"secret_prefix":{"type":"string"},"kiosk_ids":{"type":["array","null"],"items":{"type":"string"}},"expires_at":{"type":["string","null"]}},"required":["key_id","name","secret_once","secret_prefix","kiosk_ids"]},"IntegrationKiosksResponse":{"type":"object","properties":{"count":{"type":"number"},"kiosks":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationKiosk"}}},"required":["count","kiosks"]},"IntegrationAptosResponse":{"type":"object","properties":{"count":{"type":"number"},"apartamentos":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationApto"}}},"required":["count","apartamentos"]},"IntegrationApto":{"type":"object","properties":{"kiosk_id":{"type":"string"},"id":{"type":"number"},"torre":{"type":"string"},"whatsapp1":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"null"},{"type":"null"}]},"whatsapp2":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"null"},{"type":"null"}]},"whatsapp3":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"null"},{"type":"null"}]},"mensagem_para_entregador":{"type":["string","null"]},"updated_at":{"type":["string","null"]}},"required":["kiosk_id","id","torre"]},"IntegrationAptoPatchBody":{"type":"object","properties":{"whatsapp1":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"null"},{"type":"null"}]},"whatsapp2":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"null"},{"type":"null"}]},"whatsapp3":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"null"},{"type":"null"}]},"senha":{"anyOf":[{"type":"string"},{"type":"number"}]}}},"IntegrationSagaConfirmedResponse":{"type":"object","properties":{"saga_id":{"type":"string"},"status":{"type":"string","enum":["confirmed","superseded"]},"final_state":{"type":["object","null"],"additionalProperties":{}}},"required":["saga_id","status","final_state"]},"IntegrationCommand":{"type":"object","properties":{"id":{"type":"string"},"kiosk_id":{"type":"string"},"command":{"type":"string"},"status":{"type":["string","null"]},"error":{"type":["string","null"]},"params":{"type":["object","null"],"additionalProperties":{}},"result":{},"created_at":{"type":["string","null"]},"issued_at":{"type":["string","null"]},"queued_until":{"type":["string","null"]},"completed_at":{"type":["string","null"]}},"required":["id","kiosk_id","command","status","error","params","created_at","issued_at","queued_until","completed_at"]},"IntegrationEventType":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"data_fields":{"type":"array","items":{"type":"string"}},"subscribable":{"type":"boolean"}},"required":["type","description","data_fields","subscribable"]},"WebhookEvent_entrega_criada":{"type":"object","required":["id","type","kiosk_id","created_at","data"],"properties":{"id":{"type":"string"},"type":{"type":"string","const":"entrega.criada"},"kiosk_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","required":["id","id_apto","torre","tipo"],"properties":{"id":{"type":"integer"},"id_apto":{"type":"integer"},"torre":{"type":"string"},"tipo":{"type":"string"},"numero_porta":{"type":"integer","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true}}}}},"WebhookEvent_retirada_criada":{"type":"object","required":["id","type","kiosk_id","created_at","data"],"properties":{"id":{"type":"string"},"type":{"type":"string","const":"retirada.criada"},"kiosk_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","required":["id","entrega_id","id_apto","torre","tipo"],"properties":{"id":{"type":"integer"},"entrega_id":{"type":"integer"},"id_apto":{"type":"integer"},"torre":{"type":"string"},"tipo":{"type":"string"},"numero_porta":{"type":"integer","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true}}}}},"WebhookEvent_apartamento_criado":{"type":"object","required":["id","type","kiosk_id","created_at","data"],"properties":{"id":{"type":"string"},"type":{"type":"string","const":"apartamento.criado"},"kiosk_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","required":["id","torre"],"properties":{"id":{"type":"integer"},"torre":{"type":"string"},"whatsapp1":{"type":"integer","nullable":true},"whatsapp2":{"type":"integer","nullable":true},"whatsapp3":{"type":"integer","nullable":true}}}}},"WebhookEvent_apartamento_atualizado":{"type":"object","required":["id","type","kiosk_id","created_at","data"],"properties":{"id":{"type":"string"},"type":{"type":"string","const":"apartamento.atualizado"},"kiosk_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","required":["id","torre","changed_fields","senha_alterada"],"properties":{"id":{"type":"integer"},"torre":{"type":"string"},"changed_fields":{"type":"array","items":{"type":"string"}},"whatsapp1":{"type":"integer","nullable":true},"whatsapp2":{"type":"integer","nullable":true},"whatsapp3":{"type":"integer","nullable":true},"senha_alterada":{"type":"boolean"}}}}},"WebhookEvent_apartamento_excluido":{"type":"object","required":["id","type","kiosk_id","created_at","data"],"properties":{"id":{"type":"string"},"type":{"type":"string","const":"apartamento.excluido"},"kiosk_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","required":["id","torre"],"properties":{"id":{"type":"integer"},"torre":{"type":"string"}}}}},"WebhookEvent_comando_atualizado":{"type":"object","required":["id","type","kiosk_id","created_at","data"],"properties":{"id":{"type":"string"},"type":{"type":"string","const":"comando.atualizado"},"kiosk_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","required":["saga_id","command","applied_fields","superseded_fields"],"properties":{"saga_id":{"type":"string"},"command":{"type":"string"},"status":{"type":"string"},"applied_fields":{"type":"array","items":{"type":"string"}},"superseded_fields":{"type":"array","items":{"type":"string"}},"error":{"type":"string","nullable":true}}}}},"WebhookEvent_kiosk_online":{"type":"object","required":["id","type","kiosk_id","created_at","data"],"properties":{"id":{"type":"string"},"type":{"type":"string","const":"kiosk.online"},"kiosk_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","required":["kiosk_id"],"properties":{"kiosk_id":{"type":"string"},"connected_at":{"type":"string","format":"date-time","nullable":true}}}}},"WebhookEvent_kiosk_offline":{"type":"object","required":["id","type","kiosk_id","created_at","data"],"properties":{"id":{"type":"string"},"type":{"type":"string","const":"kiosk.offline"},"kiosk_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","required":["kiosk_id"],"properties":{"kiosk_id":{"type":"string"},"last_seen_at":{"type":"string","format":"date-time","nullable":true}}}}},"IntegrationKiosk":{"type":"object","properties":{"kiosk_id":{"type":"string"},"nome":{"type":["string","null"]},"online":{"type":"boolean"},"last_seen_at":{"type":["string","null"]},"agent_version":{"type":["string","null"]},"is_sandbox":{"type":"boolean"}},"required":["kiosk_id","nome","online","last_seen_at","agent_version","is_sandbox"]},"MePhone":{"type":"object","properties":{"phone":{"type":"string"},"verified":{"type":"boolean"},"primary":{"type":"boolean"}},"required":["phone","verified","primary"]},"MeKiosk":{"type":"object","properties":{"kiosk_id":{"type":"string"},"nome":{"type":["string","null"]},"role":{"type":"string"}},"required":["kiosk_id","nome","role"]},"MeApto":{"type":"object","properties":{"kiosk_id":{"type":"string"},"apto_id":{"type":"number"},"torre":{"type":"string"},"role":{"type":"string"}},"required":["kiosk_id","apto_id","torre","role"]}},"parameters":{}},"paths":{"/v1/me":{"get":{"tags":["Me"],"summary":"Resolved scope for the calling user/bot session","security":[{"sessionAuth":[]},{"botToken":[]}],"responses":{"200":{"description":"Resolved scope (user info, phones, staffed kiosks, apartamentos)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}}}}},"/v1/me/prefs":{"patch":{"tags":["Me"],"summary":"Update the caller UI preferences","security":[{"sessionAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"advanced_filters":{"type":"boolean"}},"required":["advanced_filters"]}}}},"responses":{"200":{"description":"Preferência salva.","content":{"application/json":{"schema":{"type":"object","properties":{"advanced_filters":{"type":"boolean"}},"required":["advanced_filters"]}}}},"403":{"description":"Sessão não é de usuário — body: { error }"}}}},"/v1/me/password":{"post":{"tags":["Me"],"summary":"Set or change the caller login password","security":[{"sessionAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_password":{"type":"string","minLength":10},"current_password":{"type":"string"}},"required":["new_password"]}}}},"responses":{"200":{"description":"Senha definida/trocada.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"has_password":{"type":"boolean"}},"required":["ok","has_password"]}}}},"400":{"description":"Senha atual ausente/incorreta — body: { error }"},"403":{"description":"Sessão não é de usuário — body: { error }"}}}},"/v1/integration/sandbox/simulate/entrega":{"post":{"tags":["Integration: Sandbox"],"summary":"Simula uma nova entrega no armário de teste","security":[{"sessionAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxSimEntregaBody"}}}},"responses":{"201":{"description":"Evento entrega.criada disparado"},"404":{"description":"Sem armário de teste"}}}},"/v1/integration/sandbox/simulate/retirada":{"post":{"tags":["Integration: Sandbox"],"summary":"Simula a retirada de uma entrega existente","security":[{"sessionAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxSimRetiradaBody"}}}},"responses":{"201":{"description":"Evento retirada.criada disparado"},"404":{"description":"Entrega inexistente / sem armário"}}}},"/v1/integration/sandbox/simulate/kiosk-status":{"post":{"tags":["Integration: Sandbox"],"summary":"Simula kiosk.online / kiosk.offline","security":[{"sessionAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxSimStatusBody"}}}},"responses":{"201":{"description":"Evento de status disparado"},"404":{"description":"Sem armário"}}}},"/v1/integration/sandbox/reset":{"post":{"tags":["Integration: Sandbox"],"summary":"Restaura o armário de teste ao estado inicial","security":[{"sessionAuth":[]}],"responses":{"200":{"description":"Armário re-seedado"},"404":{"description":"Sem armário"}}}},"/v1/integration/sandbox/api-keys":{"post":{"tags":["Integration: Sandbox"],"summary":"Gera uma chave zint_test_ (escopo: só o armário de teste)","security":[{"sessionAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxKeyCreateBody"}}}},"responses":{"201":{"description":"Chave criada — capture secret_once agora"},"404":{"description":"Sem armário"}}}},"/v1/integration/sandbox/webhooks":{"post":{"tags":["Integration: Sandbox"],"summary":"Cadastra um webhook de TESTE (is_test) — secret mostrado uma vez","security":[{"sessionAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxWebhookCreateBody"}}}},"responses":{"201":{"description":"Webhook de teste criado — capture secret_once"},"400":{"description":"URL insegura / eventos inválidos"},"404":{"description":"Sem armário de teste"}}}},"/v1/integration/sandbox/entregas":{"get":{"tags":["Integration: Sandbox"],"summary":"Entregas abertas (sem retirada) do armário de teste","security":[{"sessionAuth":[]}],"responses":{"200":{"description":"Entregas que ainda ocupam uma porta (alvos válidos pra simular retirada)","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"entregas":{"type":"array","items":{"$ref":"#/components/schemas/SandboxEntrega"}}},"required":["count","entregas"]}}}},"404":{"description":"Sem armário de teste"}}}},"/v1/integration/webhooks":{"get":{"tags":["Integration: Webhooks"],"summary":"Lista os webhooks da conta (sem secret)","security":[{"sessionAuth":[]}],"responses":{"200":{"description":"Webhooks da conta.","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"webhooks":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationWebhook"}}},"required":["count","webhooks"]}}}}}},"post":{"tags":["Integration: Webhooks"],"summary":"Cadastra um webhook (secret mostrado uma única vez)","security":[{"sessionAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationWebhookCreateBody"}}}},"responses":{"201":{"description":"Webhook criado. Capture `secret_once` agora.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationWebhookCreateResponse"}}}},"400":{"description":"URL insegura (IP privado/local) ou eventos inválidos"}}}},"/v1/integration/webhooks/{id}":{"patch":{"tags":["Integration: Webhooks"],"summary":"Edita nome/url/eventos/ativo","security":[{"sessionAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationWebhookPatchBody"}}}},"responses":{"200":{"description":"Webhook atualizado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationWebhook"}}}},"400":{"description":"URL insegura ou nada para atualizar"},"404":{"description":"Não encontrado (ou de outra conta)"}}},"delete":{"tags":["Integration: Webhooks"],"summary":"Remove um webhook (deliveries caem em cascata)","security":[{"sessionAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Removido — body: { id, deleted: true }"},"404":{"description":"Não encontrado (ou de outra conta)"}}}},"/v1/integration/webhooks/{id}/test":{"post":{"tags":["Integration: Webhooks"],"summary":"Dispara um teste.ping síncrono para o endpoint","security":[{"sessionAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Resultado da entrega — body: { delivered, status_code?, error?, duration_ms }"},"404":{"description":"Não encontrado (ou de outra conta)"}}}},"/v1/integration/webhooks/{id}/deliveries":{"get":{"tags":["Integration: Webhooks"],"summary":"Log de tentativas de entrega deste webhook","security":[{"sessionAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Tentativas mais recentes primeiro.","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationWebhookDelivery"}}},"required":["count","deliveries"]}}}},"404":{"description":"Não encontrado (ou de outra conta)"}}}},"/v1/integration/api-keys":{"get":{"tags":["Integration: API Keys"],"summary":"Lista as chaves zint_ da conta","security":[{"sessionAuth":[]}],"responses":{"200":{"description":"Chaves da conta (sem o segredo).","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"keys":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationKey"}}},"required":["count","keys"]}}}}}},"post":{"tags":["Integration: API Keys"],"summary":"Cria uma chave zint_ (escopo ⊆ conta, validado server-side)","security":[{"sessionAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationKeyCreateBody"}}}},"responses":{"201":{"description":"Chave criada. Capture `secret_once` agora — não é recuperável.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationKeyCreateResponse"}}}},"400":{"description":"kiosk_ids fora do escopo da conta — body: { error, kiosk_id }"}}}},"/v1/integration/api-keys/{id}/revoke":{"post":{"tags":["Integration: API Keys"],"summary":"Revoga uma chave da conta","security":[{"sessionAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"]}}}},"responses":{"200":{"description":"Revogada — body: { id, revoked_at }"},"404":{"description":"Não encontrada, de outra conta, não-zint_ ou já revogada"}}}},"/v1/integration/kiosks":{"get":{"tags":["Integration"],"summary":"Kiosks do escopo da conta (∩ whitelist da chave)","security":[{"sessionAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["test","live"]},"required":false,"name":"mode","in":"query"}],"responses":{"200":{"description":"Kiosks visíveis para esta credencial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationKiosksResponse"}}}}}}},"/v1/integration/kiosks/{id}/aptos":{"get":{"tags":["Integration"],"summary":"Apartamentos do kiosk (sem senha)","security":[{"sessionAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Lista de apartamentos. `senha` nunca é retornada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationAptosResponse"}}}},"403":{"description":"Kiosk fora do escopo da conta/chave — body: { error: string }"}}}},"/v1/integration/kiosks/{id}/aptos/{torre}/{aptoId}":{"get":{"tags":["Integration"],"summary":"Detalhe de um apartamento (sem senha)","security":[{"sessionAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"torre","in":"path"},{"schema":{"type":["integer","null"]},"required":false,"name":"aptoId","in":"path"}],"responses":{"200":{"description":"Apartamento. `senha` nunca é retornada.","content":{"application/json":{"schema":{"type":"object","properties":{"apto":{"$ref":"#/components/schemas/IntegrationApto"}},"required":["apto"]}}}},"403":{"description":"Kiosk fora do escopo"},"404":{"description":"Apto não encontrado"}}},"patch":{"tags":["Integration"],"summary":"Altera telefones/senha de um apartamento (saga; enfileira se offline)","description":"Online → 200 confirmed/superseded com final_state (sem senha). Offline elegível → 202 queued. Offline inelegível → 502 kiosk_offline (queue_supported: false). Fila cheia → 429 queue_full.","security":[{"sessionAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"torre","in":"path"},{"schema":{"type":["integer","null"]},"required":false,"name":"aptoId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationAptoPatchBody"}}}},"responses":{"200":{"description":"Saga confirmada (confirmed) ou no-op LWW (superseded) — ambas sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationSagaConfirmedResponse"}}}},"202":{"description":"Kiosk offline e elegível — body: { saga_id, status: \"queued\" }"},"400":{"description":"Body vazio, telefone fora do formato 55+DDD+9dígitos ou senha inválida"},"403":{"description":"Kiosk fora do escopo"},"404":{"description":"Apto não encontrado"},"429":{"description":"Fila do kiosk cheia — body: { error: \"queue_full\", queue_supported: true }"},"502":{"description":"Kiosk offline inelegível ({ error: \"kiosk_offline\", queue_supported: false }) ou saga falhou ({ saga_id, status, error })"}}}},"/v1/integration/commands":{"get":{"tags":["Integration"],"summary":"Histórico de comandos desta conta","security":[{"sessionAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"kiosk_id","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Comandos iniciados por esta conta, mais recentes primeiro.","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"commands":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationCommand"}}},"required":["count","commands"]}}}}}}},"/v1/integration/commands/{sagaId}":{"get":{"tags":["Integration"],"summary":"Status de um comando","security":[{"sessionAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"sagaId","in":"path"}],"responses":{"200":{"description":"Comando (params/final_state sem senha).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationCommand"}}}},"404":{"description":"Não encontrado ou de outra conta (sem distinção, anti-enumeração)"}}},"delete":{"tags":["Integration"],"summary":"Cancela um comando ainda na fila (status queued)","security":[{"sessionAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"sagaId","in":"path"}],"responses":{"200":{"description":"Cancelado — body: { saga_id, status: \"cancelled\" }"},"404":{"description":"Não encontrado ou de outra conta"},"409":{"description":"Saga não está mais na fila (já drenada/terminal)"}}}},"/v1/integration/event-types":{"get":{"tags":["Integration"],"summary":"Catálogo de eventos de webhook","security":[{"sessionAuth":[]}],"responses":{"200":{"description":"Catálogo v1. teste.ping não é assinável (só endpoint de teste).","content":{"application/json":{"schema":{"type":"object","properties":{"event_types":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationEventType"}}},"required":["event_types"]}}}}}}}},"webhooks":{"entrega.criada":{"post":{"summary":"Nova entrega registrada no armário","description":"Disparado quando um entregador deposita um pacote em uma porta do armário. O header `X-Zibox-Signature` contém `t=<unix_seconds>,v1=<hex>` onde v1 = HMAC-SHA256(whsec_…, `${t}.${rawBody}`). Valide com tolerância de ~5 min (anti-replay). Entrega é at-least-once — deduplique pelo campo `id` do envelope.","parameters":[{"name":"X-Zibox-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hmac sha256 hex>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent_entrega_criada"},"example":{"id":"evt_8kQ2mZpY3nR7","type":"entrega.criada","kiosk_id":"ED_SKYHOUSE","created_at":"2026-06-12T17:32:42.045Z","data":{"id":4821,"id_apto":13,"torre":"Única","tipo":"entrega","numero_porta":7,"created_at":"2026-06-12T17:32:41.900Z"}}}}},"responses":{"2XX":{"description":"Evento recebido. Responda 2xx em até 10s; qualquer outra resposta agenda retry (backoff até 24h)."}}}},"retirada.criada":{"post":{"summary":"Retirada de pacote registrada no armário","description":"Disparado quando um morador retira um pacote do armário. O header `X-Zibox-Signature` contém `t=<unix_seconds>,v1=<hex>` onde v1 = HMAC-SHA256(whsec_…, `${t}.${rawBody}`). Valide com tolerância de ~5 min (anti-replay). Entrega é at-least-once — deduplique pelo campo `id` do envelope.","parameters":[{"name":"X-Zibox-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hmac sha256 hex>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent_retirada_criada"},"example":{"id":"evt_8kQ2mZpY3nR7","type":"retirada.criada","kiosk_id":"ED_SKYHOUSE","created_at":"2026-06-12T17:32:42.045Z","data":{"id":991,"entrega_id":4821,"id_apto":13,"torre":"Única","tipo":"retirada","numero_porta":7,"created_at":"2026-06-12T18:05:00.000Z"}}}}},"responses":{"2XX":{"description":"Evento recebido. Responda 2xx em até 10s; qualquer outra resposta agenda retry (backoff até 24h)."}}}},"apartamento.criado":{"post":{"summary":"Novo apartamento cadastrado no armário","description":"Disparado quando um apartamento é criado no kiosk. O header `X-Zibox-Signature` contém `t=<unix_seconds>,v1=<hex>` onde v1 = HMAC-SHA256(whsec_…, `${t}.${rawBody}`). Valide com tolerância de ~5 min (anti-replay). Entrega é at-least-once — deduplique pelo campo `id` do envelope.","parameters":[{"name":"X-Zibox-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hmac sha256 hex>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent_apartamento_criado"},"example":{"id":"evt_8kQ2mZpY3nR7","type":"apartamento.criado","kiosk_id":"ED_SKYHOUSE","created_at":"2026-06-12T17:32:42.045Z","data":{"id":13,"torre":"Única","whatsapp1":5511994826486,"whatsapp2":null,"whatsapp3":null}}}}},"responses":{"2XX":{"description":"Evento recebido. Responda 2xx em até 10s; qualquer outra resposta agenda retry (backoff até 24h)."}}}},"apartamento.atualizado":{"post":{"summary":"Apartamento atualizado (telefones ou senha)","description":"Disparado quando telefones, senha ou mensagem de um apartamento mudam. `changed_fields` lista os campos alterados; `senha_alterada: true` indica que a senha mudou (o valor da senha nunca aparece no payload). O header `X-Zibox-Signature` contém `t=<unix_seconds>,v1=<hex>` onde v1 = HMAC-SHA256(whsec_…, `${t}.${rawBody}`). Valide com tolerância de ~5 min (anti-replay). Entrega é at-least-once — deduplique pelo campo `id` do envelope.","parameters":[{"name":"X-Zibox-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hmac sha256 hex>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent_apartamento_atualizado"},"example":{"id":"evt_8kQ2mZpY3nR7","type":"apartamento.atualizado","kiosk_id":"ED_SKYHOUSE","created_at":"2026-06-12T17:32:42.045Z","data":{"id":13,"torre":"Única","changed_fields":["whatsapp2","senha"],"whatsapp1":5511994826486,"whatsapp2":5511988887777,"whatsapp3":null,"senha_alterada":true}}}}},"responses":{"2XX":{"description":"Evento recebido. Responda 2xx em até 10s; qualquer outra resposta agenda retry (backoff até 24h)."}}}},"apartamento.excluido":{"post":{"summary":"Apartamento excluído do armário","description":"Disparado quando um apartamento é removido do kiosk. O header `X-Zibox-Signature` contém `t=<unix_seconds>,v1=<hex>` onde v1 = HMAC-SHA256(whsec_…, `${t}.${rawBody}`). Valide com tolerância de ~5 min (anti-replay). Entrega é at-least-once — deduplique pelo campo `id` do envelope.","parameters":[{"name":"X-Zibox-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hmac sha256 hex>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent_apartamento_excluido"},"example":{"id":"evt_8kQ2mZpY3nR7","type":"apartamento.excluido","kiosk_id":"ED_SKYHOUSE","created_at":"2026-06-12T17:32:42.045Z","data":{"id":13,"torre":"Única"}}}}},"responses":{"2XX":{"description":"Evento recebido. Responda 2xx em até 10s; qualquer outra resposta agenda retry (backoff até 24h)."}}}},"comando.atualizado":{"post":{"summary":"Comando de integração mudou de status","description":"Disparado quando um saga iniciado via API de integração (ou enfileirado) muda para um estado terminal ou intermediário. `status` pode ser `confirmed`, `timeout`, `failed`, `rolled_back` ou `queued`. O header `X-Zibox-Signature` contém `t=<unix_seconds>,v1=<hex>` onde v1 = HMAC-SHA256(whsec_…, `${t}.${rawBody}`). Valide com tolerância de ~5 min (anti-replay). Entrega é at-least-once — deduplique pelo campo `id` do envelope.","parameters":[{"name":"X-Zibox-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hmac sha256 hex>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent_comando_atualizado"},"example":{"id":"evt_8kQ2mZpY3nR7","type":"comando.atualizado","kiosk_id":"ED_SKYHOUSE","created_at":"2026-06-12T17:32:42.045Z","data":{"saga_id":"f593b867-4268-4a4b-a1b2-96f9e1566838","command":"update_apartamento","status":"confirmed","applied_fields":["whatsapp2"],"superseded_fields":[],"error":null}}}}},"responses":{"2XX":{"description":"Evento recebido. Responda 2xx em até 10s; qualquer outra resposta agenda retry (backoff até 24h)."}}}},"kiosk.online":{"post":{"summary":"Kiosk conectou (SSE)","description":"Disparado quando o kiosk estabelece conexão SSE com a Central. Pode oscilar em reconexões — considere debounce no consumidor. O header `X-Zibox-Signature` contém `t=<unix_seconds>,v1=<hex>` onde v1 = HMAC-SHA256(whsec_…, `${t}.${rawBody}`). Valide com tolerância de ~5 min (anti-replay). Entrega é at-least-once — deduplique pelo campo `id` do envelope.","parameters":[{"name":"X-Zibox-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hmac sha256 hex>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent_kiosk_online"},"example":{"id":"evt_8kQ2mZpY3nR7","type":"kiosk.online","kiosk_id":"ED_SKYHOUSE","created_at":"2026-06-12T17:32:42.045Z","data":{"kiosk_id":"ED_SKYHOUSE","connected_at":"2026-06-12T17:30:00.000Z"}}}}},"responses":{"2XX":{"description":"Evento recebido. Responda 2xx em até 10s; qualquer outra resposta agenda retry (backoff até 24h)."}}}},"kiosk.offline":{"post":{"summary":"Kiosk desconectou (SSE)","description":"Disparado quando a conexão SSE do kiosk cai. Pode oscilar em reconexões — considere debounce no consumidor. O header `X-Zibox-Signature` contém `t=<unix_seconds>,v1=<hex>` onde v1 = HMAC-SHA256(whsec_…, `${t}.${rawBody}`). Valide com tolerância de ~5 min (anti-replay). Entrega é at-least-once — deduplique pelo campo `id` do envelope.","parameters":[{"name":"X-Zibox-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hmac sha256 hex>"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent_kiosk_offline"},"example":{"id":"evt_8kQ2mZpY3nR7","type":"kiosk.offline","kiosk_id":"ED_SKYHOUSE","created_at":"2026-06-12T17:32:42.045Z","data":{"kiosk_id":"ED_SKYHOUSE","last_seen_at":"2026-06-12T18:05:12.000Z"}}}}},"responses":{"2XX":{"description":"Evento recebido. Responda 2xx em até 10s; qualquer outra resposta agenda retry (backoff até 24h)."}}}}}}