Importação de cases

A API GraphQL da Notrus expõe as conversas da sua organização e seu estado de classificação, recebe o envio de documentos e a importação de cases. Este portal documenta todas as operações e permite testá-las ao vivo no seu navegador.

A operação

A importação usa o mesmo endpoint GraphQL e a mesma chave de API das consultas, no cabeçalho apikey (veja Autenticação). A organização vem da chave: o input não tem campo de organização.

https://api.hom.notrus.ai/graphql

mutation ImportCase($input: ImportCaseInput!) {
  importCase(input: $input) {
    outcome
    case { id code outcome }
    customer { id outcome }
    conversations {
      conversationId
      threads {
        id
        outcome
        active
        traces { inserted duplicated missingFromPayload }
        tags { linked replaced tagsCreated valuesCreated }
      }
    }
    warnings
  }
}

Os tipos ImportCaseInput e ImportCaseResult estão na Referência do schema, e a mutation pode ser executada no Console da API.

Estrutura do input

O input é o case. Dentro dele vêm as conversas que fizeram parte do atendimento, cada uma com as suas threads e as mensagens de cada thread:

ImportCaseInput    caseId · status · resolution · assignedUserName · transferredAt · assumedAt · closedAt · customerData
└─ conversations[]  conversationId · channelType
   └─ threads[]     threadId
      ├─ tags[]     reference · value · label
      └─ messages[] sentAt · role · text · hasMedia · authorIdentifier

• ImportCaseInput: o atendimento, com protocolo, status e datas. A Notrus gera o código legível (CS-0042).
• ImportCaseConversationInput: um canal, como um WhatsApp ou um endereço de e-mail. Um case pode ter várias conversas.
• ImportCaseThreadInput: um trecho do atendimento dentro daquela conversa. Uma conversa pode ter várias threads no mesmo case.

Exemplo

As variáveis de um case encerrado, atendido por WhatsApp e por e-mail. A requisição é um POST com query (a mutation acima) e variables:

{
  "input": {
    "caseId": "protocolo-777",
    "status": "ENCERRADO",
    "resolution": "RESOLVIDO",
    "assignedUserName": "Marina Souza",
    "transferredAt": "2026-10-15T09:02:00-03:00",
    "assumedAt": "2026-10-15T09:06:00-03:00",
    "closedAt": "2026-10-15T11:00:00-03:00",
    "customerData": { "nome": "João Silva", "plano": "gold", "clienteDesde": 2019 },
    "conversations": [
      {
        "conversationId": "whatsapp-5511988887766",
        "channelType": "WHATSAPP",
        "threads": [
          {
            "threadId": "atendimento-981",
            "tags": [{ "reference": "marca", "value": "cyrela", "label": "Cyrela" }],
            "messages": [
              { "sentAt": "2026-10-15T09:00:00-03:00", "role": "ai", "text": "Olá! Como posso ajudar?" },
              {
                "sentAt": "2026-10-15T09:00:40-03:00",
                "role": "user",
                "text": "Preciso da 2ª via do boleto.",
                "authorIdentifier": "529.982.247-25"
              },
              {
                "sentAt": "2026-10-15T09:01:10-03:00",
                "role": "user",
                "hasMedia": true,
                "authorIdentifier": "529.982.247-25"
              },
              { "sentAt": "2026-10-15T09:06:30-03:00", "role": "human", "text": "Vou te mandar por e-mail." }
            ]
          }
        ]
      },
      {
        "conversationId": "email-joao.silva@exemplo.com",
        "channelType": "EMAIL",
        "threads": [
          {
            "threadId": "ticket-5521",
            "messages": [
              { "sentAt": "2026-10-15T10:30:00-03:00", "role": "human", "text": "Segue o boleto em anexo.", "hasMedia": true },
              {
                "sentAt": "2026-10-15T11:00:00-03:00",
                "role": "user",
                "text": "Recebi, obrigado!",
                "authorIdentifier": "529.982.247-25"
              }
            ]
          }
        ]
      }
    ]
  }
}

curl https://api.hom.notrus.ai/graphql \
  -H "Content-Type: application/json" \
  -H "apikey: $NOTRUS_API_KEY" \
  -d @import-case.json   # {"query": "<a mutation acima>", "variables": {"input": {...}}}

Campos

Case (ImportCaseInput)

Conversa (ImportCaseConversationInput)

Thread (ImportCaseThreadInput)

Tag (ImportCaseTagInput)

Mensagem (ImportCaseMessageInput)

Status do case

• resolution só é gravado com o status ENCERRADO. Enviado com outro status, é ignorado e a resposta traz o aviso resolution_ignored.
• Um case ENCERRADO sem closedAt é fechado no horário da última mensagem.
• As datas seguem a ordem transferredAt → assumedAt → closedAt. Uma data anterior à que vem antes dela é descartada, com aviso.
• assignedUserName é procurado entre os usuários da sua organização na Notrus, sem diferenciar maiúsculas, acentos e espaços. Se houver exatamente um com esse nome, ele vira o responsável; se não houver nenhum, ou houver mais de um, o case fica sem responsável e a resposta traz um aviso.

