{"openapi":"3.1.0","info":{"title":"API de marcações (demonstração)","version":"2.0.0","summary":"Projeto demonstrativo da 2k3software, com dados fictícios.","description":"API REST de marcações para um estúdio fictício com um único profissional. Cada chave abre uma caixa de areia privada com serviços e marcações de exemplo, que se apaga ao fim de 24 horas. Horas em RFC 3339, no fuso de Lisboa. Erros no formato Problem Details (RFC 9457). Não use dados pessoais reais.","contact":{"name":"2k3software","url":"https://2k3software.com/#contacto"}},"servers":[{"url":"https://api-demo.2k3software.com"}],"tags":[{"name":"keys","description":"Chaves de demonstração e estado da caixa de areia."},{"name":"catalog","description":"Serviços e horas livres."},{"name":"bookings","description":"Criar, consultar, alterar e cancelar marcações."}],"security":[{"bearer":[]}],"paths":{"/v1/health":{"get":{"operationId":"health","tags":["keys"],"security":[],"summary":"Estado do serviço","description":"Não precisa de chave.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"version":{"type":"string"},"time":{"type":"string","format":"date-time"}}}}}}}}},"/v1/keys":{"post":{"operationId":"createKey","tags":["keys"],"security":[],"summary":"Pedir uma chave de demonstração","description":"Cria uma caixa de areia com 3 serviços e 3 marcações de exemplo. A chave dura 24 horas; depois, tudo é apagado. Limite: 5 chaves por minuto por IP.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"locale":{"type":"string","enum":["pt","en"],"description":"Idioma dos nomes e das mensagens de erro."}}},"example":{"locale":"pt"}}}},"responses":{"201":{"description":"Chave criada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Key"}}}},"422":{"$ref":"#/components/responses/Validation"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/me":{"get":{"operationId":"me","tags":["keys"],"summary":"Estado da minha caixa de areia","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/services":{"get":{"operationId":"listServices","tags":["catalog"],"summary":"Listar serviços","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Service"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/availability":{"get":{"operationId":"availability","tags":["catalog"],"summary":"Horas livres de um serviço num dia","description":"Horário: segunda a sexta 9h-13h e 14h-18h, sábado 9h-13h (hora de Lisboa), em blocos de 30 minutos.","parameters":[{"name":"service_id","in":"query","required":true,"schema":{"type":"string"},"example":"srv_consulta"},{"name":"date","in":"query","required":true,"description":"Dia local, AAAA-MM-DD.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Availability"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/Validation"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/bookings":{"get":{"operationId":"listBookings","tags":["bookings"],"summary":"Listar marcações","description":"Ordenadas por hora de início, com paginação por cursor.","parameters":[{"name":"from","in":"query","description":"Primeiro dia (por omissão, hoje).","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","description":"Último dia, inclusive (por omissão, from + 30 dias; máximo 62 dias).","schema":{"type":"string","format":"date"}},{"name":"status","in":"query","schema":{"type":"string","enum":["confirmed","cancelled"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","description":"O next_cursor da página anterior.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Booking"}},"next_cursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/Validation"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"createBooking","tags":["bookings"],"summary":"Criar uma marcação","description":"Tem de caber no horário e não se pode sobrepor a outra marcação confirmada. Com o cabeçalho Idempotency-Key, repetir o mesmo pedido devolve a mesma marcação em vez de criar outra.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Opcional. 8 a 64 letras, números, - ou _.","example":"pedido-0001","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingInput"},"example":{"service_id":"srv_consulta","start":"2026-12-01T10:00:00Z","customer":{"name":"Cliente Exemplo"},"notes":"Primeira visita."}}}},"responses":{"201":{"description":"Marcação criada","headers":{"Location":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"},"415":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Validation"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/bookings/{id}":{"get":{"operationId":"getBooking","tags":["bookings"],"parameters":[{"name":"id","in":"path","required":true,"description":"Id da marcação, ex.: bk_k7m2p9qa.","schema":{"type":"string","pattern":"^bk_[a-z0-9]+$"}}],"summary":"Ver uma marcação","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"updateBooking","tags":["bookings"],"parameters":[{"name":"id","in":"path","required":true,"description":"Id da marcação, ex.: bk_k7m2p9qa.","schema":{"type":"string","pattern":"^bk_[a-z0-9]+$"}}],"summary":"Alterar uma marcação","description":"Mudar a hora (remarcar), o nome ou as notas. O serviço não muda; para isso, cancele e crie outra.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingPatch"},"example":{"start":"2026-12-01T11:00:00Z"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Validation"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/bookings/{id}/cancel":{"post":{"operationId":"cancelBooking","tags":["bookings"],"parameters":[{"name":"id","in":"path","required":true,"description":"Id da marcação, ex.: bk_k7m2p9qa.","schema":{"type":"string","pattern":"^bk_[a-z0-9]+$"}}],"summary":"Cancelar uma marcação","description":"A marcação fica com status cancelled e o horário volta a ficar livre.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Chave de POST /v1/keys."}},"schemas":{"Key":{"type":"object","properties":{"key":{"type":"string","example":"demo_..."},"expires_at":{"type":"string","format":"date-time"},"locale":{"type":"string"},"note":{"type":"string"}}},"Me":{"type":"object","properties":{"locale":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"bookings":{"type":"integer"},"limits":{"type":"object"}}},"Service":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"duration_minutes":{"type":"integer"}}},"Slot":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"Availability":{"type":"object","properties":{"service_id":{"type":"string"},"date":{"type":"string","format":"date"},"timezone":{"type":"string"},"closed":{"type":"boolean"},"slots":{"type":"array","items":{"$ref":"#/components/schemas/Slot"}}}},"Booking":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["confirmed","cancelled"]},"service":{"$ref":"#/components/schemas/Service"},"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"},"customer":{"type":"object","properties":{"name":{"type":"string"}}},"notes":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"cancelled_at":{"type":["string","null"],"format":"date-time"}}},"BookingInput":{"type":"object","additionalProperties":false,"required":["service_id","start","customer"],"properties":{"service_id":{"type":"string"},"start":{"type":"string","format":"date-time","description":"RFC 3339 com fuso. Horas certas ou meias horas."},"customer":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","minLength":2,"maxLength":60,"description":"Nome fictício. Emails e telefones são recusados."}}},"notes":{"type":["string","null"],"maxLength":280}}},"BookingPatch":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"start":{"type":"string","format":"date-time"},"customer":{"$ref":"#/components/schemas/BookingInput/properties/customer"},"notes":{"type":["string","null"],"maxLength":280}}},"Problem":{"type":"object","description":"RFC 9457","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}},"request_id":{"type":"string"}}}},"responses":{"BadRequest":{"description":"JSON inválido ou tipo de conteúdo errado","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unauthorized":{"description":"Falta a chave, ou é inválida ou expirou","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"Marcação não encontrada","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Conflict":{"description":"Horário ocupado, marcação cancelada ou caixa de areia cheia","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Validation":{"description":"Campos inválidos (lista em errors)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"RateLimited":{"description":"Demasiados pedidos (60 por minuto por chave)","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}