API paga · Subscrição

Referência de API para programadores (paga)

Integre a API de produção para envio de escalas com uma chave API associada à sua subscrição paga. As predefinições do inquilino guardam-se com PATCH /v1/schedule-defaults; os desejos semanais por colaborador leem-se ou substituem-se com GET/PUT /v1/staff/{staffId}/weekly-shift-wish. A faturação segue o seu plano e contrato (não há cobrança por chamada API medida). Esta página documenta direitos, regras de validação e códigos de erro — use a barra lateral para saltar para cada campo.

Esta página documenta apenas a API REST de produto no API Gateway ({stage}/v1/*, autenticação com x-api-key).

As rotas Next.js /api/* (webhooks Stripe, imagens OG, Web Vitals, etc.) são internas à aplicação web e não fazem parte desta API para programadores. Não as utilize para integrações externas.

GET /v1/processing-history não é oferecido (removido com a interface antiga) e não consta da lista de endpoints desta página.

Esta API HTTP faz parte do produto pago: o acesso requer um acordo comercial ativo e as chaves são emitidas à sua organização após o onboarding.

A faturação baseia-se na subscrição e no contrato. Em planos pagos, os custos seguem normalmente a página de preços (p. ex. por colaborador registado e mês).

Os limites do playground ou do nível gratuito não se aplicam às chaves API pagas. Os limites efetivos (duração, número de colaboradores, granularidade de 15 minutos) dependem dos seus direitos pagos. Consulte Limites e predefinições nesta página.

Os pedidos devem incluir uma chave API válida emitida na sua subscrição paga. Crie, rode e revogue chaves na área da conta após iniciar sessão.

Envie a chave no cabeçalho x-api-key. As chaves estão ligadas à sua organização para identificação do inquilino e limites de acesso do plano.

Gerir chaves: Gestão de API

Envie uma condição de escala em JSON. É a superfície de integração paga; o URL base exato é fornecido por ambiente após o acesso à API ser provisionado.

POST {baseUrl}/v1/schedule

Use o URL base fornecido quando o acesso à API foi provisionado ou pelo seu contacto de operações.

Substitua **BASE_URL** pelo URL base da API (prefixo do caminho) fornecido quando o seu acesso foi provisionado.

Envie a sua chave API no cabeçalho **x-api-key**. A sua organização (inquilino) é identificada pela chave — não precisa de passar um ID de inquilino separado na query string.

A leitura e atualização da empresa (GET/PATCH /v1/company) exigem uma subscrição paga ativa. Pode receber **503** (p. ex. código **STRIPE_NOT_CONFIGURED**) quando a faturação não estiver configurada para o seu inquilino.

Exemplo com curl (bash / macOS / Linux / WSL)

Windows PowerShell: uma barra invertida final `\` **não** continua a linha. Use uma só linha, ou termine cada linha com crase (`) para continuar.

curl -sS -D - \
  -H "x-api-key: YOUR_API_KEY" \
  "BASE_URL/v1/schedule-results?limit=10"

curl -sS -D - \
  -H "x-api-key: YOUR_API_KEY" \
  "BASE_URL/v1/company"

Mesmo URL de base e mesma chave API que POST /v1/schedule. Consulta opcional: limit (1–100, predefinição 50), cursor (token opaco: reenvie o campo nextCursor da resposta anterior).

GET /v1/company e atualizações da empresa exigem uma subscrição paga ativa. Pode receber **503 / STRIPE_NOT_CONFIGURED** quando a faturação não estiver configurada.

Método	Caminho	Descrição
GET	{baseUrl}/v1/schedule-results	Lista linhas pai SCHEDULE_RESULT: conditionId, status, candidateCount, createdAt/updatedAt, etc. Paginação DynamoDB.
GET	{baseUrl}/v1/schedule-results/history	Pesquisa de histórico de resultados (como no navegador). from / to (ISO 8601, padrão início do serviço até agora), keyword, eventName (INSERT,MODIFY,REMOVE separados por vírgula), limit, cursor. Funde recente e arquivo automaticamente; só items / nextCursor.
GET	{baseUrl}/v1/schedule-results/{conditionId}	Obtém uma linha pai SCHEDULE_RESULT por conditionId (atributos JSON; sem PK/SK).
GET	{baseUrl}/v1/schedule-results/{conditionId}/resolution	Saída de otimização resolvida: status, candidates, confirmedAssignments quando presentes. Se status for completed e ainda não confirmado, rank-1 pode ser auto-confirmado neste GET (efeito colateral). Use POST …/confirm-assignments para confirmação manual.
GET	{baseUrl}/v1/schedule-results/{conditionId}/review	Payload de revisão para confirmação manual (candidatos, requiredByCellKey, allowedCellKeys do pessoal, etc.).
GET	{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift-context	Contexto de turno de emergência (datas, pessoal, slots). Subscrição paga necessária; null se a condição não existir.
GET	{baseUrl}/v1/schedule-conditions	Lista linhas pai SCHEDULE_CONDITION (conditionId, datas, publicApiCancelledAt opcional).
GET	{baseUrl}/v1/schedule-conditions/{conditionId}	Linha pai da condição mais reqDays e staffSnapshots (sem PK/SK).
GET	{baseUrl}/v1/audit-logs	Lista entradas de auditoria (mais recentes primeiro; paginação por cursor).
GET	{baseUrl}/v1/schedule-defaults	Linha de predefinições do inquilino (SCHEDULE_DEFAULTS) ou null se ainda não guardada.
GET	{baseUrl}/v1/schedule-actual/{conditionId}	Linha SCHEDULE_ACTUAL de turnos reais, ou null se inexistente.
GET	{baseUrl}/v1/staff/{staffId}/weekly-shift-wish	Linha de desejos semanais do colaborador, ou null se inexistente.
GET	{baseUrl}/v1/company	Devolve campos Stripe Customer (nome, e-mail, telefone, morada) para o customerId da sua chave API.
GET	{baseUrl}/v1/users	Lista utilizadores do inquilino (opcional: limit, cursor, userName, permissionProfileId, scope fullAccess\|nonFullAccess).
GET	{baseUrl}/v1/users/{userId}	Obtém um utilizador pelo userId no caminho.
GET	{baseUrl}/v1/staff	Lista pessoal ativo do inquilino (ordenado por nome apresentado).
GET	{baseUrl}/v1/staff/{staffId}	Obtém uma pessoa por staffId com detalhes laborais (laborLawCompliance, laborFlsaExempt, tetos pessoais, laborConstraintMask). Eliminação lógica → 404.

Use a mesma chave API com corpos JSON. PATCH /v1/company rejeita cadeias vazias em campos como o nome da empresa (alinhado com a aplicação web). PATCH /v1/schedule-defaults guarda predefinições do inquilino (requirementsByCellKey, horizonte de planeamento, etc.); os campos pagos seguem a sua subscrição. PUT /v1/staff/{staffId}/weekly-shift-wish substitui por completo a grelha semanal de desejos desse colaborador (veja a nota de validação). DELETE /v1/users/{userId} devolve 409 se a organização ficasse sem utilizadores ou ao remover o último administrador. POST /v1/staff devolve 409 STAFF_LIMIT se a lista excedesse o limite contratual.

POST /v1/users exige userName, email, permissionProfileId; opcional: locale, password. PATCH utilizador: apenas campos a alterar. POST /v1/staff: só JSON { "displayName": "..." }. PATCH /v1/staff/{staffId}: displayName, laborLawCompliance, laborFlsaExempt, personalMaxWeeklyMinutes / personalMaxMonthlyMinutes / personalMaxThreeMonthMinutes (inteiro ou null), laborConstraintMask (objeto ou null se laborLawCompliance true) — campos laborais pagos. POST /v1/schedule-results/{conditionId}/emergency-shift: absentStaffIds, absentDatesYmd e/ou absentSlots (pago, plano fonte concluído). POST …/confirm-assignments: array assignments e relaxAvailability opcional. PATCH /v1/schedule-defaults: PUBLIC_API_SCHEDULE_REQUEST_BODY.md §12. PUT /v1/staff/{staffId}/weekly-shift-wish: scheduleStartDate, scheduleEndDate, timeRangeStart, timeRangeEnd, wishByCellKey.

Método	Caminho	Descrição
PATCH	{baseUrl}/v1/company	Atualiza os campos do perfil da empresa (cliente de faturação).
PATCH	{baseUrl}/v1/schedule-defaults	Guarda predefinições de horários do inquilino (corpo alinhado com saveSchema em schedule-defaults-actions). Os campos pagos seguem a sua subscrição.
POST	{baseUrl}/v1/users	Cria um utilizador. Devolve 201 com JSON user.
PATCH	{baseUrl}/v1/users/{userId}	Atualiza campos do utilizador (userName, email, permissionProfileId, locale).
DELETE	{baseUrl}/v1/users/{userId}	Elimina um utilizador. 409 se não restassem utilizadores ou regra do último administrador.
POST	{baseUrl}/v1/staff	Cria uma pessoa (displayName). Devolve 201 com JSON staff.
POST	{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift	Clona plano fonte concluído com ausências aplicadas; devolve 201 com conditionId. Subscrição paga necessária.
POST	{baseUrl}/v1/schedule-results/{conditionId}/confirm-assignments	Valida e grava atribuições editadas manualmente (200 com { ok: true }).
PATCH	{baseUrl}/v1/staff/{staffId}	Atualiza displayName e detalhes laborais (laborLawCompliance, laborFlsaExempt, tetos pessoais, laborConstraintMask).
DELETE	{baseUrl}/v1/staff/{staffId}	Eliminação lógica de uma pessoa (define deletedAt).
DELETE	{baseUrl}/v1/schedule-conditions/{conditionId}	Marca a condição como cancelada (publicApiCancelledAt); não elimina linhas filhas.
PUT	{baseUrl}/v1/schedule-actual/{conditionId}	Guarda atribuições reais JSON { "assignments": [ ... ] } (validadas contra a grelha da condição).
PUT	{baseUrl}/v1/staff/{staffId}/weekly-shift-wish	Substitui desejos semanais: grelha completa (1–7 dias), wishByCellKey por célula (NONE\|LOW\|HIGH); granularidade dos padrões do inquilino.
POST	{baseUrl}/v1/users/{userId}/restore	Restaura um utilizador eliminado logicamente.

Cabeçalho	Descrição
x-api-key	Chave API ligada à sua subscrição paga (identifica o inquilino e os limites do plano).
Content-Type	application/json

Cabeçalhos de resposta

Alguns cabeçalhos de resposta (como IDs de pedido) são metadados de rastreio, não a sua chave API. Trate os **corpos** JSON como confidenciais quando incluírem dados da empresa ou do utilizador.

Limites de validação típicos do seu contrato (granularidade de 15 minutos, horizonte de escala, número de colaboradores registados e tetos relacionados).

Definição	API paga (típico)
Modelo de faturação	Subscrição Stripe; as taxas do produto escalam normalmente com os lugares de pessoal registados conforme a página de preços (sem cobrança por chamada API).
maxScheduleDays	Até 14 dias civis por envio no planeamento detalhado padrão de duas semanas (intervalos maiores só se o contrato permitir).
maxStaffPerSchedule	Até 500 linhas staff por POST /v1/schedule (PUBLIC_SCHEDULE_MAX_STAFF; staffId inline no corpo).
maxRosterStaff	Até 30 colaboradores ativos via POST /v1/staff (STAFF_ROSTER_MAX_PAID); 409 STAFF_LIMIT se excedido.
allowedGranularities	[60, 15] — slots de 15 minutos são uma capacidade paga; 60 minutos também é suportado.
maxPayloadBytes	524288 (512 KiB) UTF-8 salvo um teto superior concedido.
strictUnknownRootKeys	true — chaves desconhecidas no nível superior ou em staff são rejeitadas

A necessidade de pessoal por célula continua a ser um inteiro de 0 a 15. Exceder os limites de frequência de pedidos pode devolver uma resposta de erro.

Com o modo estrito ativo, só são aceites as seguintes chaves de nível superior. Qualquer outra devolve UNKNOWN_FIELD.

apiVersion
timeZone
scheduleStartDate
scheduleEndDate
timeRangeStart
timeRangeEnd
slotGranularityMinutes
requirementsByCell
staff

O payload segue o modelo público pago: datas de calendário, fuso horário, grelha de slots (60 ou 15 minutos na API paga), necessidades por célula e disponibilidade do pessoal. A jurisdição laboral, os indicadores de otimização paga e os campos laborais ao nível do colaborador não fazem parte do JSON — o servidor escreve predefinições na linha ascendente SCHEDULE_CONDITION ao persistir (veja «Legislação laboral e opções pagas»). Não inclua chaves DynamoDB nem tipos de entidade internos no corpo.

apiVersion — Opcional. Se presente, apenas a cadeia de versão de esquema suportada.
Formato cellKey — As chaves em requirementsByCell e availableCells devem corresponder a `${date}__${slotId}`, onde date é YYYY-MM-DD no intervalo e slotId vem dos slots enumerados para o seu intervalo horário e granularidade (igual a `cellKey` nos helpers do playground).

Campo	Tipo	Obrigatório	Notas
timeZone	string	Sim	Fuso horário IANA para interpretar datas e slots.
scheduleStartDate / scheduleEndDate	string (YYYY-MM-DD)	Sim	Intervalo de calendário inclusivo; início ≤ fim.
timeRangeStart / timeRangeEnd	string (HH:mm)	Sim	Intervalo horário de relógio que define a coluna de slots; deve gerar pelo menos um slot.
slotGranularityMinutes	60 \| 15	Sim	API paga: 60 (hora) ou 15 (quartos hora). Deve constar em allowedGranularities.
requirementsByCell	object	Sim	Chaves = cellKey na grelha calculada; valores = inteiro 0–15.
staff	array	Sim	Não vazio; tamanho máx. segundo limites; cada item: staffId, displayName, availableCells opcional.

Referência de campos (valores permitidos)

As secções seguintes espelham o validador em `app/lib/public-schedule-api/validate.ts` e os sanitizadores em `sanitize.ts`, com os predefinidos pagos de `PUBLIC_SCHEDULE_SUBMIT_DEFAULTS` salvo opções explícitas. Envie números JSON como números reais (não como strings). Após a validação, `build-schedule-transact-items.ts` adiciona campos da linha ascendente (cópia de otimização paga, jurisdição laboral, versão do modelo) que não são chaves de pedido — veja «Legislação laboral e opções pagas».

Valores permitidos

Omitido: aceite (comportamento atual).
Se presente, deve ser exatamente "2026-04-01" (PUBLIC_SCHEDULE_API_VERSION).
Qualquer outra cadeia é rejeitada (TYPE_ERROR).

Comportamento

Comparação após tratamento equivalente a trim em sanitizeApiVersion.

Erros típicos

TYPE_ERRORValor apiVersion não suportado.

Valores permitidos

Formato: uma única cadeia. A API não publica um enum fechado de todas as zonas: o servidor valida dinamicamente.
A validação corresponde a `isValidIanaTimeZone`: Luxon `DateTime.now().setZone(zone).isValid` deve ser true.
Use identificadores IANA canónicos, p. ex. `Asia/Tokyo`, `America/New_York`, `Europe/Berlin`, `UTC`.
Não confie apenas em abreviaturas (`EST`, `JST`, `GMT`) — não são IDs IANA estáveis e podem ser rejeitadas.
Listas de referência: distribuição IANA (https://www.iana.org/time-zones) ou a API de fuso horário da sua plataforma.

Comportamento

Usado com datas e horas de slot na normalização a jusante.
Se precisar de uma lista fixa no cliente, derive-a com as mesmas regras (IDs IANA), não espere um enum do servidor no esquema JSON.

Erros típicos

INVALID_TIME_ZONEEm falta, vazio ou zona IANA inválida.

Valores permitidos

Deve corresponder a /^\d{4}-\d{2}-\d{2}$/ (após trim).
Datas de calendário reais; o intervalo inclusivo deve produzir pelo menos um dia via enumerateDates.
O número de dias não deve exceder maxScheduleDays (API paga tipicamente até 14 dias; teto exato = direitos do inquilino).

Comportamento

scheduleStartDate deve ser anterior ou igual a scheduleEndDate.

Erros típicos

INVALID_DATE_RANGEFormato incorreto, datas inválidas ou intervalo vazio.
SCHEDULE_SPAN_TOO_LONGMais de maxScheduleDays dias.

Valores permitidos

Cadeias não vazias (trim) interpretadas com a mesma enumeração de slots que a UI (`enumerateSlotsByGranularity`).
O par deve gerar pelo menos um slot; caso contrário a validação falha.

Comportamento

Juntamente com slotGranularityMinutes, define os slotId usados em cellKey.

Erros típicos

INVALID_TIME_RANGEValores em falta ou zero slots para o intervalo.

Valores permitidos

Exatamente 60 ou 15 (não uma string).
Também deve constar em allowedGranularities. Na API paga ambos estão normalmente ativos; se 15 estiver desativado para o seu inquilino, INVALID_GRANULARITY.

Comportamento

Define o número de slots juntamente com o intervalo horário.

Erros típicos

INVALID_GRANULARITYNão é 60/15 ou não permitido no plano.

Valores permitidos

Deve ser um objeto JSON simples (não um array).
Cada chave deve ser um cellKey na grelha esperada (datas × slotIds). Chaves desconhecidas → UNKNOWN_CELL_KEY.
Cada valor: número JSON inteiro entre 0 e 15 inclusive.
Células omitidas tratam-se como necessidade 0 (SHORTFALL só para necessidade ≥ 1).

Comportamento

As chaves são comparadas após trim via sanitizeCellKey.

Erros típicos

INVALID_REQUIREMENTSNão é um objeto ou valor numérico inválido para uma chave.
UNKNOWN_CELL_KEYChave fora da grelha data × slot calculada.

Valores permitidos

Comprimento entre 1 e maxStaffPerSchedule (500 por defeito em POST /v1/schedule; distinto do teto de plantel em POST /v1/staff).
Cada elemento deve ser um objeto simples apenas com chaves permitidas: staffId, displayName, availableCells (modo estrito).
staffId e displayName devem passar a sanitização (veja «Sanitização»).
staffId deve ser único no array (DUPLICATE_STAFF_ID).

Comportamento

A ordem é preservada para a contagem de disponibilidade.

Erros típicos

INVALID_STAFFArray vazio, demasiadas linhas, objeto inválido ou sanitização falhada.
UNKNOWN_FIELDChave extra num objeto staff em modo estrito.
DUPLICATE_STAFF_IDO mesmo staffId duas vezes.

Valores permitidos

Se omitido: o colaborador é considerado disponível em todas as células da grelha (internamente null = «todas as células»).
Se presente: array JSON de strings; cada string não vazia deve ser um cellKey na grelha esperada.
Strings vazias no array são inválidas (INVALID_AVAILABLE_CELL).

Verificação SHORTFALL

Para cada célula com necessidade ≥ 1, o número de colaboradores disponíveis deve ser ≥ necessidade, senão SHORTFALL_CELLS.

Erros típicos

INVALID_AVAILABLE_CELLChave de célula desconhecida ou entrada vazia.
SHORTFALL_CELLSPessoal insuficiente face à necessidade numa célula.

O que a API guarda na linha ascendente

A API pública só aceita ROOT_KEYS no nível superior e STAFF_KEYS em cada linha de colaborador. Não envie laborLawJurisdiction, usLaborStateCode, laborModelVersion nem paidOptimization.
No envio, o servidor define a linha ascendente SCHEDULE_CONDITION com valores partilhados: paidOptimization = DEFAULT_PAID_OPTIMIZATION — laborLawCompliance false; balanceStaffLoad, honorShiftWishes e preferConsecutiveShifts true (veja schedule-defaults-shared.ts e build-schedule-transact-items.ts). laborLawJurisdiction JP, usLaborStateCode GENERIC, laborModelVersion v1.
As restrições laborais estilo lei no optimizador exigem indicadores de conformidade no ascendente e por colaborador; este caminho deixa-os desativados — não espere tetos legais só com este JSON.
O modelo laboral é uma aproximação para o planeamento, não aconselhamento jurídico. Catálogo: optimizer/config/labor_models.json.

Documentação

Detalhe completo: docs/data-and-api/PUBLIC_API_SCHEDULE_REQUEST_BODY.md §2.1.1 e §3.1.

Se enviar chaves não permitidas

UNKNOWN_FIELDO modo estrito rejeita propriedades desconhecidas na raiz ou em staff.

Aplicadas antes ou durante a validação como em `sanitize.ts`. Explicam rejeições como INVALID_STAFF.

staffId

Trim; comprimento 1–128.
Caracteres: /^[a-zA-Z0-9._-]+$/ (sem barras nem contrabarras).

displayName

Remover caracteres de controlo e zero-width; colapsar espaços; trim.
Os sinais < e > não são permitidos.
Máx. 128 caracteres após sanitização; não pode ficar vazio.

Chaves de célula (requirements / availableCells)

As chaves são cortadas; devem coincidir exatamente com as cellKey da grelha calculada.

202 Accepted

O corpo passou na validação e a condição foi escrita; a otimização pode continuar de forma assíncrona. O manipulador pode devolver JSON com conditionId e campos relacionados.

Os erros de validação devolvem informação estruturada com um `code` estável. A análise ocorre antes da validação (INVALID_JSON, PAYLOAD_TOO_LARGE). Falhas de persistência podem aparecer como DYNAMODB_ERROR. PATCH /v1/schedule-defaults pode devolver SCHEDULE_DEFAULTS_SAVE_FAILED (HTTP 400) com detalhes.

Código	Significado
INVALID_JSON	O corpo não é JSON válido.
PAYLOAD_TOO_LARGE	O comprimento em bytes UTF-8 excede maxPayloadBytes (predefinição 512 KiB).
TYPE_ERROR	Tipo JSON incorreto ou cadeia apiVersion não suportada.
UNKNOWN_FIELD	Modo estrito: propriedade não permitida na raiz ou no objeto staff.
INVALID_TIME_ZONE	timeZone em falta ou não é um nome IANA válido.
INVALID_DATE_RANGE	Datas não YYYY-MM-DD, intervalo inválido ou enumeração vazia.
SCHEDULE_SPAN_TOO_LONG	Demasiados dias entre início e fim (veja maxScheduleDays).
INVALID_TIME_RANGE	Intervalo horário em falta ou gera zero slots.
INVALID_GRANULARITY	slotGranularityMinutes não é 60/15 ou não permitido no plano.
INVALID_REQUIREMENTS	requirementsByCell não é objeto ou a contagem não é inteiro 0–15.
UNKNOWN_CELL_KEY	Chave não está na grelha de planeamento calculada.
INVALID_STAFF	staff vazio, demasiado grande, linha inválida ou sanitização falhada.
DUPLICATE_STAFF_ID	Valores staffId duplicados.
INVALID_AVAILABLE_CELL	Entrada vazia ou desconhecida em availableCells.
SHORTFALL_CELLS	Disponibilidade insuficiente face às necessidades.
DYNAMODB_ERROR	Erro transitório ou de persistência após validação (depende do manipulador).
SCHEDULE_DEFAULTS_SAVE_FAILED	PATCH /v1/schedule-defaults: validação ou regras de negócio falharam (ver error.details).
LABOR_COMPLIANCE_REQUIRED	PATCH /v1/staff/{staffId}: laborConstraintMask enviado com laborLawCompliance false.

{
  "apiVersion": "2026-04-01",
  "timeZone": "Asia/Tokyo",
  "scheduleStartDate": "2026-04-07",
  "scheduleEndDate": "2026-04-13",
  "timeRangeStart": "08:00",
  "timeRangeEnd": "20:00",
  "slotGranularityMinutes": 60,
  "requirementsByCell": {
    "2026-04-07__slot-0": 2
  },
  "staff": [
    {
      "staffId": "550e8400-e29b-41d4-a716-446655440000",
      "displayName": "Example",
      "availableCells": ["2026-04-07__slot-0"]
    }
  ]
}

Leitura adicional. Planos e funcionalidades pagas: docs/architecture/NURSE_SCHEDULING_SERVICE_SPECIFICATION.md. Corpo POST /v1/schedule: docs/data-and-api/PUBLIC_API_SCHEDULE_REQUEST_BODY.md §1–§11. Corpo PATCH das predefinições do inquilino: mesmo ficheiro §12. Código: app/lib/public-schedule-api/, app/features/schedule-settings/schedule-defaults-actions.ts, app/lib/public-api-write/weekly-shift-wish-tenant.ts. Implantação: docs/aws/CDK_DEPLOY.md.

Referência de API para programadores (paga)

Método

Caminho

Descrição

GET

{baseUrl}/v1/schedule-results

Lista linhas pai SCHEDULE_RESULT: conditionId, status, candidateCount, createdAt/updatedAt, etc. Paginação DynamoDB.

GET

{baseUrl}/v1/schedule-results/history

Pesquisa de histórico de resultados (como no navegador). from / to (ISO 8601, padrão início do serviço até agora), keyword, eventName (INSERT,MODIFY,REMOVE separados por vírgula), limit, cursor. Funde recente e arquivo automaticamente; só items / nextCursor.

GET

{baseUrl}/v1/schedule-results/{conditionId}

Obtém uma linha pai SCHEDULE_RESULT por conditionId (atributos JSON; sem PK/SK).

GET

{baseUrl}/v1/schedule-results/{conditionId}/resolution

Saída de otimização resolvida: status, candidates, confirmedAssignments quando presentes. Se status for completed e ainda não confirmado, rank-1 pode ser auto-confirmado neste GET (efeito colateral). Use POST …/confirm-assignments para confirmação manual.

GET

{baseUrl}/v1/schedule-results/{conditionId}/review

Payload de revisão para confirmação manual (candidatos, requiredByCellKey, allowedCellKeys do pessoal, etc.).

GET

{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift-context

Contexto de turno de emergência (datas, pessoal, slots). Subscrição paga necessária; null se a condição não existir.

GET

{baseUrl}/v1/schedule-conditions

Lista linhas pai SCHEDULE_CONDITION (conditionId, datas, publicApiCancelledAt opcional).

GET

{baseUrl}/v1/schedule-conditions/{conditionId}

Linha pai da condição mais reqDays e staffSnapshots (sem PK/SK).

GET

{baseUrl}/v1/audit-logs

Lista entradas de auditoria (mais recentes primeiro; paginação por cursor).

GET

{baseUrl}/v1/schedule-defaults

Linha de predefinições do inquilino (SCHEDULE_DEFAULTS) ou null se ainda não guardada.

GET

{baseUrl}/v1/schedule-actual/{conditionId}

Linha SCHEDULE_ACTUAL de turnos reais, ou null se inexistente.

GET

{baseUrl}/v1/staff/{staffId}/weekly-shift-wish

Linha de desejos semanais do colaborador, ou null se inexistente.

GET

{baseUrl}/v1/company

Devolve campos Stripe Customer (nome, e-mail, telefone, morada) para o customerId da sua chave API.

GET

{baseUrl}/v1/users

Lista utilizadores do inquilino (opcional: limit, cursor, userName, permissionProfileId, scope fullAccess|nonFullAccess).

GET

{baseUrl}/v1/users/{userId}

Obtém um utilizador pelo userId no caminho.

GET

{baseUrl}/v1/staff

Lista pessoal ativo do inquilino (ordenado por nome apresentado).

GET

{baseUrl}/v1/staff/{staffId}

Obtém uma pessoa por staffId com detalhes laborais (laborLawCompliance, laborFlsaExempt, tetos pessoais, laborConstraintMask). Eliminação lógica → 404.

Método

Caminho

Descrição

PATCH

{baseUrl}/v1/company

Atualiza os campos do perfil da empresa (cliente de faturação).

PATCH

{baseUrl}/v1/schedule-defaults

Guarda predefinições de horários do inquilino (corpo alinhado com saveSchema em schedule-defaults-actions). Os campos pagos seguem a sua subscrição.

POST

{baseUrl}/v1/users

Cria um utilizador. Devolve 201 com JSON user.

PATCH

{baseUrl}/v1/users/{userId}

Atualiza campos do utilizador (userName, email, permissionProfileId, locale).

DELETE

{baseUrl}/v1/users/{userId}

Elimina um utilizador. 409 se não restassem utilizadores ou regra do último administrador.

POST

{baseUrl}/v1/staff

Cria uma pessoa (displayName). Devolve 201 com JSON staff.

POST

{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift

Clona plano fonte concluído com ausências aplicadas; devolve 201 com conditionId. Subscrição paga necessária.

POST

{baseUrl}/v1/schedule-results/{conditionId}/confirm-assignments

Valida e grava atribuições editadas manualmente (200 com { ok: true }).

PATCH

{baseUrl}/v1/staff/{staffId}

Atualiza displayName e detalhes laborais (laborLawCompliance, laborFlsaExempt, tetos pessoais, laborConstraintMask).

DELETE

{baseUrl}/v1/staff/{staffId}

Eliminação lógica de uma pessoa (define deletedAt).

DELETE

{baseUrl}/v1/schedule-conditions/{conditionId}

Marca a condição como cancelada (publicApiCancelledAt); não elimina linhas filhas.

PUT

{baseUrl}/v1/schedule-actual/{conditionId}

Guarda atribuições reais JSON { "assignments": [ ... ] } (validadas contra a grelha da condição).

PUT

{baseUrl}/v1/staff/{staffId}/weekly-shift-wish

Substitui desejos semanais: grelha completa (1–7 dias), wishByCellKey por célula (NONE|LOW|HIGH); granularidade dos padrões do inquilino.

POST

{baseUrl}/v1/users/{userId}/restore

Restaura um utilizador eliminado logicamente.

Cabeçalho

Descrição

x-api-key

Chave API ligada à sua subscrição paga (identifica o inquilino e os limites do plano).

Content-Type

application/json

Definição

API paga (típico)

Modelo de faturação

Subscrição Stripe; as taxas do produto escalam normalmente com os lugares de pessoal registados conforme a página de preços (sem cobrança por chamada API).

maxScheduleDays

Até 14 dias civis por envio no planeamento detalhado padrão de duas semanas (intervalos maiores só se o contrato permitir).

maxStaffPerSchedule

Até 500 linhas staff por POST /v1/schedule (PUBLIC_SCHEDULE_MAX_STAFF; staffId inline no corpo).

maxRosterStaff

Até 30 colaboradores ativos via POST /v1/staff (STAFF_ROSTER_MAX_PAID); 409 STAFF_LIMIT se excedido.

allowedGranularities

[60, 15] — slots de 15 minutos são uma capacidade paga; 60 minutos também é suportado.

maxPayloadBytes

524288 (512 KiB) UTF-8 salvo um teto superior concedido.

strictUnknownRootKeys

true — chaves desconhecidas no nível superior ou em staff são rejeitadas

Campo

Tipo

Obrigatório

Notas

timeZone

string

Sim

Fuso horário IANA para interpretar datas e slots.

scheduleStartDate / scheduleEndDate

string (YYYY-MM-DD)

Sim

Intervalo de calendário inclusivo; início ≤ fim.

timeRangeStart / timeRangeEnd

string (HH:mm)

Sim

Intervalo horário de relógio que define a coluna de slots; deve gerar pelo menos um slot.

slotGranularityMinutes

60 | 15

Sim

API paga: 60 (hora) ou 15 (quartos hora). Deve constar em allowedGranularities.

requirementsByCell

object

Sim

Chaves = cellKey na grelha calculada; valores = inteiro 0–15.

staff

array

Sim

Não vazio; tamanho máx. segundo limites; cada item: staffId, displayName, availableCells opcional.

Referência de campos (valores permitidos)

Código

Significado

INVALID_JSON

O corpo não é JSON válido.

PAYLOAD_TOO_LARGE

O comprimento em bytes UTF-8 excede maxPayloadBytes (predefinição 512 KiB).

TYPE_ERROR

Tipo JSON incorreto ou cadeia apiVersion não suportada.

UNKNOWN_FIELD

Modo estrito: propriedade não permitida na raiz ou no objeto staff.

INVALID_TIME_ZONE

timeZone em falta ou não é um nome IANA válido.

INVALID_DATE_RANGE

Datas não YYYY-MM-DD, intervalo inválido ou enumeração vazia.

SCHEDULE_SPAN_TOO_LONG

Demasiados dias entre início e fim (veja maxScheduleDays).

INVALID_TIME_RANGE

Intervalo horário em falta ou gera zero slots.

INVALID_GRANULARITY

slotGranularityMinutes não é 60/15 ou não permitido no plano.

INVALID_REQUIREMENTS

requirementsByCell não é objeto ou a contagem não é inteiro 0–15.

UNKNOWN_CELL_KEY

Chave não está na grelha de planeamento calculada.

INVALID_STAFF

staff vazio, demasiado grande, linha inválida ou sanitização falhada.

DUPLICATE_STAFF_ID

Valores staffId duplicados.

INVALID_AVAILABLE_CELL

Entrada vazia ou desconhecida em availableCells.

SHORTFALL_CELLS

Disponibilidade insuficiente face às necessidades.

DYNAMODB_ERROR

Erro transitório ou de persistência após validação (depende do manipulador).

SCHEDULE_DEFAULTS_SAVE_FAILED

PATCH /v1/schedule-defaults: validação ou regras de negócio falharam (ver error.details).

LABOR_COMPLIANCE_REQUIRED

PATCH /v1/staff/{staffId}: laborConstraintMask enviado com laborLawCompliance false.

{ "apiVersion": "2026-04-01", "timeZone": "Asia/Tokyo", "scheduleStartDate": "2026-04-07", "scheduleEndDate": "2026-04-13", "timeRangeStart": "08:00", "timeRangeEnd": "20:00", "slotGranularityMinutes": 60, "requirementsByCell": { "2026-04-07__slot-0": 2 }, "staff": [ { "staffId": "550e8400-e29b-41d4-a716-446655440000", "displayName": "Example", "availableCells": ["2026-04-07__slot-0"] } ] }

Referência de API para programadores (paga)

Âmbito desta documentação

Subscrição e acesso

Autenticação

Endpoint

Utilização (início rápido)

Exemplo com curl (bash / macOS / Linux / WSL)

API de leitura (GET)

API de escrita (PATCH / POST / PUT / DELETE)

Cabeçalhos

Cabeçalhos de resposta

Limites do nível pago (direitos)

Chaves raiz permitidas (modo estrito)

Corpo do pedido (resumo)

Tabela de referência rápida

Referência de campos (valores permitidos)

apiVersion

timeZone

scheduleStartDate, scheduleEndDate

timeRangeStart, timeRangeEnd

slotGranularityMinutes

requirementsByCell

staff

staff[].availableCells

Legislação laboral e otimização paga (não vão no JSON)

Regras de sanitização

Resposta de sucesso

Códigos de erro (lista completa)

Exemplo JSON mínimo

Referência de API para programadores (paga)

Âmbito desta documentação

Subscrição e acesso

Autenticação

Endpoint

Utilização (início rápido)

Exemplo com curl (bash / macOS / Linux / WSL)

API de leitura (GET)

API de escrita (PATCH / POST / PUT / DELETE)

Cabeçalhos

Cabeçalhos de resposta

Limites do nível pago (direitos)

Chaves raiz permitidas (modo estrito)

Corpo do pedido (resumo)

Tabela de referência rápida

Referência de campos (valores permitidos)

apiVersion

timeZone

scheduleStartDate, scheduleEndDate

timeRangeStart, timeRangeEnd

slotGranularityMinutes

requirementsByCell

staff

staff[].availableCells

Legislação laboral e otimização paga (não vão no JSON)

Regras de sanitização

Resposta de sucesso

Códigos de erro (lista completa)

Exemplo JSON mínimo