API de Facturín

Tu sistema manda la foto del ticket y recibe el CFDI timbrado: el XML, el PDF y los datos del XML (subtotal, IVA, fecha y emisor) listos para tu contabilidad, sin capturar nada a mano.

Acceso por solicitud para empresas con plan Enterprise. Versión 1.0.0, base https://facturin.mx/api/v1.

Descargas: openapi.json (OpenAPI 3.1) · colección para Postman o Bruno

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.

  1. Pide acceso

    Escríbenos y activamos tu empresa en Enterprise. Te mandamos dos keys, una fk_test_ para integrar y una fk_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.

  2. 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"
  3. Crea un ticket

    Manda la foto. La respuesta llega en cuanto el ticket existe: 202 con status: "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-0042
  4. Recibe el webhook

    Unos 30 segundos después llega ticket.invoiced a tu URL de prueba, con el ticket completo y un CFDI de ejemplo sin validez fiscal. Verifica la firma (sección 6) y responde 200. Si todavía no tienes la URL, consulta GET /tickets/{id} hasta que status deje de ser processing.

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 recibe 429 el 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 con 413, 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.

POST /tickets con imageUrl
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" }
  }'
Campos opcionales de POST /tickets
CampoQué es
companyIdLa 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.
usoCFDIClave 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.
formaPagoClave 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”.
externalIdTu 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=.
metadataTus 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.
emailNotificationstrue 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:

Estados de un ticket
statusQué significa
processingLo estamos leyendo o facturando. Si algo se atora (una foto difícil, un portal caído), lo resolvemos nosotros; no tienes que hacer nada.
invoicedTimbrado. cfdi trae los datos del XML y las ligas a los archivos.
closedCerrado 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

Motivos de cierre (reason)
reasonQué pasóQué hacer
already_invoicedEl 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.
unreadableNo 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_csfFaltaba 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_closedEl 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_invoiceableEl 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.
otherNo 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.

Campos del objeto cfdi
CampoDe dónde sale
uuidFolio fiscal: el UUID del timbre (TimbreFiscalDigital), en mayúsculas.
fechaAtributo Fecha del comprobante, tal cual: hora local de México, sin zona horaria (2026-10-20T18:01:02).
rfcEmisorRFC del comercio que timbró.
nombreEmisorNombre o razón social del emisor.
serieSerie del comprobante, si el comercio la usa.
folioFolio del comprobante, si el comercio lo usa.
subtotalSubTotal del comprobante.
ivaIVA trasladado (impuesto 002). 0 cuando el CFDI no traslada IVA, como algunas casetas.
totalTotal del comprobante.
xmlUrlLiga a GET /tickets/{id}/cfdi/xml. Se descarga con tu key.
pdfUrlLiga 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.

Un ticket timbrado
{
  "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 trae cfdi.
  • ticket.closed: se cerró sin CFDI, con su reason. 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ó como invoiced sin XML recibió su XML después. Trae el ticket completo; no es un desenlace nuevo.
Cuerpo de un webhook
{
  "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.

Facturin-Signature
# 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.

Node.js
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));
}
Node.js: uso
// 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);
});
Python
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)
Python: uso
# 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
<?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;
}
PHP: uso
$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 200 y 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:

