Central de ajudaIntegrações

Para: Administradores

Execute uma importação com uma chave de gerenciamento.

Crie uma importação, carregue um arquivo CSV e anexe-o. Em seguida, verifique cada linha e tente novamente as que apresentaram falha.

Neste artigo9 seções

Antes de começar

Esta página explica como realizar a importação com o uso de uma chave de gerenciamento. As mesmas etapas de importação são aplicáveis aqui, assim como no tópico Integração › Importações. Todas as diretórios mencionados aqui estão localizados sob https://prd-api-manage.caseactive.com/v1/integration/<hub id>. Para saber quais colunas são necessárias para cada tipo de importação, consulte o tópico Consulte as colunas necessárias para cada tipo de importação.

Chamadas

ChamarO que faz
POST /importsCria uma importação.
GET /drive/private?import_id=<id>&media_group=docs&media_extension=csvFornece um endereço para que o arquivo possa ser carregado.
PUT /imports/<import_id>Anexa o arquivo carregado. Isso iniciará o processo de importação.
GET /importsLista as suas importações, começando pelas mais recentes, juntamente com o status de cada uma delas.
GET /imports/<import_id>Lista as linhas de um importador.
PUT /imports/<import_id>/<unique_id>Tenta novamente uma linha que falhou.

1. Crie a importação

CampoO que fazObrigatório
nameUm nome para isso: letras, números, espaços e traços.Sim
sourceO que causou isso? Por exemplo, claims-sync. Essa informação é exibida como sua origem no Painel de Administração.Sim
typeUm dos tipos abaixoSim
typeNa tela
post_userAdicionar usuários
put_userModificar usuários
post_caseCrie casos
put_caseModificar os casos
post_case_permissionAtribua usuários a casos específicos.
delete_case_permissionRemova os usuários que estão atribuídos a determinados casos.
post_case_postCrie postagens de casos
curl -X POST https://prd-api-manage.caseactive.com/v1/integration/ca-7e6d5c4b3a2f10/imports \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "October claimants", "source": "claims-sync", "type": "post_user"}'

Ele responde a 201 com import_id, como em import::20261002141503_3f9a1c2b7d4e60.

2. Faça o upload do arquivo

Peça um endereço de upload com GET /drive/private?import_id=<import_id>&media_group=docs&media_extension=csv. Esse endereço deve corresponder a uma url e a um conjunto de fields. Envie o arquivo para lá como um POST de tipo multipart/form-data. Cada elemento do fields deve ser inserido exatamente como indicado. O arquivo deve ser colocado no final da lista, conforme indicado em file.

curl -X POST "<url>" \
  --form-string "key=<fields.key>" \
  --form-string "<every other entry of fields, as given>" \
  -F "file=@october-claimants.csv"
  • Envie os itens de fields com --form-string, e não com -F. Alguns desses itens começam com <, ou contêm ;. O -F é interpretado como um arquivo ou uma opção.
  • O endereço funciona por uma hora.
  • Salve o arquivo como CSV em formato UTF-8. As nomes das colunas devem estar na primeira linha do arquivo.
  • O arquivo pode conter até 25.000 linhas, sob os nomes das colunas. Arquivos mais longos não conseguem ser importados; eles não contêm nenhuma informação útil. Por isso, é necessário dividir o arquivo em arquivos com no máximo 25.000 linhas cada, e fazer a importação de cada um desses arquivos separadamente.
  • Mantenha fields.key: é assim que você anexa o arquivo a seguir.

3. Anexe o arquivo

PUT /imports/<import_id> inicia a importação com a chave de carregamento. Isso responde à pergunta 204.

{"media_key": "<fields.key>"}

Anexe um arquivo apenas uma vez. Se a importação falhar, corrija o arquivo e tente a importação novamente.

4. Verificar progresso

GET /imports lista as suas importações, da mais recente para a mais antiga. Para cada uma delas, são indicados os valores status, total, passed e failed.

  • QUEUED: criado, ou anexado, mas ainda não lido.
  • PROCESSED: O arquivo foi lido em total linhas. Isso acontece uma por vez. O processo termina quando passed e failed somarem-se até atingir o valor total.
  • FAILED: O arquivo não pôde ser lido. Não havia linhas no arquivo, ou o número de linhas era superior a 25.000. A error_msg indica qual dos seguintes valores foi utilizado: ImportFileUnreadableException, ImportFileEmptyException ou ImportFileTooLargeException.

As linhas de dados são processadas no seu hub a cada duas importações. Portanto, um arquivo grande leva algum tempo para ser processado. Os administradores e gerentes do seu hub recebem e-mails quando uma importação ou a primeira linha do arquivo falha.