Identificadores e reenvio

• Com caseId, a Notrus calcula o id do case a partir dele. Sem caseId, o id vem do conteúdo das mensagens.
• Com threadId, o id da thread vem dele e da conversa. Sem threadId, vem da primeira mensagem da thread.
• O id de cada mensagem vem da conversa, do horário, do role e do texto. A mesma mensagem enviada de novo não é duplicada, e nada que já foi gravado é apagado.
• Por isso a chamada pode ser repetida com segurança: se ela falhar ou der timeout, envie as mesmas variáveis de novo. O outcome vem como UNCHANGED quando tudo já estava gravado.
• Só a thread mais recente de cada conversa fica ativa. Ao importar um case com uma conversa que já tem uma thread mais antiga, a antiga passa a inativa.

Cliente

Todo case importado tem um cliente. Ele é resolvido somente a partir das mensagens com role = user, pelo authorIdentifier, que é obrigatório nessas mensagens. Vale o primeiro identificador válido em ordem de sentAt, em qualquer conversa do case; o cliente é gravado no case e em todas as threads.

• A importação é recusada com CASE_IMPORT.VALIDATION_FAILED, e nada é gravado, quando o case não tem nenhuma mensagem user, quando uma mensagem user vem sem authorIdentifier ou quando nenhum identificador das mensagens user é válido.
• O tipo é deduzido: com @ é e-mail; no formato de CNPJ ou CPF, é documento; o resto é telefone. Telefones em formatos diferentes (com ou sem 9, com ou sem +55) são o mesmo cliente.
• A Notrus guarda só uma versão mascarada do identificador, como ***.***.***-25 ou ***7766. Um CPF ou CNPJ com dígito verificador errado não identifica ninguém: se o case tiver outro identificador válido, a importação segue com o aviso invalid_customer_identifier.
• Em mensagens com qualquer outro role (ai, human ou um valor livre), o authorIdentifier nunca é tratado como cliente: é gravado como veio, para identificar o autor.
• customerData guarda dados extras do cliente, como nome ou plano, num objeto JSON. A cada importação, as chaves enviadas substituem as gravadas e as outras continuam, inclusive as de outros cases do mesmo cliente; campos null são ignorados. Sem customerData, nada muda. Os dados saem junto com o cliente em deleteImportedCustomer.

Tags

• Toda thread importada recebe a tag importacao = true, para separar o que veio do seu sistema do que foi atendido pela Notrus.
• Uma tag que ainda não existe na sua organização é criada. Cada thread guarda um valor por tag. Tags internas da Notrus não podem ser escritas pela importação; elas são ignoradas, com aviso.
• channelType vira a tag channel da thread, quando esse valor existe no catálogo da sua organização.

Resposta

O ImportCaseResult descreve o que foi gravado: o case com o código gerado, o cliente e, para cada conversa, as threads com o que entrou de mensagens e tags.

{
  "data": {
    "importCase": {
      "outcome": "CREATED",
      "case": { "id": "3b5f2c1e-8a47-5d1b-9c2e-6f0a4d7e8b13", "code": "CS-0042", "outcome": "CREATED" },
      "customer": { "id": "c76dad57-44f0-45e6-bf23-1ca6e5cc467f", "outcome": "CREATED" },
      "conversations": [
        {
          "conversationId": "whatsapp-5511988887766",
          "threads": [
            {
              "id": "e6abb09d-a659-56fb-8cce-d8cdd3ab13e4",
              "outcome": "CREATED",
              "active": true,
              "traces": { "inserted": 4, "duplicated": 0, "missingFromPayload": 0 },
              "tags": { "linked": 2, "replaced": 0, "tagsCreated": 1, "valuesCreated": 1 }
            }
          ]
        },
        {
          "conversationId": "email-joao.silva@exemplo.com",
          "threads": [
            {
              "id": "9e04afc7-69af-5d62-ada9-bb73b80fd323",
              "outcome": "CREATED",
              "active": true,
              "traces": { "inserted": 2, "duplicated": 0, "missingFromPayload": 0 },
              "tags": { "linked": 1, "replaced": 0, "tagsCreated": 0, "valuesCreated": 0 }
            }
          ]
        }
      ],
      "warnings": []
    }
  }
}

Em cada thread, traces.inserted conta as mensagens novas, traces.duplicated as que já estavam gravadas e traces.missingFromPayload as gravadas antes que não vieram nesta chamada (elas continuam lá). active indica se a thread é a mais recente da conversa. Uma mensagem é identificada pela conversa, horário, role e texto: se a mesma mensagem já foi gravada em outra thread da conversa, ela conta como duplicated e continua na thread onde entrou primeiro.

As conversas importadas são lidas pelas queries conversations e conversation, como as demais. Um role livre volta como OTHER, com o texto gravado em rawRole (veja Trace).

Avisos

