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

Campo	Tipo	Obrigatório	Descrição
subject.duiType	string	sim	Tipo de identificador. Valores possíveis: DUI_TYPE_BR_CPF, DUI_TYPE_MX_CURP, DUI_TYPE_US_SSN, DUI_TYPE_NG_NIN, DUI_TYPE_AR_DNI, DUI_TYPE_ID_NIK.
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	string	sim	Tipo de identificador. Valores possíveis: DUI_TYPE_BR_CPF, DUI_TYPE_MX_CURP, DUI_TYPE_US_SSN, DUI_TYPE_NG_NIN, DUI_TYPE_AR_DNI, DUI_TYPE_ID_NIK.
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.

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": "DUI_TYPE_BR_CPF",
      "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: 'DUI_TYPE_BR_CPF',
      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": "DUI_TYPE_BR_CPF",
      "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: 'DUI_TYPE_BR_CPF',
      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. Valores possíveis: unico.moja.dictionary.br.rg.v2.Rg, unico.moja.dictionary.br.cnh.v2.Cnh, unico.moja.dictionary.br.cin.v1.Cin, unico.moja.dictionary.br.passaporte.v1.Passaporte.
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 — consulte abaixo.
document.fileUrls	array	URLs temporárias (validade de 10 minutos) para download das imagens do documento.

400 Bad Request

Payload malformado, imagem inválida ou campos obrigatórios ausentes. Consulte Códigos de Erro abaixo.

403 Forbidden

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

409 Conflict

O processId informado já existe para este tenant. Consulte Códigos de Erro abaixo.

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

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.