Criar Processo de Documento

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
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 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.

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

Exemplo

Nova captura — cURL
Nova captura — Node.js
Reutilização — cURL
Reutilização — Node.js

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..." }
      ]
    }
  }'

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();

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"
    }
  }'

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
403 Forbidden
409 Conflict
500 Internal Server Error

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.

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.

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

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.

Endpoint​

Requisição​

Exemplo​

Respostas​

Códigos de Erro​

Próximos passos​