# Onboarding

{% hint style="info" %}
**URL Base**:

* UAT: <mark style="color:blue;">`https://api.id.uat.unico.app`</mark>;
* Produção: <mark style="color:blue;">`https://api.id.unico.app`</mark>.
  {% endhint %}

{% hint style="success" %}
Abaixo você encontrará o endpoint para Onboarding no by Cilent com todas as capacidades habilitadas, mas também é possível utilizar as capacidades isoladamente (***exceto** score de similaridade da Serpro e Score de risco, que dependem do uso da Verificação de Identidade*).&#x20;

Entenda com o responsável pelo seu projeto quais capacidades habilitar para sua operação.
{% endhint %}

## Criar Processo de Onboarding

> Endpoint para criar um novo processo de Onboarding no by Client

```json
{"openapi":"3.0.0","info":{"title":"CreateProcess by Client","version":"1.0.0"},"servers":[{"url":"https://api.id.uat.unico.app"}],"paths":{"/processes/v1":{"post":{"summary":"Criar Processo de Onboarding","description":"Endpoint para criar um novo processo de Onboarding no by Client","parameters":[{"in":"header","name":"Authorization","required":true,"schema":{"type":"string"},"description":"Access-token válido."},{"in":"header","name":"APIKEY","required":true,"schema":{"type":"string"},"description":"APIKEY válida com as capacidades para uso do Onboarding."}],"requestBody":{"description":null,"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subject","imageBase64"],"properties":{"subject":{"type":"object","description":"Informações do usuário.","required":["code"],"properties":{"code":{"type":"string","description":"Identificador do usuário. Pode ser o CPF brasileiro ou o CURP mexicano. Deve ser enviado sem pontos ou traços."},"name":{"type":"string","description":"Nome do usuário."},"gender":{"type":"string","description":"Gênero do usuário. Valores possíveis: 'M' para homens ou 'F' para mulheres."},"birthDate":{"type":"string","description":"Data de nascimento do usuário. Deve estar no formato ISO 8601 (yyyy-MM-dd)."},"email":{"type":"string","description":"E-mail do usuário."},"phone":{"type":"string","description":"Telefone do usuário. Deve conter 13 caracteres e ser enviado sem pontos ou traços, no padrão DDI + DDD + Número de telefone."}}},"useCase":{"type":"string","description":"Caso de uso da operação."},"subsidiaryId":{"type":"string","description":"o ID da filial onde o processo será criado. Caso haja somente uma filial associada a conta de serviço, não há a necessidade de passar este parâmetro. Caso haja separação de processos por filial, você receberá os IDs das filiais do time Unico."},"imageBase64":{"type":"string","description":"Arquivo encrypted gerado pelo SDK ou base64 (caso não utilize a Prova de vida)."}}}}}},"responses":{"200":{"description":"Processo criado com sucesso.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"ID do processo."},"status":{"type":"integer","enum":[1,3,5],"description":"Status do processo. Valores possíveis: '1' - Em processamento (ocorre somente quando a resposta da Verificação de Identidade é inconclusiva e há orquestração com o Score de Risco); '3' - Concluído (ocorre quando a resposta da Verificação de Identidade é conclusiva - 'yes' ou 'no'); -  '5' - Erro (ocorre quando há algum erro no processamento)."},"unicoId":{"type":"object","description":"Informações sobre a verificação de identidade.","properties":{"result":{"type":"string","enum":["yes","no","inconclusive"],"description":"Resultado da verificação de identidade. Valores possíveis: 'yes' - É a face titular do CPF; 'no' - Não é a face titular do CPF; 'inconclusive' - Não conseguimos garantir com precisão se essa é a face titular do CPF."}}},"identityFraudsters":{"type":"object","description":"Informações sobre o alerta de comportamento.","properties":{"result":{"type":"enjum","enum":["yes","inconclusive"],"description":"Resultado do alerta de comportamento. Valores possíveis: 'yes' - A face já foi envolvida em alguma transação fraudulenta de identidade; 'inconclusive' - Não temos indícios que a face já foi envolvida em alguma transação fraudulenta de identidade."}}},"government":{"type":"object","description":"Informações sobre score de similardade da Serpro.","properties":{"serpro":{"type":"string","description":"Resultado do score de similaridade da Serpro. Quando a Serpro encontra a face, é devolvido em score de 0-100. Quando a Serpro não encontra a face, é devolvido o score -1. Quando há algum erro na integração com a Serpro, é devolvido o score -2."}}},"liveness":{"type":"integer","enum":[1,2],"description":"Resultado da prova de vida. Valores possíveis: '1' - Prova de vida aprovada; '2' - Prova de vida recusada."}}}}}},"400":{"description":"Bad Request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code."},"description":{"type":"string","description":"Error description."}}}}}}}},"403":{"description":"Forbidden.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code."},"description":{"type":"string","description":"Error description."}}}}}}}},"500":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code."},"description":{"type":"string","description":"Error description."}}}}}}}}}}}}}
```

