API: ações em lote de documentos e FAQs

Disponibilidade: contrato disponível no CRM desde 28/09/2026. O acesso exige autenticação e autorização para o assistente na conta.

POST /api/v1/accounts/{account_id}/captain/bulk_actions
api_access_token: SEU_TOKEN
Content-Type: application/json

Esse endpoint atua nos documentos e FAQs do assistente. As ações em lote de conversas têm outro endpoint e outro contrato. A autenticação segue o guia da API REST; o token precisa ter autorização para o recurso na conta indicada.

Corpo da requisição

Exemplo de formato para aprovar FAQs pendentes. Os IDs são ilustrativos; usem apenas IDs existentes na conta e numa operação autorizada.

{
  "type": "AssistantResponse",
  "ids": [123, "124"],
  "fields": { "status": "approve" }
}

fields precisa ser um objeto. ids precisa ser um array não vazio com até 100 entradas. O limite conta o array recebido antes de remover repetições: 101 cópias do mesmo ID excedem o teto. Depois da validação, IDs repetidos são processados uma vez.

Cada ID deve ser um inteiro positivo ou sua string decimal canônica, como 123 ou "123". São inválidos 0, negativos, floats, booleanos, objetos, arrays internos e strings como "01", "1.0", "+1" ou " 1 ".

Erros antes do processamento

Se qualquer ID for inválido, inexistente ou pertencer a outra conta, o lote inteiro é recusado antes de processar a parte válida. A resposta não informa qual ID falhou.

Formato inválido, combinação de tipo/ação não aceita ou lote com IDs fora do escopo:

{ "success": false }

Mais de 100 entradas:

{
  "success": false,
  "error": "too_many_ids",
  "max_ids": 100,
  "requested": 101
}

Essas recusas retornam HTTP 422. Corrijam o lote antes de tentar novamente. Para mais de 100 entradas válidas, dividam a operação em requisições de até 100; cada chamada é validada separadamente.

Resultado e limites

• Aprovação afeta apenas FAQs pendentes.
• Sincronização enfileira apenas documentos sincronizáveis e disponíveis. A resposta informa ids e count dos enfileirados; não comprova que a sincronização terminou.
• Exclusão de documentos responde com count dos documentos excluídos.
• A validação integral ocorre antes da ação, mas não transforma o processamento numa transação atômica. Falhas ou alterações concorrentes durante a operação podem exigir reconciliação. Confiram o estado antes de repetir uma exclusão ou sincronização.

Integrações que antes enviavam IDs inexistentes esperando que fossem ignorados precisam tratar a recusa do lote inteiro. O teto deste endpoint vale para todas as chamadas, inclusive aquelas feitas pela interface.

Vejam também Base de conhecimento: documentos e FAQs.