Um problema que não impede a importação não vira erro: a parte afetada é ignorada e o código vai para warnings. Nos códigos marcados com path, o que vem depois dos dois-pontos é a posição do item no input, como conversations[0].threads[1].messages[3].

Excluir um case importado

A mutation deleteImportedCase apaga um case importado e tudo o que a importação gravou nele. Identifique o case pelo seu caseId ou pelo id da Notrus:

mutation DeleteImportedCase($input: DeleteImportedCaseInput!) {
  deleteImportedCase(input: $input) {
    outcome
    case { id code }
    threads
    traces
  }
}

{
  "input": { "caseId": "protocolo-777" }
}

{
  "data": {
    "deleteImportedCase": {
      "outcome": "DELETED",
      "case": { "id": "3b5f2c1e-8a47-5d1b-9c2e-6f0a4d7e8b13", "code": "CS-0042" },
      "threads": 2,
      "traces": 6
    }
  }
}

• São apagados o case, o histórico de eventos dele, as threads, as mensagens e as tags ligadas a essas threads. threads e traces contam o que foi removido.
• O cliente continua cadastrado; para apagá-lo, use deleteImportedCustomer. As tags criadas no catálogo da organização também ficam, e o código do case (CS-0042) nunca é reaproveitado: importar o mesmo case de novo gera um código novo.
• Só dados importados são apagados. Se o case tiver uma thread que não veio da importação, a chamada é recusada com CASE_IMPORT.CASE_HAS_LIVE_THREADS; um case criado pela Notrus é recusado com CASE_IMPORT.CASE_NOT_IMPORTED. Uma thread antiga que ficou inativa quando o case foi importado continua inativa.
• A exclusão pode ser repetida com segurança: um case que já não existe, ou de outra organização, volta como NOT_FOUND, sem erro.

{
  "data": {
    "deleteImportedCase": {
      "outcome": "NOT_FOUND",
      "case": null,
      "threads": 0,
      "traces": 0
    }
  }
}

Excluir os dados de um cliente (LGPD)

Para atender a um pedido de exclusão de dados, a mutation deleteImportedCustomer apaga o cliente e todos os cases importados dele, de uma vez. Identifique o cliente pelo identificador que você enviou na importação ou pelo id da Notrus:

mutation DeleteImportedCustomer($input: DeleteImportedCustomerInput!) {
  deleteImportedCustomer(input: $input) {
    outcome
    customer { id }
    cases { id code }
    threads
    traces
  }
}

{
  "input": { "identifier": "529.982.247-25" }
}

{
  "data": {
    "deleteImportedCustomer": {
      "outcome": "DELETED",
      "customer": { "id": "c76dad57-44f0-45e6-bf23-1ca6e5cc467f" },
      "cases": [
        { "id": "3b5f2c1e-8a47-5d1b-9c2e-6f0a4d7e8b13", "code": "CS-0042" },
        { "id": "8d2e6a90-1c3b-5f47-a8e2-4b6c9d0e1f23", "code": "CS-0057" }
      ],
      "threads": 3,
      "traces": 11
    }
  }
}

• São apagados o cliente, com o customerData dele, e, em cada case dele, o mesmo que em deleteImportedCase. cases lista os cases removidos.
• O identificador é tratado como na importação: telefones em formatos diferentes, CPF com ou sem pontuação e e-mail com maiúsculas encontram o mesmo cliente. Um identificador inválido é recusado com CASE_IMPORT.VALIDATION_FAILED.
• Se o cliente também foi atendido pela Notrus, ou seja, tem algum case ou thread que não veio da importação, a chamada é recusada com CASE_IMPORT.CUSTOMER_HAS_LIVE_DATA e nada é apagado.
• Como na exclusão de case, repetir a chamada devolve NOT_FOUND, e as tags do catálogo e os códigos de case não são reaproveitados.

Erros

Quando uma chamada é recusada, nada é gravado nem apagado, data vem nulo e o motivo vem em errors, no formato descrito em Erros. Os códigos possíveis em extensions.code:

Regras do case

Todos os problemas encontrados voltam juntos em extensions.details:

{
  "data": null,
  "errors": [
    {
      "message": "The case was rejected; see extensions.details",
      "path": ["importCase"],
      "extensions": {
        "code": "CASE_IMPORT.VALIDATION_FAILED",
        "details": [
          "resolution is required when status is encerrado",
          "conversations[0].threads[0].messages[1] with role user has no authorIdentifier"
        ]
      }
    }
  ]
}

Formato e limites

Cada item de extensions.details traz o caminho do campo e o problema:

{
  "data": null,
  "errors": [
    {
      "message": "Invalid input; see extensions.details",
      "path": ["importCase"],
      "extensions": {
        "code": "BAD_USER_INPUT",
        "details": [
          "conversations.0.threads.0.messages.0.sentAt must be an ISO-8601 timestamp with a UTC offset"
        ]
      }
    }
  ]
}

Limites por chamada

Uma chamada acima de qualquer limite é recusada e nada é gravado. A mutation também conta nos Limites de uso da API.