Saltar al contenido principal

Ejemplos de Respuesta de Callback

La sección de Ejemplos de Respuesta de Callback ofrece a los usuarios una vista previa de las respuestas anticipadas que recibirán de las interacciones con la API, ayudando a comprender la estructura y formato de la respuesta. Al aprovechar estos ejemplos, los desarrolladores pueden mejorar su proceso de integración y optimizar los esfuerzos de desarrollo, garantizando una comunicación fluida entre su aplicación y la API. Esta sección sirve como un recurso valioso para probar y refinar integraciones de manera efectiva.

Descripción General

Al usar la API de Global ID Recognition con una URL de callback, el sistema procesa la solicitud de forma asíncrona y envía los resultados a su endpoint de callback especificado. Este enfoque es ideal para el procesamiento por lotes o cuando necesita manejar múltiples solicitudes sin bloquear su aplicación.

Estructura de la Respuesta

La respuesta de callback contiene los siguientes componentes clave:
  • statusCode: Código de estado HTTP que indica el resultado
  • apiType: Identificador del tipo de API (“id_recognition”)
  • transactionId: Identificador único para el seguimiento de la solicitud
  • result: Objeto que contiene resultados detallados de reconocimiento
    • data: Objeto que contiene los datos extraídos
      • raw: Datos OCR sin procesar e información de coordenadas
        • Cada campo (address, name, number, etc.) puede incluir coordinates y original_coordinates
        • coordinates: Información de coordenadas relativa a la imagen procesada
        • original_coordinates: Información de coordenadas relativa a la imagen original cuando se tomó la foto de la identificación (opcional)
      • ocr: Datos OCR estructurados definidos por Argos

Respuesta de Ejemplo para éxito

{
  "statusCode": 200,
  "apiType": "id_recognition",
  "result": {
    "data": {
      "raw": {
        "address": {
          "value": "ADDRESS 110, SOMEWHERE STREET",
          "score": 89,
          "coordinates": {
            "first": {
              "x": 95,
              "y": 221
            },
            "fourth": {
              "x": 95,
              "y": 258
            },
            "second": {
              "x": 430,
              "y": 221
            },
            "third": {
              "x": 430,
              "y": 258
            }
          },
          "original_coordinates": {
            "first": {
              "x": 211,
              "y": 714
            },
            "fourth": {
              "x": 213,
              "y": 752
            },
            "second": {
              "x": 553,
              "y": 713
            },
            "third": {
              "x": 554,
              "y": 751
            }
          }
        },
        "authority": {
          "value": "{{value}}",
          "score": 4,
          "coordinates": {
            "first": {
              "x": 796,
              "y": 1460
            },
            "fourth": {
              "x": 799,
              "y": 1637
            },
            "second": {
              "x": 1931,
              "y": 1461
            },
            "third": {
              "x": 1925,
              "y": 1641
            }
          }
        },
        "name": {
          "value": "{{value}}",
          "score": 61,
          "coordinates": {
            "first": {
              "x": 367,
              "y": 462
            },
            "fourth": {
              "x": 375,
              "y": 669
            },
            "second": {
              "x": 1379,
              "y": 454
            },
            "third": {
              "x": 1378,
              "y": 663
            }
          }
        },
        "name_chn": {
          "value": "{{value}}",
          "score": 61,
          "coordinates": {
            "first": {
              "x": 367,
              "y": 462
            },
            "fourth": {
              "x": 375,
              "y": 669
            },
            "second": {
              "x": 1379,
              "y": 454
            },
            "third": {
              "x": 1378,
              "y": 663
            }
          }
        },
        "number": {
          "value": "{{value}}",
          "score": 95,
          "accepted": true,
          "coordinates": {
            "first": {
              "x": 248,
              "y": 698
            },
            "fourth": {
              "x": 256,
              "y": 867
            },
            "second": {
              "x": 1423,
              "y": 691
            },
            "third": {
              "x": 1421,
              "y": 861
            }
          }
        },
        "rotate": {
          "value": "0"
        }
      },
      "ocr": {
        "ocr_fullName": "{{ocr_fullName}}",
        "ocr_firstName": "{{ocr_firstName}}",
        "ocr_middleName": "{{ocr_middleName}}",
        "ocr_lastName": "{{ocr_lastName}}",
        "ocr_gender": "{{ocr_gender}}",
        "ocr_nationality": "{{ocr_nationality}}",
        "ocr_birthDate": "{{ocr_birthDate}}",
        "ocr_identityNumber": "{{ocr_identityNumber}}",
        "ocr_issueDate": "{{ocr_issueDate}}",
        "ocr_expireDate": "{{ocr_expireDate}}",
        "ocr_version": "{{ocr_version}}",
        "ocr_number": "{{ocr_number}}",
        "full_mrz": "{{full_mrz}}",
        "mrz_line1": "{{mrz_line1}}",
        "mrz_line2": "{{mrz_line2}}"
      }
    },
    "review_front": true,
    "review_back": false,
    "document_type": "{{document_type}}"
  },
  "transactionId": "e0nvom3caiis7"
}

Respuesta de Ejemplo para error

{
  "statusCode": 400,
  "apiType": "id_recognition",
  "transactionId": "{{transactionId}}",
  "errorCode": "1011",
  "message": "Fail to recognize idCard"
}

Directrices de Integración

  1. Configure su endpoint de callback para recibir solicitudes POST
  2. Valide el transactionId para asegurarse de que está procesando la respuesta correcta
  3. Verifique el statusCode para determinar si la solicitud fue exitosa
  4. Analice el objeto result para extraer información del documento y personal
  5. Maneje errores con elegancia verificando los objetos de error en la respuesta

Mejores Prácticas

  • Implemente idempotencia usando el transactionId para evitar procesamiento duplicado
  • Establezca tiempos de espera apropiados para su endpoint de callback
  • Registre todas las respuestas para depuración y monitoreo
  • Valide la estructura de la respuesta antes de procesar los datos
  • Maneje errores de red e implemente lógica de reintentos si es necesario
  • Almacene los datos extraídos de forma segura siguiendo las regulaciones de protección de datos