{
  "openapi": "3.1.0",
  "info": {
    "title": "Citin Connect",
    "version": "1.1.0",
    "description": "API do Citin para sites e sistemas de parceiros: acomodações, disponibilidade, preço da tabela de venda direta e pré-reservas. Chamadas SEMPRE servidor a servidor: a chave nunca vai para o navegador. Guia completo: https://citin.com.br/desenvolvedores/guia.md"
  },
  "servers": [
    {
      "url": "https://citin.com.br/api/externo/v1",
      "description": "Produção"
    }
  ],
  "security": [
    {
      "chaveCitin": []
    }
  ],
  "tags": [
    {
      "name": "Propriedade",
      "description": "A hospedagem ligada à chave."
    },
    {
      "name": "Acomodações",
      "description": "O que a hospedagem liberou para este site."
    },
    {
      "name": "Disponibilidade",
      "description": "Calendário e cotação, sempre com o preço da tabela do Citin."
    },
    {
      "name": "Reservas",
      "description": "Pré-reservas: seguram as datas até a hospedagem confirmar."
    }
  ],
  "paths": {
    "/propriedade": {
      "get": {
        "tags": [
          "Propriedade"
        ],
        "operationId": "lerPropriedade",
        "summary": "Dados da hospedagem e regras da pré-reserva",
        "description": "Escopo: `consulta`.",
        "responses": {
          "200": {
            "description": "Dados da hospedagem.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "sucesso",
                    "dados"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "sucesso": {
                      "const": true
                    },
                    "dados": {
                      "$ref": "#/components/schemas/Propriedade"
                    }
                  }
                },
                "example": {
                  "sucesso": true,
                  "dados": {
                    "nome": "Pousada Exemplo",
                    "fuso": "America/Sao_Paulo",
                    "moeda": "BRL",
                    "checkinHora": "14:00",
                    "checkoutHora": "11:00",
                    "prazoPreReservaHoras": 24,
                    "criancaGratisAteIdade": 5
                  }
                }
              }
            }
          },
          "401": {
            "description": "Chave ausente, malformada, revogada ou inexistente (credencial_invalida, sempre a mesma resposta) ou vencida (credencial_vencida: a hospedagem muda a validade ou gera outra). Códigos possíveis: credencial_invalida, credencial_vencida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "A chave não pode fazer isto agora. `integracao_indisponivel` é genérico de propósito: a hospedagem vê o motivo no Citin. Códigos possíveis: escopo_insuficiente, uso_no_navegador, ip_nao_permitido, integracao_indisponivel.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite de pedidos por minuto atingido. Respeite o cabeçalho Retry-After. Códigos possíveis: limite_excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "500": {
            "description": "Erro do Citin. Tente de novo em instantes; se repetir, avise a hospedagem. Códigos possíveis: erro_interno.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/acomodacoes": {
      "get": {
        "tags": [
          "Acomodações"
        ],
        "operationId": "listarAcomodacoes",
        "summary": "Acomodações liberadas para este site",
        "description": "Escopo: `consulta`. Só aparece o que a hospedagem vinculou à integração. Um `grupo` reúne unidades iguais: o Citin escolhe a unidade livre na hora da pré-reserva.",
        "responses": {
          "200": {
            "description": "Lista (pode ser vazia).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "sucesso",
                    "dados"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "sucesso": {
                      "const": true
                    },
                    "dados": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Acomodacao"
                      }
                    }
                  }
                },
                "example": {
                  "sucesso": true,
                  "dados": [
                    {
                      "id": "acm_7Hq2kLm9PxR4tWz8",
                      "nome": "Apto 301",
                      "tipo": "unidade",
                      "capacidade": {
                        "base": 2,
                        "maxima": 4
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Chave ausente, malformada, revogada ou inexistente (credencial_invalida, sempre a mesma resposta) ou vencida (credencial_vencida: a hospedagem muda a validade ou gera outra). Códigos possíveis: credencial_invalida, credencial_vencida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "A chave não pode fazer isto agora. `integracao_indisponivel` é genérico de propósito: a hospedagem vê o motivo no Citin. Códigos possíveis: escopo_insuficiente, uso_no_navegador, ip_nao_permitido, integracao_indisponivel.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite de pedidos por minuto atingido. Respeite o cabeçalho Retry-After. Códigos possíveis: limite_excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "500": {
            "description": "Erro do Citin. Tente de novo em instantes; se repetir, avise a hospedagem. Códigos possíveis: erro_interno.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/acomodacoes/{id}": {
      "get": {
        "tags": [
          "Acomodações"
        ],
        "operationId": "lerAcomodacao",
        "summary": "Uma acomodação",
        "description": "Escopo: `consulta`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Código público da acomodação (acm_…), o mesmo que o site guarda no seu cadastro.",
            "schema": {
              "type": "string",
              "pattern": "^acm_[A-Za-z0-9]{16}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A acomodação.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "sucesso",
                    "dados"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "sucesso": {
                      "const": true
                    },
                    "dados": {
                      "$ref": "#/components/schemas/Acomodacao"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Chave ausente, malformada, revogada ou inexistente (credencial_invalida, sempre a mesma resposta) ou vencida (credencial_vencida: a hospedagem muda a validade ou gera outra). Códigos possíveis: credencial_invalida, credencial_vencida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "A chave não pode fazer isto agora. `integracao_indisponivel` é genérico de propósito: a hospedagem vê o motivo no Citin. Códigos possíveis: escopo_insuficiente, uso_no_navegador, ip_nao_permitido, integracao_indisponivel.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "404": {
            "description": "Código inexistente, de outra integração ou retirado do site (mesma resposta). Códigos possíveis: nao_encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite de pedidos por minuto atingido. Respeite o cabeçalho Retry-After. Códigos possíveis: limite_excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "500": {
            "description": "Erro do Citin. Tente de novo em instantes; se repetir, avise a hospedagem. Códigos possíveis: erro_interno.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/acomodacoes/{id}/calendario": {
      "get": {
        "tags": [
          "Disponibilidade"
        ],
        "operationId": "lerCalendario",
        "summary": "Noites livres, diária e regras de estadia",
        "description": "Escopo: `consulta`. Janela de até 186 noites, a partir de hoje (no fuso da hospedagem) e até 500 dias à frente. Indicativo: quem decide é a cotação ou a criação da reserva. Pode ficar em cache por até 60 s.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Código público da acomodação (acm_…), o mesmo que o site guarda no seu cadastro.",
            "schema": {
              "type": "string",
              "pattern": "^acm_[A-Za-z0-9]{16}$"
            }
          },
          {
            "name": "de",
            "in": "query",
            "required": true,
            "description": "Primeira noite (AAAA-MM-DD).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "ate",
            "in": "query",
            "required": true,
            "description": "Dia da saída, exclusivo (AAAA-MM-DD).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Uma entrada por noite.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "sucesso",
                    "dados"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "sucesso": {
                      "const": true
                    },
                    "dados": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Noite"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Datas ausentes ou fora do formato. Códigos possíveis: requisicao_invalida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "401": {
            "description": "Chave ausente, malformada, revogada ou inexistente (credencial_invalida, sempre a mesma resposta) ou vencida (credencial_vencida: a hospedagem muda a validade ou gera outra). Códigos possíveis: credencial_invalida, credencial_vencida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "A chave não pode fazer isto agora. `integracao_indisponivel` é genérico de propósito: a hospedagem vê o motivo no Citin. Códigos possíveis: escopo_insuficiente, uso_no_navegador, ip_nao_permitido, integracao_indisponivel.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "404": {
            "description": "Acomodação inexistente ou não liberada. Códigos possíveis: nao_encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "422": {
            "description": "Janela inválida (passado, longa demais ou longe demais). Códigos possíveis: datas_invalidas.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite de pedidos por minuto atingido. Respeite o cabeçalho Retry-After. Códigos possíveis: limite_excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "500": {
            "description": "Erro do Citin. Tente de novo em instantes; se repetir, avise a hospedagem. Códigos possíveis: erro_interno.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/acomodacoes/{id}/cotacao": {
      "get": {
        "tags": [
          "Disponibilidade"
        ],
        "operationId": "cotarEstadia",
        "summary": "Preço e disponibilidade de uma estadia",
        "description": "Escopo: `consulta`. O preço é sempre o da tabela de venda direta do Citin. Validação nesta ordem: datas, hóspedes, capacidade, regras da estadia (422 `regra_estadia`), preço (422 `sem_preco`) e, por fim, a disponibilidade (`disponivel: false`).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Código público da acomodação (acm_…), o mesmo que o site guarda no seu cadastro.",
            "schema": {
              "type": "string",
              "pattern": "^acm_[A-Za-z0-9]{16}$"
            }
          },
          {
            "name": "entrada",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "saida",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "adultos",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "criancas",
            "in": "query",
            "required": false,
            "description": "Idade de cada criança, separadas por vírgula (ex.: 4,9).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Cotação.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "sucesso",
                    "dados"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "sucesso": {
                      "const": true
                    },
                    "dados": {
                      "$ref": "#/components/schemas/Cotacao"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parâmetro ausente ou inválido (vem com `campo`). Códigos possíveis: requisicao_invalida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "401": {
            "description": "Chave ausente, malformada, revogada ou inexistente (credencial_invalida, sempre a mesma resposta) ou vencida (credencial_vencida: a hospedagem muda a validade ou gera outra). Códigos possíveis: credencial_invalida, credencial_vencida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "A chave não pode fazer isto agora. `integracao_indisponivel` é genérico de propósito: a hospedagem vê o motivo no Citin. Códigos possíveis: escopo_insuficiente, uso_no_navegador, ip_nao_permitido, integracao_indisponivel.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "404": {
            "description": "Acomodação inexistente ou não liberada. Códigos possíveis: nao_encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "422": {
            "description": "Estadia não vendável pelo site. Códigos possíveis: regra_estadia, capacidade, sem_preco, datas_invalidas.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite de pedidos por minuto atingido. Respeite o cabeçalho Retry-After. Códigos possíveis: limite_excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "500": {
            "description": "Erro do Citin. Tente de novo em instantes; se repetir, avise a hospedagem. Códigos possíveis: erro_interno.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/reservas": {
      "get": {
        "tags": [
          "Reservas"
        ],
        "operationId": "listarReservas",
        "summary": "Lista as pré-reservas deste site alteradas desde um ponto",
        "description": "Escopo: `reservas.ler`. Só reservas criadas por esta integração, da mais antiga alteração para a mais nova. Comece sem `alteradasDesde`; guarde o `proximoCursor` e use-o na chamada seguinte. O cursor é opaco. Uma reserva reaparece sempre que a hospedagem a muda (confirma, altera, cancela). Sem webhook: consulte de tempos em tempos.",
        "parameters": [
          {
            "name": "alteradasDesde",
            "in": "query",
            "required": false,
            "description": "O `proximoCursor` da chamada anterior.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limite",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Página de reservas.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "sucesso",
                    "dados"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "sucesso": {
                      "const": true
                    },
                    "dados": {
                      "type": "object",
                      "required": [
                        "itens",
                        "proximoCursor"
                      ],
                      "additionalProperties": false,
                      "properties": {
                        "itens": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Reserva"
                          }
                        },
                        "proximoCursor": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Cursor ou limite inválido. Códigos possíveis: requisicao_invalida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "401": {
            "description": "Chave ausente, malformada, revogada ou inexistente (credencial_invalida, sempre a mesma resposta) ou vencida (credencial_vencida: a hospedagem muda a validade ou gera outra). Códigos possíveis: credencial_invalida, credencial_vencida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "A chave não pode fazer isto agora. `integracao_indisponivel` é genérico de propósito: a hospedagem vê o motivo no Citin. Códigos possíveis: escopo_insuficiente, uso_no_navegador, ip_nao_permitido, integracao_indisponivel.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite de pedidos por minuto atingido. Respeite o cabeçalho Retry-After. Códigos possíveis: limite_excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "500": {
            "description": "Erro do Citin. Tente de novo em instantes; se repetir, avise a hospedagem. Códigos possíveis: erro_interno.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Reservas"
        ],
        "operationId": "criarPreReserva",
        "summary": "Cria uma pré-reserva (pendente)",
        "description": "Escopo: `reservas.criar`. A pré-reserva segura as datas até `expiraEm`; a hospedagem confirma pelo Citin. Exige `Idempotency-Key`: repetir o mesmo pedido com a mesma chave devolve a mesma reserva (200); a mesma chave com outro corpo é 422. `totalEsperado` só confere o valor: se o preço mudou desde a cotação, a resposta é 409 `preco_mudou` com a cotação nova.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "8 a 100 caracteres (letras, números, _ e -), única por pedido. Vale por 24 h.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{8,100}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PedidoReserva"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Pedido repetido: a reserva já criada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "sucesso",
                    "dados"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "sucesso": {
                      "const": true
                    },
                    "dados": {
                      "$ref": "#/components/schemas/Reserva"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Pré-reserva criada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "sucesso",
                    "dados"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "sucesso": {
                      "const": true
                    },
                    "dados": {
                      "$ref": "#/components/schemas/Reserva"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Campo inválido ou falta a chave de idempotência. Códigos possíveis: requisicao_invalida, idempotencia_ausente.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "401": {
            "description": "Chave ausente, malformada, revogada ou inexistente (credencial_invalida, sempre a mesma resposta) ou vencida (credencial_vencida: a hospedagem muda a validade ou gera outra). Códigos possíveis: credencial_invalida, credencial_vencida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "A chave não pode fazer isto agora. `integracao_indisponivel` é genérico de propósito: a hospedagem vê o motivo no Citin. Códigos possíveis: escopo_insuficiente, uso_no_navegador, ip_nao_permitido, integracao_indisponivel.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "404": {
            "description": "Acomodação inexistente ou não liberada. Códigos possíveis: nao_encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "409": {
            "description": "Datas tomadas ou preço mudou (vem com `dados.cotacao`). Códigos possíveis: indisponivel, preco_mudou.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "422": {
            "description": "Estadia não vendável ou chave usada com outro pedido. Códigos possíveis: regra_estadia, capacidade, sem_preco, datas_invalidas, idempotencia_divergente.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite de pedidos por minuto, ou pré-reservas pendentes demais. Códigos possíveis: limite_excedido, limite_pre_reservas.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "500": {
            "description": "Erro do Citin. Tente de novo em instantes; se repetir, avise a hospedagem. Códigos possíveis: erro_interno.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/reservas/{id}": {
      "get": {
        "tags": [
          "Reservas"
        ],
        "operationId": "consultarReserva",
        "summary": "Consulta o estado atual de uma pré-reserva deste site",
        "description": "Escopo: `reservas.ler`. Mostra datas e total atuais, inclusive o que a hospedagem alterou. Status: pendente, confirmada, cancelada, expirada, nao_compareceu.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A reserva.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "sucesso",
                    "dados"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "sucesso": {
                      "const": true
                    },
                    "dados": {
                      "$ref": "#/components/schemas/Reserva"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Chave ausente, malformada, revogada ou inexistente (credencial_invalida, sempre a mesma resposta) ou vencida (credencial_vencida: a hospedagem muda a validade ou gera outra). Códigos possíveis: credencial_invalida, credencial_vencida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "A chave não pode fazer isto agora. `integracao_indisponivel` é genérico de propósito: a hospedagem vê o motivo no Citin. Códigos possíveis: escopo_insuficiente, uso_no_navegador, ip_nao_permitido, integracao_indisponivel.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "404": {
            "description": "Reserva inexistente ou de outra integração (mesma resposta). Códigos possíveis: nao_encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite de pedidos por minuto atingido. Respeite o cabeçalho Retry-After. Códigos possíveis: limite_excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "500": {
            "description": "Erro do Citin. Tente de novo em instantes; se repetir, avise a hospedagem. Códigos possíveis: erro_interno.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    },
    "/reservas/{id}/cancelar": {
      "post": {
        "tags": [
          "Reservas"
        ],
        "operationId": "cancelarPreReserva",
        "summary": "Cancela uma pré-reserva pendente deste site",
        "description": "Escopo: `reservas.cancelar`. Só pré-reserva pendente criada por esta integração e sem pagamento. Repetir é seguro.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Reserva cancelada.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "sucesso",
                    "dados"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "sucesso": {
                      "const": true
                    },
                    "dados": {
                      "$ref": "#/components/schemas/Reserva"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Chave ausente, malformada, revogada ou inexistente (credencial_invalida, sempre a mesma resposta) ou vencida (credencial_vencida: a hospedagem muda a validade ou gera outra). Códigos possíveis: credencial_invalida, credencial_vencida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "403": {
            "description": "A chave não pode fazer isto agora. `integracao_indisponivel` é genérico de propósito: a hospedagem vê o motivo no Citin. Códigos possíveis: escopo_insuficiente, uso_no_navegador, ip_nao_permitido, integracao_indisponivel.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "404": {
            "description": "Reserva inexistente ou de outra integração (mesma resposta). Códigos possíveis: nao_encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "409": {
            "description": "Já confirmada ou com pagamento: fale com a hospedagem. Códigos possíveis: reserva_confirmada, reserva_com_pagamento.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "429": {
            "description": "Limite de pedidos por minuto atingido. Respeite o cabeçalho Retry-After. Códigos possíveis: limite_excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          },
          "500": {
            "description": "Erro do Citin. Tente de novo em instantes; se repetir, avise a hospedagem. Códigos possíveis: erro_interno.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erro"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "chaveCitin": {
        "type": "http",
        "scheme": "bearer",
        "description": "Cabeçalho `Authorization: Bearer ctn_…`. Guarde a chave em variável de ambiente do servidor."
      }
    },
    "schemas": {
      "Erro": {
        "type": "object",
        "required": [
          "sucesso",
          "codigo",
          "erro"
        ],
        "properties": {
          "sucesso": {
            "const": false
          },
          "codigo": {
            "type": "string",
            "enum": [
              "requisicao_invalida",
              "idempotencia_ausente",
              "credencial_invalida",
              "credencial_vencida",
              "escopo_insuficiente",
              "uso_no_navegador",
              "ip_nao_permitido",
              "integracao_indisponivel",
              "nao_encontrado",
              "indisponivel",
              "preco_mudou",
              "reserva_confirmada",
              "reserva_com_pagamento",
              "regra_estadia",
              "capacidade",
              "sem_preco",
              "datas_invalidas",
              "idempotencia_divergente",
              "limite_excedido",
              "limite_pre_reservas",
              "erro_interno"
            ]
          },
          "erro": {
            "type": "string",
            "description": "Mensagem em português, pode ser mostrada a uma pessoa."
          },
          "campo": {
            "type": "string",
            "description": "Campo inválido, quando `requisicao_invalida`."
          },
          "mensagens": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Regras de estadia violadas, quando `regra_estadia`."
          },
          "dados": {
            "description": "Informação extra do erro (ex.: a cotação nova em `preco_mudou`)."
          }
        }
      },
      "Propriedade": {
        "type": "object",
        "required": [
          "nome",
          "fuso",
          "moeda",
          "checkinHora",
          "checkoutHora",
          "prazoPreReservaHoras",
          "criancaGratisAteIdade"
        ],
        "additionalProperties": false,
        "properties": {
          "nome": {
            "type": "string"
          },
          "fuso": {
            "type": "string",
            "description": "Fuso IANA da hospedagem. Todas as datas da API são dias neste fuso."
          },
          "moeda": {
            "type": "string",
            "description": "ISO 4217 (ex.: BRL). Todos os valores da API estão nesta moeda."
          },
          "checkinHora": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d{2}:\\d{2}$"
          },
          "checkoutHora": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d{2}:\\d{2}$"
          },
          "prazoPreReservaHoras": {
            "type": "integer",
            "description": "Horas que a hospedagem tem para confirmar uma pré-reserva antes de ela expirar."
          },
          "criancaGratisAteIdade": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Crianças até esta idade (inclusive) não pagam. null = toda criança paga."
          }
        }
      },
      "Acomodacao": {
        "type": "object",
        "required": [
          "id",
          "nome",
          "tipo",
          "capacidade"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^acm_[A-Za-z0-9]{16}$"
          },
          "nome": {
            "type": "string"
          },
          "tipo": {
            "type": "string",
            "enum": [
              "unidade",
              "grupo"
            ]
          },
          "capacidade": {
            "type": "object",
            "required": [
              "base",
              "maxima"
            ],
            "additionalProperties": false,
            "properties": {
              "base": {
                "type": "integer",
                "description": "Hóspedes incluídos no preço base."
              },
              "maxima": {
                "type": "integer",
                "description": "Máximo de hóspedes (adultos + crianças)."
              }
            }
          }
        }
      },
      "Noite": {
        "type": "object",
        "required": [
          "data",
          "disponivel",
          "diaria",
          "minimoNoites",
          "maximoNoites",
          "semEntrada",
          "semSaida"
        ],
        "additionalProperties": false,
        "properties": {
          "data": {
            "type": "string",
            "format": "date"
          },
          "disponivel": {
            "type": "boolean",
            "description": "Há unidade livre e com preço nesta noite."
          },
          "diaria": {
            "type": [
              "number",
              "null"
            ],
            "description": "Valor da noite; null quando indisponível."
          },
          "minimoNoites": {
            "type": "integer"
          },
          "maximoNoites": {
            "type": [
              "integer",
              "null"
            ]
          },
          "semEntrada": {
            "type": "boolean",
            "description": "Não aceita chegada neste dia."
          },
          "semSaida": {
            "type": "boolean",
            "description": "Não aceita saída neste dia."
          }
        }
      },
      "Cotacao": {
        "type": "object",
        "required": [
          "disponivel",
          "moeda",
          "noites",
          "diarias",
          "totalDiarias",
          "taxaLimpeza",
          "total"
        ],
        "properties": {
          "disponivel": {
            "type": "boolean"
          },
          "motivo": {
            "type": "string"
          },
          "moeda": {
            "type": "string"
          },
          "noites": {
            "type": "integer"
          },
          "diarias": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "data",
                "valor"
              ],
              "properties": {
                "data": {
                  "type": "string",
                  "format": "date"
                },
                "valor": {
                  "type": "number"
                }
              }
            }
          },
          "totalDiarias": {
            "type": "number"
          },
          "taxaLimpeza": {
            "type": [
              "number",
              "null"
            ]
          },
          "total": {
            "type": "number",
            "description": "Diárias + taxa de limpeza. É o valor de `totalEsperado` na reserva."
          }
        }
      },
      "PedidoReserva": {
        "type": "object",
        "required": [
          "acomodacao",
          "entrada",
          "saida",
          "adultos",
          "hospede",
          "totalEsperado"
        ],
        "additionalProperties": false,
        "properties": {
          "acomodacao": {
            "type": "string",
            "pattern": "^acm_[A-Za-z0-9]{16}$"
          },
          "entrada": {
            "type": "string",
            "format": "date"
          },
          "saida": {
            "type": "string",
            "format": "date"
          },
          "adultos": {
            "type": "integer",
            "minimum": 1
          },
          "criancas": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 0,
              "maximum": 17
            },
            "description": "Idade de cada criança."
          },
          "hospede": {
            "type": "object",
            "required": [
              "nome",
              "telefone"
            ],
            "additionalProperties": false,
            "properties": {
              "nome": {
                "type": "string",
                "maxLength": 120
              },
              "telefone": {
                "type": "string",
                "description": "DDD + número, ou formato internacional com +."
              },
              "email": {
                "type": "string",
                "maxLength": 160
              }
            }
          },
          "observacoes": {
            "type": "string",
            "maxLength": 500
          },
          "referenciaExterna": {
            "type": "string",
            "maxLength": 64,
            "description": "Código do pedido no site."
          },
          "totalEsperado": {
            "type": "number",
            "description": "O `total` da cotação mostrada ao hóspede."
          }
        }
      },
      "Reserva": {
        "type": "object",
        "required": [
          "id",
          "status",
          "expiraEm",
          "acomodacao",
          "entrada",
          "saida",
          "hospedes",
          "valores",
          "referenciaExterna",
          "atualizadoEm"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "pendente",
              "confirmada",
              "cancelada",
              "expirada",
              "nao_compareceu"
            ]
          },
          "expiraEm": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Até quando a hospedagem pode confirmar (só pendente)."
          },
          "acomodacao": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^acm_[A-Za-z0-9]{16}$"
          },
          "entrada": {
            "type": "string",
            "format": "date"
          },
          "saida": {
            "type": "string",
            "format": "date"
          },
          "hospedes": {
            "type": "integer"
          },
          "valores": {
            "type": "object",
            "required": [
              "totalDiarias",
              "taxaLimpeza",
              "total"
            ],
            "additionalProperties": false,
            "properties": {
              "totalDiarias": {
                "type": "number"
              },
              "taxaLimpeza": {
                "type": "number"
              },
              "total": {
                "type": "number"
              }
            }
          },
          "referenciaExterna": {
            "type": [
              "string",
              "null"
            ]
          },
          "atualizadoEm": {
            "type": "string",
            "format": "date-time",
            "description": "Última alteração, por qualquer lado."
          }
        }
      }
    }
  }
}
