API atual/Referência completa/Operações em lote

Importações em andamento

Acompanha e cancela uma importação de arquivo em andamento e lê os campos que cada tipo de importação aceita.

Importar um arquivo (CSV ou planilha) de produtos, categorias, usuários e outros tipos grandes roda como uma tarefa de importação: o servidor lê o arquivo em pedaços e atualiza o andamento. Estas rotas servem a quem dispara a importação por outra rota (o assistente de importação, documentado na seção de importação) e agora quer ver o andamento, cancelar ou saber quais campos podem ser mapeados.

O id da tarefa (job_id) vem da resposta que iniciou a importação. As rotas de andamento e cancelamento exigem manage_catalog; a de campos exige manage_settings.

Campos de cada tipo de importação

GET/api/v1/admin/import-export/fields/{entity}Admin

Listar os campos que um tipo de importação aceita

Devolve os campos que podem ser mapeados para as colunas do arquivo, agrupados, e a lista dos tipos que existem. Serve para montar a tela de mapeamento de colunas.

Parâmetros de caminho

entitystringobrigatório

productscategoriesusersordersvendorsfeaturesbrandsqty_discounts

Tipo de dado. Um valor que não está na lista não dá erro: a rota devolve os campos de products, mas repete o entity que você enviou.

bash

curl "$BASE_URL/api/v1/admin/import-export/fields/categories" \
  -H "Authorization: Bearer $TOKEN"

200Campos

json

{
  "entity": "categories",
  "entity_types": ["products", "categories", "users", "orders", "vendors", "features", "brands", "qty_discounts"],
  "groups": [
    { "key": "basic", "label": "Basic", "label_pt": "Basico", "fields": [ { "key": "name", "label": "Category Name", "label_pt": "Nome da Categoria", "group": "basic", "required": true, "field_type": "string" } ] }
  ],
  "fields": [
    { "key": "name", "label": "Category Name", "label_pt": "Nome da Categoria", "group": "basic", "required": true, "field_type": "string" },
    { "key": "position", "label": "Position", "label_pt": "Posicao", "group": "basic", "required": false, "field_type": "int", "default_value": "0" }
  ]
}

Campos da resposta

entitystring

O tipo pedido, repetido.

entity_typesarray

Todos os tipos de importação conhecidos.

groupsarray

Os mesmos campos, agrupados para exibição (key, label, label_pt, fields).

fieldsarray

Lista plana dos campos.

fields[].keystring

Nome do campo, o que você usa no mapeamento.

fields[].labelstring

Rótulo em inglês.

fields[].label_ptstring

Rótulo em português.

fields[].groupstring

Grupo de exibição (basic, content, seo...).

fields[].requiredboolean

Se o campo é obrigatório na importação.

fields[].field_typestring

Tipo do valor (string, int...).

fields[].default_valuestring

Valor usado quando a coluna está vazia. Ausente quando não há.

fields[].db_columnstring

Identificador interno do campo. Informativo; não dependa dele.

Andamento de uma importação

GET/api/v1/admin/import-jobs/{id}/progressAdmin

Andamento resumido de uma importação

Devolve só os contadores e o percentual, sem a lista de erros, para um polling leve (a cada 2 segundos, por exemplo). A lista completa de erros fica na rota de status do assistente de importação.

Parâmetros de caminho

iduuidobrigatório

Id da tarefa de importação.

bash

curl "$BASE_URL/api/v1/admin/import-jobs/af361351-ce28-44ef-b389-9cac3a7bac26/progress" \
  -H "Authorization: Bearer $TOKEN"

200Andamento

json

{
  "job_id": "af361351-ce28-44ef-b389-9cac3a7bac26",
  "status": "processing",
  "total": 1200,
  "processed": 450,
  "percent": 37.5,
  "current_chunk": 9,
  "created_count": 300,
  "updated_count": 148,
  "skipped_count": 2,
  "error_count": 2
}

Campos da resposta

job_iduuid

Id da tarefa.

statusstring

pendingprocessingcompletedfailed

Estado. Quando a tarefa foi cancelada, termina em failed.

totalinteger

Linhas do arquivo.

processedinteger

Linhas já tratadas.

percentnumber

processed sobre total, de 0 a 100.

current_chunkinteger

Número do bloco em andamento. A importação grava o progresso a cada 50 linhas.

created_countinteger

Registros criados.

updated_countinteger

Registros atualizados.

skipped_countinteger

Linhas puladas.

error_countinteger

Linhas com erro.

Cancelar uma importação

POST/api/v1/admin/import-jobs/{id}/cancelAdmin

Pedir o cancelamento de uma importação em andamento

Marca a importação para cancelar. Ela para no próximo ponto de verificação (a cada 25 linhas), não imediatamente. O que já foi gravado permanece: a tarefa termina com erro "cancelled by user" e o progresso parcial fica. Só tarefas pendentes ou em execução podem ser canceladas. Sem corpo.

Parâmetros de caminho

iduuidobrigatório

Id da tarefa de importação.

bash

curl -X POST "$BASE_URL/api/v1/admin/import-jobs/af361351-ce28-44ef-b389-9cac3a7bac26/cancel" \
  -H "Authorization: Bearer $TOKEN"

200Cancelamento pedido

json

