01Inicio rápido
De la key a tu primer CFDI de prueba en cuatro pasos. Todo el inicio se hace con una key de prueba: el ticket no se lee, no entra a ningún portal y no toca tu saldo.
Pide acceso
Escríbenos y activamos tu empresa en Enterprise. Te mandamos dos keys, una
fk_test_para integrar y unafk_live_para producción, y damos de alta tus URLs https para los webhooks, una de prueba y otra de producción, cada una con su propio secreto.Busca el id de tu constancia
Cada ticket se factura con una constancia (RFC) de tu empresa. Guarda su
id.GET /companies curl https://facturin.mx/api/v1/companies \ -H "Authorization: Bearer $FACTURIN_KEY"Crea un ticket
Manda la foto. La respuesta llega en cuanto el ticket existe:
202constatus: "processing".POST /tickets curl https://facturin.mx/api/v1/tickets \ -H "Authorization: Bearer $FACTURIN_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -F image=@ticket.jpg \ -F companyId=6720b1f4c2a9e81d4f0a1b2c \ -F externalId=VIAJE-2026-10-20-0042Recibe el webhook
Unos 30 segundos después llega
ticket.invoiceda tu URL de prueba, con el ticket completo y un CFDI de ejemplo sin validez fiscal. Verifica la firma (sección 6) y responde200. Si todavía no tienes la URL, consultaGET /tickets/{id}hasta questatusdeje de serprocessing.
02Autenticación
Cada petición lleva tu key en el header Authorization: Bearer fk_live_…. La key es de tu empresa, no de una persona: con ella ves los tickets y las constancias de tu empresa y nada más. Un ticket de otra empresa responde 404, igual que uno que no existe.
- Live y prueba.
fk_live_…crea tickets reales: entramos al portal y se cobran.fk_test_…crea tickets simulados (sección 11). La URL es la misma; la key decide el modo, y un modo no ve los tickets del otro. - Se muestra una sola vez. Guardamos solo una huella de la key, así que no podemos volver a mostrártela. Tenla en tu servidor (una variable de entorno), nunca en una app móvil o en el navegador.
- Rotación. Pídenos una key nueva, cámbiala en tu sistema y avísanos para revocar la anterior. Mientras tanto funcionan las dos.
- Revocación. Es inmediata: la siguiente petición con esa key recibe
401. Lo mismo pasa con todas las keys si tu empresa deja el plan Enterprise. - Un solo error. Key ausente, mal escrita o revocada responden igual:
401 invalid_key. Tras 20 intentos fallidos en un minuto, esa IP recibe429el resto del minuto.
03Crear un ticket
POST /tickets crea un ticket por foto, y cada foto debe traer un solo comprobante. La imagen llega de una de dos formas, exactamente una:
- Multipart, con el archivo en el campo
image(como en el inicio rápido), para fotos de hasta 4.5 MB: es el tamaño máximo de petición que acepta nuestra plataforma. Una petición más grande la rechaza ella misma con413, antes de llegar a la API y sin nuestro formato de error. - JSON con
imageUrl: una URL https pública, en el puerto por defecto y sin usuario ni contraseña. La descargamos en máximo 10 segundos, siguiendo hasta 3 redirecciones, y debe responder con la imagen misma. Admite fotos de hasta 10 MB, así que es el camino para cualquier foto de más de 4.5 MB. Una liga firmada de S3 o R2 funciona si vive al menos un par de minutos.
La imagen puede ser JPEG, PNG, WebP o HEIC. Se reconoce por su contenido, no por su extensión; un PDF se rechaza.
curl https://facturin.mx/api/v1/tickets \
-H "Authorization: Bearer $FACTURIN_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"imageUrl": "https://archivos.ejemplo.mx/casetas/foto-8812.jpg",
"companyId": "6720b1f4c2a9e81d4f0a1b2c",
"usoCFDI": "G03",
"externalId": "VIAJE-2026-10-20-0042",
"metadata": { "unidad": "T-114", "operador": "J. Pérez" }
}'| Campo | Qué es |
|---|---|
| companyId | La constancia con la que se factura, de GET /companies. Si tu empresa tiene una sola constancia activa puedes omitirlo y se usa esa; con varias es obligatorio (400 company_required). Nunca se usa una constancia de otra empresa. |
| usoCFDI | Clave c_UsoCFDI. Si no la mandas es G03. Si ningún régimen de tu constancia admite el uso que pediste, se timbra con S01. |
| formaPago | Clave c_FormaPago. Si el ticket imprime la forma de pago sin ambigüedad, gana la del ticket; la tuya decide cuando el ticket solo dice “tarjeta”. |
| externalId | Tu propio id (viaje, pedido, gasto), hasta 128 caracteres, guardado tal cual. Es único por empresa y modo: repetirlo responde 409 external_id_exists. Búscalo con GET /tickets?externalId=. |
| metadata | Tus datos, en un objeto plano de texto, número o booleano, hasta 4 KB. Regresa tal cual en el ticket y en cada webhook. En multipart va como texto JSON. |
| emailNotifications | true para que al dueño de tu empresa también le llegue un correo cuando el ticket se facture o se cierre. Por defecto es false: tu sistema se entera por webhook y nadie recibe un correo por cada ticket. En multipart va como texto true o false. |
Si la petición se rechaza (cualquier 4xx), no se creó ningún ticket ni se apartó nada de tu saldo. Las constancias se dan de alta en tu cuenta de Facturín.
04Estados y motivos de cierre
Un ticket está en uno de tres estados:
| status | Qué significa |
|---|---|
| processing | Lo estamos leyendo o facturando. Si algo se atora (una foto difícil, un portal caído), lo resolvemos nosotros; no tienes que hacer nada. |
| invoiced | Timbrado. cfdi trae los datos del XML y las ligas a los archivos. |
| closed | Cerrado sin CFDI de Facturín. reason dice por qué y reasonText lo explica en español, listo para mostrarlo. Casi siempre es final; si después llega el CFDI (por ejemplo, el comercio lo manda tarde), el ticket pasa a invoiced y te llega ticket.invoiced con otro id. |
invoiced es definitivo. Un ticket closed casi siempre también: si después del cierre el comercio llega a entregar el CFDI, el ticket pasa a invoiced. Un ticket cerrado nunca se cobra.
Para conciliar, lista con GET /tickets?status=invoiced&from=2026-10-01&to=2026-10-31. from y to filtran la fecha del comprobante (extracted.date, la que leímos del ticket), no la fecha en que lo creaste. Un ticket cuya fecha todavía no se lee no aparece en un filtro por fecha: búscalo por externalId o sin fechas.
Motivos de cierre
| reason | Qué pasó | Qué hacer |
|---|---|---|
| already_invoiced | El comprobante ya estaba facturado: en otro ticket tuyo (possibleDuplicateOf trae su id) o por otro medio. | Si viene possibleDuplicateOf, el CFDI está en ese ticket. Este no se cobra. |
| unreadable | No alcanzamos a leer un dato que el portal pide. Cuando lo sabemos, reasonText dice cuál. | Toma otra foto (completa, enfocada, sin reflejos) y créala como ticket nuevo, con otro externalId o sin él: el anterior sigue ocupado. |
| missing_csf | Faltaba la constancia de situación fiscal con la que se iba a facturar. | Da de alta o actualiza la constancia en tu cuenta y vuelve a crear el ticket. |
| period_closed | El portal del comercio ya no acepta el comprobante: su periodo de facturación cerró. | Con esa fecha ya no se puede timbrar. Manda los tickets lo antes posible; cada comercio pone su propio plazo. |
| not_invoiceable | El comercio no ofrece facturación en línea para este comprobante. | No hay nada que reintentar. Si necesitas el CFDI, pídelo directo al comercio. |
| other | No fue posible generar el CFDI por otra causa. Es también el motivo de un ticket que cerramos a las 48 horas sin una causa más precisa. | Si se repite con el mismo comercio, escríbenos con el id del ticket. |
05El objeto CFDI
Cuando el ticket está invoiced, cfdi trae lo que dice el XML timbrado, no lo que leímos en la foto. Es lo que va a tu contabilidad. Un dato que el XML no trae llega en null.
| Campo | De dónde sale |
|---|---|
| uuid | Folio fiscal: el UUID del timbre (TimbreFiscalDigital), en mayúsculas. |
| fecha | Atributo Fecha del comprobante, tal cual: hora local de México, sin zona horaria (2026-10-20T18:01:02). |
| rfcEmisor | RFC del comercio que timbró. |
| nombreEmisor | Nombre o razón social del emisor. |
| serie | Serie del comprobante, si el comercio la usa. |
| folio | Folio del comprobante, si el comercio lo usa. |
| subtotal | SubTotal del comprobante. |
| iva | IVA trasladado (impuesto 002). 0 cuando el CFDI no traslada IVA, como algunas casetas. |
| total | Total del comprobante. |
| xmlUrl | Liga a GET /tickets/{id}/cfdi/xml. Se descarga con tu key. |
| pdfUrl | Liga a GET /tickets/{id}/cfdi/pdf. Se descarga con tu key. |
Los archivos se descargan por la API con tu key: GET /tickets/{id}/cfdi/xml y /cfdi/pdf. La respuesta es el archivo mismo (200 con application/xml o application/pdf), no una redirección: no hay una liga que caduque ni que se pueda compartir sin tu key. extracted, en cambio, es lo que leímos de la foto: sirve para cruzar el ticket con tu sistema, no para tus libros.
{
"id": "6720b2a1c2a9e81d4f0a1b9f",
"livemode": true,
"status": "invoiced",
"reason": null,
"reasonText": null,
"externalId": "VIAJE-2026-10-20-0042",
"metadata": {
"unidad": "T-114",
"operador": "J. Pérez",
"caseta": 3
},
"emailNotifications": false,
"companyId": "6720b1f4c2a9e81d4f0a1b2c",
"createdAt": "2026-10-20T23:58:11.000Z",
"updatedAt": "2026-10-21T00:04:37.000Z",
"extracted": {
"merchantName": "ESCUELA KEMPER URGATE",
"rfcEmisor": "EKU9003173C9",
"folio": "88120457",
"date": "2026-10-20",
"subtotal": 107.76,
"total": 125
},
"cfdi": {
"uuid": "5F1E9A3C-2B7D-4C1A-9E8F-0A1B2C3D4E5F",
"fecha": "2026-10-20T18:01:02",
"rfcEmisor": "EKU9003173C9",
"nombreEmisor": "ESCUELA KEMPER URGATE",
"serie": "A",
"folio": "88120457",
"subtotal": 107.76,
"iva": 17.24,
"total": 125,
"xmlUrl": "https://facturin.mx/api/v1/tickets/6720b2a1c2a9e81d4f0a1b9f/cfdi/xml",
"pdfUrl": "https://facturin.mx/api/v1/tickets/6720b2a1c2a9e81d4f0a1b9f/cfdi/pdf"
},
"possibleDuplicateOf": null,
"charged": true
}06Webhooks
Cuando un ticket que creaste por la API termina, mandamos un POST con JSON a la URL que diste de alta para ese modo (live o prueba). Hay dos eventos de desenlace, y uno de actualización:
ticket.invoiced: se timbró. El ticket traecfdi.ticket.closed: se cerró sin CFDI, con sureason. Incluye un comprobante que ya estaba facturado (already_invoiced, también cuando era un duplicado de otro ticket tuyo) y los tickets que cerramos a las 48 horas (sección 10).ticket.updated: un ticket que ya llegó comoinvoicedsin XML recibió su XML después. Trae el ticket completo; no es un desenlace nuevo.
{
"id": "evt_5649ac7c641341885368bc5a7036e8e0",
"type": "ticket.invoiced",
"createdAt": "2026-10-21T00:04:38.000Z",
"data": { "id": "6720b2a1c2a9e81d4f0a1b9f", "status": "invoiced", "cfdi": { … }, … }
}data es el ticket completo, igual que en GET /tickets/{id}. Cada desenlace de un ticket es un evento, una sola vez. Si el desenlace cambia después (por ejemplo, el comercio entrega el CFDI de un ticket ya cerrado), llega otro evento con otro id. El orden de llegada no está garantizado; ante la duda, consulta el ticket.
Cuando el XML llega después del PDF
Algunos portales entregan primero el PDF y el XML después. Como fecha, subtotal, iva y xmlUrl salen del XML, ticket.invoiced espera al XML hasta 2 horas; casi siempre llega en segundos. Si no llega en ese tiempo, el evento sale sin él: esos campos vienen en null. Si el XML llega más tarde, te llega ticket.updated con el ticket completo: actualiza tu registro con él. No es un desenlace nuevo (sigue en invoiced) y no se cobra de nuevo.
Entrega y reintentos
Responde con cualquier 2xx en menos de 10 segundos. Cualquier otra respuesta, una redirección incluida, o ninguna, cuenta como fallo, y reintentamos a los 2 min, 10 min, 30 min, 1 h, 2 h, 4 h, 8 h, 8 h: 9 intentos en unas 24 horas. Cada reintento manda el mismo cuerpo con el mismo id (solo cambia el t del header): guarda el id y no proceses dos veces el mismo evento. Responde primero y procesa después.
Si fallan todos los intentos, la entrega queda registrada como fallida y podemos reenviarla con el mismo id cuando tu endpoint vuelva: escríbenos si estuvo caído. Lo mismo con una entrega que se atore de nuestro lado. Mientras tanto, GET /tickets siempre tiene el estado actual: úsalo para conciliar lo que no te llegó.
Tu URL debe ser https, en el puerto por defecto, sin usuario ni contraseña, y apuntar a una dirección pública; la revisamos en cada intento. Las peticiones llegan con User-Agent: Facturin-Webhooks/1 (+https://facturin.mx). Si filtras por ese header, en tu firewall o en tu receptor, compara solo el inicio, Facturin-Webhooks/: la versión y el resto pueden cambiar. Lo que prueba que un webhook es nuestro es la firma.
Verificar la firma
Cada webhook trae el header Facturin-Signature con un t y uno o más v1: uno normalmente, y dos en las 24 horas después de una rotación del secreto.
# Normalmente
t=1761001382,v1=8f2b1c0a5d7e…
# Las 24 horas después de rotar el secreto: un v1 con el nuevo y otro con el anterior
t=1761001382,v1=8f2b1c0a5d7e…,v1=3c9d7e15a0b4…Cada v1 es el HMAC-SHA256, en hexadecimal, de <t>.<cuerpo> con un secreto de tu endpoint. Calcúlalo sobre el cuerpo crudo, tal como llegó: si lo conviertes a objeto y de vuelta a texto, ya no coincide. Junta todos los v1 del header y acepta la petición si cualquiera coincide con tu secreto; no escribas un parser que espere exactamente uno. Compara en tiempo constante y rechaza un t con más de 5 minutos de diferencia. Los tres ejemplos ya lo hacen.
import crypto from "node:crypto";
// rawBody: el cuerpo tal como llegó (Buffer o string), antes de JSON.parse.
// Tras rotar el secreto, el header trae un v1 por secreto: basta con que uno coincida.
export function verifyFacturinSignature(rawBody, header, secret, toleranceSeconds = 300) {
let t = null;
const signatures = [];
for (const part of String(header || "").split(",")) {
const [key, value = "", extra] = part.trim().split("=");
if (extra !== undefined) return false;
if (key === "t") {
if (t !== null || !/^\d{1,12}$/.test(value)) return false;
t = Number(value);
} else if (key === "v1" && /^[0-9a-f]{64}$/.test(value)) {
signatures.push(Buffer.from(value, "hex"));
}
// Otros esquemas (un v2 futuro) se ignoran.
}
if (t === null || signatures.length === 0) return false;
if (Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${t}.`)
.update(rawBody)
.digest();
return signatures.some((signature) => crypto.timingSafeEqual(expected, signature));
}// Express: el cuerpo crudo, no express.json().
app.post("/webhooks/facturin", express.raw({ type: "application/json" }), (req, res) => {
const ok = verifyFacturinSignature(
req.body,
req.get("Facturin-Signature"),
process.env.FACTURIN_WEBHOOK_SECRET
);
if (!ok) return res.sendStatus(400);
const event = JSON.parse(req.body);
// event.id se repite en cada reintento: úsalo para no procesar dos veces.
res.sendStatus(200);
});import hashlib
import hmac
import re
import time
def verify_facturin_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
"""raw_body: el cuerpo tal como llegó, en bytes, antes de json.loads.
Tras rotar el secreto, el header trae un v1 por secreto: basta con que uno coincida."""
t = None
signatures = []
for part in (header or "").split(","):
kv = part.strip().split("=")
if len(kv) > 2:
return False
key, value = kv[0], (kv[1] if len(kv) == 2 else "")
if key == "t":
if t is not None or not re.fullmatch(r"[0-9]{1,12}", value):
return False
t = int(value)
elif key == "v1" and re.fullmatch(r"[0-9a-f]{64}", value):
signatures.append(value)
# Otros esquemas (un v2 futuro) se ignoran.
if t is None or not signatures:
return False
if abs(time.time() - t) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(expected, signature) for signature in signatures)# Flask
@app.post("/webhooks/facturin")
def facturin_webhook():
if not verify_facturin_signature(
request.get_data(), request.headers.get("Facturin-Signature", ""), os.environ["FACTURIN_WEBHOOK_SECRET"]
):
abort(400)
event = request.get_json()
# event["id"] se repite en cada reintento: úsalo para no procesar dos veces.
return "", 200<?php
// $rawBody: el cuerpo tal como llegó, antes de json_decode.
// Tras rotar el secreto, el header trae un v1 por secreto: basta con que uno coincida.
function verify_facturin_signature(string $rawBody, string $header, string $secret, int $tolerance = 300): bool
{
$t = null;
$signatures = [];
foreach (explode(',', $header) as $part) {
$kv = explode('=', trim($part));
if (count($kv) > 2) {
return false;
}
$key = $kv[0];
$value = $kv[1] ?? '';
if ($key === 't') {
if ($t !== null || !preg_match('/^[0-9]{1,12}$/D', $value)) {
return false;
}
$t = (int) $value;
} elseif ($key === 'v1' && preg_match('/^[0-9a-f]{64}$/D', $value)) {
$signatures[] = $value;
}
// Otros esquemas (un v2 futuro) se ignoran.
}
if ($t === null || count($signatures) === 0) {
return false;
}
if (abs(time() - $t) > $tolerance) {
return false;
}
$expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
foreach ($signatures as $signature) {
if (hash_equals($expected, $signature)) {
return true;
}
}
return false;
}$rawBody = file_get_contents('php://input');
$header = $_SERVER['HTTP_FACTURIN_SIGNATURE'] ?? '';
if (!verify_facturin_signature($rawBody, $header, getenv('FACTURIN_WEBHOOK_SECRET'))) {
http_response_code(400);
exit;
}
$event = json_decode($rawBody, true);
// $event['id'] se repite en cada reintento: úsalo para no procesar dos veces.
http_response_code(200);Rotación del secreto
Pídenos un secreto nuevo cuando lo necesites. Durante las 24 horas siguientes, los dos secretos firman cada webhook: el header trae un v1 con el secreto nuevo y otro con el anterior. Así funciona tu receptor con cualquiera de los dos, siempre que acepte la petición cuando cualquier v1 coincida con su secreto.
Cambia al secreto nuevo dentro de esas 24 horas. Después solo firma el nuevo, y un receptor que siga con el anterior rechazará todos los webhooks.
Si rotamos otra vez antes de que pasen esas 24 horas, el secreto más viejo deja de firmar de inmediato: solo quedan el más nuevo y el inmediatamente anterior.
Los webhooks de modo prueba van a tu URL de prueba, firmados con el secreto de esa URL y con los mismos reintentos.
07Idempotencia y duplicados
Son dos problemas distintos, y la API resuelve cada uno a su manera.
Un reintento de red
Tu petición se cortó y no sabes si llegó. Manda en cada POST un header Idempotency-Key con un valor nuevo (un UUID) y repite la petición con el mismo valor:
- Misma llave y mismo cuerpo: regresa el mismo ticket con
200y no se crea nada. - Misma llave con otro cuerpo:
409 idempotency_conflict. - La primera todavía se está procesando:
409 idempotency_in_progress; reintenta en unos segundos.
La llave dura 24 horas. externalId también te protege: un segundo ticket con el mismo valor responde 409 external_id_exists con el ticketId del primero.
El mismo comprobante subido dos veces
Dos fotos del mismo ticket, quizá de dos personas distintas, no se rechazan: se crean los dos. El portal nunca timbra dos veces el mismo comprobante. Mientras el otro ticket sigue en proceso, el segundo se queda en processing. Si el otro se timbra, el segundo termina en closed con already_invoiced y no se cobra; si el otro no se pudo facturar, el segundo se procesa normal y puede ser el que se timbre. possibleDuplicateOf te señala el otro ticket; es una pista, no un estado, porque la detección no es infalible.
08Errores
Todos los errores tienen la misma forma:
{
"error": {
"code": "external_id_exists",
"message": "Ya existe un ticket con este externalId.",
"ticketId": "6720b2a1c2a9e81d4f0a1b9f"
}
}Decide con code, que no cambia. message es para el log y su redacción puede cambiar. Si llega un código que no conoces, decide por el status: un 4xx no se arregla reintentando la misma petición (salvo 429 e idempotency_in_progress); un 5xx sí, con espera.
| code | HTTP | Qué significa |
|---|---|---|
| unsupported_content_type | 400 | Manda multipart/form-data (con image) o application/json (con imageUrl). |
| invalid_body | 400 | El cuerpo no se pudo leer, no es un objeto JSON, o un campo de texto llegó como archivo. |
| invalid_json | 400 | El cuerpo no es JSON válido. |
| invalid_idempotency_key | 400 | Idempotency-Key debe ser texto ASCII imprimible de 1 a 255 caracteres. |
| invalid_company_id | 400 | companyId no tiene forma de id. Tómalo de GET /companies. |
| company_required | 400 | Tu empresa tiene varias constancias y no mandaste companyId. Elige una de GET /companies. No se creó el ticket. |
| invalid_uso_cfdi | 400 | usoCFDI no es una clave del catálogo c_UsoCFDI del SAT. |
| invalid_forma_pago | 400 | formaPago no es una clave del catálogo c_FormaPago del SAT. |
| invalid_external_id | 400 | externalId debe ser texto de 1 a 128 caracteres. |
| invalid_metadata | 400 | metadata debe ser un objeto plano de texto, número o booleano, de hasta 4 KB. |
| invalid_email_notifications | 400 | emailNotifications debe ser true o false (en multipart, el texto true o false). |
| invalid_simulate | 400 | Solo con una key de prueba: metadata.simulate debe ser invoiced o closed:<reason>, escrito exacto y en minúsculas. No se creó el ticket. |
| invalid_image_url | 400 | imageUrl debe ser texto. |
| image_required | 400 | Manda la foto como archivo image o como imageUrl: exactamente una de las dos. |
| invalid_limit | 400 | limit debe ser un entero de 1 a 100. |
| invalid_status | 400 | status debe ser processing, invoiced o closed. |
| invalid_date | 400 | from y to deben ser fechas reales AAAA-MM-DD. |
| invalid_cursor | 400 | cursor no es válido. Usa el nextCursor de la página anterior, sin modificarlo. |
| invalid_cfdi_type | 400 | El archivo es xml o pdf. |
| invalid_key | 401 | Falta la key, está mal escrita, fue revocada o tu empresa ya no tiene acceso a la API. Revisa el header Authorization. |
| no_credits | 402 | Tu empresa no tiene tickets disponibles en este periodo. No se creó el ticket. Una key de prueba no usa saldo y nunca lo recibe. |
| company_not_found | 404 | companyId no es una constancia activa de tu empresa. |
| ticket_not_found | 404 | No existe un ticket con ese id para tu key (otra empresa, el otro modo o un id que nunca existió responden igual). |
| cfdi_not_available | 404 | El ticket es tuyo pero no está invoiced, o no tiene ese archivo. |
| idempotency_conflict | 409 | Esa Idempotency-Key ya se usó con otra petición. Usa una llave nueva para cada petición distinta. |
| idempotency_in_progress | 409 | La primera petición con esa llave todavía se está procesando. Reintenta en unos segundos. |
| external_id_exists | 409 | Ya existe un ticket con ese externalId; el error trae su ticketId. Consúltalo en vez de crear otro. |
| image_too_large | 413 | La imagen pesa más de 10 MB. |
| image_invalid | 422 | La imagen no es JPEG, PNG, WebP ni HEIC (se revisa el contenido, no la extensión). |
| image_fetch_failed | 422 | No pudimos descargar imageUrl: debe ser una URL https pública que responda con la imagen en 10 segundos. |
| no_company | 422 | Tu empresa no tiene una constancia activa todavía. Pídenos darla de alta. No se creó el ticket. |
| rate_limited | 429 | Pasaste tu límite por minuto, o tu IP acumuló intentos con una key inválida. Espera los segundos de Retry-After. |
| internal_error | 500 | Error nuestro. Reintenta con espera; con Idempotency-Key el reintento de un POST es seguro. |
| service_unavailable | 503 | No pudimos verificar tu key o tu límite y por seguridad no dejamos pasar la petición. Reintenta después de Retry-After. |
09Límites
| Qué | Límite |
|---|---|
| Peticiones por key | 60 por minuto |
| Tickets creados por key | 30 por minuto, dentro de las anteriores |
| Intentos con key inválida por IP | 20 por minuto |
Imagen por imageUrl | 10 MB |
| Imagen por multipart | 4.5 MB la petición completa (límite de la plataforma) |
| Formatos de imagen | JPEG, PNG, WebP o HEIC |
metadata | 4 KB serializado |
externalId | 128 caracteres |
Idempotency-Key | 255 caracteres, vale 24 h |
| Tickets por página | 20 por defecto, hasta 100 |
Si tus fotos pueden pasar de 4.5 MB, mándalas por imageUrl. Una petición multipart más grande no llega a la API: la plataforma responde 413 sin el formato { error }, así que tu cliente no encontrará ahí un code.
Los límites por minuto son ventanas fijas. Cada respuesta trae RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset (segundos para la siguiente ventana). Al pasarte recibes 429 rate_limited con Retry-After. Si tu volumen necesita más, lo subimos para tu key.
Si en un momento no podemos verificar tu límite, la petición no pasa: recibes 503 service_unavailable con Retry-After. Reintenta.
10Cobro y tiempo de respuesta
- Se cobra por ticket timbrado. Al empezar a facturar apartamos un ticket de tu saldo, y solo se descuenta cuando el CFDI se entrega; si no se timbra, regresa.
chargedestruesolo cuando ese lugar ya se consumió: mientras el ticket se factura, o si no se timbró, esfalse. - Un comprobante, un ticket. Un viaje con ocho casetas son ocho tickets: cada comprobante se factura por separado en el portal y se cobra por separado. Si una foto trae más de un comprobante, solo se factura el principal, así que fotografía cada uno aparte.
- Sin saldo no se crea. Si tu empresa no tiene tickets disponibles, el
POSTresponde402 no_creditsy no crea nada. Una key de prueba no usa saldo.
Respuesta en 48 horas
Todo ticket live tiene respuesta en 48 horas desde que lo creas: o se timbró, o lo cerramos con su motivo. Si a las 36 horas sigue en processing, nuestro equipo lo atiende antes que los demás. Si a las 48 horas no se pudo timbrar, lo cerramos con el motivo más preciso que podamos comprobar, te devolvemos el ticket apartado de tu saldo y te llega un solo ticket.closed.
Tres casos siguen en processing después de las 48 horas, porque cerrarlos te diría que no hay CFDI cuando uno existe o puede venir en camino:
- El CFDI ya se pidió. El portal lo timbró y lo manda por correo, o se lo pedimos a una persona del comercio. El correo de un portal lo esperamos minutos; a una persona, hasta 5 días. Si llega, el ticket pasa a
invoiced. - El CFDI se timbró pero no nos llegó el archivo. El portal ya lo generó con tu RFC, así que nunca lo cerramos como “sin factura”: nuestro equipo recupera el archivo y el ticket pasa a
invoiced. - Estamos en el portal en ese momento. Esperamos a que termine ese intento: si timbra, el ticket pasa a
invoiced; si no, se cierra. Si un intento deja de dar señales por más de una hora sin haber timbrado, lo damos por perdido y el ticket se cierra con su motivo.
Los tickets de prueba no corren contra este plazo y nunca se cobran. Precios y planes en /precios.
11Modo prueba
Con una key fk_test_ usas la misma URL, los mismos endpoints y los mismos objetos, con livemode: false. La petición pasa por las mismas validaciones y responde los mismos errores que en live, así que también puedes probar tu manejo de errores. Lo que cambia: el ticket no se lee, no entra a ningún portal y no toca tu saldo.
Unos 30 segundos después de crearlo, el ticket toma el desenlace que pidas en metadata.simulate y te llega el webhook real a tu URL de prueba, firmado con el secreto de esa URL y con los mismos reintentos que en live.
| simulate | Resultado |
|---|---|
| invoiced | invoiced, con un CFDI de ejemplo. Es el valor si no mandas simulate. |
| closed:already_invoiced | closed con reason: "already_invoiced". |
| closed:unreadable | closed con reason: "unreadable". |
| closed:missing_csf | closed con reason: "missing_csf". |
| closed:period_closed | closed con reason: "period_closed". |
| closed:not_invoiceable | closed con reason: "not_invoiceable". |
| closed:other | closed con reason: "other". |
Escribe el valor exacto, en minúsculas. Cualquier otro responde 400 invalid_simulate y no crea el ticket. simulate se queda en tu metadata como cualquier otro dato, y con una key live no cambia nada.
curl https://facturin.mx/api/v1/tickets \
-H "Authorization: Bearer $FACTURIN_TEST_KEY" \
-F image=@ticket.jpg \
-F companyId=6720b1f4c2a9e81d4f0a1b2c \
-F 'metadata={"simulate": "closed:unreadable"}'- El CFDI de ejemplo no tiene validez fiscal, y el XML y el PDF lo dicen. Emisor y receptor llevan el RFC genérico
XAXX010101000, y los importes son siempre los mismos: subtotal 100, IVA 16 y total 116. Eluuidcambia en cada ticket. Los archivos se descargan con/cfdi/xmly/cfdi/pdf, como los reales. extractedllega con todo ennull, porque la foto no se lee, ychargedsiempre esfalse.- Los modos no se cruzan: una key de prueba no ve tickets reales, ni al revés, y los tickets de prueba no aparecen en tu cuenta de Facturín.
externalIdeIdempotency-Keytambién van por separado. Las constancias sí son las mismas. - Los tickets de prueba se borran, con sus archivos, después de 30 días.
{
"id": "6720b2a1c2a9e81d4f0a1c07",
"livemode": false,
"status": "invoiced",
"reason": null,
"reasonText": null,
"externalId": "PRUEBA-0001",
"metadata": {
"unidad": "T-114"
},
"emailNotifications": false,
"companyId": "6720b1f4c2a9e81d4f0a1b2c",
"createdAt": "2026-10-20T23:58:11.000Z",
"updatedAt": "2026-10-20T23:58:41.000Z",
"extracted": {
"merchantName": null,
"rfcEmisor": null,
"folio": null,
"date": null,
"subtotal": null,
"total": null
},
"cfdi": {
"uuid": "CDC2E049-6169-45D5-B18F-602801596143",
"fecha": "2026-10-20T17:58:41",
"rfcEmisor": "XAXX010101000",
"nombreEmisor": "EMISOR DE PRUEBA - SIN VALIDEZ FISCAL",
"serie": "PRUEBA",
"folio": "4F0A1C07",
"subtotal": 100,
"iva": 16,
"total": 116,
"xmlUrl": "https://facturin.mx/api/v1/tickets/6720b2a1c2a9e81d4f0a1c07/cfdi/xml",
"pdfUrl": "https://facturin.mx/api/v1/tickets/6720b2a1c2a9e81d4f0a1c07/cfdi/pdf"
},
"possibleDuplicateOf": null,
"charged": false
}12Cambios
En /api/v1 un campo nunca se renombra ni se quita: solo se agregan campos y eventos nuevos. Ignora los que no conozcas.
1.0.0 · Octubre de 2026
- Primera versión: tickets por foto (multipart o
imageUrl), constancias y descarga del XML y el PDF. - Datos del CFDI leídos del XML timbrado: subtotal, IVA, fecha y emisor.
- Webhooks firmados
ticket.invoicedyticket.closed, con reintentos. Idempotency-Key,externalIdymetadata.- Modo prueba con keys
fk_test_: desenlace a elegir conmetadata.simulate, CFDI de ejemplo y webhooks firmados. - Respuesta en 48 horas para cada ticket live: timbrado, o cerrado con su motivo y el saldo devuelto.
¿Listo para integrar? Pide tus keys y te acompañamos en la primera prueba.