Sandbox y Datos de Prueba

El sandbox es una copia completa del pipeline de verificación con sus propias credenciales y sus propios datos. Úselo para construir y validar su integración antes de que un cliente real la utilice.

Acceso

Las credenciales de sandbox y de producción nunca son intercambiables, y una verificación en sandbox nunca es una base válida para una decisión real de onboarding.

Dos Formas de Obtener un Resultado

El sandbox realiza análisis real de documentos por defecto — el mismo pipeline de extracción, autenticidad, prueba de vida y coincidencia facial que producción. Envíe imágenes y el resultado sale de ellas: una captura borrosa falla de verdad, un documento vencido se rechaza de verdad.

También acepta un número de documento reservado que dicta todo el resultado de la verificación, como funciona un número de tarjeta de prueba en pagos. Envíe uno en prefill.documentNumber y la sesión se finaliza en la creación con un resultado completo — sin imágenes, sin cámara, sin llamada a proveedor. Consulte Resultados de Verificación Simulados.

Cuál usar:

Cada resultado incluye un campo provider:

Valor	Significado
"inyo"	Un análisis real produjo este resultado
"inyo-simulated"	Un número de documento reservado lo dictó

"inyo-simulated" nunca aparece en producción.

Resultados de Verificación Simulados

Envíe un número reservado en prefill.documentNumber y la sesión se finaliza en la creación con un resultado completo. Cada valor nombra un escenario: una línea base limpia, o esa misma línea con una verificación desviándose.

capture_exhausted es la excepción a ambas mitades de esa frase — vea su fila más abajo.

curl --request POST \
  --url https://{FQDN}/v1/sessions \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "userRef": "user-123",
    "prefill": {
      "firstName": "Ada", "lastName": "Lovelace", "dateOfBirth": "1990-04-17",
      "documentType": "drivers_license", "documentNumber": "99900104",
      "issuingCountry": "USA", "issuingState": "PA"
    }
  }'

La respuesta ya viene con "status": "completed", y document_authentic ha fallado.

El catálogo

Cada tipo alcanza los ocho escenarios. Envíe el número con el documentType y la jurisdicción indicados — un valor reservado se reconoce por ese par exacto.

Envíe issuingCountry: "USA". Un valor de pasaporte o de cédula de identidad solo se reconoce cuando se nombra el país, y nada le avisa cuando falta: el número se trata como uno ordinario, la sesión queda pendiente y espera una captura que nunca llega. Una licencia también se reconoce solo por issuingState, pero envíe ambos.

capture_exhausted modela a un titular que agotó los intentos, así que es el único escenario que no desvía una sola verificación: la captura no produjo nada, toda verificación que dependía de ella queda sin evaluar, y la sesión termina failed en lugar de completed, sin decisión alguna.

El nombre del escenario es el mismo token que la sesión registra y por el que filtra la consola operativa — un solo vocabulario para usted, su ejecutivo de cuenta y el analista que revisa la sesión.

Una desviación es una verificación, no una decisión. Lo que cada valor fija es qué verificación falla; la decisión se deriva de la puntuación y el modo de decisionamiento de su tenant, y bajo decisionamiento no gestionado no existe campo decision alguno. Lea el resultado en lugar de asumir el objetivo.

Qué hace distinto una sesión simulada

Dos rechazos que encontrará

Ambos son 422 en la creación de la sesión, y ambos son deliberados — un resultado dictado que su cuenta no habría podido producir le enseñaría a su código a esperar un estado que nunca verá en producción.

Solo sandbox. Estos valores se arman por entorno. Si uno devuelve un veredicto ordinario y la sesión queda esperando una captura, pida a su contacto en Inyo que habilite la simulación en su tenant de sandbox.

No son un fixture para su suite automatizada. Úselos mientras construye y comprueba una integración — a mano, o en una prueba que ejecute deliberadamente. Para una suite que corre en cada commit, capture uno de estos resultados una vez y reprodúzcalo desde su propio mock en lugar de llamarnos: sus pruebas se mantienen rápidas, siguen en verde cuando nuestro sandbox está caído, y no dependen de un entorno compartido que usted no controla.

El Validador de Número de Documento

Una superficie separada del catálogo anterior: verifica la forma de un número declarado y nunca mira una imagen ni ejecuta una verificación. Úselo cuando necesite un veredicto valid, no un resultado.

curl --request POST \
  --url https://{FQDN}/v1/validators/document-number \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"documentType": "drivers_license", "number": "not-a-number", "issuingCountry": "USA", "issuingState": "PA"}'

{
  "documentType": "drivers_license",
  "issuingCountry": "USA",
  "issuingState": "PA",
  "valid": false,
  "rule": "drivers_license:USA:PA",
  "detail": "document number does not match the PA license format"
}

Úselo para confirmar su manejo de los tres estados — true, false y null para una jurisdicción desconocida. Consulte Validador de Número de Documento.

Números de Documento de Prueba Reservados

Estos responden solo a la verificación de formato del número de documento. No son los valores que dictan una sesión — esos están en Resultados de Verificación Simulados. Todo valor listado en esta página que no esté en ese catálogo responde solo al validador.

