Saltar para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt

Use this file to discover all available pages before exploring further.

Este documento irá apresentar uma descrição da integração da API de verificação dos três elementos do cartão bancário, que pode ser utilizada para verificar a autenticidade e a consistência das informações do número do cartão bancário, nome e número do documento de abertura.

​
Processo de Solicitação

Para usar a API, é necessário primeiro acessar a página correspondente da API de Verificação dos Três Elementos do Cartão Bancário e solicitar o serviço correspondente. Após entrar na página, clique no botão “Adquirir”, como mostrado na imagem: Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, convidando-o a se registrar e fazer login. Após o registro e login, você será redirecionado de volta para a página atual. Na primeira solicitação, haverá um limite gratuito disponível, permitindo o uso gratuito da API.

​
Uso Básico

Primeiro, entenda a forma básica de uso, que é inserir as informações do número do cartão bancário para obter a imagem do resultado processado. Primeiro, é necessário passar um campo bank_card. Em seguida, podemos preencher o conteúdo correspondente na interface, como mostrado na imagem:

Podemos ver que aqui configuramos os Headers da Requisição, incluindo:
  • accept: o formato de resposta desejado, aqui preenchido como application/json, ou seja, formato JSON.
  • authorization: a chave para chamar a API, que pode ser selecionada diretamente após a solicitação.
Além disso, configuramos o Corpo da Requisição, incluindo:
  • bank_card: as informações do número do cartão bancário a serem processadas, é um parâmetro obrigatório.
  • id_card: o número do documento de abertura, é um parâmetro obrigatório.
  • name: o nome do usuário, é um parâmetro obrigatório.
  • cert_type: o tipo de documento de abertura, deve ser consistente com o documento de abertura, caso contrário, não será possível verificar.
  • encryption: opcional, parâmetro de criptografia de campos sensíveis (caso precise enviar dados criptografados).
Após a seleção, podemos ver que o código correspondente também foi gerado à direita, como mostrado na imagem:

Clique no botão “Tentar” para realizar o teste, como mostrado na imagem acima, e aqui obtemos o seguinte resultado: 
{
  "result": "0",
  "description": "Autenticação aprovada"
}
O resultado retornado possui vários campos, descritos a seguir:
  • result, código do resultado da autenticação, a situação de cobrança é a seguinte.
    • Códigos de resultado de cobrança:
      • 0: Autenticação aprovada
      • -1: Autenticação não aprovada
      • -4: Informações do portador do cartão incorretas
      • -5: Pagamento sem cartão não ativado
      • -6: Este cartão foi confiscado
      • -7: Número do cartão inválido
      • -8: Este cartão não possui banco emissor correspondente
      • -9: Este cartão não foi inicializado ou é um cartão inativo
      • -10: Cartão fraudulento, cartão retido
      • -11: Este cartão foi perdido
      • -12: Este cartão está expirado
      • -13: Cartão restrito
      • -14: Número de tentativas de senha excedido
      • -15: O banco emissor não suporta esta transação
    • Códigos de resultado sem cobrança:
      • -2: Verificação de nome não aprovada
      • -3: Número do cartão bancário incorreto
      • -16: Serviço do centro de verificação ocupado
      • -17: Número de tentativas de verificação excedido, por favor, tente novamente no dia seguinte
  • description, descrição do resultado do negócio.
Pode-se ver que a autenticidade e a consistência das informações do número do cartão bancário, nome e número do documento de abertura foram aprovadas. Além disso, se você quiser gerar o código de integração correspondente, pode copiá-lo diretamente, por exemplo, o código CURL é o seguinte: 
curl -X POST 'https://api.xhuoapi.ai/v1/identity/bankcard/check-3e' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "name": "***",
  "bank_card": "***",
  "id_card": "***"
}'
O código de integração em Python é o seguinte: 
import requests

url = "https://api.xhuoapi.ai/v1/identity/bankcard/check-3e"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "name": "***",
    "bank_card": "***",
    "id_card": "***"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

​
Tratamento de Erros

Ao chamar a API, se ocorrer um erro, a API retornará o código de erro e a informação correspondente. Por exemplo:
  • 400 token_mismatched: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
  • 400 api_not_implemented: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
  • 401 invalid_token: Não autorizado, token de autorização inválido ou ausente.
  • 429 too_many_requests: Muitas solicitações, você excedeu o limite de taxa.
  • 500 api_error: Erro interno do servidor, algo deu errado no servidor.

​
Exemplo de Resposta de Erro

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "falha na busca"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
Conclusão

Através deste documento, você já entendeu como usar a API de verificação dos três elementos do cartão bancário para verificar a autenticidade e a consistência das informações do número do cartão bancário, nome e número do documento de abertura. Esperamos que este documento possa ajudá-lo a integrar e usar melhor a API. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico.