API de Numy

API REST para automatizar trámites fiscales mexicanos de forma programática: facturar una compra desde el portal del comercio, emitir tus propios CFDI, validar pagos SPEI contra el CEP de Banxico, y descargar del SAT tu Constancia de Situación Fiscal, tu Opinión de Cumplimiento (32-D) y tu Buzón Tributario. La mayoría de las operaciones son asíncronas: respondemos con un job_id, consultas el estado por polling y/o recibes el resultado por webhook.

Autenticación

Todas las rutas bajo /api/v1/ requieren una API Key con formato numy_sk_.... Se puede enviar de dos formas:

Límites de tasa: 60 solicitudes/minuto por API key en general y 10/min en los endpoints respaldados por robot con e.firma (/constancias, /opinion-cumplimiento, /buzon-tributario, /cfdi-descargas). Al exceder: 429 {"error": "...", "code": "rate_limited"}.

Flujo General

El flujo de facturación es asincrónico. La API acepta tu solicitud y la procesa en segundo plano:

Endpoints

1. Crear solicitud de factura

Solicita la factura (CFDI) de una compra a partir de la foto de un ticket: Numy obtiene el comprobante desde el portal de facturación del comercio por ti — aquí tú eres el comprador. Es asíncrono: respondemos con un job_id y el resultado llega por webhook o polling. ¿Eres tú quien vende y necesitas emitir el CFDI a tu cliente? Ese es otro flujo → Emitir CFDI propio.

Headers

X-API-Key: numy_sk_xxxxx
Content-Type: application/json

Body

{
  "ticket_image_url": "https://example.com/ticket.jpg",
  "fiscal_data": {
    "rfc": "XAXX010101000",
    "person_type": "fisica",
    "first_name": "Juan",
    "last_name": "Pérez",
    "mothers_last_name": "López",
    "tax_regime": "626",
    "cfdi_usage": "G03",
    "tax_zip_code": "06600",
    "email": "juan@example.com"
  },
  "metadata": {
    "external_id": "order-123",
    "client_ref": "abc"
  }
}

Campos del body

Respuesta exitosa — 202 Accepted

{
  "job_id": "inv_aBcDeFgHiJkLmNoPqRsT",
  "status": "queued",
  "message": "Solicitud recibida. Recibirás el resultado en tu webhook.",
  "estimated_time_seconds": 120,
  "created_at": "2026-03-28T12:00:00.000000Z",
  "metadata": { "external_id": "order-123" }
}

Errores posibles

Ejemplo — Error 422:

{
  "error": "Validation failed",
  "code": "validation_error",
  "details": {
    "fiscal_data.rfc": ["El RFC no tiene un formato válido."],
    "fiscal_data.tax_regime": ["El régimen fiscal no corresponde al tipo de persona."]
  }
}

Ejemplo — Error 402:

{
  "error": "No hay tickets disponibles en tu suscripción.",
  "code": "insufficient_tickets",
  "tickets_remaining": 0,
  "upgrade_url": "https://console.numy.mx/planes"
}

2. Consultar estado de solicitud

Consulta el estado de una solicitud de factura usando el job_id que recibiste al crearla (polling). Útil como alternativa o respaldo del webhook.

Headers

X-API-Key: numy_sk_xxxxx

Respuestas según estado

queued — En cola:

{
  "job_id": "inv_aBcDeFgHiJkLmNoPqRsT",
  "status": "queued",
  "message": "Tu solicitud está en cola. Recibirás el resultado en tu webhook.",
  "created_at": "2026-03-28T12:00:00.000000Z",
  "completed_at": null,
  "metadata": { "external_id": "order-123" },
  "estimated_time_seconds": 120
}

processing — En proceso:

{
  "job_id": "inv_aBcDeFgHiJkLmNoPqRsT",
  "status": "processing",
  "message": "Tu factura está siendo procesada.",
  "created_at": "2026-03-28T12:00:00.000000Z",
  "completed_at": null,
  "metadata": { "external_id": "order-123" },
  "estimated_time_seconds": 120
}

success — Completada:

