Criar Processo de Documento

MarkdownChatGPTClaude

Este endpoint gerencia dois fluxos de documento que compartilham o mesmo caminho, mas diferem nos parâmetros do body:

• Nova captura — envia imagem(ns) do documento em base64 para processamento (document.files obrigatório).
• Reutilização — pula a captura referenciando um documento capturado anteriormente (document.documentId obrigatório).

O fluxo ativo é determinado pelo fornecimento ou não de document.documentId no body da requisição.

Antes de criar um processo de documento, use Obter Documentos Reutilizáveis para verificar se o usuário já possui um documento disponível para reutilização.

Para o fluxo completo de integração, consulte Visão geral da API.

Endpoint

Ambiente	URL
Produção	POST https://api.id.unico.app/processes/v1
Sandbox	POST https://api.id.uat.unico.app/processes/v1

Requisição

Headers

Header	Valor
Authorization	Bearer <access_token> (consulte Autenticação)
APIKEY	Chave de API provisionada com Captura e Reutilização de Documentos habilitadas.
Content-Type	application/json

Parâmetros do body

Nova captura

Campo	Tipo	Obrigatório	Descrição
subject.duiType	integer	sim	Identificador do tipo de documento. Veja os valores de duiType abaixo.
subject.code	string	sim	Valor do identificador do usuário conforme definido por subject.duiType. Sem pontos ou traços.
subject.name	string	não	Nome completo.
subject.gender	string	não	M ou F.
subject.birthDate	string (ISO 8601)	não	Data de nascimento (YYYY-MM-DD).
subject.email	string	não	Endereço de e-mail.
subject.phone	string	não	Número de telefone no formato E.164.
document.purpose	string	sim	Finalidade de negócio. Valores: creditprocess, carpurchase, paybypaycheck, onboarding, fgts.
document.authProcessId	string	sim	ID do processo biométrico vinculado a esta captura de documento.
document.files	array	sim	Imagens do documento em base64 (frente e/ou verso).
document.files[].data	string	sim	Imagem do documento em base64 (PNG, JPEG ou WebP, máx. 800 KB).
subsidiaryId	string	não	ID da filial — obrigatório apenas se existirem múltiplas filiais.

Reutilização

Campo	Tipo	Obrigatório	Descrição
subject.duiType	integer	sim	Identificador do tipo de documento. Veja os valores de duiType abaixo.
subject.code	string	sim	Valor do identificador do usuário conforme definido por subject.duiType. Sem pontos ou traços.
subject.name	string	não	Nome completo.
subject.gender	string	não	M ou F.
subject.birthDate	string (ISO 8601)	não	Data de nascimento (YYYY-MM-DD).
subject.email	string	não	Endereço de e-mail.
subject.phone	string	não	Número de telefone no formato E.164.
document.purpose	string	sim	Finalidade de negócio. Valores: creditprocess, carpurchase, paybypaycheck, onboarding, fgts.
document.authProcessId	string	sim	ID do processo biométrico vinculado a este documento.
document.documentId	string	sim	ID de um documento capturado anteriormente (obtido em Obter Documentos Reutilizáveis). Quando fornecido, document.files pode ser omitido.
subsidiaryId	string	não	ID da filial — obrigatório apenas se existirem múltiplas filiais.

Valores de duiType

