VerikoDocs

Escribe para buscar. Enter abre el primer resultado.

EN

Consultar, descargar y gestionar validaciones

Objetivo

Consulta, audita y gestiona los registros de validación producidos por POST /v1/validate y POST /v1/validate-ocr. Este how-to cubre el flujo completo post-validación: encontrar registros, inspeccionar sus detalles, descargar artefactos, exportar para conciliación y controlar el comportamiento de reintentos por registro.

Requisitos previos

  • Una API key activa (veriko_…) con el permiso validations:read.
  • Para eliminar registros: validations:delete.
  • Para exportar: validations:read (mismo permiso — no se requiere permiso de exportación separado).

Pasos

1. Listar validaciones

GET /v1/validations devuelve una lista paginada de todas tus validaciones. Filtra por status, type (direct u ocr), rango de fechas o búsqueda libre search (coincide con clave de rastreo, referencia numérica, emisor y receptor).

# Últimas 20 validaciones manuales válidas
curl 'https://api.veriko.mx/v1/validations?status=valid&type=direct&per_page=20' \
  -H 'Authorization: Bearer veriko_••••'

Respuesta (abreviada):

{
  "data": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "type": "validation",
      "attributes": {
        "status": "valid",
        "validation_type": "direct",
        "created_at": "2025-03-15T14:22:10Z"
      }
    }
  ],
  "meta": { "pagination": { "page": 1, "per_page": 20, "total": 314, "total_pages": 16 } }
}

Por defecto el listado incluye los registros con soft-delete; with_deleted=0 deja solo los activos y with_deleted=1 solo los retirados.

Si enviaste client_ref al validar, client_ref=<valor> devuelve solo las validaciones con esa referencia exacta. El valor se devuelve tal cual en attributes.client_ref.

2. Consultar estadísticas agregadas

Antes de exportar o profundizar, verifica el desglose de estados con GET /v1/validations/stats. Soporta los mismos filtros que el endpoint de listado, salvo status.

curl 'https://api.veriko.mx/v1/validations/stats?from=2025-01-01&to=2025-03-31' \
  -H 'Authorization: Bearer veriko_••••'
{
  "data": {
    "type": "validation_stats",
    "attributes": {
      "total": 1240,
      "valid": 987,
      "not_found": 201,
      "deleted": 15,
      "other": 52
    }
  }
}

3. Inspeccionar un registro individual

Obtén los detalles completos — incluyendo ocr_result, retry_state y request_data — con GET /v1/validations/{id}. Usa ETag / If-None-Match para recibir respuestas 304 al sondear completaciones asíncronas.

curl 'https://api.veriko.mx/v1/validations/f47ac10b-58cc-4372-a567-0e02b2c3d479' \
  -H 'Authorization: Bearer veriko_••••'

Cuando la validación sigue en queued o processing, la respuesta incluye Retry-After y meta.next_poll_after_seconds para guiar tu intervalo de sondeo.

4. Descargar un certificado CEP

Cuando status es valid, la respuesta trae links.cep_pdf y links.cep_xml:

# XML (formato canónico Banxico)
curl 'https://api.veriko.mx/v1/validations/f47ac10b-.../cep?format=xml' \
  -H 'Authorization: Bearer veriko_••••' --output cep.xml

# PDF (legible por humanos)
curl 'https://api.veriko.mx/v1/validations/f47ac10b-.../cep?format=pdf' \
  -H 'Authorization: Bearer veriko_••••' --output cep.pdf

5. Descargar la imagen del comprobante

Las validaciones OCR almacenan la imagen saneada del comprobante en la plataforma:

curl 'https://api.veriko.mx/v1/validations/c3d4e5f6-.../image' \
  -H 'Authorization: Bearer veriko_••••' --output comprobante.png

Si la validación se envió con retain_image=false, responde 410 image_not_retained y el recurso trae image_retained en false. Si se purgó, responde 410 validation_purged.

6. Exportar resultados a CSV o XLSX

Usa GET /v1/validations/export para descargar todas las validaciones que coincidan con los filtros en un archivo. Soporta los mismos filtros que el endpoint de listado:

curl 'https://api.veriko.mx/v1/validations/export?format=xlsx&status=valid&from=2025-01-01' \
  -H 'Authorization: Bearer veriko_••••' \
  --output validaciones-q1.xlsx

Usa format=csv para el formato por defecto o format=xlsx para hoja de cálculo.

7. Gestionar el estado de reintentos por registro

Si una validación está en un ciclo de reintentos (por ejemplo, Banxico no estaba disponible), puedes:

Ver el historial de reintentos:

curl 'https://api.veriko.mx/v1/validations/f47ac10b-.../retry-attempts' \
  -H 'Authorization: Bearer veriko_••••'

Reconfigurar la política de reintentos solo para este registro:

curl -X PUT 'https://api.veriko.mx/v1/validations/f47ac10b-.../retry-policy' \
  -H 'Authorization: Bearer veriko_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "retry_policy": {
      "enabled": true,
      "max_retries": 5,
      "interval_seconds": 300,
      "outcomes": ["not_found", "cep_unavailable"]
    }
  }'

Cancelar reintentos en curso:

curl -X POST 'https://api.veriko.mx/v1/validations/f47ac10b-.../cancel-retries' \
  -H 'Authorization: Bearer veriko_••••'

Devuelve 200 con el timestamp retry_state.cancelled_at actualizado.

8. Eliminar un registro

Realiza un soft-delete de una validación para retirarla del historial activo:

curl -X DELETE 'https://api.veriko.mx/v1/validations/f47ac10b-...' \
  -H 'Authorization: Bearer veriko_••••'

Devuelve 204. Los registros con soft-delete siguen en el listado por defecto y se aíslan con ?with_deleted=1.

El soft-delete no borra el contenido: el CEP, los datos extraídos y el comprobante siguen existiendo. Para borrarlos de forma definitiva, en dos pasos, ver Borrar una validación de forma definitiva. Una validación purgada sigue en el historial como una lápida, con purged_at, su veredicto, sus fechas y su monto.

Siguientes pasos