API Docs v1 api.hubiss.com.br

Categorias

Árvore de categorias de cada loja, usada para classificar os produtos.

Em resumo
Categoria pertence a uma loja. Sem loja criada, não existe categoria.

As categorias (também chamadas de grupos de produtos) classificam o que você vende dentro de uma loja. Assim como você pode ter várias lojas, cada loja tem sua própria árvore de categorias.

Observações
Categorias só podem ser cadastradas depois da loja, pois pertencem a uma loja específica. Comece por Lojas.

Hierarquia

  • Cada loja tem sua própria árvore.
  • Uma categoria pode ter uma categoria pai (parent_id), permitindo níveis.
  • Produtos são vinculados a categorias da mesma loja.

Na resposta, parent e children_categories trazem apenas id e name (resumo), evitando árvores gigantes em cada item.

GET /stores/{storeId}/categories
Listar Categorias

Listar todas as categorias das lojas cadastradas

StatusQuando aconteceCorpo
401 401 —
404 404 —
Nome Local Tipo Descrição
storeId * path integer
padrão: 1

O Código da loja é gerado automaticamente pela plataforma, assim que você realiza o cadastro da loja você terá essa ID

root_only query integer
padrão: 1

Caso informado 1, irá mostrar somente as categorias Raiz (nível 0)

name query string

Informe um nome para filtrar as categorias contendo no nome

external_id query string

Informe um código para caso estiver utilizando código de referência externa, filtrar por ele

language_code query string

Informe o código da linguagem para filtrar somente por uma linguagem

status query string

Informe o status para filtrar categorias somente em um determinado status.

Opções: active, inactive

Resposta
json
{
    "data": [
        {
            "id": 713,
            "external_id": "externo_4",
            "name": "Categoria filha 2 de Categoria Raiz 2",
            "description": "Minha Descrição",
            "status": "active",
            "url": "",
            "language_code": "pt_BR",
            "created_at": "2022-04-19T18:15:53",
            "updated_at": "2022-04-19T18:15:53",
            "parent": {
                "id": 711,
                "external_id": "externo_2",
                "name": "Categoria Raiz 2",
                "description": "Minha Descrição",
                "status": "active",
                "url": "",
                "language_code": "pt_BR",
                "created_at": "2022-04-19T18:15:24",
                "updated_at": "2022-04-19T18:15:24",
                "parent": []
            },
            "children_categories": []
        },
        {
            "id": 712,
            "external_id": "externo_3",
            "name": "Categoria filha de Categoria Raiz 2",
            "description": "Minha Descrição",
            "status": "active",
            "url": "",
            "language_code": "pt_BR",
            "created_at": "2022-04-19T18:15:47",
            "updated_at": "2022-04-19T18:15:47",
            "parent": {
                "id": 711,
                "external_id": "externo_2",
                "name": "Categoria Raiz 2",
                "description": "Minha Descrição",
                "status": "active",
                "url": "",
                "language_code": "pt_BR",
                "created_at": "2022-04-19T18:15:24",
                "updated_at": "2022-04-19T18:15:24",
                "parent": []
            },
            "children_categories": []
        },
        {
            "id": 711,
            "external_id": "externo_2",
            "name": "Categoria Raiz 2",
            "description": "Minha Descrição",
            "status": "active",
            "url": "",
            "language_code": "pt_BR",
            "created_at": "2022-04-19T18:15:24",
            "updated_at": "2022-04-19T18:15:24",
            "parent": [],
            "children_categories": [
                {
                    "id": 712,
                    "external_id": "externo_3",
                    "name": "Categoria filha de Categoria Raiz 2",
                    "description": "Minha Descrição",
                    "status": "active",
                    "url": "",
                    "language_code": "pt_BR",
                    "created_at": "2022-04-19T18:15:47",
                    "updated_at": "2022-04-19T18:15:47",
                    "parent": {
                        "id": 711,
                        "external_id": "externo_2",
                        "name": "Categoria Raiz 2",
                        "description": "Minha Descrição",
                        "status": "active",
                        "url": "",
                        "language_code": "pt_BR",
                        "created_at": "2022-04-19T18:15:24",
                        "updated_at": "2022-04-19T18:15:24",
                        "parent": []
                    }
                },
                {
                    "id": 713,
                    "external_id": "externo_4",
                    "name": "Categoria filha 2 de Categoria Raiz 2",
                    "description": "Minha Descrição",
                    "status": "active",
                    "url": "",
                    "language_code": "pt_BR",
                    "created_at": "2022-04-19T18:15:53",
                    "updated_at": "2022-04-19T18:15:53",
                    "parent": {
                        "id": 711,
                        "external_id": "externo_2",
                        "name": "Categoria Raiz 2",
                        "description": "Minha Descrição",
                        "status": "active",
                        "url": "",
                        "language_code": "pt_BR",
                        "created_at": "2022-04-19T18:15:24",
                        "updated_at": "2022-04-19T18:15:24",
                        "parent": []
                    }
                }
            ]
        },
        {
            "id": 710,
            "external_id": "externo_1",
            "name": "Categoria Raiz",
            "description": "Minha Descrição",
            "status": "active",
            "url": "",
            "language_code": "pt_BR",
            "created_at": "2022-04-19T18:15:10",
            "updated_at": "2022-04-19T18:15:10",
            "parent": [],
            "children_categories": []
        }
    ],
    "links": {
        "first": "https://hubiss.dev/api/v1/product-lists/teste-lista-propria-2/categories?page=1",
        "last": "https://hubiss.dev/api/v1/product-lists/teste-lista-propria-2/categories?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "active": false
            },
            {
                "url": "https://hubiss.dev/api/v1/product-lists/teste-lista-propria-2/categories?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": null,
                "label": "Next »",
                "active": false
            }
        ],
        "path": "https://hubiss.dev/api/v1/product-lists/teste-lista-propria-2/categories",
        "per_page": 20,
        "to": 4,
        "total": 4
    }
}
{
    "error": "Unauthorized"
}
{
    "error": "Resource 9999 not found"
}
Exemplo
curl --request GET \
     --url 'https://api.hubiss.com.br/v1/stores/STOREID/categories' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer SEU_TOKEN'