País	Código	Descrição
AR	6	Passaporte Argentino
AR	7	DNI Argentino
AR	49	Carteira de motorista Argentina (Licencia Nacional de Conducir)
AT	34	Número de Contribuinte Austríaco (STNR)
BE	36	Número Nacional Belga (NN)
BR	1	CPF Brasileiro
BR	5	Passaporte Brasileiro
BR	14	CNPJ Brasileiro
CA	28	SIN Canadense
CH	33	Número AHV/AVS Suíço
CL	9	RUN Chileno
CL	52	Passaporte Chileno
CL	57	Carteira de motorista Chilena (Licencia de Conducir)
CO	26	NIT Colombiano
CO	53	Passaporte Colombiano
CO	55	Carteira de motorista Colombiana (Licencia de Conducción)
CO	56	Cédula de Cidadania Colombiana (Cédula de Ciudadanía)
DE	41	Número de Identificação Fiscal Alemão (IdNr)
DK	29	CPR Dinamarquês
EC	10	NI Equatoriano
ES	50	Número de Identidade de Estrangeiro Espanhol (NIE)
ES	51	Documento Nacional de Identidade Espanhol (DNI)
FI	35	Código de Identidade Pessoal Finlandês (HETU)
FR	46	Número de Referência Fiscal Francês (SPI)
GB	30	Número de Seguro Nacional Britânico (NINO)
GT	12	CUI Guatemalteco
ID	16	NIK Indonésio
IE	47	Número de Serviço Público Pessoal Irlandês (PPSN)
IT	37	Codice Fiscale Italiano (CF)
LU	48	Número de Identificação Nacional de Luxemburgo (Matricule)
MX	2	CURP Mexicano
MX	25	RFC Mexicano (Pessoa Física)
MX	58	Carteira de motorista Mexicana (Licencia de Conducir)
NG	8	NIN Nigeriano
NG	20	Número de Verificação Bancária Nigeriano (BVN)
NG	43	Token de BVN Nigeriano (hash)
NG	44	Token de NIN Nigeriano (hash)
NL	42	Número de Serviço ao Cidadão Holandês (BSN)
NO	39	Número de Identidade Nacional Norueguês (Fødselsnummer)
PE	27	RUC Peruano
PE	40	DNI Peruano
PE	54	Passaporte Peruano
PL	31	PESEL Polonês
PT	45	Número de Identificação Fiscal Português (NIF)
SE	32	Número Pessoal Sueco (PNR)
SE	38	Número de Coordenação Sueco (Samordningsnummer)
TR	24	Número de Identificação Turco (TCKN)
US	4	SSN dos Estados Unidos
US	11	Passaporte dos Estados Unidos
US	18	Carteira de motorista dos Estados Unidos
US	21	Cartão de Passaporte dos Estados Unidos
US	22	Passaporte de Policarbonato dos Estados Unidos
US	23	Carteira de Identidade dos Estados Unidos
UY	13	CI Uruguaia
ZZ	15	Endereço de e-mail
ZZ	17	Número de telefone
—	0	Não especificado
—	3	Identificador interno Unico

Exemplo

Nova captura — cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": 1,
      "code": "12345678909",
      "name": "Luke Skywalker"
    },
    "document": {
      "purpose": "onboarding",
      "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
      "files": [
        { "data": "/9j/4AAQSkZJR..." }
      ]
    }
  }'

Nova captura — Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 1,
      code: '12345678909',
      name: 'Luke Skywalker'
    },
    document: {
      purpose: 'onboarding',
      authProcessId: '80371b2a-3ac7-432e-866d-57fe37896ac6',
      files: [{ data: documentImageBase64 }]
    }
  })
});

const result = await res.json();

Reutilização — cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": 1,
      "code": "12345678909"
    },
    "document": {
      "purpose": "onboarding",
      "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
      "documentId": "doc-abc-123"
    }
  }'

Reutilização — Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 1,
      code: '12345678909'
    },
    document: {
      purpose: 'onboarding',
      authProcessId: '80371b2a-3ac7-432e-866d-57fe37896ac6',
      documentId: 'doc-abc-123'
    }
  })
});

const result = await res.json();

Respostas

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "document": {
    "id": "doc-abc-123",
    "type": "unico.moja.dictionary.br.cnh.v2.Cnh",
    "cpfMatch": true,
    "faceMatch": true,
    "content": {
      "numero": "12345678",
      "nomeCivil": "Luke Skywalker",
      "dataNascimento": "2000-05-20T00:00:00Z",
      "categoria": "B",
      "dataExpiracao": "2030-05-20T00:00:00Z"
    },
    "fileUrls": [
      "https://storage.unico.app/documents/doc-abc-123/front.jpg"
    ]
  }
}

Campo	Tipo	Descrição
id	string (UUID)	Identificador do processo.
status	integer	3 (finalizado com sucesso), 5 (finalizado com falha).
document.id	string	Identificador do documento capturado. Use este valor em futuras requisições com document.documentId para reutilização.
document.type	string	Tipo de documento identificado, como nome de dicionário totalmente qualificado. Veja os valores de document.type abaixo.
document.cpfMatch	boolean	true se o identificador extraído do documento corresponde a subject.code.
document.faceMatch	boolean	true se a foto do documento corresponde à selfie biométrica de document.authProcessId.
document.content	object	Campos extraídos via OCR. A estrutura varia conforme o tipo de documento — clique aqui para detalhes dos campos.
document.fileUrls	array	URLs temporárias (validade de 10 minutos) para download das imagens do documento.

Apenas os campos extraídos com sucesso estão presentes em document.content; o que o OCR não conseguiu ler é omitido em vez de retornado vazio.

Valores de document.type

Schema unificado

Todos os tipos de documento que usam o schema unificado — unified_schema na referência de campos — são reportados em document.type como unico.moja.dictionary.<country>.generic.v1.<DocumentType>, onde <country> é o código ISO 3166-1 alpha-2 em minúsculas e <DocumentType> é o tipo identificado. Por exemplo:

