Guias
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_idtem 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
idde workspace do qual o usuário não faz parte é recusado com403e o códigoworkspace_not_member; a API nunca troca de workspace por conta própria. Remova oidguardado (por exemplo depois de sair de um workspace) e repita sem ele para usar o workspace padrão.
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 chama | Sem X-Department-ID | Com X-Department-ID |
|---|---|---|
| Dono ou administrador do workspace | Vê 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 departamentos | Vê 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.