{% hint style="warning" %}
**Pontos Importantes**:

* Para utilizar a capacidade Prova de vida, é indispensável o uso dos nossos SDKs:
  * É possível utilizar a capacidade de Verificação de Identidade sem a Prova de vida. Para este caso de uso o retorno de liveness sempre será `liveness = 1`. Neste cenário **não há nenhuma** validação da prova de vida, nem mesmo passiva.
* Caso a resposta da capacidade Verificação de Identidade seja `unicoId = yes/no`, este retorno já engloba a Prova de vida (o*u seja, não receberá o parâmetro `liveness` no response*) e não há a necessidade de realizar a requisição para Buscar o resultado do processo;
* Caso a resposta da capacidades Verificação de Identidade seja `inconclusive`, haverá a orquestração com a capacidade Score de risco;
* Caso ocorra algum erro no processamento, o processo retornará um `status = 5`, como no exemplo abaixo:

  ```json
    {
    "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
    "status": 5
    }
  ```

{% endhint %}

{% hint style="success" %}
**Dicas**:

* Para implementar suas regras de negócio, sempre valide os status finais dos processos (`3`,`5`). Para validar a resposta das capacidades IDCloud, só considere o `status` = `3` para sua tomada de decisão.
  {% endhint %}

### Erros

{% tabs %}
{% tab title="400 Bad Request" %}

<table><thead><tr><th width="110">code</th><th width="290">message</th><th>Descrição</th></tr></thead><tbody><tr><td><code>20900</code></td><td><code>O base64 informado não é válido.</code></td><td>O parâmetro base64 é inválido. Possíveis causas: Não é uma imagem ou é uma tentativa de injection.</td></tr><tr><td><code>20807</code></td><td><code>A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.</code></td><td>A resolução da imagem enviada é muito pequena.</td></tr><tr><td><code>20507</code></td><td><code>O parâmetro subject.code é inválido.</code></td><td>CPF fora do padrão ou inexistente.</td></tr><tr><td><code>20506</code></td><td><code>O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.</code></td><td>A imagem é muito grande. A imagem pode ser comprimida para JPEG92 sem perda de qualidade.</td></tr><tr><td><code>20505</code></td><td><code>O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.</code></td><td>Base64 inválido. Possíveis causas: não é uma imagem válida ou prefixo inválido.</td></tr><tr><td><code>20009</code></td><td><code>O parâmetro imagebase64 não foi informado.</code></td><td>Falta o parâmetro imagebase64, que contém a selfie da pessoa.</td></tr><tr><td><code>20006</code></td><td><code>O parâmetro subject.name não foi informado.</code></td><td>Falta o parâmetro subject.name, que contém o nome da pessoa.</td></tr><tr><td><code>20005</code></td><td><code>O parâmetro subject.code não foi informado.</code></td><td>Falta o parâmetro subject.code, que contém o cpf da pessoa.</td></tr><tr><td><code>20004</code></td><td><code>O parâmetro subject não foi informado.</code></td><td>Falta o parâmetro subject, que contém os dados da pessoa (cpf, nome).</td></tr><tr><td><code>20003</code></td><td><code>The request body is missing or invalid.</code></td><td>Payload nulo ou inválido.</td></tr><tr><td><code>20002</code></td><td><code>O parâmetro APIKey não foi informado.</code></td><td>Falta o parâmetro APIKEY no cabeçalho da requisição.</td></tr><tr><td><code>20001</code></td><td><code>O parâmetro authtoken não foi informado</code></td><td>Falta o parâmetro do token de integração no cabeçalho da requisição.</td></tr><tr><td><code>10508</code></td><td><code>The JWT with the captured face has already been used.</code></td><td>O .jwt só pode ser usado uma única vez.</td></tr><tr><td><code>10507</code></td><td><code>The JWT with the captured face is expired.</code></td><td>JWT expirado. O .jwt deve ser enviado em até 10 minutos.</td></tr><tr><td><code>10506</code></td><td><code>The bundle is invalid.</code></td><td>Bundle inválido. APIKEY usa um método de segurança e esta solicitação não atende aos requisitos de segurança (SDK).</td></tr></tbody></table>
{% endtab %}

