Evidence

Evidence records store supporting files and records — receipts, statements, screenshots, scanned documents, contracts — that substantiate transactions. Evidence attaches to transactions (whereas documents attach to clients), and supports the same lifecycle: upload → submit → officer verify/reject, plus OCR field extraction.

Creating Evidence Records

Evidence is created in two steps: create the record, then upload the file. The high-level upload helper combines both.

// Low-level: create a record, get presigned URL, upload, confirm
const { evidence, upload } = await sdk.evidence.create({
  scope: "MX",
  type: "contrato_compraventa",
  contentType: "application/pdf",
  transactionIds: ["txn_abc123"],
});

await fetch(upload.url, {
  method: "PUT",
  body: fileBlob,
  headers: { "Content-Type": "application/pdf" },
});

await sdk.evidence.confirmUpload({
  id: evidence.id,
  filename: "contrato.pdf",
  contentType: "application/pdf",
  size: fileBlob.size,
});

console.log(evidence.id);
console.log(evidence.status); // "pending_upload"

// High-level helper: create + upload + confirm in one call
const evidence = await sdk.evidence.upload(file, {
  scope: "MX",
  type: "contrato_compraventa",
  transactionIds: ["txn_abc123"],
}, {
  onProgress: (progress) => console.log(`${Math.round(progress * 100)}%`),
  signal: abortController.signal,
});

Retry a Failed Upload

If the storage PUT step fails but the record was already created:

const evidence = await sdk.evidence.retryUpload("evid_xyz789", file);

Retrieving Evidence

const evidence = await sdk.evidence.retrieve("evid_xyz789");

console.log(evidence.id);
console.log(evidence.type);
console.log(evidence.status);
console.log(evidence.isAvailable);

You can also look up evidence by metadata:

const evidence = await sdk.evidence.retrieveByMetadata("internalRef", "REF-001");

Downloading Evidence

const { url, expiresAt } = await sdk.evidence.getDownloadUrl("evid_xyz789");

Updating Evidence

const updated = await sdk.evidence.update("evid_xyz789", {
  metadata: {
    reviewedBy: "admin@example.com",
  },
});

Review Lifecycle

Evidence follows the same review lifecycle as documents — submit an uploaded record for officer review, then verify or reject it.

await sdk.evidence.submit("evid_xyz789");          // uploaded → pending_review
await sdk.evidence.verify("evid_xyz789");           // pending_review → verified
await sdk.evidence.reject("evid_xyz789", {          // pending_review → rejected
  reason: "Illegible scan",
});

OCR Extraction

Extract structured fields from an evidence file via the OCR pipeline:

const result = await sdk.evidence.extract("evid_xyz789");
// Returns structured fields extracted from the evidence file

Linking Evidence to Transactions

Evidence can be linked to transactions from either side. Use the evidence resource:

await sdk.evidence.linkTransaction({
  evidenceId: "evid_xyz789",
  transactionId: "txn_abc123",
});

await sdk.evidence.unlinkTransaction({
  evidenceId: "evid_xyz789",
  transactionId: "txn_abc123",
});

// Replace all transaction links at once
await sdk.evidence.setTransactions({
  evidenceId: "evid_xyz789",
  transactionIds: ["txn_abc123", "txn_def456"],
});

Or link from the transaction side:

await sdk.transactions.linkEvidence({
  transactionId: "txn_abc123",
  evidenceId: "evid_xyz789",
});

await sdk.transactions.unlinkEvidence({
  transactionId: "txn_abc123",
  evidenceId: "evid_xyz789",
});

Listing Evidence

All Evidence

const { data } = await sdk.evidence.list({
  limit: 50,
});

For a Transaction

List all evidence linked to a transaction — from either resource:

const { data } = await sdk.evidence.listForTransaction("txn_abc123");

// Or from the transaction side
const { data: evidenceList } = await sdk.transactions.listEvidence("txn_abc123");

Linked Transaction IDs

const transactionIds = await sdk.evidence.listLinkedTransactions("evid_xyz789");

Async Iterator

for await (const evidence of sdk.evidence.iterate()) {
  console.log(evidence.id, evidence.type);
}

Checking Evidence Existence

// Check if a transaction has at least one verified evidence of a given type
const hasCfdi = await sdk.evidence.hasEvidenceType(
  "txn_abc123",
  "factura_cfdi_4_0",
);

if (!hasCfdi) {
  console.log("Transaction is missing a CFDI");
}

Counting Evidence

const count = await sdk.evidence.count({ type: "contrato_compraventa" });
console.log(`${count} matching evidence records`);

Deleting Evidence

await sdk.evidence.delete("evid_xyz789");

Batch Operations

Create or update multiple evidence records at once:

const result = await sdk.evidence.createMany([
  { scope: "MX", type: "contrato_compraventa", transactionIds: ["txn_abc123"] },
  { scope: "MX", type: "comprobante_pago", transactionIds: ["txn_abc123"] },
]);

const updated = await sdk.evidence.updateMany([
  { id: "evid_1", data: { metadata: { reviewed: true } } },
]);

Upsert

Create or update evidence by your own external ID:

const result = await sdk.evidence.upsertByExternalId({
  externalId: "erp-evid-123",
  scope: "MX",
  type: "contrato_compraventa",
  transactionIds: ["txn_abc123"],
});
console.log(result.action); // "created" | "updated"

const batch = await sdk.evidence.upsertManyByExternalId([...items]);

Getting Started

Core Resources

Patterns

Concepts

Creating Evidence Records

Retry a Failed Upload

Retrieving Evidence

Downloading Evidence

Updating Evidence

Review Lifecycle

OCR Extraction

Linking Evidence to Transactions

Listing Evidence

All Evidence

For a Transaction

Linked Transaction IDs

Async Iterator

Checking Evidence Existence

Counting Evidence

Deleting Evidence

Batch Operations

Upsert

​Creating Evidence Records

​Retry a Failed Upload

​Retrieving Evidence

​Downloading Evidence

​Updating Evidence

​Review Lifecycle

​OCR Extraction

​Linking Evidence to Transactions

​Listing Evidence

​All Evidence

​For a Transaction

​Linked Transaction IDs

​Async Iterator

​Checking Evidence Existence

​Counting Evidence

​Deleting Evidence

​Batch Operations

​Upsert

Creating Evidence Records

Retry a Failed Upload

Retrieving Evidence

Downloading Evidence

Updating Evidence

Review Lifecycle

OCR Extraction

Linking Evidence to Transactions

Listing Evidence

All Evidence

For a Transaction

Linked Transaction IDs

Async Iterator

Checking Evidence Existence

Counting Evidence

Deleting Evidence

Batch Operations

Upsert