Referência da API para conectar o DobroDesk ao Zapier

URL base e chaves de acesso

A integração do Zapier usa a API HTTPS de produção em https://dobrodesk.com/api/v1. Envie uma chave de acesso ativa da DobroDesk no cabeçalho Authorization de cada pedido.

Crie uma chave para iniciar automatizações e outra para adicionar notas internas. A chave do acionador pode ler metadados das conversas em toda a área de trabalho, incluindo identificadores, caixa de entrada, estado, canal de origem e datas. Não pode ler o texto das mensagens dos clientes nem os anexos. O filtro da caixa de entrada limita os eventos entregues, mas não o acesso aos metadados. A chave das notas pode adicionar uma nota interna a uma conversa na área de trabalho.

As chaves do Zapier com finalidade definida são a opção recomendada para a ligação de autosserviço. A chave do acionador usa conversations:read e funciona nas rotas de acionador descritas e na verificação da ligação. A chave das notas usa conversations:write e funciona na rota de notas internas e na verificação da ligação. Estas chaves são recusadas noutras rotas da API com HTTP 403 e o código api_token_purpose_forbidden. Uma chave REST API genérica ativa também é aceite nestas rotas do Zapier de acordo com os respetivos âmbitos habituais: a verificação da ligação não requer âmbito, as rotas de leitura e subscrição requerem conversations:read e adicionar uma nota requer conversations:write. As chaves genéricas mantêm o seu acesso REST API habitual. Para limitar as permissões, use as chaves com finalidade definida.

Trate uma chave de acesso como uma palavra-passe. Não a inclua num URL, código do navegador, registo partilhado ou URL de destino de um webhook do Zapier.

Authorization: Bearer dd_live_<dedicated-access-key>

Verificar a ligação

GET /zapier/connection verifica uma chave REST API ativa e identifica a área de trabalho e a ligação. A rota aceita uma chave genérica ou qualquer uma das chaves Zapier com finalidade definida. Não requer um âmbito adicional. Em caso de sucesso, devolve HTTP 200.

O objeto data contém workspaceId, tokenId, scopes, workspaceName e connectionName. A rota não devolve a chave de acesso.

GET https://dobrodesk.com/api/v1/zapier/connection
Authorization: Bearer dd_live_<dedicated-access-key>

{
  "data": {
    "workspaceId": "<workspaceId>",
    "tokenId": "<tokenId>",
    "scopes": ["conversations:read"],
    "workspaceName": "<workspaceName>",
    "connectionName": "<connectionName>"
  }
}

Consultar caixas de entrada e exemplos de conversas

GET /zapier/inboxes?page=0&limit=100 devolve uma página de caixas de entrada em data. Cada elemento contém id e name. page é um número inteiro entre 0 e 10 000 e tem o valor predefinido 0. limit é um número inteiro entre 1 e 100 e tem o valor predefinido 100.

GET /zapier/conversations?limit=3&inboxId=<inboxId> devolve metadados de conversas para testar o passo no editor do Zapier. inboxId é opcional e, quando indicado, tem de ser uma cadeia não vazia. limit é um número inteiro entre 1 e 100 e tem o valor predefinido 10. Cada resultado contém id, workspaceId, conversationId, status, sourceChannel e createdAt, além de inboxId quando existe. id corresponde ao ID da conversa. O texto das mensagens dos clientes e os anexos não são devolvidos.

Ambas as rotas requerem conversations:read. Use a chave do acionador com finalidade definida ou uma chave REST API genérica ativa com esse âmbito. No resultado do acionador ativo, eventId identifica o evento e occurredAt indica a respetiva hora. O ID da conversa continua a ser o identificador estável da conversa.

GET /api/v1/zapier/inboxes?page=0&limit=100
GET /api/v1/zapier/conversations?limit=3&inboxId=<inboxId>

Criar uma subscrição New Conversation

POST /zapier/subscriptions regista o destino REST Hook do Zapier e requer conversations:read. Use a chave do acionador com finalidade definida ou uma chave REST API genérica ativa com esse âmbito. O corpo JSON requer targetUrl e pode incluir inboxId como cadeia. Se omitir inboxId, a subscrição recebe conversas novas de todas as caixas de entrada. Uma área de trabalho pode ter até 100 subscrições de webhook ativas entre o Zapier e outras integrações de webhook. Em caso de sucesso, devolve HTTP 200 com o ID da subscrição em data.id.

A DobroDesk aceita apenas destinos HTTPS cujo host seja exatamente hooks.zapier.com. Não inclua credenciais, uma porta explícita nem um fragmento de URL. O Zapier fornece o caminho e os parâmetros de consulta. A URL completa de destino é um segredo opaco. Mantenha-a em sigilo. O filtro da Caixa de entrada altera somente os eventos entregues. A chave do acionador continua tendo acesso aos metadados descritos em toda a área de trabalho.

Para cada conversa nova, a DobroDesk envia um POST para o URL de destino com os cabeçalhos X-DobroDesk-Delivery e X-DobroDesk-Event: conversation.created e um corpo JSON com deliveryId. O callback não tem assinatura HMAC. O acionador do Zapier confirma se o ID de entrega no cabeçalho X-DobroDesk-Delivery corresponde a deliveryId no corpo do pedido e depois obtém o evento canónico da DobroDesk com a respetiva chave autenticada.

