JSON envelope
Estrutura JSON comum que envolve a resposta de cada endpoint da Normadata com metadados consistentes.
Toda resposta da API da Normadata segue uma estrutura JSON padrão — um "envelope" — que dá previsibilidade ao cliente. Independentemente do endpoint invocado (`/v1/verify`, `/v1/verify/tax-id`, `/v1/verify/bank`, etc.), o corpo da resposta tem a mesma forma: ```json { "contains_pii": true, "processed_at": "2025-10-15T14:32:10Z", "value": { ... }, "warnings": [ ... ] } ``` Campos: - **`contains_pii`**: booleano que indica se a resposta contém dados pessoalmente identificáveis. Serve para o cliente decidir se loga ou não. - **`processed_at`**: timestamp ISO 8601 UTC do momento exato em que a requisição foi processada. - **`value`**: o resultado do endpoint — sua forma varia conforme o que foi validado (um tax ID retorna formato + país; um endereço retorna componentes normalizados). - **`warnings`**: array opcional com avisos não fatais (ex: `"check_digit_recomputed"`, `"country_inferred_from_pattern"`). O envelope permite que um único middleware no lado do cliente extraia metadados sem conhecer a forma específica de `value`. Também simplifica logging, observabilidade e tratamento transversal de erros.