Entenda as estruturas de dados que a API do Venddor retorna e como elas se relacionam.
A API do Venddor retorna dados em formato JSON. Aqui estao os modelos de dados principais que voce vai encontrar ao integrar com a plataforma.
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"name": "Camiseta Premium",
"description": "Camiseta 100% algodao premium",
"price_cents": 8990,
"list_price_cents": 11990,
"currency": "BRL",
"sku": "SHIRT-001",
"status": "active",
"weight_grams": 250,
"category_id": "550e8400-e29b-41d4-a716-446655440002",
"vendor_id": "550e8400-e29b-41d4-a716-446655440003",
"inventory_count": 150,
"images": [
{
"id": "img_001",
"url": "https://cdn.venddor.com.br/products/shirt-001.jpg",
"alt": "Camiseta Premium frente",
"position": 0
}
],
"variants": [
{
"id": "var_001",
"name": "P",
"sku": "SHIRT-001-P",
"price_cents": 8990,
"inventory_count": 50
}
],
"features": {
"cor": "Azul",
"tamanho": "P, M, G, GG",
"material": "100% Algodao"
},
"seo": {
"meta_title": "Camiseta Premium | Loja",
"meta_description": "Camiseta premium de algodao...",
"slug": "camiseta-premium"
},
"is_featured": false,
"created_at": "2026-03-01T10:00:00Z",
"updated_at": "2026-03-15T14:30:00Z"
}| Campo | Tipo | Descrição |
|---|---|---|
| id | UUID | Identificador unico |
| price_cents | int64 | Preco em centavos (8990 = R$89,90) |
| list_price_cents | int64 | Preco de lista (antes do desconto) |
| status | string | "active" | "disabled" | "hidden" |
| weight_grams | int | Peso em gramas (para calculo de frete) |
| inventory_count | int | Quantidade em estoque |
| features | object | Caracteristicas do produto (chave-valor) |
{
"id": "ord_abc123",
"order_number": "2026-0042",
"status": "shipped",
"customer": {
"id": "usr_456",
"name": "Joao Silva",
"email": "joao@example.com",
"phone": "+5511999998888"
},
"items": [
{
"product_id": "prod_789",
"name": "Camiseta Premium",
"sku": "SHIRT-001-M",
"quantity": 2,
"price_cents": 8990,
"total_cents": 17980
}
],
"subtotal_cents": 17980,
"shipping_cents": 1500,
"discount_cents": 0,
"tax_cents": 0,
"total_cents": 19480,
"currency": "BRL",
"payment": {
"method": "pix",
"status": "paid",
"paid_at": "2026-03-27T14:32:00Z"
},
"shipping": {
"method": "correios_pac",
"tracking_code": "BR123456789",
"address": {
"street": "Rua das Flores",
"number": "123",
"complement": "Apt 4B",
"neighborhood": "Centro",
"city": "Sao Paulo",
"state": "SP",
"zip": "01001-000",
"country": "BR"
}
},
"notes": "",
"created_at": "2026-03-27T14:30:00Z",
"updated_at": "2026-03-27T16:00:00Z"
}| Status | Descrição |
|---|---|
| pending | Aguardando pagamento |
| paid | Pagamento confirmado |
| processing | Em preparacao |
| shipped | Enviado (com codigo de rastreio) |
| delivered | Entregue |
| cancelled | Cancelado |
| refunded | Reembolsado |
{
"id": "usr_456",
"email": "joao@example.com",
"name": "Joao Silva",
"phone": "+5511999998888",
"cpf": "123.456.789-00",
"role": "customer",
"is_active": true,
"addresses": [
{
"id": "addr_001",
"label": "Casa",
"street": "Rua das Flores",
"number": "123",
"city": "Sao Paulo",
"state": "SP",
"zip": "01001-000",
"is_default": true
}
],
"order_count": 5,
"total_spent_cents": 89500,
"last_order_at": "2026-03-27T14:30:00Z",
"created_at": "2026-01-15T10:00:00Z"
}{
"id": "cat_001",
"name": "Vestuario",
"slug": "vestuario",
"parent_id": null,
"position": 1,
"is_active": true,
"product_count": 42,
"children": [
{
"id": "cat_002",
"name": "Camisetas",
"slug": "camisetas",
"parent_id": "cat_001",
"position": 1,
"product_count": 15
}
],
"seo": {
"meta_title": "Vestuario",
"meta_description": "Roupas e acessorios",
"slug": "vestuario"
}
}{
"id": "vendor_001",
"name": "Loja do Joao",
"slug": "loja-do-joao",
"email": "joao@lojajoao.com.br",
"cnpj": "12.345.678/0001-90",
"status": "active",
"logo_url": "https://cdn.venddor.com.br/vendors/logo.png",
"product_count": 85,
"rating": 4.7,
"created_at": "2026-01-01T10:00:00Z"
}TODOS os valores monetarios na API sao inteiros em centavos. Isso evita erros de arredondamento com ponto flutuante.
| Valor real | Valor na API | Calculo |
|---|---|---|
| R$ 0,01 | 1 | 1 / 100 = 0.01 |
| R$ 1,00 | 100 | 100 / 100 = 1.00 |
| R$ 49,90 | 4990 | 4990 / 100 = 49.90 |
R$ 1.299,99 | 129999 | 129999 / 100 = 1299.99 |
// Converting centavos to display format
function formatBRL(centavos) {
return new Intl.NumberFormat('pt-BR', {
style: 'currency',
currency: 'BRL',
}).format(centavos / 100);
}
// Examples:
formatBRL(4990); // "R$ 49,90"
formatBRL(129999); // "R$ 1.299,99"
formatBRL(0); // "R$ 0,00"Todos os recursos na API usam UUID v4 como identificador. UUIDs sao strings de 36 caracteres no formato:
550e8400-e29b-41d4-a716-446655440000UUIDs sao preferidos sobre IDs sequenciais porque nao expoe quantidade de registros e sao seguros em ambiente multi-tenant.
Todos os timestamps sao em formato ISO 8601 com timezone UTC:
"created_at": "2026-03-27T14:30:00Z"
"updated_at": "2026-03-27T16:45:00Z"// Parsing in JavaScript
const date = new Date(item.created_at);
// Display in Brazilian format
date.toLocaleDateString('pt-BR'); // "27/03/2026"
date.toLocaleTimeString('pt-BR'); // "14:30:00"
// Python
from datetime import datetime
date = datetime.fromisoformat(item['created_at'].replace('Z', '+00:00'))O Venddor e uma plataforma multi-tenant. Cada loja (tenant) tem seus proprios dados isolados. Ao chamar a API, voce sempre precisa especificar qual tenant esta acessando via header X-Tenant-ID.
O tenant_id e retornado durante o fluxo OAuth e deve ser armazenado junto com o access_token. Seu app pode ser instalado em multiplos tenants.
// Store per-tenant credentials
const tenantTokens = {
'tenant-uuid-1': { accessToken: '...', refreshToken: '...' },
'tenant-uuid-2': { accessToken: '...', refreshToken: '...' },
};
// Use the correct token for each tenant
async function callApi(tenantId, endpoint) {
const { accessToken } = tenantTokens[tenantId];
return fetch(`https://api.io.venddor.com.br${endpoint}`, {
headers: {
'Authorization': `Bearer ${accessToken}`,
'X-Tenant-ID': tenantId,
},
});
}