POST /api/v1/zapier/subscriptions
Authorization: Bearer dd_live_<trigger-access-key>
Content-Type: application/json

{
  "targetUrl": "https://hooks.zapier.com/<Zapier-assigned-path>",
  "inboxId": "<inboxId>"
}

{
  "data": {
    "id": "<subscriptionId>"
  }
}

Ler um evento entregue e cancelar a subscrição

GET /zapier/events/<deliveryId> requer conversations:read e a mesma chave que criou a subscrição. Se a subscrição estiver ativa, devolve HTTP 200 e o evento canónico. A resposta contém data.id, data.type, data.workspaceId, data.occurredAt e data.data. O tipo é conversation.created. O objeto data aninhado contém conversationId, inboxId opcional, status, sourceChannel e createdAt.

O acionador ativo expõe o ID do evento como eventId e a hora do evento como occurredAt. A API devolve apenas metadados da conversa, sem texto de mensagens dos clientes nem anexos.

DELETE /zapier/subscriptions/<subscriptionId> requer conversations:read e a mesma chave que criou a subscrição. Desativa a subscrição e, em caso de sucesso, devolve HTTP 200, data.id e data.disabled com o valor true. Se a subscrição ou o evento não existir, estiver inativo ou não for acessível com esta chave, a resposta é 404. Desative o Zap antes de desligar a chave para que o Zapier possa cancelar a subscrição corretamente.

GET /api/v1/zapier/events/<deliveryId>
Authorization: Bearer dd_live_<trigger-access-key>

DELETE /api/v1/zapier/subscriptions/<subscriptionId>
Authorization: Bearer dd_live_<trigger-access-key>

Adicionar uma nota interna

POST /conversations/<conversationId>/notes requer conversations:write. Use a chave das notas com finalidade definida ou uma chave REST API genérica ativa com esse escopo. Envie um corpo JSON com bodyText. Depois de remover os espaços do início e do fim, o texto deve ter entre 1 e 20 000 caracteres. Em caso de sucesso, a resposta HTTP 200 contém data.id e data.status, que passa a saved quando a nota é salva. Esta ação adiciona uma nota visível para a equipe. Ela não envia uma resposta ao cliente.

Envie um Idempotency-Key em cada escrita. Na ação do Zapier, associe Source event or operation ID a um valor estável não vazio com até 1 024 caracteres. O conector aplica SHA-256 e envia uma chave com o prefixo zapier-note- seguido de 64 caracteres hexadecimais minúsculos. O valor do cabeçalho Idempotency-Key deve ter entre 1 e 200 caracteres e usar apenas letras ou algarismos ASCII, além de `.`, `_`, `:` ou `-`. Ao repetir a solicitação, mantenha a mesma conexão Access key, o mesmo Idempotency-Key, o mesmo conversationId e o mesmo texto da nota. A DobroDesk retém o resultado durante 365 dias, associado à área de trabalho e à identidade da chave de acesso. Reutilizar uma chave com outro conversationId ou outro texto da nota devolve HTTP 409 com o código idempotency_conflict. Se uma repetição devolver idempotency_in_progress, aguarde um pouco e repita a solicitação com o mesmo ID de origem, conversationId e texto da nota. O conector não garante uma nova tentativa automática.

POST /api/v1/conversations/<conversationId>/notes
Authorization: Bearer dd_live_<note-access-key>
Idempotency-Key: zapier-note-<sha256-of-source-reference>
Content-Type: application/json

{
  "bodyText": "Internal update from an approved automation."
}

{
  "data": {
    "id": "<noteId>",
    "status": "saved"
  }
}

Erros e limites de pedidos

Uma chave em falta, inválida, expirada ou revogada devolve HTTP 401. Uma finalidade de chave não permitida devolve HTTP 403 com o código api_token_purpose_forbidden. Se faltar um âmbito, HTTP 403 devolve o código insufficient_scope e requiredScope.

Os pedidos de API autorizados estão limitados a 300 por minuto por chave. As respostas incluem X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Quando o limite é ultrapassado, a DobroDesk devolve HTTP 429 com o código rate_limit_exceeded e Retry-After. Este limite não garante disponibilidade nem tempo de entrega. Um pedido válido também pode devolver HTTP 5xx se o serviço estiver temporariamente indisponível.

• GET /zapier/connection: zapier_connection_unavailable (503).
• GET /zapier/inboxes e GET /zapier/conversations: zapier_query_invalid (400).
• POST /zapier/subscriptions: zapier_subscription_invalid ou zapier_target_url_invalid (400), inbox_not_found (404), zapier_subscription_conflict ou zapier_subscription_limit_reached (409), e zapier_subscription_unavailable (503). Um conflito significa que o mesmo destino já está ativo com definições diferentes. O limite da área de trabalho é de 100 subscrições de webhook ativas.
• DELETE /zapier/subscriptions/<subscriptionId>: zapier_subscription_not_found (404).
• GET /zapier/events/<deliveryId>: zapier_event_not_found (404).
• POST /conversations/<conversationId>/notes: conversation_id_required (400), conversation_not_found (404), idempotency_key_required ou internal_note_body_invalid (400), idempotency_conflict ou idempotency_in_progress (409). idempotency_in_progress significa que o mesmo pedido continua a ser processado.

HTTP 403
data.code = api_token_purpose_forbidden

HTTP 429
data.code = rate_limit_exceeded