API atual/Referência completa/Assistente de importação

Modelos de mapeamento

Lista, salva e exclui modelos de mapeamento de colunas para reaproveitar em importações futuras.

Se você recebe sempre a mesma planilha de um fornecedor, salve o mapeamento uma vez como modelo. Na próxima importação, leia o modelo e envie o field_mapping dele em validate e execute, sem remapear coluna por coluna. Os modelos são por usuário: cada pessoa da equipe vê só os seus.

Listar

GET/api/v1/vendor/import/presetsSeller

Listar os modelos

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de consulta

object_typestring

Filtro de tipo. Para o seller só existe products.

Exemplo de requisição (listar)

bash

curl "$BASE_URL/api/v1/vendor/import/presets" \
  -H "Authorization: Bearer $TOKEN"

Resposta (listar)

200Modelos

json

[
  {
    "id": "6c5b4a30-0001-4d2e-8f3a-9b8c7d6e5f40",
    "name": "Planilha do fornecedor X",
    "object_type": "products",
    "field_mapping": {
      "Código": "sku",
      "Produto": "name",
      "Preço": "price",
      "Estoque": "quantity"
    },
    "options": {
      "strategy": "import_all",
      "price_format": "decimal"
    },
    "created_by": "0fd409fb-9869-4c50-a18c-a810a19abeed",
    "created_at": "2026-10-11T20:00:00Z",
    "updated_at": "2026-10-11T20:00:00Z"
  }
]

Campos da resposta

(array)array

A resposta é uma lista JSON direta dos modelos do usuário que chamou:

idstring (uuid)

Id do modelo.

namestring

Nome do modelo.

object_typestring

Sempre products.

field_mappingobject

Mapeamento salvo (coluna para campo).

optionsobject

Opções salvas.

created_bystring (uuid)

Usuário que criou o modelo.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteração (RFC 3339).

Erros (listar)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_import_products"]}`

Salvar

POST/api/v1/vendor/import/presetsSeller

Salvar um modelo

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Corpo da requisição

namestringobrigatório

Nome do modelo (as pontas em branco são cortadas).

field_mappingobject

Mapeamento no formato {"<nome da coluna na planilha>": "<campo da plataforma>"}. Colunas não mapeadas são ignoradas.

optionsobject

Opções de importação a reaplicar (strategy, price_format, category_delimiter...).

Exemplo de requisição (salvar)

bash

curl -X POST "$BASE_URL/api/v1/vendor/import/presets" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Planilha do fornecedor X",
  "field_mapping": {
    "Código": "sku",
    "Produto": "name",
    "Preço": "price",
    "Estoque": "quantity"
  },
  "options": {
    "strategy": "import_all",
    "price_format": "decimal"
  }
}'

Resposta (salvar)

201Modelo salvo

json

{
  "id": "6c5b4a30-0001-4d2e-8f3a-9b8c7d6e5f40",
  "name": "Planilha do fornecedor X",
  "object_type": "products",
  "field_mapping": {
    "Código": "sku",
    "Produto": "name",
    "Preço": "price",
    "Estoque": "quantity"
  },
  "options": {
    "strategy": "import_all",
    "price_format": "decimal"
  },
  "created_by": "0fd409fb-9869-4c50-a18c-a810a19abeed",
  "created_at": "2026-10-11T20:00:00Z",
  "updated_at": "2026-10-11T20:00:00Z"
}

Campos da resposta

idstring (uuid)

Id do modelo.

namestring

Nome do modelo.

object_typestring

Sempre products.

field_mappingobject

Mapeamento salvo (coluna para campo).

optionsobject

Opções salvas.

created_bystring (uuid)

Usuário que criou o modelo.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteração (RFC 3339).

Erros (salvar)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_import_products"]}`
400	`name` vazio ou corpo inválido.	`{"error":"name is required"}`

Excluir

DELETE/api/v1/vendor/import/presets/{id}Seller

Excluir um modelo

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório

Id do modelo.

Exemplo de requisição (excluir)

bash

curl -X DELETE "$BASE_URL/api/v1/vendor/import/presets/$PRESET_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta (excluir)

200Modelo excluído

json

{
  "status": "deleted"
}

Campos da resposta

statusstring

Sempre deleted.

