API atual/Referência completa/Importação avançada

Predefinições de importação

Salva, lista, consulta, altera e apaga mapeamentos de colunas reutilizáveis para o assistente de importação.

Quem importa todo dia a planilha do mesmo ERP ou do mesmo fornecedor não quer remapear as colunas toda vez. Uma predefinição (preset) guarda um nome, o mapeamento de colunas e as opções, e você reaplica em cada envio: leia a predefinição, use o field_mapping e as options dela na validação e na execução.

Uma predefinição não executa nada. É só um cadastro de configuração, visível para todos os administradores da loja. Todas as rotas exigem manage_catalog.

GET/api/v1/admin/advanced-import/presetsAdmin

Lista as predefinições de importação

Devolve uma lista simples (um array JSON, sem envelope de paginação) com todas as predefinições.

Parâmetros de consulta

object_typestring

Só as predefinições deste tipo de registro (products, por exemplo).

POST/api/v1/admin/advanced-import/presetsAdmin

Cria uma predefinição

Cria a predefinição e devolve o registro com 201. O nome é obrigatório; espaços nas pontas são ignorados.

Corpo da requisição (JSON)

namestringobrigatório

Nome da predefinição, como aparecerá na tela.

object_typestring

Tipo de registro a que se aplica, normalmente products.

field_mappingobject

Mapa de nome da coluna da planilha para campo do produto, por exemplo {"Código":"sku","Preço":"price"}.

optionsobject

Opções da importação, no mesmo formato do campo options da validação (strategy, skip_errors, price_format...). A plataforma guarda o objeto como está, sem conferir as chaves.

GET/api/v1/admin/advanced-import/presets/{id}Admin

Consulta uma predefinição

Parâmetros de caminho

iduuidobrigatório

Id da predefinição.

PUT/api/v1/admin/advanced-import/presets/{id}Admin

Altera uma predefinição

Substitui o conteúdo. Mande o objeto completo: um campo omitido é gravado vazio. Em particular, um PUT sem options apaga as opções ({}).

Parâmetros de caminho

iduuidobrigatório

Id da predefinição.

Corpo da requisição (JSON)

namestringobrigatório

Nome.

field_mappingobject

Novo mapeamento. Substitui o anterior inteiro.

optionsobject

Novas opções. Substitui as anteriores inteiras.

DELETE/api/v1/admin/advanced-import/presets/{id}Admin

Apaga uma predefinição

Remove a predefinição de forma definitiva. Importações anteriores que a usaram não são afetadas.

Parâmetros de caminho

iduuidobrigatório

Id da predefinição.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/advanced-import/presets" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "ERP diário",
    "object_type": "products",
    "field_mapping": {"Código": "sku", "Descrição": "name", "Preço": "price"},
    "options": {"strategy": "update_existing", "skip_errors": true}
  }'

Resposta

201Predefinição criada

json

{
  "id": "8556d3ae-3b49-4140-bb79-477387d25bba",
  "name": "ERP diário",
  "object_type": "products",
  "field_mapping": { "Código": "sku", "Descrição": "name", "Preço": "price" },
  "options": { "strategy": "update_existing", "skip_errors": true },
  "created_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "created_at": "2026-10-11T21:17:44.758654Z",
  "updated_at": "2026-10-11T21:17:44.758654Z"
}

200Predefinição apagada

json

{ "status": "deleted" }

Campos da resposta

iduuid

Id da predefinição.

namestring

Nome.

object_typestring

Tipo de registro.

field_mappingobject

Mapa de coluna para campo.

optionsobject

Opções guardadas.

created_byuuid

Usuário que criou.

created_atstring

Criação, RFC 3339 em UTC.

updated_atstring

Última alteração, RFC 3339 em UTC.

Erros

Status	Quando	Corpo de exemplo
400	`POST` sem `name` (ou só espaços)	`{"error":"name is required"}`
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Falta `manage_catalog`	`{"error":"insufficient privileges","required":"manage_catalog"}`
404	`GET` de um id que não existe ou que não é UUID	`{"error":"import preset not found","detail":"import preset not found: <id>"}`
500	`PUT` ou `DELETE` de um id que não existe	`{"error":"update import preset failed","detail":"import preset not found: <id>"}`