{
  "job_id": "inv_aBcDeFgHiJkLmNoPqRsT",
  "status": "success",
  "created_at": "2026-03-28T12:00:00.000000Z",
  "completed_at": "2026-03-28T12:02:15.000000Z",
  "metadata": { "external_id": "order-123" },
  "estimated_time_seconds": 120,
  "result": {
    "comercio": "Oxxo",
    "folio": "ABC123",
    "total": "152.50",
    "files": {
      "pdf_url": "https://api.numy.mx/api/dl/tok_xxxxx",
      "xml_url": "https://api.numy.mx/api/dl/tok_xxxxx"
    },
    "download_page_url": "https://api.numy.mx/api/factura/tok_xxxxx"
  }
}

failed — Error:

{
  "job_id": "inv_aBcDeFgHiJkLmNoPqRsT",
  "status": "failed",
  "created_at": "2026-03-28T12:00:00.000000Z",
  "completed_at": "2026-03-28T12:00:05.000000Z",
  "metadata": { "external_id": "order-123" },
  "estimated_time_seconds": 120,
  "error": {
    "code": "vision_failed",
    "message": "No se pudo leer el ticket. La imagen puede estar borrosa o dañada."
  }
}

3. Validar pago SPEI (CEP de Banxico)

Valida de forma asíncrona que un pago SPEI se haya liquidado, consultando el CEP del Banco de México. Entrada por datos estructurados (sin imagen). El resultado llega por webhook payment.completed / payment.failed o por polling.

Headers

X-API-Key: numy_sk_xxxxx
Content-Type: application/json

Body

{
  "tracking_key": "ABCD1234567890",
  "operation_date": "2026-05-20",
  "amount": "1500.00",
  "sender_bank": "BBVA",
  "receiver_bank": "STP",
  "beneficiary_account": "012345678901234567",
  "is_bank_payment": false,
  "metadata": { "external_id": "pago-001" }
}

Campos del body

Respuesta — 202 Accepted

{
  "job_id": "pay_aBcDeFgHiJkLmNoPqRsT",
  "status": "queued",
  "message": "Solicitud recibida. Recibirás el resultado en tu webhook.",
  "estimated_time_seconds": 180,
  "created_at": "2026-05-26T12:00:00.000000Z",
  "metadata": { "external_id": "pago-001" }
}

Si operation_date excede la ventana de ~45 días hábiles que Banxico conserva el CEP, la solicitud se rechaza con 422 y código out_of_window — sin consumir ticket.

4. Descargar Constancia de Situación Fiscal

Descarga de forma asíncrona la Constancia de Situación Fiscal desde el portal del SAT usando la e.firma. El PDF llega por webhook constancia.completed / constancia.failed o por polling.

Body — multipart/form-data

Respuesta — 202 Accepted

{
  "job_id": "con_aBcDeFgHiJkLmNoPqRsT",
  "status": "queued",
  "message": "Solicitud recibida. Recibirás la constancia en tu webhook.",
  "estimated_time_seconds": 300,
  "created_at": "2026-05-26T12:00:00.000000Z",
  "metadata": null
}

El webhook constancia.completed incluye el resultado:

{
  "event": "constancia.completed",
  "job_id": "con_aBcDeFgHiJkLmNoPqRsT",
  "status": "success",
  "result": {
    "rfc": "VAGL960809SQ0",
    "constancia_pdf_url": "https://api.numy.mx/api/dl/tok_xxxxx"
  },
  "completed_at": "2026-05-26T12:05:00.000000Z"
}

5. Descargar Opinión de Cumplimiento (forma 32-D)

Descarga de forma asíncrona la Opinión de Cumplimiento de Obligaciones Fiscales (forma 32-D) del portal SAT con la e.firma del contribuyente. El PDF oficial llega por webhook opinion_cumplimiento.completed / opinion_cumplimiento.failed o por polling. El resultado incluye el dictamen extraído (Positiva, Negativa, Inscrito sin obligaciones, Suspensión de actividades — Regla 2.1.36 RMF 2026).

Body — multipart/form-data

Respuesta — 202 Accepted

{
  "job_id": "opn_aBcDeFgHiJkLmNoPqRsT",
  "status": "queued",
  "message": "Solicitud recibida. Recibirás la Opinión de Cumplimiento en tu webhook.",
  "estimated_time_seconds": 300,
  "created_at": "2026-05-27T12:00:00.000000Z",
  "metadata": null
}

El webhook opinion_cumplimiento.completed incluye el resultado:

