> 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/credit-services/credit-history.md). # Histórico de crédito Consulte o **histórico de crédito** de uma pessoa nos **birôs de crédito da Nigéria** a partir do seu BVN e retorna o perfil de crédito do titular, incluindo o **resumo de empréstimos** e seu desempenho. ### Endpoint ``` POST /kyc/nga/credit-history/{provider} ``` ### Autenticação | Tipo | Localização | Nome | | ------- | ----------- | ------------- | | API Key | Cabeçalho | **x-api-key** | ### Parâmetros de rota | Parâmetro | Tipo | Obrigatório | Descrição | | ---------- | ------ | ----------- | ----------------------------------------------------------------------------------------------- | | `provider` | string | **Sim** | Birô de crédito a consultar. Valores possíveis: `crc`, `xds`, `all` (consulta **ambos** birôs). | ### Corpo da solicitação **Content-Type:** `application/json` #### Parâmetros | Parâmetro | Tipo | Obrigatório | Descrição | | --------- | ------ | ----------- | ------------------------------------------------------ | | `bvn` | string | **Sim** | Bank Verification Number de **11 dígitos** do titular. | #### Exemplo de solicitação ``` POST /kyc/nga/credit-history/all ``` ```json { "bvn": "12345678901" } ``` ### 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 [Service Result Code](#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 o perfil de crédito do titular. Veja a tabela abaixo. | #### Parâmetros de resposta — `data` **Nota:** o objeto `data` é retornado **sem mapeamento nem normalização de campos**. O perfil do titular e o histórico de crédito são **únicos** (consolidados), não um bloco por birô. | Parâmetro | Tipo | Descrição | | ---------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `providers` | array | Lista de **birôs que retornaram informações**, como um array de strings. Valores possíveis: `crc`, `xds`. Ao consultar um único birô, contém apenas esse valor. | | `profile` | object | **Perfil do titular** (único). Veja a tabela abaixo. | | `credit_history` | array | **Histórico de crédito** agrupado por instituição financeira. Veja a tabela abaixo. | #### Parâmetros de resposta — `profile` | Parâmetro | Tipo | Descrição | | ----------------- | ------ | ------------------------------------------------------------------------------------------------------ | | `full_name` | string | Nome completo do titular. | | `date_of_birth` | string | Data de nascimento. | | `gender` | string | Gênero, em minúsculas. Ex.: `male`, `female` | | `address_history` | array | Endereços informados. Cada elemento contém `address`, `type` e `date_reported`. | | `email_address` | array | E-mails cadastrados (array de strings). | | `phone_number` | array | Números de telefone cadastrados (array de strings). | | `identifications` | array | Identificações do titular. Cada elemento contém `não` (número) e `type` (ex.: `BVN`, `NIN`, `PENCOM`). | #### Parâmetros de resposta — `credit_history[]` | Parâmetro | Tipo | Descrição | | ------------- | ------ | ----------------------------------------------------------------------- | | `institution` | string | Instituição financeira que reportou os empréstimos. | | `history` | array | Lista de empréstimos informados pela instituição. Veja a tabela abaixo. | #### Parâmetros de resposta — `history[]` | Parâmetro | Tipo | Descrição | | --------------------- | ------ | ----------------------------------------------------------------- | | `date_opened` | string | Data de abertura do empréstimo. | | `closed_date` | string | Data de fechamento do empréstimo. | | `currency` | string | Moeda do empréstimo. Ex.: `NGN` | | `institution` | string | Instituição financeira (repete-se dentro de cada empréstimo). | | `loan_status` | string | Status do empréstimo. Ex.: `open`, `closed` | | `opening_balance` | number | Valor de abertura do empréstimo. | | `performance_status` | string | Desempenho do empréstimo. Ex.: `performing` | | `repayment_amount` | number | Valor da parcela de pagamento. | | `repayment_frequency` | string | Frequência de pagamento. Ex.: `monthly` | | `repayment_schedule` | array | Cronograma de pagamentos. Cada elemento contém `date` e `status`. | | `tenor` | number | Prazo do empréstimo (em meses). | #### Service Result Code 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 ```json { "serviceResultCode": 200, "serviceTime": "2400", "serviceResultLog": "Success", "serviceTransactionId": "e41h235i-34i2-1h3l-h86h-2i681hj22jk", "data": { "credit_history": [ { "institution": "GUARANTY TRUST BANK PLC", "history": [ { "date_opened": "09-05-2019", "closed_date": "25-10-2020", "currency": "NGN", "institution": "GUARANTY TRUST BANK PLC", "loan_status": "closed", "opening_balance": 2009930, "performance_status": "performing", "repayment_amount": 0, "repayment_frequency": "monthly", "repayment_schedule": [ { "date": "01-06-2019", "status": "performing" } ], "tenor": 12 } ] } ], "profile": { "full_name": "JOHN PAUL DOE", "date_of_birth": "15-01-1990", "gender": "male", "address_history": [ { "address": "12 SAMPLE STREET, IKEJA, LAGOS", "type": "residential", "date_reported": "30-11-2021" } ], "email_address": [ "john.doe@example.com" ], "phone_number": [ "08012345678" ], "identifications": [ { "no": "12345678901", "type": "BVN" }, { "no": "09876543212", "type": "NIN" } ] }, "providers": ["crc", "xds"] } } ``` #### `400` Bad Request É retornado quando o `provider` indicado **não é válido**. Nesse caso, a resposta usa o formato `application/problem+json`, já que a validação ocorre **antes** antes de processar a consulta: ```json { "status": 400, "title": "Requisição inválida", "detail": "Solicitação inválida.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400", "errors": [ "provider must be one of: crc, xds, all" ] } ``` Quando a solicitação contém dados incorretos para a consulta, o erro é retornado com o envelope do serviço (`serviceResultCode` reflete o código HTTP da resposta): ```json { "serviceResultCode": 400, "serviceResultLog": "Sorry, lookup failed. Please check the details and try again", "serviceTime": "151", "serviceTransactionId": "08ac9699-dc9e-4cdc-81d7-264f71838309" } ``` #### `502` Bad Gateway É retornado quando o serviço não está temporariamente disponí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": "Service temporarily unavailable. Please try again later", "serviceTime": "3000", "serviceTransactionId": "38de2932-0f2h-7gff-14g0-597h04161632" } ``` #### `504` Gateway Timeout Erro de **timeout**, retornado com o envelope do serviço: ```json { "serviceResultCode": 504, "serviceResultLog": "Request timeout. Please try again", "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 obter detalhes das três formas de resposta. {% endhint %}