Catálogo
POST /products/bulk — upsert de até 500 produtos por external_id, semântica por item, bloco stores[] e estoque decimal.
Use POST /integration/v1/products/bulk para criar ou atualizar produtos no
catálogo OnmIA. A chave de upsert é o external_id do seu ERP. Esta rota exige o
scope catalog:write.
Requisição
curl -sS https://api.onmia.com.br/integration/v1/products/bulk \
-H "X-API-Key: $ONMIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"external_id": "ERP-7891",
"name": "Acucar Coco Kodilar 250g",
"price": 18.9,
"gtin": "7891234567890",
"category": "Mercearia",
"stores": [
{
"store_id": "c5745b49-3883-45f9-8dc4-63cc7d9f2611",
"stock_quantity": 12.5,
"price_override": 17.99,
"active": true
}
]
}
]
}'O bloco stores[] grava estoque e preço por loja na mesma chamada. Toda
store_id do item é validada contra o escopo da chave antes de qualquer
gravação — uma loja proibida invalida o item inteiro, sem efeito colateral.
Resposta
O status HTTP é 200 mesmo com itens em erro — o resultado é reportado por
item no array results.
{
"sync_id": "0d4f3a52-8a9d-4f30-9c1e-1a2b3c4d5e6f",
"summary": { "created": 1, "updated": 0, "errors": 0 },
"results": [
{ "index": 0, "external_id": "ERP-7891", "status": "created" }
]
}Um item com erro aparece no mesmo array; os demais itens do lote são processados normalmente:
{
"index": 3,
"external_id": "ERP-9999",
"status": "error",
"error": { "code": "FORBIDDEN_STORE", "message": "Loja fora do escopo da chave de integracao: <store_id>." }
}Regras
| Regra | Detalhe |
|---|---|
| Itens por lote | Até 500. Acima disso, 400 VALIDATION_ERROR no lote inteiro. |
| Chave de upsert | external_id. status por item indica created ou updated. |
external_id duplicado no lote | O primeiro vale; os repetidos retornam erro por item (external_id duplicado no lote.). |
gtin | Persistido só se tiver mais de 5 caracteres. Valores com 5 ou menos viram null. |
stock_quantity | Decimal até 3 casas, nunca arredondado (ex.: 0.5 kg). |
stores[].store_id | Validada contra o escopo antes da gravação. Loja proibida → item inteiro falha. |
sync_id | Identifica a operação no histórico de sincronizações (útil ao abrir chamado). |
Cadastre o produto antes do pedido
Pedidos com external_id sem produto mapeado retornam 422 UNMAPPED_ITEMS.
Envie o produto via POST /products/bulk antes de criar pedidos que o
referenciem.
Códigos de erro por item
VALIDATION_ERROR, FORBIDDEN_STORE, STORE_WRITE_FAILED, INTERNAL.