Dask

Dask

Referencia da Dask API para WorkItems, contatos e workspace.

A Dask API usa Authorization Bearer com PAT criada dentro de um workspace. Cada token carrega scopes, revalida permissoes no backend e so opera nos dados do workspace emissor.

Conhecer a home Contato

Autenticacao

Headers obrigatorios

Crie uma PAT em Settings > Integrations > Dask API. O segredo aparece somente no momento da criacao e deve ser usado apenas server-to-server.

  • Envie Authorization: Bearer dask_live_... em todas as chamadas.
  • Envie Idempotency-Key em POST, PATCH e DELETE para proteger replays.
  • Envie Content-Type: application/json quando houver body.
  • Nunca envie o segredo para browser, apps publicos ou logs.
  • A PAT pertence a um workspace e falha se tentar acessar dados de outro workspace.
  • Reusar a mesma Idempotency-Key com outro metodo, path, query ou payload retorna conflito.

Workspace

Rotas de discovery

Use estas rotas antes de gravar dados para descobrir ids, slugs, tags e campos customizados publicados no workspace.

  • GET /api/v1/dask/api-keyAuth: PAT valida

    Retorna id, workspaceId, name, keyPrefix, scopes e createdByUserId da PAT autenticada sem expor o segredo completo.

  • GET /api/v1/dask/workspace/configScope: workspace:schema:read

    Retorna snapshot de configuracao operacional do workspace para montar payloads validos.

  • GET /api/v1/dask/workspace/item-typesScope: workspace:schema:read

    Lista tipos aceitos em WorkItems. Use typeId ou typeSlug em criacao e atualizacao.

  • GET /api/v1/dask/workspace/workflow-statesScope: workspace:schema:read

    Lista estados de workflow aceitos. Use stateId ou stateSlug em criacao e atualizacao.

  • GET /api/v1/dask/workspace/tagsScope: workspace:schema:read

    Lista tags disponiveis para associar a WorkItems.

  • GET /api/v1/dask/workspace/custom-fieldsScope: workspace:schema:read

    Lista campos customizados publicados para montar customFieldValues.

WorkItems

CRUD de WorkItems

Todas as rotas sao tenant-scoped pelo workspace da PAT e revalidam permissao de board no backend.

  • GET /api/v1/dask/work-itemsScope: workitems:read

    Query: search, limit, pageSize, cursor, typeId/typeSlug, stateId/stateSlug, assigneeId, dueDateFrom/dueDateTo, createdAtFrom/createdAtTo, updatedAtFrom/updatedAtTo, customFieldFilters, sortBy e sortDirection. Retorna items, nextCursor e total.

  • GET /api/v1/dask/work-items/{itemId}Scope: workitems:read

    Path param: itemId uuid. Retorna a projecao publica do WorkItem quando ele pertence ao workspace da PAT.

  • POST /api/v1/dask/work-itemsScope: workitems:create

    Payload: title obrigatorio; description, boardId, typeId/typeSlug, stateId/stateSlug, columnId, assigneeId, parentId, contactId, dueDate, position, checklist, metadata, fields, tags e customFieldValues opcionais. Exige Idempotency-Key. Retorna 201 com o WorkItem.

  • PATCH /api/v1/dask/work-items/{itemId}Scope: workitems:update

    Path param: itemId uuid. Payload parcial com pelo menos um campo permitido: title, description, typeId/typeSlug, stateId/stateSlug, columnId, assigneeId, parentId, contactId, dueDate, position, checklist, metadata, fields ou customFieldValues. Exige Idempotency-Key. Retorna 200 com o WorkItem atualizado.

  • DELETE /api/v1/dask/work-items/{itemId}Scope: workitems:delete

    Path param: itemId uuid. Remove o WorkItem, exige Idempotency-Key e retorna 204 sem corpo.

Contatos

CRUD de contatos

Contatos usam o modulo commercial e exigem que o usuario emissor da PAT continue membro do workspace.

  • GET /api/v1/dask/contactsScope: contacts:read

    Query: search, lifecycleStage, originId, hasCustomer, hasWorkItem, hasWhatsapp, hasEmail, productId, planId, createdFrom, updatedAtFrom, updatedAtTo, limit, pageSize e cursor. Retorna items e nextCursor.

  • GET /api/v1/dask/contacts/{contactId}Scope: contacts:read

    Path param: contactId uuid. Retorna o contato quando ele pertence ao workspace da PAT.

  • POST /api/v1/dask/contactsScope: contacts:create ou contacts:write

    Payload aceita displayName, contactName, companyId, companyName, customerName, primaryEmail, primaryPhone, primaryWhatsapp, legalName, document, addressText, addressCity, addressState, addressCountry, logoUrl, originId, referrerName, productId, externalSource, externalId, lifecycleStage, marketingStatus, whatsappOptInStatus, emailOptInStatus e metadata. Pelo menos uma identidade deve existir: displayName, contactName, companyName, customerName, primaryEmail, primaryPhone, primaryWhatsapp ou document. Exige Idempotency-Key e retorna 201 com created e contact.

  • PATCH /api/v1/dask/contacts/{contactId}Scope: contacts:update ou contacts:write

    Path param: contactId uuid. Payload parcial com pelo menos um campo de contato. Exige Idempotency-Key e retorna 200 com o contato atualizado.

  • DELETE /api/v1/dask/contacts/{contactId}Scope: contacts:delete

    Path param: contactId uuid. Remove o contato, exige Idempotency-Key e retorna 204 sem corpo.

Exemplos

cURL e respostas

A pagina renderizada mostra um bloco cURL copiavel para cada rota, alem de exemplo de entrada e saida em JSON.

  • Criar contato: curl -X POST https://my-dask.com/api/v1/dask/contacts -H "Authorization: Bearer dask_live_..." -H "Content-Type: application/json" -H "Idempotency-Key: contact-create-001" --data '{ "displayName": "Maria Silva", "primaryEmail": "[email protected]" }'
  • Criar WorkItem: curl -X POST https://my-dask.com/api/v1/dask/work-items -H "Authorization: Bearer dask_live_..." -H "Content-Type: application/json" -H "Idempotency-Key: workitem-create-001" --data '{ "title": "Follow up", "typeSlug": "task" }'
  • Resposta de contato: { "created": true, "contact": { "id": "uuid", "displayName": "Maria Silva" } }
  • Resposta de WorkItem: { "id": "uuid", "title": "Follow up", "typeSlug": "task" }

Erros

Codigos comuns

Erros conhecidos incluem WORKSPACE_API_KEY_INVALID para PAT invalida, WORKSPACE_API_KEY_FORBIDDEN para scope ausente, WORKSPACE_API_KEY_ACTOR_NOT_MEMBER quando o emissor nao e mais membro, DASK_API_IDEMPOTENCY_KEY_REQUIRED quando uma mutacao nao envia Idempotency-Key, DASK_API_IDEMPOTENCY_KEY_TOO_LONG quando a chave passa de 160 caracteres e DASK_API_IDEMPOTENCY_KEY_CONFLICT quando a mesma chave e usada com outro payload.