{
  "event": "opinion_cumplimiento.completed",
  "job_id": "opn_aBcDeFgHiJkLmNoPqRsT",
  "status": "success",
  "result": {
    "rfc": "VAGL960809SQ0",
    "dictamen": "Positiva",
    "opinion_pdf_url": "https://api.numy.mx/api/dl/tok_xxxxx"
  },
  "completed_at": "2026-05-27T12:05:00.000000Z"
}

Estados posibles del dictamen (Regla 2.1.36 RMF 2026):

• "Positiva" — al corriente.
• "Negativa" — con incumplimientos.
• "Inscrito sin obligaciones fiscales" — RFC sin obligaciones periódicas.
• "Suspensión de actividades" — RFC suspendido.
• null — el agente bajó el PDF pero no se pudo extraer el dictamen (el PDF está intacto, solo es metadata adicional).

Vigencia del documento: 30 días naturales en general, 90 días para subsidios y estímulos fiscales.

6. Consultar Buzón Tributario (modo solo lectura)

Consulta de forma asíncrona el Buzón Tributario del SAT del contribuyente. Devuelve los listados de las bandejas (Pendientes, Notificados, Comunicados, Documentos) más PDFs descargados de comunicados y documentos. El resultado llega por webhook buzon_tributario.completed / buzon_tributario.failed.

Body — multipart/form-data

Mismos campos que /api/v1/opinion-cumplimiento: cer, key, password, rfc, metadata (opcional).

Respuesta — 202 Accepted

{
  "job_id": "bzn_aBcDeFgHiJkLmNoPqRsT",
  "status": "queued",
  "message": "Solicitud recibida. El listado de tu Buzón llegará a tu webhook (modo solo lectura, sin abrir notificaciones).",
  "estimated_time_seconds": 360,
  "created_at": "2026-05-27T12:00:00.000000Z",
  "metadata": null
}

El webhook buzon_tributario.completed incluye los listados completos:

{
  "event": "buzon_tributario.completed",
  "job_id": "bzn_aBcDeFgHiJkLmNoPqRsT",
  "status": "success",
  "result": {
    "rfc": "VAGL960809SQ0",
    "buzon_habilitado": true,
    "resumen": {
      "pendientes": 2,
      "comunicados": 3,
      "documentos": 5
    },
    "notificaciones_pendientes": [
      { "folio": "N001", "fecha_aviso": "2026-05-25", "asunto": "Requerimiento", "remitente": "SAT" }
    ],
    "comunicados": [
      { "folio": "C001", "fecha": "2026-05-20", "asunto": "Recordatorio", "pdf_path": "..." }
    ],
    "documentos": [
      { "folio": "D001", "fecha": "2026-05-15", "tipo": "Acuse", "pdf_path": "..." }
    ],
    "buzon_url": "https://api.numy.mx/api/buzon/abc123token",
    "expires_at": "2026-06-03T12:00:00+00:00"
  },
  "completed_at": "2026-05-27T12:06:00.000000Z"
}

Notas clave:

• buzon_habilitado: false cuando el SAT reporta que el Buzón no está activado (caso típico: PF RESICO antes del 1-ene-2027). En ese caso los listados llegan vacíos.
• buzon_url sirve a un endpoint público sin auth (token URL-safe, expira 7 días) con los PDFs descargados.
• Si el agente IA intenta abrir una notificación pendiente, el job falla con código intent_blocked_open_pendiente (no reintentable).

Disclaimer legal: las notificaciones del Buzón tienen efectos jurídicos bajo CFF arts. 17-K y 134-I. Tienes 3 días hábiles desde el aviso para abrirlas; al cuarto día se tienen por notificadas. Numy NO las abre por ti — solo te informa que existen.

7. Emitir CFDI

Emite un CFDI de Ingreso (tipo I) como emisor/vendedor, de forma síncrona: el comprobante timbrado se devuelve en la misma respuesta (no usa webhook). ¿Solo quieres la factura de algo que compraste? Ese es otro flujo → Facturar una compra.

Body

{
  "cliente_rfc": "XAXX010101000",
  "cliente_nombre": "JOHN DOE",
  "cliente_cp": "83240",
  "cliente_regimen_codigo": "616",
  "cliente_uso_codigo": "S01",
  "cliente_email": "cliente@ejemplo.com",
  "forma_pago_codigo": "08",
  "metodo_pago_codigo": "PUE",
  "conceptos": [
    {
      "descripcion": "Servicio de consultoría",
      "cantidad": 1,
      "valor_unitario": 1000,
      "precio_con_iva": false,
      "tipo_iva": "16"
    }
  ],
  "metadata": { "external_id": "cfdi-001" }
}

