> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/api-rest/identity-api/identity-api-reference/onboarding/kyc/nigeria/identity-verification/nin-slip.md). # Comprovante NIN Verifique o **Número de Identificação Nacional** (NIN) da Nigéria, assim como [NIN Verify](/docs.facephi-pt-br/api-rest/identity-api/identity-api-reference/onboarding/kyc/nigeria/identity-verification/nin-verify.md) e, adicionalmente, gera uma **cópia em PDF do NIN slip** do titular. A geração do PDF é **assíncrona**: a resposta inicial inclui um objeto `pdf` com um `jobId` e o estado `processing`. O cliente deve consultar o estado do trabalho por meio do endpoint de consulta até que o estado seja `completed`, momento em que é retornada a **URL de download** do PDF. Observe que no **no Sandbox não é retornado** o campo `pdf`; aparece apenas no modo **live** (veja a nota abaixo). ### Endpoint ``` POST /kyc/nga/nin/slip ``` ### Autenticação | Tipo | Localização | Nome | | ------- | ----------- | ------------- | | API Key | Cabeçalho | **x-api-key** | ### Corpo da solicitação **Content-Type:** `application/json` #### Parâmetros | Parâmetro | Tipo | Obrigatório | Descrição | | --------- | ------ | ----------- | --------------------------------------------------- | | `nin` | string | **Sim** | Número de Identificação Nacional de **11 dígitos**. | #### Exemplo de solicitação ```json { "nin": "09876543212" } ``` ### Respostas #### `200` Sucesso #### Parâmetros de resposta | Parâmetro | Tipo | Descrição | | ---------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- | | `serviceResultCode` | integer | Código que indica o **resultado geral** da execução do serviço. Ver [Código de Resultado do Serviço](#service-result-code) | | `serviceTime` | string | Tempo de processamento **(milissegundos)**. | | `serviceResultLog` | string | Campo descritivo do resultado da execução do serviço. Inclui detalhes quando há um erro ou exceção no módulo. | | `serviceTransactionId` | string | Identificador de transação associado à solicitação processada pela API. | | `data` | object | Objeto com os dados completos do NIN e o estado de geração do PDF. Veja a tabela abaixo. | #### Parâmetros de resposta — `data` **Nota:** o objeto `data` é retornado **sem mapeamento nem normalização de campos**. Os nomes e a ortografia dos campos são mantidos exatamente como são recebidos. | Parâmetro | Tipo | Descrição | | ------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | `nin` | string | Número de Identificação Nacional. | | `title` | string | Título do titular. | | `firstname` | string | Nome(s) do titular. | | `middlename` | string | Nome do meio. | | `surname` | string | Sobrenome(s) do titular. | | `birthdate` | string | Data de nascimento. | | `birthcountry` | string | País de nascimento. | | `birthstate` | string | Estado de nascimento. | | `birthlga` | string | Área de Governo Local (LGA) de nascimento. | | `gender` | string | Gênero. | | `maritalstatus` | string | Estado civil. | | `heigth` | string | Altura em centímetros. O campo se chama literalmente `heigth` (sic): a ortografia é preservada exatamente como é recebida; não usar `height`. | | `email` | string | E-mail registrado. | | `telephoneno` | string | Número de telefone registrado. | | `residence_address` | string | Endereço de residência. | | `residence_state` | string | Estado de residência. | | `residence_lga` | string | Área de Governo Local (LGA) de residência. | | `residence_town` | string | Cidade de residência. | | `residencestatus` | string | Status de residência. | | `self_origin_state` | string | Estado de origem. | | `self_origin_lga` | string | Área de Governo Local (LGA) de origem. | | `self_origin_place` | string | Local de origem. | | `profession` | string | Profissão. | | `educationallevel` | string | Nível de escolaridade. | | `employmentstatus` | string | Situação de emprego. | | `religion` | string | Religião. | | `spoken_language` | string | Idioma principal falado. | | `ospokenlang` | string | Outro(s) idioma(s) falado(s). | | `nok_firstname` | string | Nome do **parente de contato** (parente próximo). | | `nok_middlename` | string | Segundo nome do parente de contato. | | `nok_surname` | string | Sobrenome do parente de contato. | | `nok_address1` | string | Endereço (linha 1) do parente de contato. | | `nok_address2` | string | Endereço (linha 2) do parente de contato. | | `nok_town` | string | Cidade do parente de contato. | | `nok_lga` | string | Área de Governo Local (LGA) do parente de contato. | | `nok_state` | string | Estado do parente de contato. | | `nok_postalcode` | string | Código postal do parente de contato. | | `pfirstname` | string | Nome anterior do titular (se existir; normalmente vazio). | | `pmiddlename` | string | Segundo nome anterior do titular (se existir; normalmente vazio). | | `psurname` | string | Sobrenome anterior do titular (se existir; normalmente vazio). | | `photo` | string | Foto do titular em formato **Base64**. | | `signature` | string | Assinatura do titular em formato **Base64**. | | `userid` | string | Identificador interno de usuário. | | `vnin` | string | NIN virtual (vNIN) do titular. | | `central_iD` | string | Identificador central do registro. O campo se chama literalmente `central_iD` (sic). | | `tracking_id` | string | Identificador de rastreamento do registro. | | `pdf` | object | Status de geração do **NIN slip em PDF**. Presente apenas no modo **live**. Veja a tabela abaixo. | #### Parâmetros de resposta — `data.pdf` | Parâmetro | Tipo | Descrição | | --------- | ------ | --------------------------------------------------------------------------------- | | `jobId` | string | Identificador do **trabalho de geração** do PDF. É usado para consultar o status. | | `status` | string | Status da geração. Valores possíveis: `processing`, `completed`. | **Nota:** em **no Sandbox não é retornado** o campo `pdf` (confirmado empiricamente em 13-07-2026); nesse caso não há `jobId` nada a consultar. No modo **live**, o objeto `pdf` (`jobId`, `status`) permite fazer *polling* do status por meio de `GET /kyc/nga/nin/slip/{jobId}`. Existem tenants de produção com credenciais live; a confirmação do ciclo completo do PDF em live requer uma consulta com um NIN real e será realizada como parte da validação de QA com um tenant live. #### Código de Resultado do Serviço O `serviceResultCode` indica o resultado geral da execução do serviço e reflete o **código de status HTTP** da resposta: | serviceResultCode | Descrição | Código HTTP | | ----------------- | -------------------------------------------------------------------------------------- | ----------- | | 200 | A execução do serviço foi bem-sucedida, o módulo processou a solicitação corretamente. | 200 | #### Exemplo de resposta (modo live) ```json { "serviceResultCode": 200, "serviceTime": "2100", "serviceResultLog": "Success", "serviceTransactionId": "b18e902f-01f9-8e0i-e53e-9f3589eg99gh", "data": { "nin": "09876543212", "title": "mr", "firstname": "JOHN", "middlename": "PAUL", "surname": "DOE", "birthdate": "15-01-1990", "birthcountry": "nigeria", "birthstate": "Lagos", "birthlga": "Lagos Island", "gender": "m", "maritalstatus": "single", "heigth": "175", "email": "john.doe@example.com", "telephoneno": "08012345678", "residence_address": "123 Main Street, Lagos", "residence_state": "Lagos", "residence_lga": "Ikeja", "residence_town": "Ikeja", "residencestatus": "birth", "self_origin_state": "Lagos", "self_origin_lga": "Lagos Island", "self_origin_place": "Lagos", "profession": "Engineer", "educationallevel": "tertiary", "employmentstatus": "employed", "religion": "christianity", "spoken_language": "YORUBA", "ospokenlang": "ENGLISH", "nok_firstname": "JANE", "nok_middlename": "", "nok_surname": "DOE", "nok_address1": "123 Main Street", "nok_address2": "", "nok_town": "Ikeja", "nok_lga": "Ikeja", "nok_state": "Lagos", "nok_postalcode": "100001", "pfirstname": "JOHN", "pmiddlename": "PAUL", "psurname": "DOE", "photo": "base64encodedphoto...", "signature": "base64encodedsignature...", "userid": "", "vnin": "AB012345678901234YZ", "central_iD": "12345678", "tracking_id": "ABC123DEF456GH", "pdf": { "jobId": "4", "status": "processing" } } } ``` ## Consultar status do PDF Consulte o **status do trabalho de geração** do NIN slip em PDF a partir do `jobId` obtido na resposta anterior. Recomenda-se consultar o status **a cada poucos segundos** até que seja `completed`. **Nota:** a URL de download do PDF **expira em 7 dias** após sua geração. Baixe e armazene o documento antes desse prazo. ### Endpoint ``` GET /kyc/nga/nin/slip/{jobId} ``` ### Autenticação | Tipo | Localização | Nome | | ------- | ----------- | ------------- | | API Key | Cabeçalho | **x-api-key** | ### Parâmetros de rota | Parâmetro | Tipo | Obrigatório | Descrição | | --------- | ------ | ----------- | ----------------------------------------------------------- | | `jobId` | string | **Sim** | **ID do trabalho** de geração obtido na resposta do `POST`. | ### Exemplo de solicitação ``` GET /kyc/nga/nin/slip/4 ``` ### Respostas #### `200` Sucesso #### Parâmetros de resposta — `data` | Parâmetro | Tipo | Descrição | | --------- | ------ | -------------------------------------------------------------------------------------------- | | `id` | string | Identificador do trabalho de geração. | | `status` | string | Status da geração. Valores possíveis: `processing`, `completed`. | | `url` | string | **URL de download** do PDF. Presente apenas quando `status` é `completed`. Expira em 7 dias. | #### Exemplo de resposta — em processamento ```json { "serviceResultCode": 200, "serviceTime": "120", "serviceResultLog": "Success", "serviceTransactionId": "c29f013g-12g0-9f1j-f64f-0g4690fh00hi", "data": { "id": "4", "status": "processing" } } ``` #### Exemplo de resposta — concluído ```json { "serviceResultCode": 200, "serviceTime": "110", "serviceResultLog": "Success", "serviceTransactionId": "d30g124h-23h1-0g2k-g75g-1h5701gi11ij", "data": { "id": "4", "status": "completed", "url": "https://files.example.com/nin-slips/4/nin-slip.pdf" } } ``` ## Respostas de erro Os seguintes erros se aplicam a **ambos endpoints**: #### `400` Requisição inválida Erro retornado com o envelope do serviço (`serviceResultCode` reflete o código HTTP da resposta): ```json { "serviceResultCode": 400, "serviceResultLog": "Desculpe, a consulta falhou. Verifique os dados e tente novamente", "serviceTime": "151", "serviceTransactionId": "08ac9699-dc9e-4cdc-81d7-264f71838309" } ``` #### `502` Gateway inválido É retornado quando o serviço está temporariamente indisponível ou sua resposta não pôde ser interpretada. O corpo usa o envelope do serviço com `serviceResultCode: 500`: ```json { "serviceResultCode": 500, "serviceResultLog": "Serviço temporariamente indisponível. Tente novamente mais tarde", "serviceTime": "3000", "serviceTransactionId": "38de2932-0f2h-7gff-14g0-597h04161632" } ``` #### `504` Tempo esgotado no gateway Erro de **Timeout**, retornado com o envelope do serviço: ```json { "serviceResultCode": 504, "serviceResultLog": "Timeout da solicitação. Tente novamente", "serviceTime": "30000", "serviceTransactionId": "48ef3043-1g3i-8hgg-25h1-608i15272743" } ``` {% hint style="info" %} Os erros de autenticação (`401`/`403`) são rejeitados pelo **gateway antes de chegar ao serviço** e **não** usam o envelope `serviceResultCode`. Os erros de validação da plataforma usam o formato `application/problem+json`. Consulte [Tratamento de erros](/docs.facephi-pt-br/api-rest/identity-api/identity-api-reference/onboarding/kyc/nigeria.md#manejo-de-errores) para ver os detalhes das três formas de resposta. {% endhint %}