Facturas

Las facturas son el recurso principal. Usted las crea, nosotros nos encargamos de la generacion del XML, la firma digital, el timbrado con el PAC y la generacion del PDF.

Tipos de factura

Tipo	Valor de `tipo`	Descripcion
Ingreso	`"ingreso"`	Factura de ingreso estandar
Egreso	`"egreso"`	Nota de credito / reembolso

Ciclo de vida

crear ──▶ borrador ──▶ timbrar ──▶ timbrada ──▶ cancelar ──▶ cancelada

Por defecto, crear timbra automaticamente. Establezca auto_timbrar: false para crear primero un borrador.

Crear una factura

curl https://api.facturacion.srs-ngr.com/v1/facturas \
  -u sk_test_xxx: \
  -H "Content-Type: application/json" \
  -d '{
    "organizacion": "org_1a2b3c4d",
    "tipo": "ingreso",
    "cliente": "XAXX010101000",
    "forma_pago": "03",
    "metodo_pago": "PUE",
    "conceptos": [
      {
        "producto": "prod_xyz789",
        "cantidad": 2
      },
      {
        "descripcion": "Servicio adicional",
        "cantidad": "1",
        "valor_unitario": "500.00",
        "clave_prod_serv": "80101500",
        "clave_unidad": "E48",
        "objeto_imp": "02",
        "impuestos": {
          "traslados": [
            {"impuesto": "002", "tipo_factor": "Tasa", "tasa_o_cuota": "0.160000"}
          ]
        }
      }
    ]
  }'

Los conceptos pueden referenciar productos o ser en linea

Con producto: Hereda clave_prod_serv, clave_unidad, valor_unitario, objeto_imp e impuestos del producto. Solo se requiere cantidad.
En linea: Proporcione todos los campos directamente. No se necesita referencia a un producto.

Puede combinar ambos en la misma factura.

Valores por defecto

Campo	Valor por defecto si no se proporciona
`moneda`	`"MXN"`
`exportacion`	`"01"` (sin exportacion)
`lugar_expedicion`	`codigo_postal` de la organizacion
`auto_timbrar`	`true`

Obtener una factura

curl https://api.facturacion.srs-ngr.com/v1/facturas/fac_1a2b3c4d \
  -u sk_test_xxx:

Devuelve la factura completa con conceptos, impuestos y relaciones anidados.

Listar facturas

curl "https://api.facturacion.srs-ngr.com/v1/facturas?organizacion=org_1a2b3c4d&estado=timbrada" \
  -u sk_test_xxx:

Soporta filtros: organizacion, cliente, estado, tipo.

Paginacion basada en cursor:

{
  "datos": [...],
  "paginacion": {
    "hay_mas": true,
    "siguiente_cursor": "..."
  }
}

Pase siguiente_cursor como paginacion.cursor_inicio para la siguiente pagina.

Timbrar una factura en borrador

Si creo la factura con auto_timbrar: false:

curl -X POST https://api.facturacion.srs-ngr.com/v1/facturas/fac_1a2b3c4d/timbrar \
  -u sk_test_xxx:

Cancelar una factura

curl -X POST https://api.facturacion.srs-ngr.com/v1/facturas/fac_1a2b3c4d/cancelar \
  -u sk_test_xxx: \
  -H "Content-Type: application/json" \
  -d '{
    "motivo": "02"
  }'

Motivos de cancelacion

Codigo	Motivo	Notas
`01`	Con sustitucion	Debe proporcionar `uuid_sustitucion`
`02`	Sin sustitucion	Error en la factura, sin reemplazo
`03`	Operacion no realizada	La transaccion no se llevo a cabo
`04`	Nominativa en factura global	Reemplazada por CFDI nominativo

Descargar XML

curl https://api.facturacion.srs-ngr.com/v1/facturas/fac_1a2b3c4d/xml \
  -u sk_test_xxx: \
  -o factura.xml

Devuelve el XML timbrado en crudo (Content-Type: application/xml).

Descargar PDF

curl https://api.facturacion.srs-ngr.com/v1/facturas/fac_1a2b3c4d/pdf \
  -u sk_test_xxx: \
  -o factura.pdf

Devuelve el PDF conforme al SAT con codigo QR (Content-Type: application/pdf).

Autenticación Clientes