Shape do Payload
Estrutura canónica de resposta dos endpoints e do payload de webhook. Campos expostos e garantia anti-leak de dados internos do provider.
Estrutura canónica
O mesmo objeto é retornado pelo GET /api/v1/reports/{reportId} e enviado no corpo do webhook.
{
reportId: string;
externalRef: string | null;
status: "PROCESSING" | "DELIVERED" | "ERROR";
driver: {
id: string;
cpf: string | null;
name: string | null;
licenseNumber: string | null;
licenseCategory: string | null; // ex.: "A" | "B" | "AB" | "C" | "D" | "E"
expiryDate: string | null; // ISO 8601 date
issueState: string | null; // sigla UF, ex.: "SP"
};
// Diagnóstico curado. null enquanto status !== "DELIVERED".
diagnosis: {
status: string;
hasReportData: boolean;
hasPartialData: boolean;
validity: object | null;
category: object | null;
blocks: object[];
medicalExams: object | null;
toxicological: object | null;
points: object | null;
fines: object | null;
rollingPoints: object | null;
autosuspensionRisk: object | null;
allAlerts: object[];
diagnosisDate: string; // ISO 8601
} | null;
// Resumos normalizados por secção (espelham o diagnóstico).
normalized: {
validity: object | null;
blocks: object[] | null;
medicalExams: object[] | null;
toxicological: object | null;
points: object | null;
fines: object[] | null;
};
// Análise em linguagem natural gerada por IA a partir do diagnóstico.
// Opcional e anulável — ver nota abaixo.
aiAnalysis: {
markdown: string; // texto em markdown (pt-BR)
status: string | null; // veredito: VALID | WARNING | BLOCKED | EXPIRED | UNKNOWN
generatedAt: string; // ISO 8601
} | null;
createdAt: string; // ISO 8601
deliveredAt: string | null; // ISO 8601, preenchido quando DELIVERED
}Campos nunca expostos
Garantia anti-leak
Os seguintes campos nunca aparecem na resposta da API, mesmo existindo internamente no relatório:
payload/response— respostas brutas do provider (DETRAN/SENATRAN/Datacube/Serpro)requestUid/cost/provideraddons.*.response— payloads internos dos add-ons de enriquecimentocnhDocumentUrl(URL interna),monitoring(estado interno),reportsUsed(ids federais internos)- Contadores internos de retry e tempos de pipeline
A garantia é construída por allow-list (o serializer monta o objeto campo a campo, nunca por exclusão) e validada por snapshot tests automáticos em toda PR que toca o serializer.
Comportamento quando status não é DELIVERED
Enquanto o relatório está em PROCESSING, o campo diagnosis é null, os campos de normalized
são null, e deliveredAt é null. O driver pode ter apenas id e cpf se o enriquecimento
ainda não completou.
O campo aiAnalysis é gerado automaticamente também para relatórios criados via API. É null
enquanto o relatório está em PROCESSING; e pode continuar null num relatório já DELIVERED se a
geração falhar — a análise é best-effort e nunca bloqueia nem atrasa a entrega do relatório em
si. Quando presente, é gravada antes de o status virar DELIVERED e antes de o webhook
report.delivered ser enfileirado, então um relatório entregue com análise a traz tanto no
GET /api/v1/reports/{reportId} quanto no corpo do webhook. Por ser opcional e anulável, o campo
é retrocompatível: integrações existentes não precisam de nenhuma mudança.