# API de Agendamento Donc

**Versao:** v2.0 -- Nov 2025
**URL base:** `https://apiv2.donc.com.br/api`
**Autenticacao:** Token (api_key) informado pela Donc

A API funciona em duas etapas:
1. Consultar disponibilidade
2. Reservar agendamento (coloca na fila de processamento automatico)

## 1. GET /api/agendamento/disponibilidade-por-tipo

Consulta disponibilidade de datas/turnos.

### Parametros

| Parametro | Tipo | Obrigatorio | Descricao |
|-----------|------|-------------|-----------|
| tipoJobId | int | Sim | ID do tipo de servico |
| cep | string | Sim | CEP com ou sem hifen |
| data | date (yyyy-MM-dd) | Sim | Data inicial da consulta |
| intervalo | int | Nao (padrao: 3) | Dias a considerar a partir da data inicial |

### Comportamentos

- Remove hifens/pontos do CEP automaticamente
- Ignora datas passadas
- Retorna manha/tarde/noite como booleanos

### Erros

| Codigo | Descricao |
|--------|-----------|
| 400 | CEP ausente |
| 500 | Erro interno |

## 2. POST /api/agendamento/reservar-agendamento

Cria uma reserva na fila de processamento.

### Parametros obrigatorios

| Parametro | Tipo | Descricao |
|-----------|------|-----------|
| dataAgendamento | date (yyyy-MM-dd) | Data do agendamento |
| turno | string | "Manha", "Tarde" ou "Noite" |

### Parametros opcionais

| Parametro | Tipo | Descricao |
|-----------|------|-----------|
| codigoServico | string | Codigo do servico a ser reservado |
| nomeCliente | string | Nome do cliente |
| tipoJobId | int | ID do tipo de servico |
| cep | string | CEP do endereco |

### Regra obrigatoria

E necessario informar **OU**:
- `codigoServico`

**OU**:
- `nomeCliente` + `tipoJobId` + `cep`

Sem isso retorna 400.

### Validacoes

- Data nao pode ser passada
- Turno deve ser exatamente "Manha", "Tarde" ou "Noite"
- Verifica disponibilidade antes de reservar

### Erros

| Codigo | Descricao |
|--------|-----------|
| 400 | Dados invalidos/faltando |
| 409 | Turno ou data indisponiveis |
| 500 | Erro interno |

## 3. Processamento Automatico da Reserva

Apos o POST:

1. A vaga fica **imediatamente bloqueada** para outros agendamentos
2. Um servico interno monitora reservas com `Processado = false`
3. Quando o protocolo (Pedido) e criado na Donc:
   - Se `codigoServico` foi informado na reserva, busca direta
   - Senao, busca por `nomeCliente` + `tipoJobId` + `cep` (dados devem ser identicos)
4. O pedido deve ter `StatusCalculadoId` 500 ou 550
5. Havendo disponibilidade final:
   - Define horario exato a partir de:
     - Manha -> 08:00
     - Tarde -> 14:00
     - Noite -> 19:00
   - Atualiza data de agendamento
   - Se a reserva nao tinha `codigoServico`, ele e preenchido automaticamente
6. Se a reserva ficar **> 3h sem processar**:
   - Expira
   - Libera a vaga
   - Preenche `DataExpiracao`
7. `RetornoProcessamento` guarda mensagens de sucesso/erro para auditoria

## 4. Codigos de Status HTTP

| Codigo | Quando ocorre |
|--------|---------------|
| 200 | Consulta OK / Reserva criada |
| 400 | Dados invalidos ou faltando |
| 409 | Indisponibilidade para a data/turno |
| 500 | Erro interno |

## 5. Fluxo Recomendado

1. **Consultar disponibilidade** -- `GET /api/agendamento/disponibilidade-por-tipo`
2. Escolher uma data e turno com disponibilidade = true
3. **Reservar a vaga** -- `POST /api/agendamento/reservar-agendamento`
4. **Criar o protocolo** no sistema Donc com: nomeCliente, tipoJobId, CEP
5. O servico interno finaliza o agendamento automaticamente