409
{
  "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.

Códigos de error
codeHTTPQué significa
unsupported_content_type400Manda multipart/form-data (con image) o application/json (con imageUrl).
invalid_body400El cuerpo no se pudo leer, no es un objeto JSON, o un campo de texto llegó como archivo.
invalid_json400El cuerpo no es JSON válido.
invalid_idempotency_key400Idempotency-Key debe ser texto ASCII imprimible de 1 a 255 caracteres.
invalid_company_id400companyId no tiene forma de id. Tómalo de GET /companies.
company_required400Tu empresa tiene varias constancias y no mandaste companyId. Elige una de GET /companies. No se creó el ticket.
invalid_uso_cfdi400usoCFDI no es una clave del catálogo c_UsoCFDI del SAT.
invalid_forma_pago400formaPago no es una clave del catálogo c_FormaPago del SAT.
invalid_external_id400externalId debe ser texto de 1 a 128 caracteres.
invalid_metadata400metadata debe ser un objeto plano de texto, número o booleano, de hasta 4 KB.
invalid_email_notifications400emailNotifications debe ser true o false (en multipart, el texto true o false).
invalid_simulate400Solo 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_url400imageUrl debe ser texto.
image_required400Manda la foto como archivo image o como imageUrl: exactamente una de las dos.
invalid_limit400limit debe ser un entero de 1 a 100.
invalid_status400status debe ser processing, invoiced o closed.
invalid_date400from y to deben ser fechas reales AAAA-MM-DD.
invalid_cursor400cursor no es válido. Usa el nextCursor de la página anterior, sin modificarlo.
invalid_cfdi_type400El archivo es xml o pdf.
invalid_key401Falta la key, está mal escrita, fue revocada o tu empresa ya no tiene acceso a la API. Revisa el header Authorization.
no_credits402Tu 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_found404companyId no es una constancia activa de tu empresa.
ticket_not_found404No existe un ticket con ese id para tu key (otra empresa, el otro modo o un id que nunca existió responden igual).
cfdi_not_available404El ticket es tuyo pero no está invoiced, o no tiene ese archivo.
idempotency_conflict409Esa Idempotency-Key ya se usó con otra petición. Usa una llave nueva para cada petición distinta.
idempotency_in_progress409La primera petición con esa llave todavía se está procesando. Reintenta en unos segundos.
external_id_exists409Ya existe un ticket con ese externalId; el error trae su ticketId. Consúltalo en vez de crear otro.
image_too_large413La imagen pesa más de 10 MB.
image_invalid422La imagen no es JPEG, PNG, WebP ni HEIC (se revisa el contenido, no la extensión).
image_fetch_failed422No pudimos descargar imageUrl: debe ser una URL https pública que responda con la imagen en 10 segundos.
no_company422Tu empresa no tiene una constancia activa todavía. Pídenos darla de alta. No se creó el ticket.
rate_limited429Pasaste tu límite por minuto, o tu IP acumuló intentos con una key inválida. Espera los segundos de Retry-After.
internal_error500Error nuestro. Reintenta con espera; con Idempotency-Key el reintento de un POST es seguro.
service_unavailable503No 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

Límites
QuéLímite
Peticiones por key60 por minuto
Tickets creados por key30 por minuto, dentro de las anteriores
Intentos con key inválida por IP20 por minuto
Imagen por imageUrl10 MB
Imagen por multipart4.5 MB la petición completa (límite de la plataforma)
Formatos de imagenJPEG, PNG, WebP o HEIC
metadata4 KB serializado
externalId128 caracteres
Idempotency-Key255 caracteres, vale 24 h
Tickets por página20 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. charged es true solo cuando ese lugar ya se consumió: mientras el ticket se factura, o si no se timbró, es false.
  • 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 POST responde 402 no_credits y 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.

Valores de metadata.simulate
simulateResultado
invoicedinvoiced, con un CFDI de ejemplo. Es el valor si no mandas simulate.
closed:already_invoicedclosed con reason: "already_invoiced".
closed:unreadableclosed con reason: "unreadable".
closed:missing_csfclosed con reason: "missing_csf".
closed:period_closedclosed con reason: "period_closed".
closed:not_invoiceableclosed con reason: "not_invoiceable".
closed:otherclosed 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.

Un ticket de prueba que termina ilegible
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. El uuid cambia en cada ticket. Los archivos se descargan con /cfdi/xml y /cfdi/pdf, como los reales.
  • extracted llega con todo en null, porque la foto no se lee, y charged siempre es false.
  • 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. externalId e Idempotency-Key tambié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.
Un ticket de prueba timbrado
{
  "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.invoiced y ticket.closed, con reintentos.
  • Idempotency-Key, externalId y metadata.
  • Modo prueba con keys fk_test_: desenlace a elegir con metadata.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.

Referencia

Cada endpoint, esquema y error, generado del mismo openapi.json.

Cargando la referencia… El contrato completo está en openapi.json.