Campos del body

Respuesta — 200 OK

{
  "uuid": "bb56f134-8427-4664-8d0f-7e3d8f83fea2",
  "folio": "1",
  "series": "F",
  "total": 1160.00,
  "currency": "MXN",
  "verification_url": "https://verificacfdi.facturaelectronica.sat.gob.mx/...",
  "livemode": false,
  "test_mode": true,
  "duplicate": false,
  "downloads": [
    { "type": "pdf", "url": "https://api.numy.mx/api/dl/tok_xxxxx" },
    { "type": "xml", "url": "https://api.numy.mx/api/dl/tok_xxxxx" }
  ],
  "metadata": { "external_id": "cfdi-001" }
}

Errores posibles

7.1 Ciclo del CFDI emitido: cancelar, nota de crédito, complemento y consulta

Todos estos endpoints aceptan {cfdi} como el cfdi_id que devuelve la emisión o el UUID fiscal, siempre acotado a tu cuenta.

Cancela un CFDI timbrado con los motivos SAT 01–04; el motivo 01 exige substitution_uuid (una factura timbrada tuya que sustituye a la cancelada). No consume operaciones. La respuesta trae el cancellation_status inicial (accepted / pending — el receptor tiene hasta 72 h — / verifying); la resolución final llega por el webhook cfdi.cancellation.updated.

{
  "cfdi_id": 123,
  "uuid": "bb56f134-...",
  "folio": "15",
  "cancellation_status": "pending",
  "message": "Solicitud enviada. El receptor tiene hasta 72 horas para aceptar o rechazar."
}

Nota de crédito (Egreso, tipo E) contra un Ingreso timbrado. Body según mode: {"mode": "total"} (espejo del Ingreso), {"mode": "partial", "items": [{"index": 1, "cantidad": 1}]} (subset por índice, con cantidad nunca mayor a la original) o {"mode": "descuento", "monto": 500} (monto fijo como concepto plano). Opcional uso_cfdi (default G02). Consume 1 operación; el tope de sobre-acreditación responde 422 over_credited.

Complemento de pago (REP, tipo P) contra una factura PPD con saldo. Body: forma_pago_codigo (forma SAT concreta; 99 no se permite), monto (≤ saldo restante) y fecha_pago opcional. La parcialidad se calcula sola. La respuesta trae last_balance_after y paid: true cuando liquida. Consume 1 operación.

Consulta de CFDI emitidos — listado paginado con filtros (type, status, cancellation_status, uuid, folio, fechas), detalle con derivados (complementos y notas de crédito) y descarga del PDF/XML timbrado. Sin costo.

8. Descargar facturas del SAT (emitidas y recibidas)

Descarga masiva, directo del SAT, de los CFDI que tu RFC emitió o recibió en un periodo, de forma asíncrona. Requiere una e.firma validada almacenada en la bóveda del RFC (se sube una sola vez en el panel; el proceso dura de minutos a horas y no acepta e.firma inline). El resultado llega por webhook cfdi_descarga.completed / sin_resultados / failed y por polling en /api/v1/requests/{job_id}.

Body

direction (requerido, emitidas|recibidas), year (requerido, 2014..año en curso), month (opcional, 1–12, no futuro), rfc (opcional — elige entre los RFC de tu cuenta; default: el del titular) y metadata (opcional).

Respuesta — 202 Accepted

{
  "message": "Solicitud de descarga encolada. El SAT suele tardar de minutos a unas horas; el resultado llegará a tu webhook.",
  "downloads": [
    { "job_id": "dsc_aBcDeFgHiJkLmNoPqRsT", "direction": "emitidas", "year": 2025,
      "month": null, "status": "queued", "estimated_time_seconds": 3600 }
  ],
  "skipped": [],
  "metadata": null
}

El webhook cfdi_descarga.completed llega un periodo a la vez:

{
  "event": "cfdi_descarga.completed",
  "job_id": "dsc_aBcDeFgHiJkLmNoPqRsT",
  "status": "success",
  "result": {
    "rfc": "VAGC981118D95",
    "direction": "emitidas",
    "year": 2025,
    "month": null,
    "period_label": "2025",
    "total_cfdi_reported": 29,
    "stored_count": 29,
    "duplicate_count": 0,
    "charged": true
  },
  "metadata": null,
  "completed_at": "2026-08-22T12:00:00.000000Z"
}

