Verificar TIN

Verifique o Número de Identificação Fiscal (TIN) da Nigéria e retorna os dados do contribuinte registrados perante a autoridade tributária.

Endpoint

POST /kyc/nga/tin

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
number	string	Sim	Tax Identification Number (TIN) do contribuinte. Formato: 12345678-0001.

Nota: o parâmetro channel (com valor TIN) o injeta automaticamente o serviço; não deve ser enviado na solicitação.

Exemplo de solicitação

{
  "number": "12345678-0001"
}

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
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 do contribuinte. Veja a tabela abaixo.

Parâmetros de resposta — data

Nota: o objeto data é retornado sem mapeamento nem normalização de campos.

Parâmetro	Tipo	Descrição
taxpayer_name	string	Nome cadastrado do contribuinte (pessoa física ou jurídica).
phone_number	string	Número de telefone registrado.
email	string	E-mail cadastrado.
tax_office	string	Escritório tributário atribuído ao contribuinte.
tin_type	string	Tipo de contribuinte associado ao TIN.
jittin	string	TIN do Joint Tax Board (JTB) do contribuinte.
firstin	string	TIN do Federal Inland Revenue Service (FIRS) do contribuinte.
cac_reg_number	string	Número de registro CAC da empresa (aplica-se a contribuintes empresariais).

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

{
  "serviceResultCode": 200,
  "serviceTime": "1300",
  "serviceResultLog": "Success",
  "serviceTransactionId": "g63j457k-56k4-3j5n-j08j-4k803jl44lm",
  "data": {
    "taxpayer_name": "ACME NIGERIA LIMITED",
    "phone_number": "08012345678",
    "email": "[email protected]",
    "tax_office": "MSTO IKEJA",
    "tin_type": "Non Individual",
    "jittin": "1234567890",
    "firstin": "12345678-0001",
    "cac_reg_number": "RC1234567"
  }
}

400 Bad Request

Erro retornado com o envelope do serviço (serviceResultCode reflete o código HTTP da resposta):

{
  "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:

{
  "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:

{
  "serviceResultCode": 504,
  "serviceResultLog": "Request timeout. Please try again",
  "serviceTime": "30000",
  "serviceTransactionId": "48ef3043-1g3i-8hgg-25h1-608i15272743"
}

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 para obter detalhes das três formas de resposta.