La verificación de formato del número de documento acepta un pequeño conjunto de valores reservados que devuelven el veredicto elegido bajo demanda. Úselos cuando necesite un resultado valid específico — habitualmente desde la creación de remitente de remesas, que ejecuta esta verificación sobre todo documento declarado — sin tener que aprender antes el formato real de numeración de una jurisdicción.

Solo en sandbox. Estos valores se habilitan por entorno; si los valores de abajo devuelven un veredicto ordinario, pida a su contacto de Inyo que los habilite en su tenant de sandbox.

Todo tipo capturable publica los tres estados de valid, así que puede ejercitar su propio manejo por tipo sin aprender el formato real de numeración de una jurisdicción. ssn e itin traen solo un valor de aprobación — vea más abajo.

Las filas de identity_card son mexicanas porque no existe una regla para cédulas de identidad de EE. UU. — un valor estadounidense sería un caso de prueba para una verificación que no existe. La CURP codifica el nombre y la fecha de nacimiento del titular, así que el campo de nombre todo en X es estructuralmente válido y no puede colisionar con una persona real.

Por la misma razón, los valores de escenario de identity_card de EE. UU. del catálogo anterior devuelven valid: null en lugar de true: una cédula de identidad estadounidense no tiene regla de formato, así que document_number_valid queda genuinamente sin evaluar para ella — armada o no. Todo otro valor de escenario devuelve el veredicto que le da la regla real de su jurisdicción.

Envíe cada número con el issuingCountry y el issuingState indicados. Un valor reservado se reconoce por ese par exacto, por lo que el mismo número bajo cualquier otra jurisdicción se valida con las reglas ordinarias.

curl --request POST \
  --url https://{FQDN}/v1/validators/document-number \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"documentType": "drivers_license", "number": "99900002", "issuingCountry": "USA", "issuingState": "PA"}'

{
  "documentType": "drivers_license",
  "issuingCountry": "USA",
  "issuingState": "PA",
  "valid": false,
  "rule": "reserved:drivers_license:PA:invalid",
  "detail": "reserved sandbox test value — simulated invalid verdict"
}

Un resultado simulado lleva la cabecera de respuesta X-Inyo-Simulated: true. Está presente solo cuando un valor reservado produjo el resultado, y ausente en caso contrario — incluso en producción, donde nunca aparece.

Los valores reservados son números reales y válidos en el formato de su jurisdicción. Esto es deliberado: significa que una regla de formato previa — como la que la creación de remitente de remesas aplica antes de llamar a esta verificación — deja pasar el valor en lugar de rechazarlo antes, que es justamente lo que permite que 99900002 llegue hasta nosotros y vuelva como false.

La consecuencia es que donde los valores reservados no están habilitados, devuelven el veredicto que les dan las reglas reales de formato — valid: true para todos los valores excepto el ITIN, que devuelve false, y los valores de cédula de identidad de EE. UU., que devuelven null porque no existe regla de formato para ellos. Un valor reservado nunca produce un resultado más estricto que un número ordinario, así que dejar uno en el código no es un riesgo de seguridad — pero deja de simular en silencio, así que no lleve ninguno a producción.

912891234 es el único valor que devuelve false con la simulación desactivada. No existe un espécimen de ITIN anulado como lo es 078-05-1120 para los SSN, así que proviene de un grupo que el IRS reserva para otros programas — la única forma de garantizar que nunca pertenecerá a una persona real. El costo es que una regla de formato previa más estricta puede rechazarlo antes de que llegue a esta verificación. Si eso ocurre de su lado, úselo directamente contra este endpoint en lugar de pasar por un llamador que pre-valida.

Pruebas de Entrega de Resultados

La entrega merece probarse por sí sola, independientemente de los resultados de verificación:

1. Verificación de firma — capture el cuerpo de un webhook real de sandbox y su X-Inyo-Signature, luego pruebe unitariamente su verificador contra esos bytes exactos. Agregue un caso que mute un byte del cuerpo y verifique el rechazo, y un caso que re-serialice el JSON parseado y verifique el rechazo. Esos dos casos detectan el error que rompe la mayoría de las integraciones. Después agregue tres que detectan los que solo encontrará más adelante: un t= vencido, fuera de su tolerancia; un encabezado que trae un v2= extra que su código no implementa (debe validar igual con v1); y un encabezado que repite v1= dos veces (debe rechazarse de plano, no resolverse eligiendo uno).
2. Comportamiento de reintentos — devuelva 500 desde su endpoint y confirme que ve hasta tres intentos, y luego nada.
3. Ordenamiento — reproduzca dos notificaciones almacenadas de una sesión fuera de orden y verifique que su handler conserva la que tiene el notifiedAt más alto.
4. Idempotencia — entregue el mismo resultado dos veces y verifique que su sistema no lo procesa por duplicado.

Los pasos 1, 3 y 4 no requieren ninguna llamada al sandbox una vez que haya capturado un payload real.

Antes de Salir a Producción

Próximos Pasos

• Primeros Pasos — el recorrido de extremo a extremo
• Recepción de Resultados — firmas, reintentos y ordenamiento