JSON envelope

Definição

Estrutura JSON comum que envolve a resposta de cada endpoint da Normadata com metadados consistentes.

Cada endpoint batch da Normadata compartilha o mesmo "envelope" JSON: a requisição é `{ "items": [...] }` e a resposta é `{ "results": [...] }`. Independentemente do endpoint invocado (`/v1/validate/tax-ids`, `/v1/validate/accounts`, `/v1/validate/emails`, `/v1/validate/phones`, `/v1/validate/records`), o envelope tem a mesma forma — o mesmo endpoint serve para 1 ou N itens: ```json { "results": [ { "id": "1", "valid": true, "normalized": "..." }, { "id": "2", "valid": false, "error": "..." } ] } ``` Como funciona: - **`items`**: array de itens a validar (até 1.000; 500 em `/records`). Cada item leva um `id` (ou `reference_id` em records) que você fornece. - **`results`**: um resultado por item, na mesma ordem, correlacionado pelo `id` que você enviou (devolvido verbatim). - **Por item**: `valid`, o valor `normalized` e, quando `valid` é false, um `error` acionável. Um item que falha na validação não interrompe o resto do lote. O envelope permite que um único cliente processe lotes independentemente do endpoint, mapeando cada resultado de volta à sua entrada de origem pelo `id`.