{% tab title="403 Forbidden" %}

<table><thead><tr><th width="183">code</th><th>message</th><th>Descrição</th></tr></thead><tbody><tr><td><code>30017</code></td><td><code>Jwt header is an invalid JSON.</code></td><td>Quando o access-token utilizado contém caracteres errados.</td></tr><tr><td><code>10502</code></td><td><code>O token informado está expirado.</code></td><td>Quando o access-token utilizado expirou</td></tr><tr><td><code>10501</code></td><td><code>O token informado é inválido.</code></td><td>O token de autenticação é inválido.</td></tr><tr><td><code>10201</code></td><td><code>O AppKey informado é inválido.</code></td><td>O parâmetro APIKEY não foi informado ou não existe.</td></tr></tbody></table>
{% endtab %}

{% tab title="500 Internal Server Error" %}

<table><thead><tr><th width="99">code</th><th width="299">message</th><th>Descrição</th></tr></thead><tbody><tr><td>99999</td><td><code>Internal failure! Try again later</code></td><td>Quando há algum erro interno.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

## Consultar Resultado do Processo

> Endpoint para buscar o resultado de um processo de Onboarding no by Client (específico para quando há orquestração com o Score de risco)

```json
{"openapi":"3.0.0","info":{"title":"Get Process Info","version":"1.0.0"},"servers":[{"url":"https://api.id.uat.unico.app"}],"paths":{"/processes/v1/{processId}":{"get":{"summary":"Consultar Resultado do Processo","description":"Endpoint para buscar o resultado de um processo de Onboarding no by Client (específico para quando há orquestração com o Score de risco)","parameters":[{"in":"header","name":"Authorization","required":true,"schema":{"type":"string"},"description":"Access-token válido."},{"in":"header","name":"APIKEY","required":true,"schema":{"type":"string"},"description":"APIKEY válida com as capacidades para uso do Onboarding."},{"name":"processId","in":"path","required":true,"description":"ID do processo.","schema":{"type":"string"}}],"responses":{"200":{"description":"Informações do processo obtidas com sucesso.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"ID do processo."},"status":{"type":"integer","enum":[1,2,3,4],"description":"Status do processo. Valores possíveis: '1' - Em processamento; '2' - Divergência (ocorre quando o Score de risco encontrou uma divergência para esta face e ainda irá concluir a verificação) '3' - Concluído; '4' - Cancelado (ex.: timeout); -  '5' - Erro."},"unicoId":{"type":"object","description":"Informações sobre a verificação de identidade.","properties":{"result":{"type":"string","enum":["yes","no","inconclusive"],"description":"Resultado da verificação de identidade. Valores possíveis: 'yes' - É a face titular do CPF; 'no' - Não é a face titular do CPF; 'inconclusive' - Não conseguimos garantir com precisão se essa é a face titular do CPF."}}},"identityFraudsters":{"type":"object","description":"Informações sobre o alerta de comportamento.","properties":{"result":{"type":"string","enum":["yes","inconclusive"],"description":"Resultado do alerta de comportamento. Valores possíveis: 'yes' - A face já foi envolvida em alguma transação fraudulenta de identidade; 'inconclusive' - Não temos indícios que a face já foi envolvida em alguma transação fraudulenta de identidade."}}},"score":{"type":"integer","description":"Resultado do score de risco."},"government":{"type":"object","description":"Informações sobre score de similardade da Serpro.","properties":{"serpro":{"type":"string","description":"Resultado do score de similaridade da Serpro. Quando a Serpro encontra a face, é devolvido em score de 0-100. Quando a Serpro não encontra a face, é devolvido o score -1. Quando há algum erro na integração com a Serpro, é devolvido o score -2."}}},"liveness":{"type":"integer","enum":[1,2],"description":"Resultado da prova de vida. Valores possíveis: '1' - Prova de vida aprovada; '2' - Prova de vida recusada."}}}}}},"400":{"description":"Bad Request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code."},"description":{"type":"string","description":"Error description."}}}}}}}},"403":{"description":"Forbidden.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code."},"description":{"type":"string","description":"Error description."}}}}}}}},"404":{"description":"Not Found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code."},"description":{"type":"string","description":"Error description."}}}}}}}},"410":{"description":"Gone.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Process ID."},"status":{"type":"integer","description":"Process status."}}}}}},"500":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code."},"description":{"type":"string","description":"Error description."}}}}}}}}}}}}}
```

