Saltar para o conteúdo principal

Formatos: JSON e XML

Escolhendo o formato da resposta​

As respostas saem em JSON por padrão. Para receber XML:

ComoExemplo
Cabeçalho AcceptAccept: 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çãoHTTPcode
Outro Content-Type (inclusive XML)415unsupported_media_type
JSON malformado400invalid_json
Corpo maior que 256 KB413payload_too_large
Campo desconhecido ou valor inválido422validation_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​

TipoFormatoExemplo
IdentificadoresUUID"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úmero6.49
Valores ausentesnull"code": null
Nomes dos campossnake_casedays_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/false e datas são escritos como texto, no mesmo formato do JSON.
  • Listas viram um elemento com um filho por item, no singular:
ListaItem
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>