Veja também

Predefinições de importação

Salva, lista, consulta, altera e apaga mapeamentos de colunas reutilizáveis para o assistente de importação.

Uma predefinição não executa nada. É só um cadastro de configuração, visível para todos os administradores da loja. Todas as rotas exigem manage_catalog.

GET/api/v1/admin/advanced-import/presetsAdmin

Lista as predefinições de importação

Devolve uma lista simples (um array JSON, sem envelope de paginação) com todas as predefinições.

Parâmetros de consulta

object_typestring

Só as predefinições deste tipo de registro (products, por exemplo).

POST/api/v1/admin/advanced-import/presetsAdmin

Cria uma predefinição

Cria a predefinição e devolve o registro com 201. O nome é obrigatório; espaços nas pontas são ignorados.

Corpo da requisição (JSON)

namestringobrigatório

Nome da predefinição, como aparecerá na tela.

object_typestring

Tipo de registro a que se aplica, normalmente products.

field_mappingobject

Mapa de nome da coluna da planilha para campo do produto, por exemplo {"Código":"sku","Preço":"price"}.

optionsobject

Opções da importação, no mesmo formato do campo options da validação (strategy, skip_errors, price_format...). A plataforma guarda o objeto como está, sem conferir as chaves.

GET/api/v1/admin/advanced-import/presets/{id}Admin

Consulta uma predefinição

Parâmetros de caminho

iduuidobrigatório

Id da predefinição.

PUT/api/v1/admin/advanced-import/presets/{id}Admin

Altera uma predefinição

Substitui o conteúdo. Mande o objeto completo: um campo omitido é gravado vazio. Em particular, um PUT sem options apaga as opções ({}).

Parâmetros de caminho

iduuidobrigatório

Id da predefinição.

Corpo da requisição (JSON)

namestringobrigatório

Nome.

field_mappingobject

Novo mapeamento. Substitui o anterior inteiro.

optionsobject

Novas opções. Substitui as anteriores inteiras.

DELETE/api/v1/admin/advanced-import/presets/{id}Admin

Apaga uma predefinição

Remove a predefinição de forma definitiva. Importações anteriores que a usaram não são afetadas.

Parâmetros de caminho

iduuidobrigatório

Id da predefinição.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/advanced-import/presets" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "ERP diário",
    "object_type": "products",
    "field_mapping": {"Código": "sku", "Descrição": "name", "Preço": "price"},
    "options": {"strategy": "update_existing", "skip_errors": true}
  }'

Resposta

201Predefinição criada

json

{
  "id": "8556d3ae-3b49-4140-bb79-477387d25bba",
  "name": "ERP diário",
  "object_type": "products",
  "field_mapping": { "Código": "sku", "Descrição": "name", "Preço": "price" },
  "options": { "strategy": "update_existing", "skip_errors": true },
  "created_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "created_at": "2026-10-11T21:17:44.758654Z",
  "updated_at": "2026-10-11T21:17:44.758654Z"
}

200Predefinição apagada

json

{ "status": "deleted" }

Campos da resposta

iduuid

Id da predefinição.

namestring

Nome.

object_typestring

Tipo de registro.

field_mappingobject

Mapa de coluna para campo.

optionsobject

Opções guardadas.

created_byuuid

Usuário que criou.

created_atstring

Criação, RFC 3339 em UTC.

updated_atstring

Última alteração, RFC 3339 em UTC.

Erros

Status	Quando	Corpo de exemplo
400	`POST` sem `name` (ou só espaços)	`{"error":"name is required"}`
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
401	Token ausente ou expirado	`{"error":"invalid or expired token"}`
403	Falta `manage_catalog`	`{"error":"insufficient privileges","required":"manage_catalog"}`
404	`GET` de um id que não existe ou que não é UUID	`{"error":"import preset not found","detail":"import preset not found: <id>"}`
500	`PUT` ou `DELETE` de um id que não existe	`{"error":"update import preset failed","detail":"import preset not found: <id>"}`