Workspaces e departamentos

Como os cabeçalhos X-Workspace-ID e X-Department-ID definem o contexto de cada chamada e limitam os resultados.

Um usuário pode fazer parte de vários workspaces, e um workspace pode ser dividido em departamentos. Cada chamada com token de login acontece dentro de um workspace e, opcionalmente, de um departamento.

X-Workspace-ID

Envie o id do workspace no cabeçalho X-Workspace-ID:

curl "https://api.vozkoia.com/leads" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "X-Workspace-ID: SEU_WORKSPACE_ID"
  • Os workspaces do usuário vêm de GET /workspaces.
  • O parâmetro de URL workspace_id tem o mesmo efeito do cabeçalho. Rotas com {workspaceId} no caminho usam o valor do caminho.
  • Sem nenhum dos dois, a API usa o workspace padrão do usuário.
  • Um id de workspace do qual o usuário não faz parte é ignorado, e a API também usa o workspace padrão. Confira o id antes de enviar, para não ler nem gravar dados no workspace errado.

As permissões são do usuário naquele workspace. Uma rota que exige uma permissão que ele não tem responde 403, com o código <ação>_permission_required (por exemplo read_permission_required) e a permissão exigida em expected.required_permission:

{
  "error": true,
  "code": "read_permission_required",
  "message": "Insufficient permissions: requires leads:read in this workspace",
  "expected": {
    "required_permission": "leads:read"
  }
}

Quando a rota exige um workspace e nenhum pôde ser definido, a resposta é 400 com a mensagem workspace_id is required.

X-Department-ID

Departamentos dividem o atendimento e os recursos do workspace, como conversas, campanhas, agentes e fluxos. O cabeçalho X-Department-ID restringe a chamada a um departamento:

curl "https://api.vozkoia.com/leads" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "X-Workspace-ID: SEU_WORKSPACE_ID" \
  -H "X-Department-ID: SEU_DEPARTMENT_ID"

O efeito depende do papel do usuário no workspace:

Quem chamaSem X-Department-IDCom X-Department-ID
Dono ou administrador do workspaceVê todos os departamentos.Restringe ao departamento informado. Um departamento de outro workspace responde 403 (Selected department does not belong to this workspace).
Demais membros, em um workspace com departamentosVê apenas os departamentos de que faz parte.Restringe ao departamento informado, que precisa ser um dos seus; senão, 403 (Not a member of the selected department).

O cabeçalho apenas estreita o que o usuário já pode ver; ele nunca dá acesso a um departamento de que o usuário não faz parte. Os departamentos do workspace estão em /departments.

Chaves de API

As rotas que aceitam a chave de API do workspace tiram o workspace da própria chave e ignoram X-Workspace-ID.


Did this page help you?