{
  "job_id": "af361351-ce28-44ef-b389-9cac3a7bac26",
  "status": "cancelling",
  "message": "cancel requested; the import loop will stop at the next 25-row checkpoint"
}

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Sem o privilégio exigido (`manage_catalog`; `manage_settings` para os campos).	`{"error":"insufficient privileges","required":"manage_catalog"}`
404	`progress`: tarefa inexistente ou `{id}` que não é UUID.	`{"error":"progress lookup failed","detail":"import job not found: ..."}`
404	`cancel`: tarefa inexistente, já terminada, ou `{id}` inválido.	`{"error":"cancel failed","detail":"import job ... not found or already finished"}`

Veja também

API atual/Referência completa/Operações em lote

Importações em andamento

Acompanha e cancela uma importação de arquivo em andamento e lê os campos que cada tipo de importação aceita.

O id da tarefa (job_id) vem da resposta que iniciou a importação. As rotas de andamento e cancelamento exigem manage_catalog; a de campos exige manage_settings.

Campos de cada tipo de importação

GET/api/v1/admin/import-export/fields/{entity}Admin

Listar os campos que um tipo de importação aceita

Devolve os campos que podem ser mapeados para as colunas do arquivo, agrupados, e a lista dos tipos que existem. Serve para montar a tela de mapeamento de colunas.

Parâmetros de caminho

entitystringobrigatório

productscategoriesusersordersvendorsfeaturesbrandsqty_discounts

Tipo de dado. Um valor que não está na lista não dá erro: a rota devolve os campos de products, mas repete o entity que você enviou.

bash

curl "$BASE_URL/api/v1/admin/import-export/fields/categories" \
  -H "Authorization: Bearer $TOKEN"

200Campos

json

{
  "entity": "categories",
  "entity_types": ["products", "categories", "users", "orders", "vendors", "features", "brands", "qty_discounts"],
  "groups": [
    { "key": "basic", "label": "Basic", "label_pt": "Basico", "fields": [ { "key": "name", "label": "Category Name", "label_pt": "Nome da Categoria", "group": "basic", "required": true, "field_type": "string" } ] }
  ],
  "fields": [
    { "key": "name", "label": "Category Name", "label_pt": "Nome da Categoria", "group": "basic", "required": true, "field_type": "string" },
    { "key": "position", "label": "Position", "label_pt": "Posicao", "group": "basic", "required": false, "field_type": "int", "default_value": "0" }
  ]
}

Campos da resposta

entitystring

O tipo pedido, repetido.

entity_typesarray

Todos os tipos de importação conhecidos.

groupsarray

Os mesmos campos, agrupados para exibição (key, label, label_pt, fields).

fieldsarray

Lista plana dos campos.

fields[].keystring

Nome do campo, o que você usa no mapeamento.

fields[].labelstring

Rótulo em inglês.

fields[].label_ptstring

Rótulo em português.

fields[].groupstring

Grupo de exibição (basic, content, seo...).

fields[].requiredboolean

Se o campo é obrigatório na importação.

fields[].field_typestring

Tipo do valor (string, int...).

fields[].default_valuestring

Valor usado quando a coluna está vazia. Ausente quando não há.

fields[].db_columnstring

Identificador interno do campo. Informativo; não dependa dele.

Andamento de uma importação

GET/api/v1/admin/import-jobs/{id}/progressAdmin

Andamento resumido de uma importação

Devolve só os contadores e o percentual, sem a lista de erros, para um polling leve (a cada 2 segundos, por exemplo). A lista completa de erros fica na rota de status do assistente de importação.

Parâmetros de caminho

iduuidobrigatório

Id da tarefa de importação.

bash

curl "$BASE_URL/api/v1/admin/import-jobs/af361351-ce28-44ef-b389-9cac3a7bac26/progress" \
  -H "Authorization: Bearer $TOKEN"

200Andamento

json

{
  "job_id": "af361351-ce28-44ef-b389-9cac3a7bac26",
  "status": "processing",
  "total": 1200,
  "processed": 450,
  "percent": 37.5,
  "current_chunk": 9,
  "created_count": 300,
  "updated_count": 148,
  "skipped_count": 2,
  "error_count": 2
}

Campos da resposta

job_iduuid

Id da tarefa.

statusstring

pendingprocessingcompletedfailed

Estado. Quando a tarefa foi cancelada, termina em failed.

totalinteger

Linhas do arquivo.

processedinteger

Linhas já tratadas.

percentnumber

processed sobre total, de 0 a 100.

current_chunkinteger

Número do bloco em andamento. A importação grava o progresso a cada 50 linhas.

created_countinteger

Registros criados.

updated_countinteger

Registros atualizados.

skipped_countinteger

Linhas puladas.

error_countinteger

Linhas com erro.

Cancelar uma importação

POST/api/v1/admin/import-jobs/{id}/cancelAdmin

Pedir o cancelamento de uma importação em andamento

Parâmetros de caminho

iduuidobrigatório

Id da tarefa de importação.

bash

curl -X POST "$BASE_URL/api/v1/admin/import-jobs/af361351-ce28-44ef-b389-9cac3a7bac26/cancel" \
  -H "Authorization: Bearer $TOKEN"

200Cancelamento pedido

json

{
  "job_id": "af361351-ce28-44ef-b389-9cac3a7bac26",
  "status": "cancelling",
  "message": "cancel requested; the import loop will stop at the next 25-row checkpoint"
}

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Sem o privilégio exigido (`manage_catalog`; `manage_settings` para os campos).	`{"error":"insufficient privileges","required":"manage_catalog"}`
404	`progress`: tarefa inexistente ou `{id}` que não é UUID.	`{"error":"progress lookup failed","detail":"import job not found: ..."}`
404	`cancel`: tarefa inexistente, já terminada, ou `{id}` inválido.	`{"error":"cancel failed","detail":"import job ... not found or already finished"}`