Estruturas de Resposta da API

Esta página detalha os formatos JSON padronizados retornados pela API do SantoID, tanto para requisições síncronas quanto para notificações via Webhook (assíncronas).

Visão Geral

A estrutura da resposta varia de acordo com o serviço utilizado (OCR, Tipificação, Face Match ou Workflow), mas segue um envelope comum contendo metadados da requisição.

Estrutura Padrão (OCR e Tipificação)

Utilizada pelos serviços de OCR e Tipificação.

{
    "domain": <string>,
    "track": <string>,
    "service": <string>,
    "requestId": <string>,
    "requestType": <string>,
    "customerRequestId": <string>,
    "executionDatetime": <string>,
    "count": 0,
    "documents": [
        {
            "typification": <object (Typification)>,
            "ocr": {
                "labels": <Array (Labels)>
                "template": <string>
            }
        }
    ],
    "status": <string>
}

Campos Comuns

Campo	Tipo	Descrição
domain	string	Domínio SantoID onde a requisição foi processada
track	string	ID do track (processo) relacionado
service	string	Serviço que realizou o processamento
requestId	string	ID único gerado pelo SantoID
customerRequestId	string	ID externo para agrupamento de requisições (opcional)
requestType	string	Tipo original da requisição
executionDatetime	string	Timestamp do processamento (UTC ISO)
count	int	Número de documentos processados
status	string	Status geral do processamento
documents	list(object)	Corpo da resposta de processamento com resultados coletados. Os objetos são relativos ao tipo de processamento – se um documento não requer certas etapas (tipificação, ocr), o objeto relacionado não será retornado. objects: Typification Ocr: template: ID do template OCR Array de Labels

Resposta Específica para FaceMatch

{
    "domain": "string",
    "track": "string",
    "service": "string",
    "requestId": "string",
    "requestType": "string",
    "customerRequestId": "string",
    "executionDatetime": "string",
    "error": {
        "error": "string"
    },
    "status": "string",
    "comparison_score": 0.0,
    "similarity_score": 0.0,
    "match": false
}

Campos Exclusivos do FaceMatch

Campo	Tipo	Descrição
comparison_score	float	Distância entre rostos (valores menores indicam mais similaridade)
similarity_score	float	Pontuação de similaridade facial (0-1)
match	boolean	Indica se os rostos pertencem à mesma pessoa
error	object	Detalhes do erro, se aplicável

Resposta de Workflow

{
    "domain": "string",
    "track": "string",
    "service": "string",
    "requestId": "string",
    "requestType": "string",
    "customerRequestId": "string",
    "executionDatetime": "string",
    "count": 0,
    "documents": [
        {
            "workflow": "list(object_workflow)"
        }
    ],
    "status": "string",
    "rejectedReasons": ["string"]
}

Campos Exclusivos do Workflow

Campo	Tipo	Descrição
rejectedReasons	string[]	Razões de rejeição de acordo com políticas definidas
documents	list(object)	list(object_workflow) - Corpo da resposta de processamento com resultados coletados. object: - Workflow

Detalhes dos Objetos

Para ver a estrutura detalhada dos objetos internos, consulte as páginas específicas:

Visão Geral​

Estrutura Padrão (OCR e Tipificação)​

Campos Comuns​

Resposta Específica para FaceMatch​

Campos Exclusivos do FaceMatch​

Resposta de Workflow​

Campos Exclusivos do Workflow​

Detalhes dos Objetos​