# Citin Connect — guia para quem integra um site

O Citin Connect deixa o site de uma hospedagem mostrar a disponibilidade e o preço do Citin e enviar **pré-reservas**.
A pré-reserva segura as datas até a hospedagem confirmar; se ninguém confirmar no prazo, ela expira e as datas voltam a ficar livres.
O contrato completo (campos, tipos, exemplos) está em [openapi.json](openapi.json). Este guia explica o que o contrato não diz.

Base: `https://citin.com.br/api/externo/v1`

## 1. Antes de começar

- A hospedagem gera a **chave de acesso** na tela Configurações → Integrações. Ela aparece uma única vez, no formato `ctn_<prefixo>_<segredo>`.
- A chave fica **só no servidor** do site, em variável de ambiente. Nunca no navegador, no repositório, em log ou em resposta ao front. Pedido que chega com o cabeçalho `Origin` é recusado (`uso_no_navegador`).
- Não existe ambiente de teste separado: tudo acontece no sistema real da hospedagem, nas acomodações que ela liberou (normalmente todas). Toda pré-reserva enviada entra de verdade e segura as datas: cancele as de teste ao terminar. A hospedagem pode lhe dar um login no Citin para conferir as pré-reservas que chegaram.
- A chave pode ter validade (sem prazo, ou 7, 30 ou 90 dias, ou 1 ano). Vencida, o Citin responde `401 credencial_vencida`: peça à hospedagem para mudar a validade (a mesma chave volta a funcionar) ou gerar outra.
- Envie sempre `Authorization: Bearer <chave>`.

## 2. Conceitos

| Termo | O que é |
|---|---|
| Acomodação | O que o site vende. Id público `acm_…`, mostrado na tela da hospedagem. Pode ser uma unidade ou um grupo de unidades iguais. Com todas as unidades liberadas, uma unidade nova aparece sozinha em `GET /acomodacoes`: atualize a lista do site uma vez por dia |
| Pré-reserva | Reserva em estado `pendente`, com `expiraEm`. A hospedagem confirma pelo app do Citin |
| Prazo | 24 horas por padrão (1 a 72, definido pela hospedagem). Vem em `GET /propriedade` e em cada reserva |
| Datas | `AAAA-MM-DD`, no fuso da hospedagem (`fuso` em `GET /propriedade`). A diária é a da noite: o dia da saída não conta como noite |
| Preço | **Sempre calculado pelo Citin**, na tabela de venda direta. O site nunca calcula nem altera preço |
| Moeda | A da hospedagem (`moeda`). Valores são números com 2 casas |

## 3. Calendário

`GET /acomodacoes/{id}/calendario?de=AAAA-MM-DD&ate=AAAA-MM-DD`

- Até 186 noites por chamada, a partir de hoje, até 500 dias à frente.
- Cada noite traz `disponivel`, `diaria`, `minimoNoites`, `maximoNoites`, `semEntrada` e `semSaida`. Use para desabilitar datas no seletor.
- A resposta pode ser guardada em cache por **até 60 segundos**. Não guarde mais que isso.
- O calendário de um grupo é indicativo: quem decide é a cotação e a criação.

## 4. Cotação

`GET /acomodacoes/{id}/cotacao?entrada=…&saida=…&adultos=2&criancas=4,9`

Devolve `disponivel` e, quando disponível, `diarias[]`, `totalDiarias`, `taxaLimpeza` e `total`.
Quando não está disponível, vêm `motivo` e `mensagens` explicando (regra de estadia, capacidade, datas ocupadas). Mostre a mensagem ao hóspede.
`criancas` é a lista de idades. Crianças até a idade grátis da hospedagem não entram no preço.

## 5. Pré-reserva

`POST /reservas`, com o cabeçalho `Idempotency-Key`.

```json
{
  "acomodacao": "acm_xxxxxxxxxxxxxxxx",
  "entrada": "2027-01-10",
  "saida": "2027-01-12",
  "adultos": 2,
  "criancas": [4],
  "hospede": { "nome": "Maria Souza", "telefone": "48988887777", "email": "maria@exemplo.com" },
  "observacoes": "Chegamos à noite.",
  "referenciaExterna": "pedido-1234",
  "totalEsperado": 1500.00
}
```