Notas clave:

• skipped[] lista periodos omitidos con reason: conflict (ya hay una descarga activa del periodo), blocked (el periodo se logró hace <24 h o se pidió 3 veces hoy) o sin_saldo.
• Si ningún periodo se encoló, el código HTTP refleja el motivo: 409, 429 o 402.
• Errores 422: no_efirma_validada, rfc_no_encontrado, periodo_futuro.

9. Consultar los CFDI descargados

La cartera de CFDI descargados pertenece al RFC (sobrevive a bajas de números y de la e.firma). Solo lectura, sin costo. El listado (?direction=emitidas&year=2025[&month=3][&rfc=...]) pagina hasta 200 por página e incluye por CFDI el UUID, tipo, serie/folio, fechas, emisor/receptor, importes y el estado_sat (Vigente / Cancelado, sincronizado contra el SAT), más total_amount y el conteo by_month del año. /{uuid}/xml descarga el XML original y /export genera el reporte Excel (.xlsx, 5 pestañas — mismo layout que el panel) del periodo.

Webhooks

Configuración

Los webhooks se gestionan bajo /api/me/webhook-endpoints con autenticación Sanctum.

Crear webhook endpoint

{
  "url": "https://tu-servidor.com/webhook",
  "events": ["invoice.completed", "invoice.failed"],
  "description": "Producción"
}

Eventos disponibles: invoice.completed, invoice.failed, payment.completed, payment.failed, constancia.completed, constancia.failed, opinion_cumplimiento.completed, opinion_cumplimiento.failed, buzon_tributario.completed, buzon_tributario.failed, cfdi_descarga.completed, cfdi_descarga.sin_resultados, cfdi_descarga.failed, cfdi.cancellation.updated, webhook.test

Respuesta 201 Created:

{
  "webhook_endpoint": {
    "id": 1,
    "url": "https://tu-servidor.com/webhook",
    "events": ["invoice.completed", "invoice.failed"],
    "is_active": true,
    "description": "Producción",
    "last_triggered_at": null,
    "created_at": "2026-03-28T10:00:00.000000Z"
  },
  "secret": "whsec_aBcDeFgHiJkLmNoPqRsTuVwXyZ...",
  "warning": "Guarda este secret de forma segura. No podrás verlo de nuevo."
}

Listar webhook endpoints

{
  "data": [
    {
      "id": 1,
      "url": "https://tu-servidor.com/webhook",
      "events": ["invoice.completed", "invoice.failed"],
      "is_active": true,
      "description": "Producción",
      "last_triggered_at": "2026-03-28T12:05:00.000000Z",
      "created_at": "2026-03-28T10:00:00.000000Z"
    }
  ]
}

Actualizar webhook endpoint

{
  "url": "https://nuevo-servidor.com/webhook",
  "events": ["invoice.completed"],
  "is_active": false,
  "description": "Staging"
}

Eliminar webhook endpoint

Respuesta: 204 No Content

Rotar secret

{
  "webhook_endpoint": { ... },
  "secret": "whsec_NuEvOsEcReTaQuI...",
  "warning": "Guarda este nuevo secret de forma segura. No podrás verlo de nuevo."
}

Enviar webhook de prueba

Respuesta exitosa:

{ "success": true, "message": "Webhook de prueba enviado correctamente." }

Respuesta fallida (502):

{ "success": false, "message": "No se pudo entregar el webhook de prueba. Verifica la URL." }

Payloads de webhook

Numy envía un POST con body JSON a la URL configurada.

Headers del webhook

Evento: invoice.completed

{
  "event": "invoice.completed",
  "job_id": "inv_aBcDeFgHiJkLmNoPqRsT",
  "status": "success",
  "result": {
    "comercio": "Oxxo",
    "folio": "ABC123",
    "total": "152.50",
    "files": {
      "pdf_url": "https://api.numy.mx/api/dl/tok_xxxxx",
      "xml_url": "https://api.numy.mx/api/dl/tok_xxxxx"
    },
    "download_page_url": "https://api.numy.mx/api/factura/tok_xxxxx"
  },
  "metadata": { "external_id": "order-123" },
  "completed_at": "2026-03-28T12:02:15.000000Z"
}

