Integre calendários e agendamentos.
Disponibilidade, reservas e recorrência em uma API independente. Comece pela conexão; depois implemente um comando e acompanhe seu resultado.
1. Executar e integrar
Requisitos: Node 24.22.0, pnpm na versão de packageManager e PostgreSQL 18.6. Use a main oficial deste repositório. O README descreve os três papéis do banco e as variáveis necessárias. A API e o worker são processos distintos.
nvm use
npm run local:startExecute no clone existente do serviço. O comando instala dependências travadas, prepara o banco sem reset e inicia API, worker e portal. Para usar processos separados, siga o README; não execute as duas formas juntas. Verifique GET /readyz antes de integrar.
Use a credencial emitida pelo setup no seu backend, fora do histórico do shell e dos logs. Não use as credenciais de desenvolvimento em produção. Nos exemplos abaixo, CALENDAR_API_URL, CALENDAR_API_KEY e TENANT_ID são variáveis do cliente, preenchidas a partir da sua instalação.
curl --fail-with-body "$CALENDAR_API_URL/v1/tenants?limit=20" \
-H "Authorization: Bearer $CALENDAR_API_KEY"
curl --fail-with-body "$CALENDAR_API_URL/v1/me" \
-H "Authorization: Bearer $CALENDAR_API_KEY" \
-H "Anam-Tenant: $TENANT_ID"Verifique o escopo exigido em cada operação na referência da API. Não reutilize credenciais administrativas para um frontend.
2. Autenticação, tenant e recurso
Credenciais permanentes autenticam o backend. Uma credencial de organização seleciona o tenant pelo cabeçalho Anam-Tenant; uma credencial de tenant já está vinculada a ele. Um ID público apenas localiza um recurso.
POST /v1/console-sessions emite grants temporários com host, ações e, quando informado, tipo de evento exatos. acting_as é obrigatório. A integração deve comprovar ator, tenant, recurso e ação antes de emitir e renovar. A revogação persistida e a autoridade atual são verificadas pelo serviço; impedir a renovação sozinho não revoga um grant existente.
Envie o bearer em Authorization, mantenha-o somente em memória e descarte-o na troca de contexto. Nunca em URL, configuração pública, localStorage ou logs. CORS aceita somente origens configuradas, sem conceder autorização por si só. Escopo vazio não autoriza recursos.
3. Entidades e fronteiras
| Entidade | Responsabilidade |
|---|---|
| Organization / Tenant | Integração contratante e fronteira de isolamento. |
| Subject / Host | Recurso cujo horário é disponibilizado. |
| Event type | Duração, intervalos, horizonte e regras de agendamento. |
| Booking | Compromisso genérico; uma série pode ter várias ocorrências. |
| Booking occurrence | Identidade de uma ocorrência e seu intervalo/estado atual. |
| Occupancy | Ledger único que arbitra reservas, holds e bloqueios. |
| Connection / sync operation | Credenciais protegidas, projeção externa e tentativas recuperáveis. |
| Audit / outbox | Trilha persistida e intenção de entrega at-least-once. |
Participantes usam referências externas opacas. O serviço não guarda modelo clínico, paciente, plano comercial ou assinatura da aplicação. Metadados aceitos têm schema e limites; não concedem permissão. A ligação entre Booking e uma entidade da aplicação pertence à integração.
4. Mutações, recibos e concorrência
Use uma chave estável em Idempotency-Key para o mesmo comando. O fingerprint inclui tenant, recurso e pedido normalizado. Repetir o pedido devolve o recibo original; reutilizar a chave com conteúdo incompatível retorna conflito. Guarde a identidade da operação antes do envio.
Um timeout significa resultado desconhecido. Recupere a mesma operação; não crie outra chave para tentar novamente. Envie a revisão exigida por cada endpoint, normalmente If-Match. ETags são opacos: não incremente, ordene ou compare numericamente. Um 412 exige recarregar e revisar o estado antes de um novo comando.
| Operação | Contrato |
|---|---|
| Criação | POST /v1/bookings |
| Consulta | GET /v1/bookings/:id |
| Remarcação individual | POST /v1/occurrences/:id/reschedule |
| Edição com escopo | PATCH /v1/occurrences/:id (veja campos e restrições OpenAPI) |
| Prévia de exclusão | GET /v1/bookings/:id/removal-plan |
| Exclusão | POST /v1/bookings/:id/remove com revisão e hash da prévia |
Confirmado significa que a reserva foi aceita pelo Calendar. Não comprova resposta do participante, presença, pagamento nem sincronização externa. Cancelar e excluir são operações distintas; tombstones impedem que tentativas antigas recriem o evento.
5. Fuso horário, recorrência e disponibilidade
Registros passados: POST /v1/bookings com autoridade autenticada booking:write aceita inícios passados fora da oferta atual, mantendo isolamento e conflitos do ledger. Na criação, datas passadas não enfileiram confirmação nem lembrete; uma série mista mantém lembretes somente das ocorrências futuras. Booking tokens públicos não concedem essa autoridade. Importações materializadas preservam seu contrato próprio de somente leitura.
IANA é o padrão de identificadores de fuso horário, como America/Sao_Paulo e Europe/London; não tem relação com assistentes da aplicação. Um instante UTC e a hora civil são informações diferentes. Recorrências são ancoradas na hora local do host, preservando as transições de horário de verão.
Horas inexistentes e ambíguas possuem uma resolução registrada no contrato. Não deduza fuso desconhecido. As consultas e a expansão de séries exigem intervalo e limites; nunca materialize uma série infinita de uma vez. Identidade e posição original da ocorrência sobrevivem à remarcação.
O ledger decide a concorrência dos períodos ocupados, incluindo buffers. Uma consulta de disponibilidade não garante uma reserva: duas requisições podem ver o mesmo horário, e somente o comando transacional decide. Eventos livres não devem consumir capacidade. As regras e campos de dia inteiro só se aplicam aos endpoints que os declaram explicitamente; não converta uma duração arbitrária em “dia inteiro”.
6. Webhooks e transporte de atualizações
O outbox persiste a intenção no mesmo banco da alteração. A entrega é repetível; não há promessa de exactly-once. Cada envio leva Anam-Event-Id, Anam-Delivery-Id, tentativa e Anam-Signature: t=<segundos>,v1=<HMAC-SHA256>. O conteúdo assinado é <t>.<corpo bruto>.
- Limite tamanho e tempo antes de ler o corpo.
- Verifique assinatura em tempo constante sobre os bytes brutos e a tolerância temporal.
- Persista uma inbox com chave única por tenant + Event-Id e o fingerprint.
- Confirme o HTTP somente depois dessa persistência; processe de forma idempotente.
- Use sequência/revisão do recurso para rejeitar publicação antiga. IDs e ETags opacos não são números ordenáveis.
Retries usam limites, backoff e jitter; consulte dead letters e replay autorizado na API operacional. Trate Retry-After. Uma notificação de provedor é sinal para reconciliar: Google e Microsoft possuem validações próprias, diferentes da assinatura de saída.
O feed SSE entrega metadados de mudanças para reconciliação de clientes. É transporte do estado do serviço; não é entrega de e-mail, WhatsApp, push ou aviso de negócio. Consumidores recuperam a API após desconexão. A aplicação escolhe destinatários e semântica; o serviço de notifications executa entregas solicitadas. Falha de entrega não desfaz uma reserva confirmada.
7. Provedores externos
Google e Microsoft são adaptadores. A projeção é one-way out; a leitura de calendários selecionados é free/busy. Alterações externas nos campos controlados podem ser corrigidas pela reconciliação. Isso não equivale a edição bidirecional completa.
O backend mantém OAuth, state, PKCE e refresh tokens protegidos. Conectar exige configuração e consentimento reais. Cursores expirados acionam resync limitado; assinaturas precisam de renovação. A confirmação ambígua de criação externa deve reconciliar a identidade antes de repetir para evitar duplicação. A API expõe estados e falhas; testes com adaptador sintético não certificam o provedor real.
8. Erros e limites
| HTTP | Tratamento |
|---|---|
| 400 / 422 | Entrada inválida ou operação não suportada; corrigir o comando. |
| 401 / 403 / 404 | Revalidar identidade, recurso e permissão; não ampliar escopo automaticamente. |
| 409 | Conflito de horário, estado ou chave idempotente; verificar o código específico. |
| 412 | Revisão obsoleta. Recarregar e revisar. |
| 429 | Respeitar Retry-After e o orçamento do consumidor. |
| 5xx / timeout | Resultado possivelmente ambíguo. Recuperar com a mesma identidade. |
As respostas usam application/problem+json. Não apresente sucesso antes do recibo durável. O OpenAPI define limites de campos, paginação e intervalos de cada rota. O limite global do corpo HTTP é 1 MiB; limites menores por campo continuam valendo. Paginação exige consumir o cursor, sem interpretar página parcial como total.
GET /v1/bookings/:id retorna o histórico não removido completo até 2.048 ocorrências e 50 participantes. Acima disso, responde 422 validation_failed com code_detail e reconciliation_required, sem truncar. Para a grade, prefira GET /v1/bookings/summary: até 50 bookings por página, 10 ocorrências por booking e janela de 62 dias. A edição ampla de uma série reconcilia até 366 posições/folhas atuais; excesso falha antes de mudar padrão ou ocupação. A remoção autorizada mantém seu plano próprio limitado a 10.000 linhas, sem depender do limite de detalhe.
9. Configuração, auditoria e operação
Configuração de host, tipos, disponibilidade e aparência usa APIs autorizadas, com validação, revisão e auditoria. Não edite tabelas manualmente como rotina. Parâmetros de processo (conexões, timeouts, segredos) são variáveis de runtime e não uma permissão comercial. O console apresenta apenas capacidades efetivamente suportadas.
A auditoria persistida por tenant independe dos exportadores. Logs, métricas, analytics e auditoria têm finalidades diferentes. Portas opcionais de telemetria filtram campos e limitam filas/tempo; o domínio funciona sem Sentry, OpenTelemetry ou outro destino. Não exporte títulos, participantes, tokens, headers nem payloads.
/health verifica o processo; /ready verifica prontidão. /metrics exige a autoridade configurada. Monitore filas, idade das operações, retries, conflitos, chamadas por provedor e latência. Use carga representativa para medir custo; mocks e uma medição local não demonstram capacidade de produção.
QA_REQUIRE_DATABASE=true corepack pnpm test
corepack pnpm typecheck
corepack pnpm contract:build
corepack pnpm contract:check
corepack pnpm licenses:check10. Console e integração com aplicações
apps/console é o console existente, servido separadamente em http://127.0.0.1:4189/console no desenvolvimento. A API redireciona /console somente se CONSOLE_PUBLIC_URL estiver configurada. A sessão de desenvolvimento local requer opt-in explícito e origem loopback. Em produção, o integrador autentica e autoriza o usuário antes de fornecer o grant pelo provedor de sessão; não há emissão anônima com chave de backend.
A integração específica da Ana M. fica documentada no monorepo. Ela mapeia Account para tenant, associa entidades da aplicação e expõe sua rota de validação. Este serviço não depende do monorepo nem do Firestore para o estado canônico.