Docs
EN

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 (mxcep_…) 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 directas válidas
curl 'https://api.example.com/v1/validations?status=valid&type=direct&per_page=20' \
  -H 'Authorization: Bearer mxcep_••••'

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": { "total": 314, "page": 1, "per_page": 20 }
}

Para incluir registros con soft-delete, añade with_deleted=1.

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.

curl 'https://api.example.com/v1/validations/stats?date_from=2025-01-01&date_to=2025-03-31' \
  -H 'Authorization: Bearer mxcep_••••'
{
  "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.example.com/v1/validations/f47ac10b-58cc-4372-a567-0e02b2c3d479' \
  -H 'Authorization: Bearer mxcep_••••'

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 y has_cep es true:

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

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

5. Descargar la imagen del comprobante

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

curl 'https://api.example.com/v1/validations/c3d4e5f6-.../image' \
  -H 'Authorization: Bearer mxcep_••••' --output comprobante.png

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.example.com/v1/validations/export?format=xlsx&status=valid&date_from=2025-01-01' \
  -H 'Authorization: Bearer mxcep_••••' \
  --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.example.com/v1/validations/f47ac10b-.../retry-attempts' \
  -H 'Authorization: Bearer mxcep_••••'

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

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

Cancelar reintentos en curso:

curl -X POST 'https://api.example.com/v1/validations/f47ac10b-.../cancel-retries' \
  -H 'Authorization: Bearer mxcep_••••'

Devuelve 200 con el timestamp retry_state.cancelled_at actualizado.

8. Eliminar un registro

Realiza un soft-delete de una validación para quitarla de tu vista de lista por defecto:

curl -X DELETE 'https://api.example.com/v1/validations/f47ac10b-...' \
  -H 'Authorization: Bearer mxcep_••••'

Devuelve 204. Los registros con soft-delete siguen siendo recuperables vía GET /v1/validations?with_deleted=1.

Siguientes pasos