use Illuminate\Support\Facades\Http;

$response = Http::withToken('SEU_TOKEN')
    ->acceptJson()
    ->get('https://api.hubiss.com.br/v1/stores/STOREID/categories');

$response->json();
const response = await fetch('https://api.hubiss.com.br/v1/stores/STOREID/categories', {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Authorization': 'Bearer SEU_TOKEN'
    }
});

const data = await response.json();
import requests

response = requests.GET(
    'https://api.hubiss.com.br/v1/stores/STOREID/categories',
    headers={'Authorization': 'Bearer SEU_TOKEN', 'Accept': 'application/json'},
)

print(response.json())
O token é usado apenas nesta requisição e não é armazenado.
GET /stores/{storeId}/categories/{categoryId}
Recuperar Categoria

Retorna uma categoria da loja. Os campos parent e children_categories trazem apenas id e name.

StatusQuando aconteceCorpo
401 Token ausente, invalido, expirado, conta inativa ou cadastro incompleto. {"error":"Unauthorized"}
404 Categoria inexistente ou de outra loja —
Nome Local Tipo Descrição
storeId * path integer
padrão: 101

Código da loja

categoryId * path integer
padrão: 1

Código da categoria

Resposta
json
200
Categoria inexistente ou de outra loja
Exemplo
curl --request GET \
     --url 'https://api.hubiss.com.br/v1/stores/STOREID/categories/CATEGORYID' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer SEU_TOKEN'
use Illuminate\Support\Facades\Http;

$response = Http::withToken('SEU_TOKEN')
    ->acceptJson()
    ->get('https://api.hubiss.com.br/v1/stores/STOREID/categories/CATEGORYID');

$response->json();
const response = await fetch('https://api.hubiss.com.br/v1/stores/STOREID/categories/CATEGORYID', {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Authorization': 'Bearer SEU_TOKEN'
    }
});

const data = await response.json();
import requests

response = requests.GET(
    'https://api.hubiss.com.br/v1/stores/STOREID/categories/CATEGORYID',
    headers={'Authorization': 'Bearer SEU_TOKEN', 'Accept': 'application/json'},
)

print(response.json())
O token é usado apenas nesta requisição e não é armazenado.
POST /stores/{storeId}/categories
Cadastrar Categoria
StatusQuando aconteceCorpo
401 401 —
404 404 —
422 422 —
Nome Local Tipo Descrição
storeId * path integer
padrão: 1

O Código da loja é gerado automaticamente pela plataforma, assim que você realiza o cadastro da loja você terá essa ID

CampoTipoDescrição
external_id string

Caso estiver cadastrando as categorias com base na lista de categorias do banco de dados de seu sistema ERP, informe o código aqui

name * string

Nome da sua categoria

description string

Descrição da categoria, para controle interno

status * string
url string

Caso sua categoria tiver uma url pública para acessa-la, informe a url

language_code * string

Código da linguagem da categoria em que a lista de produto está.

Busque o código aqui: https://api.hubiss.com.br/reference/linguagens#endpoint-listar-linguagens

parent_id integer

ID da categoria pai (Caso estiver cadastrando uma subcategoria)