GET /imports/<import_id> lista as linhas que foram executadas, na ordem em que estão no arquivo. limit indica o número de linhas executadas, até 1000 linhas. start_key…

{
  "data": {
    "items": [
      {
        "unique_id": "unique::20261002141503_3f9a1c2b7d4e60_0000002",
        "line": 2,
        "type": "post_user",
        "status": "SUCCEEDED",
        "data": {"username": "jane.sample@example.com", "given_name": "Jane", "family_name": "Sample", "host_ref_id": "cl-1042"},
        "output": {"host_id": "ca-7e6d5c4b3a2f10", "user_id": "cu-4f1c2a9e8b7d60"}
      }
    ],
    "currentItemCount": 1,
    "selfLink": "https://prd-api-manage.caseactive.com/v1/integration/ca-7e6d5c4b3a2f10/imports/import::20261002141503_3f9a1c2b7d4e60"
  }
}
CampoO que contém
lineO número da linha no seu arquivo, como uma planilha conta as linhas; os nomes das colunas correspondem às linhas 1.
dataAs células da linha, conforme enviadas
statusSUCCEEDED, FAILED ou QUEUED, enquanto uma nova tentativa está em espera.
outputO que isso faz: o user_id, o case_id, ou ambos, para uma linha que coloca alguém em um caso.
schema_errorsPara uma célula que não passou no teste: a coluna em questão, e o que está errado.
error_msgPor que a linha falhou, como nome de um erro, como por exemplo CaseReferenceIdExistsException

Uma linha é considerada bem-sucedida apenas quando consegue realizar sua alteração. Uma linha cujo ID de etiqueta, ID de referência ou identificador de pessoa coincida com outro registro falha na execução da alteração. O nome do responsável pela rejeição também é exibido nesse caso. error_msg. É possível atribuir usuários a casos, ou criar linhas de postagem para casos que já foram encerrados. No entanto, isso não funciona corretamente. {"_schema": ["Case is closed"]} em schema_errors: Reabrir o caso, e então importar novamente a linha em questão.

Uma linha de… unique_id É feito a partir do ID da importação e do número da linha no seu arquivo. Ou seja, a linha número 2… import::20261002141503_3f9a1c2b7d4e60 É unique::20261002141503_3f9a1c2b7d4e60_0000002.

5. Tente novamente uma linha

Com PUT /imports/<import_id>/<unique_id> e {"retry": true}, uma linha falha novamente, exatamente como antes, no final da ordem de processamento do seu hub. Isso responde ao comando 204; a contagem de failed diminui por um valor, até que a linha seja processada. Use isso para linhas que falharam por motivos temporários, como momentos de grande volume de trabalho. Linhas cujas células estão incorretas também falham novamente: corrija o arquivo e inicie um novo processo de importação.

O que acontece a seguir?

As linhas de importação fazem o mesmo que as linhas no ecrã: as pessoas adicionadas não recebem e-mails; as pessoas que são incluídas nas casas de investigação recebem a notificação por e-mail. Novas casas de investigação são criadas de acordo com as regras de atribuição de casas, e novas mensagens são enviadas para as pessoas envolvidas na situação. A importação é registada no hub do seu sistema. Assistente VirtualAssistente Virtual Um membro de equipe automatizado que publica mensagens de boas-vindas, atualizações e posts de apresentação para a empresa; suas publicações exibem um selo de Assistente Virtual.Enviar o mesmo arquivo duas vezes faz com que cada linha seja processada novamente. As linhas que não são compatíveis com a primeira execução falham, e as postagens são feitas duas vezes. Para corrigir essas linhas que falharam na tela, veja… Determine as linhas de importação que apresentam erros..

Se uma chamada for recusada

StatusmessagePor que
400SchemaFieldsExceptionO campo está ausente ou inválido. Por exemplo, um name contendo outros caracteres, ou um media_key sem nenhum conteúdo carregado.
403ImportFileAlreadyAttachedExceptionA importação já possui seu arquivo, ou já foi lido: inicie uma nova importação.
403BotNotAllowedExceptionVocê usou /v1/<hub id>/imports em vez de /v1/integration/<hub id>/imports.
404ItemNotFoundExceptionNão importa, ou não há necessidade de inserir essa linha com aquele ID no seu hub.

Artigos relacionados

Consulte as colunas que cada importação precisa.As colunas CSV obrigatórias e opcionais para cada tipo de importação, com os formatos que cada uma aceita.Casos e admissãoCorrigir importação com linhas com falhaLeia o registro de importação e os erros de linha, tente novamente as linhas que falharam por outros motivos e corrija e reenvie o arquivo.Casos e admissão