- **`Idempotency-Key`**: 8 a 100 caracteres `[A-Za-z0-9_-]`, **uma por pedido do hóspede**. Repetir o mesmo pedido (por exemplo após uma falha de rede) com a mesma chave devolve a mesma reserva (HTTP 200, em vez de 201). A mesma chave com corpo diferente dá `idempotencia_divergente`. A chave vale por 24 horas.
- **`totalEsperado`**: o total que o hóspede viu na cotação. O Citin recalcula; se o valor mudou, responde **409 `preco_mudou`** com a cotação nova em `dados.cotacao`. Mostre o novo valor e peça confirmação.
- **Telefone** é obrigatório. **Limites**: nome até 120 caracteres, observações até 500, `referenciaExterna` até 64. Campos desconhecidos são ignorados.
- A resposta 201 traz `status: "pendente"` e `expiraEm`. Diga ao hóspede que a hospedagem confirma até aquele horário. **Não cobre nada**: o pagamento é combinado direto com a hospedagem.
- Cada integração tem um máximo de pré-reservas pendentes ao mesmo tempo (`limite_pre_reservas`).

## 6. Acompanhar e cancelar

- `GET /reservas/{id}`: estado atual. `status`: `pendente`, `confirmada`, `cancelada`, `expirada` ou `nao_compareceu`. Datas e total refletem alterações feitas pela hospedagem.
- `GET /reservas?alteradasDesde=<cursor>&limite=50`: reservas deste site que mudaram. Comece **sem** `alteradasDesde`, guarde o `proximoCursor` e use-o na chamada seguinte. O cursor é opaco; não monte nem interprete. Sem novidades, vem a lista vazia e o mesmo cursor. Não há webhook: consulte de tempos em tempos (a cada poucos minutos basta).
- `POST /reservas/{id}/cancelar`: cancela uma pré-reserva **pendente** deste site. Repetir é seguro. Reserva já confirmada não cancela por aqui (`reserva_confirmada`): a hospedagem cancela no app.
- Para alterar datas, cancele e crie outra.

## 7. Erros

Formato: `{ "sucesso": false, "codigo": "...", "erro": "mensagem em português" }`. Use o `codigo`, nunca o texto.

| HTTP | `codigo` | O que fazer |
|---|---|---|
| 400 | `requisicao_invalida` | Corrija o campo indicado em `campo` |
| 400 | `idempotencia_ausente` | Envie `Idempotency-Key` |
| 401 | `credencial_invalida` | Chave ausente, errada ou revogada. Não repita |
| 401 | `credencial_vencida` | A chave venceu. Não repita; peça à hospedagem para mudar a validade ou gerar outra |
| 403 | `escopo_insuficiente` | A chave não tem essa permissão. Fale com a hospedagem |
| 403 | `uso_no_navegador` | A chamada partiu de um navegador. Mova para o servidor |
| 403 | `ip_nao_permitido` | O IP do servidor não está liberado |
| 403 | `integracao_indisponivel` | Integração desativada ou conta com pendência. A hospedagem vê o motivo na tela |
| 404 | `nao_encontrado` | Id inexistente ou de outra integração |
| 409 | `indisponivel` | As datas foram ocupadas. Peça outras datas |
| 409 | `preco_mudou` | Mostre `dados.cotacao` e reenvie com o novo `totalEsperado` |
| 409 | `reserva_confirmada`, `reserva_com_pagamento` | Não dá para cancelar por aqui |
| 422 | `regra_estadia` | Mínimo ou máximo de noites, sem entrada ou sem saída. Mostre a mensagem |
| 422 | `capacidade` | Mais hóspedes que a acomodação comporta |
| 422 | `sem_preco` | Há noite sem preço de venda direta |
| 422 | `datas_invalidas` | Entrada no passado, saída antes da entrada ou estadia longa demais |
| 422 | `idempotencia_divergente` | Mesma chave com corpo diferente. Gere outra chave |
| 429 | `limite_excedido` | Espere o tempo de `Retry-After` |
| 429 | `limite_pre_reservas` | Há pré-reservas pendentes demais deste site |
| 500 | `erro_interno` | Tente de novo depois; se persistir, avise a hospedagem |

## 8. Limites

- 120 consultas por minuto e 20 escritas por minuto, por integração.
- Corpo de até 32 KB.

## 9. Aceite

Antes de ir para produção, passe pelo [checklist.md](checklist.md). A tela da hospedagem marca sozinha o que o Citin viu acontecer.

## 10. Versões

O prefixo `/v1` só muda em quebra de contrato. Campos novos podem aparecer nas respostas: ignore os que não conhece.