Corpo enviado (JSON) json
{
    "external_id": "externo_1",
    "name": "Categoria filha 1 de Categoria Raiz",
    "description": "Minha Descrição",
    "status": "active",
    "url": "",
    "language_code": "pt_BR",
    "parent_id": 711
}
Resposta
json
{
    "data": {
        "id": 713,
        "external_id": "externo_1",
        "name": "Categoria filha 1 de Categoria Raiz",
        "description": "Minha Descrição",
        "status": "active",
        "url": "",
        "language_code": "pt_BR",
        "created_at": "2022-04-19T18:15:53",
        "updated_at": "2022-04-19T18:15:53",
        "parent": {
            "id": 711,
            "external_id": "externo_2",
            "name": "Categoria Raiz 2",
            "description": "Minha Descrição",
            "status": "active",
            "url": "",
            "language_code": "pt_BR",
            "created_at": "2022-04-19T18:15:24",
            "updated_at": "2022-04-19T18:15:24",
            "parent": []
        },
        "children_categories": []
    },
    "success": true,
    "message": "Register Successfull Inserted"
}
{
    "error": "Unauthorized"
}
{
    "error": "Resource 9999 not found"
}
{
    "success": false,
    "message": "Validation errors",
    "data": {
        "name": [
            "The name field is required."
        ]
    }
}
Exemplo
curl --request POST \
     --url 'https://api.hubiss.com.br/v1/stores/STOREID/categories' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer SEU_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{    "external_id": "externo_1",    "name": "Categoria filha 1 de Categoria Raiz",    "description": "Minha Descrição",    "status": "active",    "url": "",    "language_code": "pt_BR",    "parent_id": 711}'
use Illuminate\Support\Facades\Http;

$response = Http::withToken('SEU_TOKEN')
    ->acceptJson()
    ->withBody("{\n    \"external_id\": \"externo_1\",\n    \"name\": \"Categoria filha 1 de Categoria Raiz\",\n    \"description\": \"Minha Descri\u00e7\u00e3o\",\n    \"status\": \"active\",\n    \"url\": \"\",\n    \"language_code\": \"pt_BR\",\n    \"parent_id\": 711\n}", 'application/json')
    ->post('https://api.hubiss.com.br/v1/stores/STOREID/categories');

$response->json();
const response = await fetch('https://api.hubiss.com.br/v1/stores/STOREID/categories', {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Authorization': 'Bearer SEU_TOKEN',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
    "external_id": "externo_1",
    "name": "Categoria filha 1 de Categoria Raiz",
    "description": "Minha Descrição",
    "status": "active",
    "url": "",
    "language_code": "pt_BR",
    "parent_id": 711
})
});

const data = await response.json();
import requests

response = requests.POST(
    'https://api.hubiss.com.br/v1/stores/STOREID/categories',
    headers={'Authorization': 'Bearer SEU_TOKEN', 'Accept': 'application/json'},
    json={
    "external_id": "externo_1",
    "name": "Categoria filha 1 de Categoria Raiz",
    "description": "Minha Descrição",
    "status": "active",
    "url": "",
    "language_code": "pt_BR",
    "parent_id": 711
},
)

print(response.json())
O token é usado apenas nesta requisição e não é armazenado.
PUT /stores/{storeId}/categories/{categoryId}
Atualizar Categoria
StatusQuando aconteceCorpo
401 401 —
404 404 —
422 422 —
Nome Local Tipo Descrição
storeId * path integer
padrão: 1

O Código da loja é gerado automaticamente pela plataforma, assim que você realiza o cadastro da loja você terá essa ID

categoryId * path integer

ID da categoria cadastrada na Hubiss. Esse ID será gerado automaticamente pela plataforma ao cadastrar.

CampoTipoDescrição
external_id string

Caso estiver cadastrando as categorias com base na lista de categorias do banco de dados de seu sistema ERP, informe o código aqui

name * string

Nome da sua categoria

description string

Descrição da categoria, para controle interno

status * string
url string

Caso sua categoria tiver uma url pública para acessa-la, informe a url

language_code * string

Código da linguagem da categoria em que a lista de produto está.

Busque o código aqui: https://api.hubiss.com.br/reference/linguagens#endpoint-listar-linguagens

parent_id integer

ID da categoria pai (Caso estiver cadastrando uma subcategoria)

