Formatos: JSON e XML
Escolhendo o formato da resposta
As respostas saem em JSON por padrão. Para receber XML:
| Como | Exemplo |
|---|---|
Cabeçalho Accept | Accept: application/xml (ou text/xml) |
Parâmetro format | ?format=xml |
O parâmetro format tem prioridade sobre o cabeçalho, e é útil em ferramentas que não permitem mudar cabeçalhos. Accept: application/json, */* ou nenhum Accept resultam em JSON. Qualquer outro formato recebe o erro 406 (not_acceptable).
Os erros também saem no formato escolhido.
Corpo das requisições
O corpo de POST e PATCH deve ser JSON em UTF-8, com Content-Type: application/json.
| Situação | HTTP | code |
|---|---|---|
Outro Content-Type (inclusive XML) | 415 | unsupported_media_type |
| JSON malformado | 400 | invalid_json |
| Corpo maior que 256 KB | 413 | payload_too_large |
| Campo desconhecido ou valor inválido | 422 | validation_error |
Campos desconhecidos são recusados, e não ignorados. Assim, um erro de digitação, como day_to_be_next no lugar de days_to_be_next, aparece na hora.
Formato dos dados
| Tipo | Formato | Exemplo |
|---|---|---|
| Identificadores | UUID | "6b7e1f0a-…" |
Datas de validade (exp_date) | AAAA-MM-DD, sem fuso horário | "2026-12-31" |
Data e hora (created_at, updated_at, deleted_at) | ISO 8601 em UTC | "2026-11-05T17:40:00.123Z" |
Números (amount, price, cost_price) | número | 6.49 |
| Valores ausentes | null | "code": null |
| Nomes dos campos | snake_case | days_to_be_next |
A data de validade nunca muda por causa de fuso horário: o que você envia é o que volta.
Nos filtros de data e hora (updated_since, since), informe sempre o fuso, por exemplo 2026-11-06T13:00:00Z ou 2026-11-06T10:00:00-03:00.
Exemplo em JSON
{
"data": {
"id": "6b7e1f0a-3c2d-4e5f-8a9b-0c1d2e3f4a5b",
"name": "Leite integral 1L",
"code": "7891000100103",
"days_to_be_next": 15,
"brand_id": null,
"category_id": "a1c2d3e4-…",
"store_id": null,
"has_image": false,
"created_at": "2026-11-05T17:40:00.000Z",
"updated_at": "2026-11-05T17:40:00.000Z"
}
}
O mesmo exemplo em XML
<?xml version="1.0" encoding="UTF-8"?>
<response>
<data>
<id>6b7e1f0a-3c2d-4e5f-8a9b-0c1d2e3f4a5b</id>
<name>Leite integral 1L</name>
<code>7891000100103</code>
<days_to_be_next>15</days_to_be_next>
<brand_id nil="true"/>
<category_id>a1c2d3e4-…</category_id>
<store_id nil="true"/>
<has_image>false</has_image>
<created_at>2026-11-05T17:40:00.000Z</created_at>
<updated_at>2026-11-05T17:40:00.000Z</updated_at>
</data>
</response>
Regras do XML
- O documento começa com
<?xml version="1.0" encoding="UTF-8"?>e tem um único elemento raiz,<response>. - Os elementos têm os mesmos nomes dos campos do JSON.
- Valores nulos viram um elemento vazio com
nil="true". - Números,
true/falsee datas são escritos como texto, no mesmo formato do JSON. - Listas viram um elemento com um filho por item, no singular:
| Lista | Item |
|---|---|
data de /v1/products | <product> |
data de /v1/batches e /v1/products/{id}/batches | <batch> |
data de /v1/categories, /v1/brands, /v1/stores | <category>, <brand>, <store> |
data de /v1/deletions | <deletion> |
batches (com include=batches) | <batch> |
scopes | <scope> |
details (erros) | <detail> |
Exemplo de lista:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<data>
<batch>
<id>…</id>
<exp_date>2026-12-31</exp_date>
…
</batch>
</data>
<pagination>
<limit>50</limit>
<has_more>false</has_more>
<next_cursor nil="true"/>
</pagination>
</response>