Erros (excluir)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_import_products"]}`
404	Modelo inexistente ou de outro usuário.	`{"error":"import preset not found","detail":"..."}`

Veja também

Assistente de importação: visão geral

API atual/Referência completa/Assistente de importação

Modelos de mapeamento

Lista, salva e exclui modelos de mapeamento de colunas para reaproveitar em importações futuras.

Listar

GET/api/v1/vendor/import/presetsSeller

Listar os modelos

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de consulta

object_typestring

Filtro de tipo. Para o seller só existe products.

Exemplo de requisição (listar)

bash

curl "$BASE_URL/api/v1/vendor/import/presets" \
  -H "Authorization: Bearer $TOKEN"

Resposta (listar)

200Modelos

json

[
  {
    "id": "6c5b4a30-0001-4d2e-8f3a-9b8c7d6e5f40",
    "name": "Planilha do fornecedor X",
    "object_type": "products",
    "field_mapping": {
      "Código": "sku",
      "Produto": "name",
      "Preço": "price",
      "Estoque": "quantity"
    },
    "options": {
      "strategy": "import_all",
      "price_format": "decimal"
    },
    "created_by": "0fd409fb-9869-4c50-a18c-a810a19abeed",
    "created_at": "2026-10-11T20:00:00Z",
    "updated_at": "2026-10-11T20:00:00Z"
  }
]

Campos da resposta

(array)array

A resposta é uma lista JSON direta dos modelos do usuário que chamou:

idstring (uuid)

Id do modelo.

namestring

Nome do modelo.

object_typestring

Sempre products.

field_mappingobject

Mapeamento salvo (coluna para campo).

optionsobject

Opções salvas.

created_bystring (uuid)

Usuário que criou o modelo.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteração (RFC 3339).

Erros (listar)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_import_products"]}`

Salvar

POST/api/v1/vendor/import/presetsSeller

Salvar um modelo

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Corpo da requisição

namestringobrigatório

Nome do modelo (as pontas em branco são cortadas).

field_mappingobject

Mapeamento no formato {"<nome da coluna na planilha>": "<campo da plataforma>"}. Colunas não mapeadas são ignoradas.

optionsobject

Opções de importação a reaplicar (strategy, price_format, category_delimiter...).

Exemplo de requisição (salvar)

bash

curl -X POST "$BASE_URL/api/v1/vendor/import/presets" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Planilha do fornecedor X",
  "field_mapping": {
    "Código": "sku",
    "Produto": "name",
    "Preço": "price",
    "Estoque": "quantity"
  },
  "options": {
    "strategy": "import_all",
    "price_format": "decimal"
  }
}'

Resposta (salvar)

201Modelo salvo

json

{
  "id": "6c5b4a30-0001-4d2e-8f3a-9b8c7d6e5f40",
  "name": "Planilha do fornecedor X",
  "object_type": "products",
  "field_mapping": {
    "Código": "sku",
    "Produto": "name",
    "Preço": "price",
    "Estoque": "quantity"
  },
  "options": {
    "strategy": "import_all",
    "price_format": "decimal"
  },
  "created_by": "0fd409fb-9869-4c50-a18c-a810a19abeed",
  "created_at": "2026-10-11T20:00:00Z",
  "updated_at": "2026-10-11T20:00:00Z"
}

Campos da resposta

idstring (uuid)

Id do modelo.

namestring

Nome do modelo.

object_typestring

Sempre products.

field_mappingobject

Mapeamento salvo (coluna para campo).

optionsobject

Opções salvas.

created_bystring (uuid)

Usuário que criou o modelo.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteração (RFC 3339).

Erros (salvar)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_import_products"]}`
400	`name` vazio ou corpo inválido.	`{"error":"name is required"}`

Excluir

DELETE/api/v1/vendor/import/presets/{id}Seller

Excluir um modelo

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório

Id do modelo.

Exemplo de requisição (excluir)

bash

curl -X DELETE "$BASE_URL/api/v1/vendor/import/presets/$PRESET_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta (excluir)

200Modelo excluído

json

{
  "status": "deleted"
}

Campos da resposta

statusstring

Sempre deleted.

Erros (excluir)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_import_products"]}`
404	Modelo inexistente ou de outro usuário.	`{"error":"import preset not found","detail":"..."}`

Veja também

Assistente de importação: visão geral