Inicio rápido
Crea tu primera integración
Configura una API key de prueba, haz tu primera solicitud y sigue los flujos REST y MCP.
Producción y entorno de prueba
Haz tu primera solicitud autenticada
Comienza con una organización de prueba aislada y una API key de prueba.
Abre la consola para desarrolladores
Abre /consola desde Exac, selecciona Prueba y entra a Claves API para tu workspace actual.
Crea una API key de prueba
Crea una clave para Prueba y cópiala una sola vez. Exac prepara el entorno aislado automáticamente.
Verifica la organización de prueba
Llama GET /v1/organization con la clave de prueba contra el servidor de prueba mostrado en OpenAPI.
Ejecuta un flujo Test
Crea un contacto y un borrador CFDI; luego crea, consulta y cancela un timbrado de prueba. Los artefactos de sandbox no se envían al SAT y no tienen validez fiscal.
curl "https://api.sandbox.exac.mx/v1/organization" \ --header "Authorization: Bearer <EXAC_API_KEY>"const response = await fetch("https://api.sandbox.exac.mx/v1/organization", { method: "GET", headers: { "Authorization": "Bearer <EXAC_API_KEY>" }});// File downloads (PDF, XML, ZIP) are binary; everything else is JSON.const isJson = response.headers.get('Content-Type')?.includes('json');const payload: unknown = isJson ? await response.json() : await response.arrayBuffer();if (!response.ok) { const retryAfter = response.headers.get('Retry-After'); const apiError = payload as { error?: { code?: string; message?: string; details?: unknown }; }; throw new Error( [ apiError.error?.code ?? `http_${response.status}`, apiError.error?.message ?? 'Request failed', retryAfter ? `retry after ${retryAfter}s` : null, ] .filter(Boolean) .join(': '), );}const result = payload;import requestsurl = "https://api.sandbox.exac.mx/v1/organization"response = requests.request("GET", url, headers = { "Authorization": "Bearer <EXAC_API_KEY>"})if not response.ok: raise RuntimeError(f"HTTP {response.status_code}: {response.text}")# File downloads (PDF, XML, ZIP) are binary; everything else is JSON.is_json = "json" in response.headers.get("Content-Type", "")print(response.json() if is_json else response.content)Tu primera escritura
Cada escritura requiere Idempotency-Key. Genera una clave por operación y reutilízala en cada reintento: tras un timeout o un error 429 o 5xx, repetir la misma solicitud devuelve el resultado original en lugar de duplicar el efecto.
curl -X POST "https://api.sandbox.exac.mx/v1/contacts" \ -H "Authorization: Bearer <EXAC_API_KEY>" \ -H "Idempotency-Key: sandbox-create-contact" \ -H "Content-Type: application/json" \ -d '{ "kind": "customer", "legalName": "Estudio Jacaranda", "email": "administracion@jacaranda.example", "rfc": "AAA010101AAA", "taxSystem": "601", "cfdiUse": "G03", "address": { "postalCode": "82110", "country": "MEX" } }'const url = "https://api.sandbox.exac.mx/v1/contacts";const body = { "kind": "customer", "legalName": "Estudio Jacaranda", "email": "administracion@jacaranda.example", "rfc": "AAA010101AAA", "taxSystem": "601", "cfdiUse": "G03", "address": { "postalCode": "82110", "country": "MEX" }};// One key per intended write. Reuse it on every retry of that same write.const idempotencyKey = crypto.randomUUID();type ApiError = { error?: { code?: string; message?: string; details?: { retryable?: boolean } };};async function sendWithRetry(maxAttempts = 4): Promise<unknown> { for (let attempt = 1; ; attempt++) { let delayMs = 2 ** attempt * 250; let response: Response | undefined; let payload: unknown = null; try { response = await fetch(url, { method: "POST", headers: { "Authorization": "Bearer <EXAC_API_KEY>", "Content-Type": "application/json", "Idempotency-Key": idempotencyKey, }, body: JSON.stringify(body), signal: AbortSignal.timeout(10_000), }); // Reading the body can time out too, so it stays inside the try. const text = await response.text(); try { payload = JSON.parse(text); } catch { // Not JSON (for example a proxy error page). } } catch (error) { // Timeout or network failure: the write may or may not have been applied. response = undefined; if (attempt >= maxAttempts) throw error; } if (response) { if (response.ok) return payload; const apiError = (payload as ApiError | null)?.error; const retryable = (response.status === 429 || response.status >= 500) && apiError?.code !== "recovery_required" && apiError?.details?.retryable !== false; if (!retryable || attempt >= maxAttempts) { throw new Error( `${apiError?.code ?? `http_${response.status}`}: ${apiError?.message ?? "Request failed"}`, ); } // Retry-After is either delay-seconds or an HTTP date. const retryAfter = response.headers.get("Retry-After") ?? ""; const waitMs = /^\d+$/.test(retryAfter) ? Number(retryAfter) * 1000 : Date.parse(retryAfter) - Date.now(); if (waitMs > 0) delayMs = waitMs; } await new Promise((resolve) => setTimeout(resolve, delayMs)); }}const result = await sendWithRetry();import timeimport uuidfrom datetime import datetime, timezonefrom email.utils import parsedate_to_datetimeimport requestsurl = "https://api.sandbox.exac.mx/v1/contacts"body = { "kind": "customer", "legalName": "Estudio Jacaranda", "email": "administracion@jacaranda.example", "rfc": "AAA010101AAA", "taxSystem": "601", "cfdiUse": "G03", "address": { "postalCode": "82110", "country": "MEX", },}# One key per intended write. Reuse it on every retry of that same write.idempotency_key = str(uuid.uuid4())def retry_after_seconds(value): # Retry-After is either delay-seconds or an HTTP date. if value.isdigit(): return int(value) try: wait = parsedate_to_datetime(value) - datetime.now(timezone.utc) return max(wait.total_seconds(), 0) except (TypeError, ValueError): return 0def send_with_retry(max_attempts=4): for attempt in range(1, max_attempts + 1): delay = 2**attempt * 0.25 try: response = requests.request( "POST", url, json=body, headers={ "Authorization": "Bearer <EXAC_API_KEY>", "Idempotency-Key": idempotency_key, }, timeout=10, ) except requests.exceptions.RequestException: # Timeout or network failure: the write may or may not have been applied. if attempt == max_attempts: raise else: try: payload = response.json() except ValueError: payload = None if response.ok: return payload error = payload.get("error") if isinstance(payload, dict) else None error = error if isinstance(error, dict) else {} details = error.get("details") retryable = ( (response.status_code == 429 or response.status_code >= 500) and error.get("code") != "recovery_required" and not (isinstance(details, dict) and details.get("retryable") is False) ) if not retryable or attempt == max_attempts: code = error.get("code", f"http_{response.status_code}") raise RuntimeError(f"{code}: {error.get('message', 'Request failed')}") delay = retry_after_seconds(response.headers.get("Retry-After", "")) or delay time.sleep(delay)result = send_with_retry()print(result)Convenciones de solicitudes, respuestas y reintentos
Envía Authorization: Bearer <credencial> en cada solicitud de API y Content-Type: application/json cuando envíes un cuerpo JSON. Los éxitos JSON usan { data }; las respuestas paginadas también incluyen pagination. Las fallas usan { error: { code, message, status, details? } }. Decide con error.code, no con el mensaje humano. Las descargas devuelven bytes en lugar de un sobre JSON.
Al crear una API key de organización eliges su nivel de acceso con accessLevel: full (predeterminado) o read. Una clave read puede llamar a todas las operaciones REST y herramientas MCP que solo leen datos, y recibe 403 en cualquier otra, incluida la administración de claves API. No hay permisos personalizados por operación.
Cada respuesta HTTP de REST y MCP, exitosa o con error, incluye un encabezado Request-Id como req_0123456789abcdef0123456789abcdef. Regístralo en cada llamada e inclúyelo cuando contactes a soporte.
Cada intento HTTP recibe su propio Request-Id, también un reintento con la misma Idempotency-Key que repite el resultado original: la repetición devuelve el resultado original con un Request-Id nuevo, así que conserva el del intento sobre el que preguntas.
Los administradores de la organización pueden encontrar ese mismo ID en la consola de desarrolladores, en Actividad, para el entorno seleccionado: llamadas autenticadas de REST y herramientas MCP, con resultado, operación, credencial y duración. Los registros se conservan 14 días y son diagnóstico de mejor esfuerzo, no una bitácora de auditoría. El acceso a la actividad en la consola y en REST requiere el permiso apiKeys:manage.
Cada escritura requiere Idempotency-Key, incluso el primer intento. Genera una clave única por operación deseada y consérvala con la solicitud.
Tras un timeout, reintenta con la misma credencial, clave, ruta y carga. Cambiar la operación o la carga con una clave retenida devuelve idempotency_conflict.
Las claves se limitan a la organización e identidad que llama, compartidas entre REST y MCP; cambiar de credencial puede cambiar ese alcance. Una operación exitosa repite su resultado original, que puede diferir del estado actual del recurso.
Los registros de idempotencia se conservan 7 días; los secretos de creación de API keys se pueden recuperar durante 15 minutos. No dependas de la deduplicación después de ese periodo: verifica el recurso antes de enviar otra escritura.
Espera Retry-After cuando esté presente.
Nunca reintentes automáticamente recovery_required o details.retryable = false, ni cambies de clave para evadir un resultado incierto.
Usa details.document.documentRef para consultar el documento afectado cuando exista.
Los límites son cubetas de tokens: la cubeta se rellena a una tasa constante por minuto y su capacidad es la ráfaga máxima que puedes enviar de golpe. Cada solicitud consume un token; si no quedan, la API responde 429.
Cada solicitud descuenta de la cubeta global: 300 por minuto, ráfaga máxima de 300. Además, las escrituras descuentan de la cubeta de escritura (120 por minuto, ráfaga máxima de 30) y las operaciones sensibles, como timbrado, certificados, API keys y miembros, de la cubeta sensible (60 por minuto, ráfaga máxima de 30). Las lecturas GET solo usan la cubeta global.
Cada operación REST declara su clase en x-exac-rate-limit dentro de openapi.json (global, write o sensitive). Cada herramienta MCP usa la misma clase que su operación REST equivalente.
Las cubetas se cuentan por organización e identidad que llama (API key, usuario OAuth o agente): otra organización o credencial no consume tu cuota.
Antes de autenticar, las solicitudes se limitan por dirección de red (600 por minuto, ráfaga máxima de 600) y, en conjunto, para todos los clientes (3,000 por minuto, ráfaga máxima de 3,000).
El timbrado de nómina se dosifica por organización (120 por minuto, ráfaga máxima de 20 recibos): el exceso espera en segundo plano y no devuelve 429.
Una solicitud MCP no puede superar 1 MiB; un cuerpo mayor devuelve 413.
En REST, un 429 incluye el encabezado Retry-After con los segundos de espera. En MCP, el HTTP 429 también incluye Retry-After y el cuerpo JSON-RPC trae el error -32029 con error.data.retryAfterSeconds. Espera ese tiempo, conserva la misma Idempotency-Key en escrituras y reintenta; no abras más conexiones en paralelo para compensar.
Empieza sin cursor y después envía pagination.nextCursor sin cambios con los mismos filtros hasta que pagination.hasMore sea false. Una página corta o vacía no termina la consulta si hasMore es true.
Los IDs y documentRef son opacos y pertenecen a una organización: conserva el valor completo, incluido el prefijo de documentRef, y codifícalo como segmento de URL. No sustituyas documentRef por un UUID del SAT.
Los instantes usan RFC 3339 con desplazamiento, por ejemplo 2026-07-15T18:00:00.000Z.
Las fechas usan YYYY-MM-DD y los meses YYYY-MM.
Los campos CFDI que terminan en LocalDateTime representan hora civil sin desplazamiento: no agregues Z ni supongas UTC.
Los objetos monetarios estándar { amount, currency } usan unidades mayores numéricas (116 significa 116 pesos en MXN); los campos que terminan en Minor usan unidades menores, como centavos.
Algunos montos fiscales, bases de impuestos y campos rateOrFee usan cadenas decimales exactas: conserva el tipo y la precisión del esquema sin convertirlos a punto flotante ni centavos.
Las tasas numéricas son fracciones, como 0.16 para 16%.
Los campos opcionales pueden omitirse; envía null solo cuando el esquema lo permita explícitamente.
Flujos canónicos
Usa la misma intención de dominio mediante REST o MCP. Estos ejemplos se validan contra los contratos de ejecución; reemplaza los identificadores y credenciales de ejemplo con valores de tu organización.
Crea, timbra, descarga y cancela un CFDI de prueba sin validez fiscal usando únicamente operaciones REST de sandbox.
- 1
Verifica la organización
Confirma que la clave de sandbox resuelva a la organización aislada esperada.
REST · Producción y pruebaGET /v1/organizationGuía de reintentos: Esta lectura se puede repetir de forma segura.
- 2
Crea un cliente de prueba
Crea el cliente con su identidad fiscal. Usa el contactId devuelto como customerId en la siguiente solicitud.
REST · Producción y pruebaPOST /v1/contactsGuía de reintentos: Reutiliza la misma clave solo para una solicitud idéntica.
- 3
Crea un borrador CFDI
Crea un borrador que puedas revisar antes del timbrado de prueba explícito.
REST · Producción y pruebaPOST /v1/invoicesGuía de reintentos: Reutiliza la misma clave solo para la carga idéntica del borrador.
- 4
Crea un timbrado de prueba
Sandbox crea un artefacto de prueba. No se envía al SAT y no tiene validez fiscal.
REST · Producción y pruebaPOST /v1/invoices/invoice:invoice-example/stampGuía de reintentos: Reintenta solo con la misma clave y documentRef.
- 5
Descarga el PDF de prueba
Descarga el documento de prueba generado desde el servidor de sandbox.
REST · Producción y pruebaGET /v1/documents/invoice:invoice-example/files/pdfGuía de reintentos: Esta lectura de archivo se puede repetir de forma segura.
- 6
Cancela el CFDI de prueba
Ejercita la transición de cancelación contra datos de prueba aislados.
REST · Producción y pruebaPOST /v1/invoices/invoice:invoice-example/cancelGuía de reintentos: Reutiliza la misma clave solo para la misma solicitud de cancelación.
{ "steps": [ { "id": "verify-sandbox-organization", "rest": { "operationId": "getOrganization", "method": "GET", "path": "/v1/organization", "environments": [ "production", "sandbox" ] } }, { "id": "create-sandbox-contact", "rest": { "operationId": "createContact", "method": "POST", "path": "/v1/contacts", "environments": [ "production", "sandbox" ], "headers": { "Idempotency-Key": "sandbox-create-contact" }, "body": { "kind": "customer", "legalName": "Estudio Jacaranda", "email": "administracion@jacaranda.example", "rfc": "AAA010101AAA", "taxSystem": "601", "cfdiUse": "G03", "address": { "postalCode": "82110", "country": "MEX" } } } }, { "id": "create-sandbox-cfdi", "rest": { "operationId": "createInvoiceDraft", "method": "POST", "path": "/v1/invoices", "environments": [ "production", "sandbox" ], "headers": { "Idempotency-Key": "sandbox-create-cfdi" }, "body": { "customerId": "customer-example", "items": [ { "kind": "custom", "description": "Consultoría administrativa · julio 2026", "quantity": 1, "unitPrice": 10000, "satProductCode": "84111506", "satUnitCode": "E48", "taxRate": 0.16, "taxability": "standard" } ], "kind": "income", "cfdiUse": "G03", "payment": { "timing": "deferred_or_installments", "formCode": "99", "conditions": "Crédito a 30 días" } } } }, { "id": "stamp-sandbox-cfdi", "rest": { "operationId": "stampInvoice", "method": "POST", "path": "/v1/invoices/invoice:invoice-example/stamp", "environments": [ "production", "sandbox" ], "headers": { "Idempotency-Key": "sandbox-stamp-cfdi" }, "body": {} } }, { "id": "download-sandbox-pdf", "rest": { "operationId": "downloadDocumentFile", "method": "GET", "path": "/v1/documents/invoice:invoice-example/files/pdf", "environments": [ "production", "sandbox" ] } }, { "id": "cancel-sandbox-cfdi", "rest": { "operationId": "cancelInvoice", "method": "POST", "path": "/v1/invoices/invoice:invoice-example/cancel", "environments": [ "production", "sandbox" ], "headers": { "Idempotency-Key": "sandbox-cancel-cfdi" }, "body": { "reason": "02" } } } ]}Configura la identidad fiscal, carga el CSD y verifica la disponibilidad antes de crear CFDI.
- 1
Configura la identidad fiscal
Usa la identidad del emisor de tus datos fiscales, con el RFC que corresponda al CSD que cargarás. Actualiza una sección de configuración de la organización a la vez.
REST · Solo producciónPATCH /v1/organizationMCP · Solo producciónupdate_organizationGuía de reintentos: Reutiliza el mismo Idempotency-Key únicamente para la misma carga de sección.
- 2
Carga el par CSD
Carga el certificado y la clave privada en base64; el material secreto nunca se devuelve.
REST · Producción y pruebaPUT /v1/organization/certificates/csdGuía de reintentos: Reintenta con la misma clave y la carga de certificado sin cambios.
- 3
Verifica la disponibilidad
Lee la proyección de la organización y confirma la disponibilidad fiscal antes de emitir.
REST · Producción y pruebaGET /v1/organizationMCP · Solo producciónget_organizationGuía de reintentos: Las lecturas se pueden repetir; no agregues un idempotency key.
{ "steps": [ { "id": "update-fiscal-settings", "rest": { "operationId": "updateOrganization", "method": "PATCH", "path": "/v1/organization", "environments": [ "production" ], "headers": { "Idempotency-Key": "workflow-fiscal-settings" }, "body": { "section": "fiscal", "legalName": "Consultoría Bruma SA de CV", "rfc": "EKU9003173C9", "taxSystem": "601", "address": { "postalCode": "82110" } } }, "mcp": { "tool": "update_organization", "arguments": { "idempotencyKey": "workflow-fiscal-settings", "input": { "section": "fiscal", "legalName": "Consultoría Bruma SA de CV", "rfc": "EKU9003173C9", "taxSystem": "601", "address": { "postalCode": "82110" } } }, "environments": [ "production" ] } }, { "id": "upload-csd", "rest": { "operationId": "uploadCertificate", "method": "PUT", "path": "/v1/organization/certificates/csd", "environments": [ "production", "sandbox" ], "headers": { "Idempotency-Key": "workflow-upload-csd" }, "body": { "certificateBase64": "BASE64_CER", "privateKeyBase64": "BASE64_KEY", "password": "certificate-password", "certificateFileName": "certificate.cer", "privateKeyFileName": "private.key" } } }, { "id": "verify-organization", "rest": { "operationId": "getOrganization", "method": "GET", "path": "/v1/organization", "environments": [ "production", "sandbox" ] }, "mcp": { "tool": "get_organization", "arguments": {}, "environments": [ "production" ] } } ]}Flujo de producción: configura la identidad fiscal y el CSD de la organización, agrega saldo a la cartera API/MCP y crea un cliente con RFC, razón social, régimen fiscal y domicilio postal. Usa ese contactId como customerId. Después crea un borrador, revísalo, timbra explícitamente ante el SAT y envía el documento.
- 1
Crea el borrador
La creación solo produce un borrador. No timbra ni envía el CFDI; revisa el borrador devuelto antes de cualquier transición explícita.
REST · Producción y pruebaPOST /v1/invoicesMCP · Solo produccióncreate_invoice_draftGuía de reintentos: Usa la misma clave para un reintento exacto; una carga modificada es una nueva solicitud.
- 2
Revisa el borrador
Usa el documentRef devuelto para revisar la proyección canónica del documento.
REST · Producción y pruebaGET /v1/invoices/invoice:invoice-exampleMCP · Solo producciónget_documentGuía de reintentos: Esta lectura se puede repetir y no lleva idempotency key.
- 3
Previsualiza el PDF del borrador (opcional)
Usa preview_pdf para revisar el documento renderizado antes de timbrar. La vista previa no tiene validez fiscal.
REST · Producción y pruebaGET /v1/documents/invoice:invoice-example/files/preview_pdfMCP · Solo producciónget_document_fileGuía de reintentos: Esta lectura de archivo se puede repetir y no lleva idempotency key.
- 4
Timbra ante el SAT
El timbrado es una transición irreversible separada. Revisa primero el borrador.
REST · Producción y pruebaPOST /v1/invoices/invoice:invoice-example/stampMCP · Solo producciónstamp_invoiceGuía de reintentos: Reintenta únicamente con la misma clave y documentRef; las fallas del proveedor pueden requerir recuperación.
- 5
Envía el CFDI
Envía por correo el CFDI timbrado y sus archivos fiscales a un destinatario explícito.
REST · Solo producciónPOST /v1/documents/invoice:invoice-example/sendMCP · Solo producciónsend_documentGuía de reintentos: Reutiliza la clave para el mismo destinatario y documento; el envío sigue siendo un efecto externo.
{ "steps": [ { "id": "create-cfdi-draft", "rest": { "operationId": "createInvoiceDraft", "method": "POST", "path": "/v1/invoices", "environments": [ "production", "sandbox" ], "headers": { "Idempotency-Key": "workflow-create-cfdi" }, "body": { "customerId": "customer-example", "items": [ { "kind": "custom", "description": "Consultoría administrativa · julio 2026", "quantity": 1, "unitPrice": 10000, "satProductCode": "84111506", "satUnitCode": "E48", "taxRate": 0.16, "taxability": "standard" } ], "kind": "income", "cfdiUse": "G03", "payment": { "timing": "deferred_or_installments", "formCode": "99", "conditions": "Crédito a 30 días" } } }, "mcp": { "tool": "create_invoice_draft", "arguments": { "idempotencyKey": "workflow-create-cfdi", "input": { "customerId": "customer-example", "items": [ { "kind": "custom", "description": "Consultoría administrativa · julio 2026", "quantity": 1, "unitPrice": 10000, "satProductCode": "84111506", "satUnitCode": "E48", "taxRate": 0.16, "taxability": "standard" } ], "kind": "income", "cfdiUse": "G03", "payment": { "timing": "deferred_or_installments", "formCode": "99", "conditions": "Crédito a 30 días" } } }, "environments": [ "production" ] } }, { "id": "inspect-cfdi-draft", "rest": { "operationId": "getInvoice", "method": "GET", "path": "/v1/invoices/invoice:invoice-example", "environments": [ "production", "sandbox" ] }, "mcp": { "tool": "get_document", "arguments": { "documentRef": "invoice:invoice-example" }, "environments": [ "production" ] } }, { "id": "preview-cfdi-draft-pdf", "rest": { "operationId": "downloadDocumentFile", "method": "GET", "path": "/v1/documents/invoice:invoice-example/files/preview_pdf", "environments": [ "production", "sandbox" ] }, "mcp": { "tool": "get_document_file", "arguments": { "documentRef": "invoice:invoice-example", "file": "preview_pdf" }, "environments": [ "production" ] } }, { "id": "stamp-cfdi", "rest": { "operationId": "stampInvoice", "method": "POST", "path": "/v1/invoices/invoice:invoice-example/stamp", "environments": [ "production", "sandbox" ], "headers": { "Idempotency-Key": "workflow-stamp-cfdi" }, "body": {} }, "mcp": { "tool": "stamp_invoice", "arguments": { "documentRef": "invoice:invoice-example", "idempotencyKey": "workflow-stamp-cfdi" }, "environments": [ "production" ] } }, { "id": "send-cfdi", "rest": { "operationId": "sendDocument", "method": "POST", "path": "/v1/documents/invoice:invoice-example/send", "environments": [ "production" ], "headers": { "Idempotency-Key": "workflow-send-cfdi" }, "body": { "recipient": "administracion@jacaranda.example" } }, "mcp": { "tool": "send_document", "arguments": { "idempotencyKey": "workflow-send-cfdi", "input": { "documentRef": "invoice:invoice-example", "recipient": "administracion@jacaranda.example" } }, "environments": [ "production" ] } } ]}Registra uno o más pagos de una factura PPD. Exac distribuye los impuestos conocidos de la factura en cada pago parcial.
- 1
Revisa el CFDI relacionado
Usa taxes: "auto" cuando Exac tenga la factura timbrada. Para una factura externa desconocida, envía su taxObject SAT y los impuestos del pago; no se requiere importar XML.
REST · Producción y pruebaGET /v1/invoices/invoice:invoice-exampleMCP · Solo producciónget_documentGuía de reintentos: Esta lectura se puede repetir de forma segura.
- 2
Crea el borrador del complemento
En el primer pago usa installment 1 y el total de la factura como previousBalance. En pagos posteriores, incrementa installment y usa el saldo insoluto anterior. Exac resuelve los impuestos automáticos antes de crear el borrador.
REST · Producción y pruebaPOST /v1/invoicesMCP · Solo produccióncreate_invoice_draftGuía de reintentos: Reutiliza la misma clave solo para el mismo pago.
- 3
Revisa antes de timbrar
Confirma saldos, parcialidad e impuestos del pago en la proyección canónica del borrador.
REST · Producción y pruebaGET /v1/invoices/invoice:payment-exampleMCP · Solo producciónget_documentGuía de reintentos: Esta lectura se puede repetir de forma segura.
- 4
Timbra el complemento
Timbra solo después de confirmar el UUID relacionado, la parcialidad, los saldos anterior, pagado e insoluto, y los impuestos proporcionales.
REST · Producción y pruebaPOST /v1/invoices/invoice:payment-example/stampMCP · Solo producciónstamp_invoiceGuía de reintentos: Reutiliza la misma clave solo para el mismo borrador revisado y fecha de emisión.
{ "steps": [ { "id": "inspect-related-cfdi", "rest": { "operationId": "getInvoice", "method": "GET", "path": "/v1/invoices/invoice:invoice-example", "environments": [ "production", "sandbox" ] }, "mcp": { "tool": "get_document", "arguments": { "documentRef": "invoice:invoice-example" }, "environments": [ "production" ] } }, { "id": "create-payment-complement-draft", "rest": { "operationId": "createInvoiceDraft", "method": "POST", "path": "/v1/invoices", "environments": [ "production", "sandbox" ], "headers": { "Idempotency-Key": "workflow-create-payment-complement" }, "body": { "kind": "payment_complement", "customerId": "customer-example", "payments": [ { "formCode": "03", "paidLocalDateTime": "2026-07-15T12:00:00", "documents": [ { "uuid": "00000000-0000-4000-8000-000000000001", "amount": 11600, "installment": 1, "previousBalance": 11600, "taxes": "auto" } ] } ] } }, "mcp": { "tool": "create_invoice_draft", "arguments": { "idempotencyKey": "workflow-create-payment-complement", "input": { "kind": "payment_complement", "customerId": "customer-example", "payments": [ { "formCode": "03", "paidLocalDateTime": "2026-07-15T12:00:00", "documents": [ { "uuid": "00000000-0000-4000-8000-000000000001", "amount": 11600, "installment": 1, "previousBalance": 11600, "taxes": "auto" } ] } ] } }, "environments": [ "production" ] } }, { "id": "inspect-payment-complement-draft", "rest": { "operationId": "getInvoice", "method": "GET", "path": "/v1/invoices/invoice:payment-example", "environments": [ "production", "sandbox" ] }, "mcp": { "tool": "get_document", "arguments": { "documentRef": "invoice:payment-example" }, "environments": [ "production" ] } }, { "id": "stamp-payment-complement", "rest": { "operationId": "stampInvoice", "method": "POST", "path": "/v1/invoices/invoice:payment-example/stamp", "environments": [ "production", "sandbox" ], "headers": { "Idempotency-Key": "workflow-stamp-payment-complement" }, "body": {} }, "mcp": { "tool": "stamp_invoice", "arguments": { "documentRef": "invoice:payment-example", "idempotencyKey": "workflow-stamp-payment-complement" }, "environments": [ "production" ] } } ]}Crea un borrador de CFDI a partir de ventas seleccionadas de recibos. El timbrado permanece como una operación explícita separada.
- 1
Crea el recibo
Usa un producto de catálogo con su identidad fiscal configurada. Sin productId, envía satProductCode y satUnitCode al crear este recibo pagado. Exac conserva los datos fiscales como se cobraron para facturar después.
REST · Producción y pruebaPOST /v1/sales-receiptsMCP · Solo produccióncreate_sales_receiptGuía de reintentos: Reutiliza la misma clave solo para la venta idéntica.
- 2
Convierte los recibos
La operación valida la propiedad y conciliación de los recibos y devuelve un borrador de CFDI. No timbra ni envía el CFDI.
REST · Producción y pruebaPOST /v1/invoices/from-sales-receiptsMCP · Solo produccióncreate_invoice_draft_from_sales_receiptsGuía de reintentos: Reintenta el mismo conjunto de recibos con la misma clave; nunca cambies el conjunto usando una clave existente.
- 3
Lee el CFDI resultante
Usa el documentRef de CFDI devuelto por la conversión para obtener el detalle canónico.
REST · Producción y pruebaGET /v1/invoices/invoice:invoice-exampleMCP · Solo producciónget_documentGuía de reintentos: Las lecturas se pueden repetir y no necesitan idempotency key.
{ "steps": [ { "id": "create-invoiceable-receipt", "rest": { "operationId": "createSalesReceipt", "method": "POST", "path": "/v1/sales-receipts", "environments": [ "production", "sandbox" ], "headers": { "Idempotency-Key": "workflow-create-invoiceable-receipt" }, "body": { "saleType": "paid", "customer": { "kind": "stored", "customerId": "customer-example" }, "items": [ { "productId": "product-example", "description": "Servicio", "quantity": 1, "unitPrice": 1250 } ], "paymentForm": "03" } }, "mcp": { "tool": "create_sales_receipt", "arguments": { "idempotencyKey": "workflow-create-invoiceable-receipt", "input": { "saleType": "paid", "customer": { "kind": "stored", "customerId": "customer-example" }, "items": [ { "productId": "product-example", "description": "Servicio", "quantity": 1, "unitPrice": 1250 } ], "paymentForm": "03" } }, "environments": [ "production" ] } }, { "id": "create-cfdi-from-receipts", "rest": { "operationId": "createInvoiceDraftFromSalesReceipts", "method": "POST", "path": "/v1/invoices/from-sales-receipts", "environments": [ "production", "sandbox" ], "headers": { "Idempotency-Key": "workflow-receipts-to-cfdi" }, "body": { "salesReceiptRefs": [ "sales_receipt:receipt-example" ], "customer": { "kind": "existing", "customerId": "customer-example" }, "cfdiUse": "S01" } }, "mcp": { "tool": "create_invoice_draft_from_sales_receipts", "arguments": { "idempotencyKey": "workflow-receipts-to-cfdi", "input": { "salesReceiptRefs": [ "sales_receipt:receipt-example" ], "customer": { "kind": "existing", "customerId": "customer-example" }, "cfdiUse": "S01" } }, "environments": [ "production" ] } }, { "id": "read-converted-cfdi", "rest": { "operationId": "getInvoice", "method": "GET", "path": "/v1/invoices/invoice:invoice-example", "environments": [ "production", "sandbox" ] }, "mcp": { "tool": "get_document", "arguments": { "documentRef": "invoice:invoice-example" }, "environments": [ "production" ] } } ]}Busca en la colección de CFDI con filtros fiscales, recupera un documento y descarga su PDF o XML.
- 1
Busca CFDI
Usa kind y paymentTiming en lugar de un filtro genérico de tipo de documento.
REST · Producción y pruebaGET /v1/invoicesMCP · Solo producciónsearch_documentsGuía de reintentos: Esta lectura se puede repetir y usa paginación por cursor para las páginas siguientes.
- 2
Recupera el CFDI
Usa la referencia opaca de CFDI devuelta por la colección.
REST · Producción y pruebaGET /v1/invoices/invoice:invoice-exampleMCP · Solo producciónget_documentGuía de reintentos: Las lecturas se pueden repetir y no necesitan idempotency key.
- 3
Descarga el PDF
La ruta REST devuelve un adjunto; la herramienta MCP devuelve un recurso binario.
REST · Producción y pruebaGET /v1/documents/invoice:invoice-example/files/pdfMCP · Solo producciónget_document_fileGuía de reintentos: Las lecturas de archivos se pueden repetir y no necesitan idempotency key.
- 4
Descarga el XML
Usa el mismo documentRef para recuperar el XML fiscal cuando esté disponible.
REST · Producción y pruebaGET /v1/documents/invoice:invoice-example/files/xmlMCP · Solo producciónget_document_fileGuía de reintentos: Las lecturas de archivos se pueden repetir y no necesitan idempotency key.
{ "steps": [ { "id": "search-cfdis", "rest": { "operationId": "listInvoices", "method": "GET", "path": "/v1/invoices", "environments": [ "production", "sandbox" ], "query": { "kind": "income", "status": "valid", "dateFrom": "2026-01-01", "dateTo": "2026-01-31", "limit": 20 } }, "mcp": { "tool": "search_documents", "arguments": { "input": { "category": "invoice", "kind": "income", "status": "valid", "dateFrom": "2026-01-01", "dateTo": "2026-01-31", "limit": 20 } }, "environments": [ "production" ] } }, { "id": "get-cfdi", "rest": { "operationId": "getInvoice", "method": "GET", "path": "/v1/invoices/invoice:invoice-example", "environments": [ "production", "sandbox" ] }, "mcp": { "tool": "get_document", "arguments": { "documentRef": "invoice:invoice-example" }, "environments": [ "production" ] } }, { "id": "download-pdf", "rest": { "operationId": "downloadDocumentFile", "method": "GET", "path": "/v1/documents/invoice:invoice-example/files/pdf", "environments": [ "production", "sandbox" ] }, "mcp": { "tool": "get_document_file", "arguments": { "documentRef": "invoice:invoice-example", "file": "pdf" }, "environments": [ "production" ] } }, { "id": "download-xml", "rest": { "operationId": "downloadDocumentFile", "method": "GET", "path": "/v1/documents/invoice:invoice-example/files/xml", "environments": [ "production", "sandbox" ] }, "mcp": { "tool": "get_document_file", "arguments": { "documentRef": "invoice:invoice-example", "file": "xml" }, "environments": [ "production" ] } } ]}Consulta al SAT el estado actual de un CFDI timbrado en producción después de una respuesta asíncrona o un resultado incierto. Este flujo no admite retenciones. Los documentos de prueba y simulados no se consultan ante el SAT; lee su estado almacenado.
- 1
Actualiza el estado ante el SAT
La actualización requiere datos de verificación capturados del XML fiscal y concilia el estado local.
REST · Solo producciónPOST /v1/invoices/invoice:invoice-example/status/refreshMCP · Solo producciónrefresh_invoice_statusGuía de reintentos: Reutiliza la misma clave para la misma observación del documento; es una lectura externa que cambia estado.
- 2
Lee el documento conciliado
Obtén el documento de nuevo para consumir el estado local canónico y la proyección de cancelación.
REST · Producción y pruebaGET /v1/invoices/invoice:invoice-exampleMCP · Solo producciónget_documentGuía de reintentos: Las lecturas se pueden repetir y no necesitan idempotency key.
{ "steps": [ { "id": "refresh-cfdi-status", "rest": { "operationId": "refreshInvoiceStatus", "method": "POST", "path": "/v1/invoices/invoice:invoice-example/status/refresh", "environments": [ "production" ], "headers": { "Idempotency-Key": "workflow-refresh-cfdi-status" }, "body": {} }, "mcp": { "tool": "refresh_invoice_status", "arguments": { "documentRef": "invoice:invoice-example", "idempotencyKey": "workflow-refresh-cfdi-status" }, "environments": [ "production" ] } }, { "id": "read-reconciled-cfdi", "rest": { "operationId": "getInvoice", "method": "GET", "path": "/v1/invoices/invoice:invoice-example", "environments": [ "production", "sandbox" ] }, "mcp": { "tool": "get_document", "arguments": { "documentRef": "invoice:invoice-example" }, "environments": [ "production" ] } } ]}Consulta por separado los agregados CFDI ya sincronizados y los totales autorizados de declaraciones.
- 1
Consulta los agregados CFDI
Los totales CFDI excluyen ventas de recibos/POS y son distintos de los totales fiscales declarados.
REST · Producción y pruebaGET /v1/reports/income-expensesMCP · Solo producciónget_income_expenses_summaryGuía de reintentos: Este reporte es de solo lectura y se puede repetir.
- 2
Consulta los totales declarados
Los totales fiscales provienen únicamente de declaraciones analizadas; si no están disponibles permanecen como null y no se estiman.
REST · Solo producciónGET /v1/reports/taxesMCP · Solo producciónget_tax_summaryGuía de reintentos: Este reporte es de solo lectura y se puede repetir.
{ "steps": [ { "id": "read-cfdi-summary", "rest": { "operationId": "getIncomeExpensesReport", "method": "GET", "path": "/v1/reports/income-expenses", "environments": [ "production", "sandbox" ], "query": { "fiscalYear": 2026, "period": 1 } }, "mcp": { "tool": "get_income_expenses_summary", "arguments": { "fiscalYear": 2026, "period": 1 }, "environments": [ "production" ] } }, { "id": "read-tax-summary", "rest": { "operationId": "getTaxReport", "method": "GET", "path": "/v1/reports/taxes", "environments": [ "production" ], "query": { "fiscalYear": 2026 } }, "mcp": { "tool": "get_tax_summary", "arguments": { "fiscalYear": 2026 }, "environments": [ "production" ] } } ]}