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.
Âmbito desta documentação
Esta página documenta a API REST de produto para integrações externas.
Os webhooks de conclusao de resultados sao notificacoes HTTPS de saida configuradas na gestao de API (nao CRUD REST). Ver Completion webhooks nesta pagina.
Rotas internas do browser (p. ex. callbacks de pagamento ou analytics) nao substituem esta API de produto. Para sistemas externos, use /v1/* e os webhooks de conclusao.
Subscrição e acesso
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.
Autenticação
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. Operações fora dos scopes devolvem 403 (API_KEY_SCOPE_DENIED). Chaves sem atributo scopes ainda permitem todas as operações.
Cole o bloco abaixo num assistente de chat quando quiser ajuda para chamar esta API do produto sem configurar MCP.
Resume URL base, autenticação, operações principais e cuidados de escrita. Nunca inclui uma chave de API real.
Para chamadas de API reais a partir de um agente, configure MCP (agentes) em vez de confiar só neste texto.
Contexto para colar
Auto Scheduler — Public API context for LLM assistants
Use this when helping a developer call the Auto Scheduler paid product REST API (/v1/*). Prefer configuring Tools MCP when available; this paste is for chat without MCP.
Base URL
- https://api.autoschedulers.com
- Paths are under /v1/*. Do not confuse this with the marketing website origin.
Authentication
- Every request needs header: x-api-key: <API_KEY>
- Never paste a real API key into chat logs or this prompt; ask the user to supply it via environment or a secret store.
- Keys are created in the product under Account → API management.
- JSON writes: Content-Type: application/json
Read endpoints
- GET /v1/schedule-results?limit=10
- GET /v1/schedule-results/{conditionId}
- GET /v1/schedule-conditions
- GET /v1/staff
- GET /v1/staff/{staffId}
- GET /v1/schedule-defaults
- GET /v1/schedule-results/{conditionId}/emergency-shift-context
Write endpoints (confirm with the user before calling)
- POST /v1/schedule — starts a job; may incur charges; max 14 calendar days
- PATCH /v1/schedule-defaults — tenant-wide
- POST /v1/staff
- PATCH /v1/staff/{staffId}
- PUT /v1/staff/{staffId}/weekly-shift-wish — full replace
- POST /v1/schedule-results/{conditionId}/emergency-shift — paid
- POST /v1/schedule-results/{conditionId}/confirm-assignments
- DELETE /v1/schedule-conditions/{conditionId}
- PUT /v1/schedule-actual/{conditionId} — full replace
Minimal curl (read)
curl -sS -H "x-api-key: YOUR_API_KEY" "https://api.autoschedulers.com/v1/staff"
curl -sS -H "x-api-key: YOUR_API_KEY" "https://api.autoschedulers.com/v1/schedule-results?limit=10"
Contract notes
- Schedule submit body needs a supported apiVersion and valid JSON fields — see api-docs Field reference or Docs MCP Resources; do not invent fields.
- planningHorizon on defaults is only week or two_weeks (month_attendance is rejected).
- Outbound completion webhooks are HMAC-signed HTTPS callbacks configured in API management (not REST CRUD).
Safety
- Write endpoints change tenant data. Confirm destructive or irreversible actions with the user before calling them.
- Prefer read/list first when exploring an unfamiliar tenant.
Endpoint
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.
URL base
Host da API REST pública (/v1/*), não a URL do site no navegador. Defina AUTO_SCHEDULER_PUBLIC_API_BASE_URL (MCP) e BASE_URL (curl) com este valor.
AUTO_SCHEDULER_PUBLIC_API_BASE_URL — URL base configurada para este ambiente de documentação. Use o mesmo valor no MCP e no curl.
Use o URL base fornecido quando o acesso à API foi provisionado ou pelo seu contacto de operações.
Utilização (início rápido)
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.
Funções pagas (detalhes laborais, alguns valores predefinidos) exigem uma subscrição paga ativa. Pode receber **503** (p. ex. código **STRIPE_NOT_CONFIGURED**) quando a faturação não estiver configurada. O perfil da empresa, registos de auditoria e gestão de utilizadores (contas) são feitos na aplicação web e não fazem parte da API pública.
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.
Você pode chamar a mesma API REST do produto a partir de agentes como Cursor, Claude, Gemini e GPT via MCP. As operações correspondem à superfície /v1 desta página.
Os servidores MCP incluídos usam stdio local. Adicione command / args / env em cada arquivo de configuração do cliente. Crie chaves em Gerenciamento de API (nunca faça commit nem cole em chats públicos).
Só para documentação, um MCP de Resources não precisa de login nem chave de API (mcp/api-docs). Esta página (/{locale}/api-docs) também pode ser vista sem entrar; criar chaves ainda exige Conta → Gerenciamento de API.
Caminho mais rápido (recomendado)
Create an API key in Account → API management (never paste the real key into chat).
In the repo: cd mcp/public-api && npm install && npm run build (also mcp/api-docs if you want documentation Resources).
Copy the env snippet below and the Cursor mcp.json under Client-specific setup; replace paths and YOUR_* placeholders.
Restart the client and confirm Tools (list_staff, …) appear. Prefer read tools before any write.
Qual opção usar
Tools MCP (public-api)
Live /v1 calls with your API key. Use this when the agent should actually list staff, submit schedules, etc.
Docs MCP (api-docs Resources)
Contract markdown only—no API key. Use when the agent needs field rules or request-body shape.
Copy for LLM (this page)
Orientation text for chat assistants without MCP. Not enough alone for correct request bodies—pair with MCP or the sections below.
Variáveis de ambiente obrigatórias (Tools MCP)
AUTO_SCHEDULER_PUBLIC_API_BASE_URL
URL base da API REST pública (/v1/*)—não o domínio do site. Use o host de API informado (barra final opcional)
AUTO_SCHEDULER_API_KEY
Chave do Gerenciamento de API (não faça commit nem publique)
Variável
Descrição
AUTO_SCHEDULER_PUBLIC_API_BASE_URL
URL base da API REST pública (/v1/*)—não o domínio do site. Use o host de API informado (barra final opcional)
AUTO_SCHEDULER_API_KEY
Chave do Gerenciamento de API (não faça commit nem publique)
Os conectores do console cloud do Gemini miram MCP remoto. Use Gemini CLI para stdio local.
GPT (ChatGPT / OpenAI)
Configurações do conector do ChatGPT (somente MCP remoto). Não há mcp.json local para o ChatGPT.
O ChatGPT (conectores web / desktop) não pode iniciar processos MCP stdio locais
Este produto só inclui MCP stdio local, então o ChatGPT não pode conectar diretamente
Para agentes classe GPT: (1) execute o mesmo MCP no Cursor / Claude / Gemini CLI, ou (2) chame a API REST desta página com x-api-key em Custom Actions / seu cliente de API
Só é possível registrar um conector do ChatGPT se você hospedar um MCP HTTPS remoto (não é oferta padrão do produto).
OpenAI Agents / Responses API também esperam MCP remoto (HTTP). Os servidores incluídos são para clientes stdio.
Visão geral das ferramentas (public-api)
Há ferramentas de leitura e escrita. Escritas podem iniciar jobs cobrados ou alterar configurações da organização—confirme antes de chamar.
If status is completed and not yet confirmed, rank-1 may be auto-confirmed on this GET (side effect). Prefer POST …/confirm-assignments for explicit confirmation.
Endpoints de escrita (PATCH / POST / PUT / DELETE)
Mesma chave API e corpos JSON que outras rotas /v1. Cada cartão mostra um corpo de pedido mínimo que pode copiar. Utilizadores de conta, perfil da empresa e logs de auditoria ficam na app web — não nesta API. POST /v1/staff devolve 409 STAFF_LIMIT quando o plantel excede o limite do inquilino.
Campos laborais e Soft prefer/avoid exigem subscrição paga. Substitua UUID, datas e chaves de célula de exemplo pelos dados do seu inquilino.
PATCH{baseUrl}/v1/schedule-defaults
Saves tenant-wide schedule defaults. Paid-tier fields follow your subscription.
requirementsByCellKey must include every cell in period × slots (missing/extra keys → 400). Cell key = YYYY-MM-DD__HH:mm. planningHorizon: week | two_weeks (month_attendance rejected). Optional: requiredRolesByCellKey, laborLawJurisdiction, usLaborStateCode, linkedMonthPlanStartDate / linkedMonthPlanEndDate, laborModelVersion.
Clones a completed source schedule with absences applied. Returns 201 with new conditionId. Paid subscription required.
Prefer absentDayPairs. Legacy: absentStaffIds + absentDatesYmd (Cartesian). You may also send absentSlots. Optional substituteDayPairs / substituteSlots open coverage (source must be completed).
Updates one staff member. Send any subset of the fields in the example.
Personal max minutes: integer or null to clear. laborConstraintMask only when laborLawCompliance is true. schedulingRoleIds / Soft prefer-avoid: UUID arrays; unknown catalog IDs filtered; prefer and avoid must be disjoint. Labor and Soft require paid.
Replaces the weekly wish grid for one staff member (full replace).
Dates/time range must match the tenant weekly-wish navigation window from schedule defaults. wishByCellKey must cover every cell in that window. Values: NONE | LOW | HIGH.
Quando um resultado de escala atinge um status terminal, fazemos POST de uma notificação JSON assinada à sua URL HTTPS. O corpo não inclui o resultado completo; busque detalhes com GET /v1/schedule-results/{conditionId}.
Resultados do playground não são entregues. Se o webhook estiver desabilitado ou não houver URL salva, nada é enviado.
Configuração
Após entrar, abra Gerenciamento de API e salve uma URL de notificação HTTPS.
Ative «Habilitar notificações».
Copie o segredo de assinatura mostrado uma vez (não pode ser revelado de novo; regenere se perder).
Verifique a assinatura no receptor e, se precisar, faça GET de links.result com sua chave de API.
Eventos
Tipo de evento e quando é enviado.
schedule.result.terminal
O status do resultado da escala vira completed, no_solution, failed, error ou canceled
type
Quando
schedule.result.terminal
O status do resultado da escala vira completed, no_solution, failed, error ou canceled
Corpo da solicitação
status é apenas terminal. customerId é omitido do corpo.
Calcule um digest do corpo bruto (antes do parse JSON) e do Timestamp e compare com Signature. Rejeite quando |now − timestamp| ultrapassar 300 segundos (5 minutos), a menos que permita de propósito maior skew de relógio.
HMAC-SHA256(signingSecret, `${timestamp}.${rawBody}`) → hex; o valor do cabeçalho é v1=<hex>
Novas tentativas
Em 5xx ou timeout tentamos de novo automaticamente. Falhas persistentes vão para uma fila dead-letter. Notificações push do navegador usam outro caminho.
Chave API ligada à sua subscrição paga (identifica o inquilino e os limites do plano).
Content-Type
application/json
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 do nível pago (direitos)
Limites de validação típicos do seu contrato (granularidade de 15 minutos, horizonte de escala, número de colaboradores registados e tetos relacionados).
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 de duas semanas (teto fixo; o contrato não alarga).
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
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 de duas semanas (teto fixo; o contrato não alarga).
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.
Chaves raiz permitidas (modo estrito)
Com o modo estrito ativo, só são aceites as seguintes chaves de nível superior. Qualquer outra devolve UNKNOWN_FIELD.
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 não está no JSON. paidOptimization é opcional para apiVersion 2026-09-13+ (caso contrário, predefinições do inquilino). Campos Soft prefer/avoid do colaborador exigem 2026-09-14. Veja «Legislação laboral e opções pagas». Não inclua chaves DynamoDB nem tipos de entidade internos no corpo.
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).
Tabela de referência rápida
timeZone
Tipo
string
Obrigatório
Sim
Fuso horário IANA para interpretar datas e slots.
scheduleStartDate / scheduleEndDate
Tipo
string (YYYY-MM-DD)
Obrigatório
Sim
Intervalo de calendário inclusivo; início ≤ fim.
timeRangeStart / timeRangeEnd
Tipo
string (HH:mm)
Obrigatório
Sim
Intervalo horário de relógio que define a coluna de slots; deve gerar pelo menos um slot.
slotGranularityMinutes
Tipo
60 | 15
Obrigatório
Sim
API paga: 60 (hora) ou 15 (quartos hora). Deve constar em allowedGranularities.
requirementsByCell
Tipo
object
Obrigatório
Sim
Chaves = cellKey na grelha calculada; valores = inteiro 0–15.
requiredRolesByCell
Tipo
object
Obrigatório
Não — somente 2026-09-09
cellKey → roleId→need. Soma de need por célula ≤ requirementsByCell. Versões legadas → UNKNOWN_FIELD.
staff
Tipo
array
Obrigatório
Sim
Não vazio; tamanho máx. segundo limites; cada item: staffId, displayName, availableCells / laborConstraintMask / schedulingRoleIds (2026-09-09+) / Soft prefer-avoid (2026-09-14) opcionais.
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.
requiredRolesByCell
object
Não — somente 2026-09-09
cellKey → roleId→need. Soma de need por célula ≤ requirementsByCell. Versões legadas → UNKNOWN_FIELD.
staff
array
Sim
Não vazio; tamanho máx. segundo limites; cada item: staffId, displayName, availableCells / laborConstraintMask / schedulingRoleIds (2026-09-09+) / Soft prefer-avoid (2026-09-14) opcionais.
Referência de campos (valores permitidos)
As regras de campo abaixo coincidem com o validador da API pública. Envie números JSON como números reais (não como strings). Após a validação, o servidor pode persistir predefinições da linha ascendente (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».
apiVersion
string | omitido · Obrigatório: Não — opcional
Valores permitidos
Omitido: aceite (comportamento atual).
Se presente, deve ser "2026-04-01", "2026-09-09", "2026-09-13" ou "2026-09-14". Última versão publicada: 2026-09-14.
Qualquer outra cadeia é rejeitada (TYPE_ERROR).
Comportamento
Comparação após tratamento equivalente a trim em sanitizeApiVersion.
A versão seleciona os conjuntos de chaves permitidos no nível superior e no objeto staff (funções em 2026-09-09+; paidOptimization em 2026-09-13+; Soft prefer/avoid em 2026-09-14).
Erros típicos
TYPE_ERRORValor apiVersion não suportado.
timeZone
string · Obrigatório: Sim
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.
scheduleStartDate, scheduleEndDate
string, string · Obrigatório: Sim — ambos
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: teto fixo de 14 dias para planeamento de duas semanas).
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.
timeRangeStart, timeRangeEnd
string, string · Obrigatório: Sim — ambos
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.
slotGranularityMinutes
number (número JSON) · Obrigatório: Sim
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.
requirementsByCell
Record<string, number> · Obrigatório: Sim
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.
requiredRolesByCell
object | omitted · Obrigatório: Não — opcional; somente apiVersion 2026-09-09
Valores permitidos
Aceito apenas quando apiVersion é "2026-09-09". Omitido / 2026-04-01 → UNKNOWN_FIELD.
Deve ser um objeto JSON simples. Cada chave é um cellKey na grade requirements.
Cada valor é um objeto que mapeia roleId (UUID) → need inteiro ≥ 1.
Para cada célula, sum(need) deve ser ≤ requirementsByCell[cell] (ou 0 se omitido).
O caminho de envio valida apenas a forma UUID e a soma (sem lookup de catálogo).
Comportamento
Os valores são normalizados e validados (IDs de função UUID; soma de need ≤ quadro).
Persistido como requiredRolesBySlot nas linhas de requisitos diários.
Erros típicos
UNKNOWN_FIELDEnviado com apiVersion legada.
INVALID_REQUIREMENTSFormato inválido, roleId não UUID ou soma excede o quadro.
UNKNOWN_CELL_KEYcellKey fora da grade calculada.
staff
array · Obrigatório: Sim — array não vazio
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 para o apiVersion: staffId, displayName, availableCells, laborConstraintMask; mais schedulingRoleIds em 2026-09-09+; mais preferredSchedulingRoleIds / avoidedSchedulingRoleIds em 2026-09-14 (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.
staff[].availableCells
string[] | omitido · Obrigatório: Não — opcional
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.
staff[].schedulingRoleIds / Soft prefer-avoid
string[] | omitted · Obrigatório: Não — opcional; funções em 2026-09-09+; Soft em 2026-09-14
Valores permitidos
schedulingRoleIds: aceite em apiVersion 2026-09-09+. Soft preferredSchedulingRoleIds / avoidedSchedulingRoleIds: só 2026-09-14. Versões anteriores → UNKNOWN_FIELD.
Arrays JSON de strings UUID. Duplicatas removidas. Soft prefer ∩ avoid deve estar vazio.
Array vazio / omitir = sem quadro de função Hard / preferência Soft no snapshot de condição.
O caminho de envio não filtra contra o catálogo do inquilino; PATCH /v1/staff/{staffId} sim (PATCH Soft pago).
Comportamento
Os valores são normalizados (strings UUID; duplicatas removidas). Sobreposição Soft → INVALID_STAFF.
Copiado para linhas do snapshot de condição da equipe quando não vazio.
Erros típicos
UNKNOWN_FIELDEnviado com apiVersion que não permite a chave.
INVALID_STAFFNão é array, elemento não UUID ou sobreposição Soft prefer/avoid.
Legislação laboral e otimização paga (não vão no JSON)
n/d — persistido no servidor · No pedido: Não — nunca envie estas chaves
O que a API guarda na linha ascendente
A API pública só aceita as chaves de topo e de objeto staff permitidas para o seu apiVersion. Não envie laborLawJurisdiction, usLaborStateCode nem laborModelVersion. paidOptimization é opcional para apiVersion 2026-09-13+. Campos Soft prefer/avoid do colaborador exigem 2026-09-14.
No envio, o servidor define a linha ascendente SCHEDULE_CONDITION com valores partilhados: paidOptimization do corpo (apiVersion 2026-09-13+) ou SCHEDULE_DEFAULTS do inquilino se omitido; senão DEFAULT_PAID_OPTIMIZATION (laborLawCompliance do pai forçado a true). laborLawJurisdiction / usLaborStateCode / laborModelVersion são herdados de SCHEDULE_DEFAULTS do inquilino (reserva JP / GENERIC / modelo conforme a jurisdição).
As restrições laborais estilo lei no optimizador exigem indicadores de conformidade no ascendente e por colaborador. Os indicadores por pessoa não vêm no JSON: o servidor herda da lista de pessoal (staffIds ausentes ficam ativos por omissão). POST /v1/staff também cria ativo; desligar por pessoa exige PATCH pago /v1/staff/{staffId}.
O modelo laboral é uma aproximação para o planeamento, não aconselhamento jurídico. Catálogo: .
Documentação
Detalhe completo: this page e §3.1.
Se enviar chaves não permitidas
UNKNOWN_FIELDO modo estrito rejeita propriedades desconhecidas na raiz ou em staff.
Regras de sanitização
Aplicado antes ou durante a validação. Estas regras explicam porque um valor pode ser rejeitado 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.
Resposta de sucesso
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.
Códigos de erro (lista completa)
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.
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.
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.
Nesta página. POST /v1/schedule: referência de campos e tabela. Predefinições: endpoints de escrita → PATCH /v1/schedule-defaults. Labor / Soft: PATCH /v1/staff/{staffId}. Planos: página de preços.