• unico.moja.dictionary.ar.generic.v1.IdCard: Documento de identidade argentino
• unico.moja.dictionary.us.generic.v1.PolycarbonatePassport: Passaporte de policarbonato dos EUA

Schemas específicos

Os tipos de documento que usam o próprio schema de campos — listados em specific_document_schemas na referência de campos — são mostrados na tabela abaixo:

País	Valor	Documento
BR	unico.moja.dictionary.br.rg.v2.Rg	RG
BR	unico.moja.dictionary.br.cnh.v2.Cnh	CNH (carteira de habilitação)
BR	unico.moja.dictionary.br.cin.v1.Cin	CIN
BR	unico.moja.dictionary.br.passaporte.v1.Passaporte	Passaporte
MX	unico.moja.dictionary.mx.ine.v1.Ine	Credencial de eleitor INE
MX	unico.moja.dictionary.mx.lpc.v1.Lpc	Licencia para conducir (carteira de habilitação)
MX	unico.moja.dictionary.mx.pasaporte.v1.Pasaporte	Passaporte
—	unico.moja.dictionary.other.unknown.v1.Unknown	O tipo não pôde ser identificado — document.content está vazio

Nenhuma extração de OCR é realizada e nenhum campo é reportado quando document.type é unico.moja.dictionary.other.unknown.v1.Unknown.

Códigos de Erro

400 Bad Request

Código	Mensagem	Descrição
99989	The document is invalid.	O objeto document possui uma estrutura inválida.
99988	The document is empty.	O objeto document está ausente no body da requisição.
20900	O base64 informado não é válido.	O parâmetro base64 é inválido. Possíveis causas: não é uma imagem ou é uma tentativa de injeção.
20807	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	A resolução da imagem enviada está abaixo do mínimo.
20509	The subject.name field is invalid.	subject.name contém caracteres inválidos.
20508	The subject.gender field is invalid.	subject.gender deve ser M ou F.
20507	O parâmetro subject.code é inválido.	Valor de identificador não padrão ou inexistente.
20506	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	Tamanho da imagem excede 800 KB; comprima em JPEG92.
20505	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	O formato base64 é inválido ou não suportado.
20068	The document.documentId or document.files parameter must be present.	Nem document.documentId nem document.files foram fornecidos.
20067	The document.purpose parameter is invalid.	Valor não reconhecido em document.purpose.
20066	The document.authProcessId parameter is invalid.	Valor inválido em document.authProcessId.
20062	The useCase field is invalid.	Valor não reconhecido no campo useCase.
20021	The subject.phone field is invalid.	Formato de subject.phone inválido (DDI + DDD + número, 13 caracteres).
20019	The subject.birthDate field is invalid.	subject.birthDate fora do formato ISO 8601 (YYYY-MM-DD).
20009	O parâmetro imagebase64 não foi informado.	O parâmetro de imagem do documento está ausente.
20008	The subject.email field is invalid.	Formato de e-mail inválido em subject.email.
20005	O parâmetro subject.code não foi informado.	O parâmetro subject.code está ausente.
20004	O parâmetro subject não foi informado.	O parâmetro subject está ausente.
20003	The request body is missing or invalid.	Payload nulo ou inválido.
20002	O parâmetro APIKey não foi informado.	O parâmetro APIKEY está ausente no header da requisição.
20001	O parâmetro authtoken não foi informado.	O parâmetro de token de integração está ausente no header da requisição.
10508	The JWT with the captured face has already been used.	O JWT só pode ser usado uma vez.
10507	The JWT with the captured face is expired.	JWT expirado; deve ser enviado dentro de 10 minutos.
10506	The imageBase64 field is not a valid JWT from SDK.	O imageBase64 não é um JWT válido gerado pelo SDK.

403 Forbidden

Bearer token ou APIKEY ausente, expirado ou inválido. Consulte Autenticação.

Código	Mensagem	Descrição
30017	User does not have permission to perform this action.	JWT malformado ou usuário sem permissão para realizar esta operação.
10502	O token informado está expirado.	O access-token expirou.
10501	O token informado é inválido.	O token de autenticação é inválido.
10201	O AppKey informado é inválido.	A APIKEY é inválida ou não existe.

409 Conflict

Código	Mensagem	Descrição
20073	The processID already exists.	O processId informado já existe para este tenant.

500 Internal Server Error

Código	Mensagem	Descrição
99999	Internal failure! Try again later	Quando ocorre um erro interno.

Próximos passos

• Para verificar se um documento já está disponível antes desta chamada, consulte Obter Documentos Reutilizáveis.
• Para criação do processo biométrico (necessário para document.authProcessId), consulte Criar Processo.