Ana MCalendar
DOCUMENTAÇÃO DO SERVIÇO · API V1

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:start

Execute 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

EntidadeResponsabilidade
Organization / TenantIntegração contratante e fronteira de isolamento.
Subject / HostRecurso cujo horário é disponibilizado.
Event typeDuração, intervalos, horizonte e regras de agendamento.
BookingCompromisso genérico; uma série pode ter várias ocorrências.
Booking occurrenceIdentidade de uma ocorrência e seu intervalo/estado atual.
OccupancyLedger único que arbitra reservas, holds e bloqueios.
Connection / sync operationCredenciais protegidas, projeção externa e tentativas recuperáveis.
Audit / outboxTrilha 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çãoContrato
CriaçãoPOST /v1/bookings
ConsultaGET /v1/bookings/:id
Remarcação individualPOST /v1/occurrences/:id/reschedule
Edição com escopoPATCH /v1/occurrences/:id (veja campos e restrições OpenAPI)
Prévia de exclusãoGET /v1/bookings/:id/removal-plan
ExclusãoPOST /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>.

  1. Limite tamanho e tempo antes de ler o corpo.
  2. Verifique assinatura em tempo constante sobre os bytes brutos e a tolerância temporal.
  3. Persista uma inbox com chave única por tenant + Event-Id e o fingerprint.
  4. Confirme o HTTP somente depois dessa persistência; processe de forma idempotente.
  5. 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

HTTPTratamento
400 / 422Entrada inválida ou operação não suportada; corrigir o comando.
401 / 403 / 404Revalidar identidade, recurso e permissão; não ampliar escopo automaticamente.
409Conflito de horário, estado ou chave idempotente; verificar o código específico.
412Revisão obsoleta. Recarregar e revisar.
429Respeitar Retry-After e o orçamento do consumidor.
5xx / timeoutResultado 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:check

10. 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.

Documentação versionada, runbooks e relatórios · API