{% hint style="danger" %}
**Atenção**:

* Quando a requisição `GET` for para um processo com `status = 5` (erro), o status code de retorno é `410` (Gone) ao invés de `200` (Success);
* Pode haver casos de drop na orquestração com a capacidade Score de risco. Neste cenário, o processo terá a combinação: {*`status = 3`, `unicoId = inconclusive`, `liveness = 1`, `identityFraudsters = inconclusive/yes` e **SEM** score no response da API*}. Entenda mais na seção Cenários de response;
* Caso consulte um processo que esteja no `status = 2`, implemente um polling até que obtenha um `status = 3` ou implemente o Webhook da Unico para saber quando consultar o resultado.
  {% endhint %}

{% hint style="success" %}
**Dicas**:

* **P**ara implementar suas regras de negócio, sempre valide os status finais dos processos (`3`,`4`,`5`). Para validar a resposta das capacidades IDCloud, só considere o `status` = `3` para sua tomada de decisão;
* Para melhorar a performance da sua operação, você pode utilizar nossos Webhooks e só consultar o resultado de processos que estiverem nos status finalizados;
* Para mais informações sobre os cenários que pode receber no response, consulte a seção Cenários de response.
  {% endhint %}

### Erros

{% tabs %}
{% tab title="400 Bad Request" %}

<table><thead><tr><th width="108">code</th><th width="310">message</th><th>Descrição</th></tr></thead><tbody><tr><td><code>20023</code></td><td><code>O parâmetro processId não foi informado.</code></td><td>Falta o parâmetro id do processo.</td></tr><tr><td><code>20002</code></td><td><code>O parâmetro APIKey não foi informado.</code></td><td>Falta o parâmetro APIKEY no header da requisição.</td></tr><tr><td><code>20001</code></td><td><code>O parâmetro authtoken não foi informado.</code></td><td>QFalta o parâmetro do token de integração no header da requisição.</td></tr></tbody></table>
{% endtab %}

{% tab title="404 Not Found" %}

<table><thead><tr><th width="150">code</th><th width="252">message</th><th>Descrição</th></tr></thead><tbody><tr><td><code>50001</code></td><td><code>O processo informado não foi encontrado.</code></td><td>O processo não existe na base de dados.</td></tr></tbody></table>
{% endtab %}

{% tab title="403 Forbidden" %}

<table><thead><tr><th width="182">code</th><th>message</th><th>Descrição</th></tr></thead><tbody><tr><td><code>30017</code></td><td><code>O usuário não tem permissão para executar está ação.</code></td><td>Quando o access-token utilizado contém caracteres errados.</td></tr><tr><td><code>10502</code></td><td><code>O token informado está expirado.</code></td><td>Quando o access-token utilizado expirou.</td></tr><tr><td><code>10501</code></td><td><code>O token informado é inválido.</code></td><td>O token de autenticação é inválido.</td></tr><tr><td><code>10201</code></td><td><code>O AppKey informado é inválido.</code></td><td>O parâmetro APIKEY não foi informado ou não existe.</td></tr></tbody></table>
{% endtab %}

{% tab title="410 Gone" %}

```json
  {
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 5
  }
```

{% endtab %}

{% tab title="500 Internal Server Error" %}

<table><thead><tr><th width="99">code</th><th width="299">message</th><th>Descrição</th></tr></thead><tbody><tr><td>99999</td><td><code>Internal failure! Try again later</code></td><td>Quando há algum erro interno.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://devcenter.unico.io/unico-idcloud/by-client-integration/pt/by-client-api/api-reference/onboarding.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.