Evento: invoice.failed

{
  "event": "invoice.failed",
  "job_id": "inv_aBcDeFgHiJkLmNoPqRsT",
  "status": "failed",
  "error": {
    "code": "vision_failed",
    "message": "No se pudo leer el ticket. La imagen puede estar borrosa o dañada.",
    "retryable": false
  },
  "metadata": { "external_id": "order-123" },
  "failed_at": "2026-03-28T12:00:05.000000Z"
}

Evento: webhook.test

{
  "event": "webhook.test",
  "message": "Este es un webhook de prueba desde Numy.",
  "timestamp": "2026-03-28T12:00:00.000000Z"
}

Códigos de error en eventos de webhook

retryable: true indica que reintentar (p.ej. con una imagen más clara) podría funcionar.

Verificación de firma

1. Obtén el timestamp del header X-Numy-Timestamp
2. Obtén la firma del header X-Numy-Signature (quitar el prefijo sha256=)
3. Computa el HMAC: HMAC-SHA256(timestamp + "." + body, SHA256(secret))
   • El secret es el plain text whsec_... recibido al crear el endpoint
   • Primero hashea el secret con SHA-256, luego úsalo como clave del HMAC
4. Compara tu HMAC con la firma recibida

Ejemplo en Node.js

const crypto = require('crypto');

function verifyWebhook(body, signature, timestamp, secret) {
  const signingKey = crypto.createHash('sha256').update(secret).digest('hex');
  const expected = crypto
    .createHmac('sha256', signingKey)
    .update(`${timestamp}.${body}`)
    .digest('hex');

  const received = signature.replace('sha256=', '');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(received, 'hex')
  );
}

Ejemplo en PHP

function verifyWebhook(string $body, string $signature, string $timestamp, string $secret): bool
{
    $signingKey = hash('sha256', $secret);
    $expected   = hash_hmac('sha256', $timestamp . '.' . $body, $signingKey);
    $received   = str_replace('sha256=', '', $signature);

    return hash_equals($expected, $received);
}

Reintentos y desactivación

• Numy intenta entregar cada webhook hasta 4 veces (1 intento + 3 reintentos).
• Intervalos: 5s, 30s, 120s entre reintentos.
• Si todos los intentos fallan, el endpoint se desactiva automáticamente (is_active: false).
• El endpoint se puede reactivar manualmente via PATCH.

Tu servidor debe responder con un código 2xx dentro de 10 segundos para confirmar la recepción.

Catálogos Fiscales

Regímenes fiscales — Persona Física

Regímenes fiscales — Persona Moral

Uso de CFDI — Ambos tipos de persona

Uso de CFDI — Solo Persona Física (adicionales)

Resumen de rutas

API Key auth (X-API-Key / Bearer numy_sk_...)

Sanctum auth (panel)

Ejemplos cURL

Descargar facturas del SAT

curl -X POST https://api.numy.mx/api/v1/cfdi-descargas \
  -H "X-API-Key: numy_sk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "direction": "emitidas", "year": 2025, "metadata": { "external_id": "dl-1" } }'

Cancelar un CFDI emitido

curl -X POST https://api.numy.mx/api/v1/cfdi/123/cancel \
  -H "X-API-Key: numy_sk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "motive": "02" }'

Facturar una compra

curl -X POST https://api.numy.mx/api/v1/invoices \
  -H "X-API-Key: numy_sk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "ticket_image_url": "https://storage.example.com/ticket-001.jpg",
    "fiscal_data": {
      "rfc": "PELL900101ABC",
      "person_type": "fisica",
      "first_name": "Juan",
      "last_name": "Pérez",
      "mothers_last_name": "López",
      "tax_regime": "626",
      "cfdi_usage": "G03",
      "tax_zip_code": "06600",
      "email": "juan@example.com"
    },
    "metadata": { "external_id": "order-456" }
  }'

Consultar estado

curl https://api.numy.mx/api/v1/invoices/inv_aBcDeFgHiJkLmNoPqRsT \
  -H "X-API-Key: numy_sk_xxxxx"

Crear webhook endpoint

curl -X POST https://api.numy.mx/api/me/webhook-endpoints \
  -H "Authorization: Bearer {sanctum_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-servidor.com/numy-webhook",
    "events": ["invoice.completed", "invoice.failed"],
    "description": "Producción"
  }'