Corpo enviado (JSON) json
{
    "external_id": "externo_1",
    "name": "Editado Categoria filha 1 de Categoria Raiz",
    "description": "Minha Descrição",
    "status": "active",
    "url": "",
    "language_code": "pt_BR",
    "parent_id": 711
}
Resposta
json
{
    "data": {
        "id": 713,
        "external_id": "externo_1",
        "name": "Editado Categoria filha 1 de Categoria Raiz",
        "description": "Minha Descrição",
        "status": "active",
        "url": "",
        "language_code": "pt_BR",
        "created_at": "2022-04-19T18:15:53",
        "updated_at": "2022-04-19T18:15:53",
        "parent": {
            "id": 711,
            "external_id": "externo_2",
            "name": "Categoria Raiz 2",
            "description": "Minha Descrição",
            "status": "active",
            "url": "",
            "language_code": "pt_BR",
            "created_at": "2022-04-19T18:15:24",
            "updated_at": "2022-04-19T18:15:24",
            "parent": []
        },
        "children_categories": []
    },
    "success": true,
    "message": "Register Successfull Updated"
}
{
    "error": "Unauthorized"
}
{
    "error": "Resource 9999 not found"
}
{
    "success": false,
    "message": "Validation errors",
    "data": {
        "name": [
            "The name field is required."
        ]
    }
}
Exemplo
curl --request PUT \
     --url 'https://api.hubiss.com.br/v1/stores/STOREID/categories/CATEGORYID' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer SEU_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{    "external_id": "externo_1",    "name": "Editado Categoria filha 1 de Categoria Raiz",    "description": "Minha Descrição",    "status": "active",    "url": "",    "language_code": "pt_BR",    "parent_id": 711}'
use Illuminate\Support\Facades\Http;

$response = Http::withToken('SEU_TOKEN')
    ->acceptJson()
    ->withBody("{\n    \"external_id\": \"externo_1\",\n    \"name\": \"Editado Categoria filha 1 de Categoria Raiz\",\n    \"description\": \"Minha Descri\u00e7\u00e3o\",\n    \"status\": \"active\",\n    \"url\": \"\",\n    \"language_code\": \"pt_BR\",\n    \"parent_id\": 711\n}", 'application/json')
    ->put('https://api.hubiss.com.br/v1/stores/STOREID/categories/CATEGORYID');

$response->json();
const response = await fetch('https://api.hubiss.com.br/v1/stores/STOREID/categories/CATEGORYID', {
    method: 'PUT',
    headers: {
        'Accept': 'application/json',
        'Authorization': 'Bearer SEU_TOKEN',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
    "external_id": "externo_1",
    "name": "Editado Categoria filha 1 de Categoria Raiz",
    "description": "Minha Descrição",
    "status": "active",
    "url": "",
    "language_code": "pt_BR",
    "parent_id": 711
})
});

const data = await response.json();
import requests

response = requests.PUT(
    'https://api.hubiss.com.br/v1/stores/STOREID/categories/CATEGORYID',
    headers={'Authorization': 'Bearer SEU_TOKEN', 'Accept': 'application/json'},
    json={
    "external_id": "externo_1",
    "name": "Editado Categoria filha 1 de Categoria Raiz",
    "description": "Minha Descrição",
    "status": "active",
    "url": "",
    "language_code": "pt_BR",
    "parent_id": 711
},
)

print(response.json())
O token é usado apenas nesta requisição e não é armazenado.
DELETE /stores/{storeId}/categories/{categoryId}
Excluir Categoria
StatusQuando aconteceCorpo
401 401 —
404 404 —
Nome Local Tipo Descrição
storeId * path integer
padrão: 1
categoryId * path integer

ID da categoria cadastrada na Hubiss. Esse ID será gerado automaticamente pela plataforma ao cadastrar.

Resposta
json
204
{
    "error": "Unauthorized"
}
{
    "error": "Resource 9999 not found"
}
Exemplo
curl --request DELETE \
     --url 'https://api.hubiss.com.br/v1/stores/STOREID/categories/CATEGORYID' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer SEU_TOKEN'
use Illuminate\Support\Facades\Http;

$response = Http::withToken('SEU_TOKEN')
    ->acceptJson()
    ->delete('https://api.hubiss.com.br/v1/stores/STOREID/categories/CATEGORYID');

$response->json();
const response = await fetch('https://api.hubiss.com.br/v1/stores/STOREID/categories/CATEGORYID', {
    method: 'DELETE',
    headers: {
        'Accept': 'application/json',
        'Authorization': 'Bearer SEU_TOKEN'
    }
});

const data = await response.json();
import requests

response = requests.DELETE(
    'https://api.hubiss.com.br/v1/stores/STOREID/categories/CATEGORYID',
    headers={'Authorization': 'Bearer SEU_TOKEN', 'Accept': 'application/json'},
)

print(response.json())
O token é usado apenas nesta requisição e não é armazenado.

Erros comuns

Sintoma Causa provável O que fazer
404 em /stores/{id}/categories Loja inexistente ou de outra conta Conferir o storeId
422 em parent_id Categoria pai de outra loja Usar categoria da mesma loja
Próximo passo
Siga para Produtos.