Ids, dinheiro e datas

Três tipos de campo causam a maioria dos erros de integração: ids, dinheiro e datas. Cada um tem um formato fixo em toda a API. Esta página reúne as regras.

Ids

Pontos importantes:

• Os ids são por loja. O mesmo UUID não existe em outra loja (Lojas e resolução de host).
• O display_id serve para mostrar ao usuário. Não use como chave nas rotas /api/v1/..., que esperam UUID.
• Lojas migradas de outra plataforma guardam o id anterior em um campo legacy_id (inteiro) em alguns recursos. Ele serve para conciliar com o sistema de origem, não para chamar rotas.
• Um UUID bem formado que não existe responde 404 (product not found). Um texto que não é UUID na própria URL também responde 404. Em filtros de lista (customer_id=...) um UUID inválido pode responder 500: valide antes de enviar.
• Trate todo id como texto opaco. Não ordene nem faça conta com ele.

Dinheiro

Centavos

Todo valor monetário da API é um inteiro em centavos, sem casas decimais. Isso evita erros de arredondamento de ponto flutuante.

Para converter: reais = centavos / 100, mas faça a conta com inteiros e só formate na tela. Em JavaScript, 4990 / 100 é seguro para mostrar, mas nunca some dinheiro como número decimal; some em centavos.

Algumas respostas trazem também uma versão em string decimal ao lado do inteiro, para facilitar a exibição (por exemplo total: 22500 e total_str: "225.00" num pedido). Os dois descrevem o mesmo valor; use o inteiro.

Percentuais não são centavos. Em alguns recursos (descontos percentuais de promoções) o percentual é guardado em pontos-base, ou seja, centésimos de ponto percentual (1500 = 15%). A página de cada rota diz a unidade do campo.

Moeda

A moeda padrão é BRL. Onde a resposta traz currency, é o código ISO 4217 de três letras.

Datas e fuso horário

Formato

Datas sem fração de segundo (2026-10-11T20:56:24Z) também são aceitas na entrada.

Filtros por data

Os filtros date_from e date_to (e equivalentes) aceitam AAAA-MM-DD ou RFC 3339. Com só a data:

• date_from=2026-10-01 começa à meia-noite UTC do dia 1.
• date_to=2026-10-31 inclui o dia 31 inteiro.

Alguns campos de calendário (início e fim de campanha, por exemplo) também aceitam AAAA-MM-DD no corpo: o início vira 00:00:00 UTC e o fim 23:59:59 UTC daquele dia.

Fuso horário

A API trabalha e devolve datas em UTC. O horário de Brasília (America/Sao_Paulo, UTC-3) não é aplicado automaticamente nas respostas: converta no seu sistema para mostrar ao usuário. Quando um relatório ou resumo agrupa por dia (por exemplo "vendas de hoje"), a página da rota diz qual fuso o dia usa, e em alguns agrupamentos esse fuso é o de Brasília.

Exemplo: converter um pedido

curl "$BASE_URL/api/v1/admin/orders?per_page=1" \
  -H "Authorization: Bearer $TOKEN" | jq '.orders[0] | {total, created_at}'

Erros comuns

• Mandar 49.90 num campo em centavos. A API não aceita decimais: mande 4990.
• Ler total como reais. 22500 é R$ 225,00.
• Mostrar created_at direto. Está em UTC; uma venda das 22h em Brasília aparece como 01h do dia seguinte.
• Usar display_id ou legacy_id em /api/v1/.... Essas rotas esperam UUID.
• Somar dinheiro em ponto flutuante. Some centavos inteiros.

Veja também