Docs
ES

Goal

Retrieve, audit, and manage the validation records produced by POST /v1/validate and POST /v1/validate-ocr. This how-to covers the full post-validation workflow: finding records, inspecting their details, downloading artifacts, exporting for reconciliation, and controlling retry behavior per-record.

Prerequisites

  • An active API key (mxcep_…) with validations:read.
  • To delete records: validations:delete.
  • To export: validations:read (same permission — no separate export permission needed).

Steps

1. List validations

GET /v1/validations returns a paginated list of all your validations. Filter by status, type (direct or ocr), date range, or free-text search (matches clave de rastreo, referencia numérica, emisor, and receptor).

# Fetch the last 20 valid direct validations
curl 'https://api.example.com/v1/validations?status=valid&type=direct&per_page=20' \
  -H 'Authorization: Bearer mxcep_••••'

Response (abbreviated):

{
  "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 }
}

To include soft-deleted records, add with_deleted=1.

2. Get aggregated stats

Before exporting or drilling in, check the status breakdown with GET /v1/validations/stats. Supports the same filters as the list endpoint.

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. Inspect a single record

Fetch full details — including ocr_result, retry_state, and request_data — with GET /v1/validations/{id}. Use ETag / If-None-Match to get 304 responses when polling for async completions.

curl 'https://api.example.com/v1/validations/f47ac10b-58cc-4372-a567-0e02b2c3d479' \
  -H 'Authorization: Bearer mxcep_••••'

When the validation is still queued or processing, the response includes Retry-After and meta.next_poll_after_seconds to guide your polling interval.

4. Download a CEP certificate

When status is valid and has_cep is true:

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

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

5. Download a receipt image

OCR validations store the sanitized comprobante image on the platform:

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

6. Export results to CSV or XLSX

Use GET /v1/validations/export to download all matching validations as a file. Supports the same filters as the list endpoint:

curl 'https://api.example.com/v1/validations/export?format=xlsx&status=valid&date_from=2025-01-01' \
  -H 'Authorization: Bearer mxcep_••••' \
  --output validations-q1.xlsx

Use format=csv for the default (no flag needed) or format=xlsx for a spreadsheet.

7. Manage retry state per record

If a validation is in a retry loop (e.g. Banxico was unavailable), you can:

View retry history:

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

Reconfigure retry policy for this record only:

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"]
  }'

Cancel ongoing retries:

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

Returns 200 with the updated retry_state.cancelled_at timestamp.

8. Delete a record

Soft-delete a validation to remove it from your default list view:

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

Returns 204. Soft-deleted records are still retrievable via GET /v1/validations?with_deleted=1.

What's next