Referencia de la API

Referencia completa de todos los endpoints de la API de Facturación. Todas las solicitudes utilizan HTTP Basic Auth con tu llave de API.

Base URL: https://api.facturacion.srs-ngr.com

Facturas

El recurso principal. Crea, timbra, cancela y descarga facturas.

Crear una factura

POST /v1/facturas

Crea y opcionalmente timbra una factura en una sola llamada.

Cuerpo de la solicitud:

Campo	Tipo	Requerido	Descripción
`organizacion`	string	Sí	ID de organización (`org_...`)
`tipo`	string	Sí	`"ingreso"` o `"egreso"`
`cliente`	string	Sí	RFC del cliente o ID (`cli_...`)
`conceptos`	array	Sí	Partidas (ver abajo)
`forma_pago`	string	Condicional	Código de forma de pago del SAT (`"01"`, `"03"`, etc.)
`metodo_pago`	string	Condicional	`"PUE"` o `"PPD"`
`moneda`	string	No	Por defecto: `"MXN"`
`tipo_cambio`	string	No	Requerido si `moneda` no es `MXN`
`lugar_expedicion`	string	No	Por defecto: `codigo_postal` de la organización
`exportacion`	string	No	Por defecto: `"01"`
`serie`	string	No	Serie de la factura
`folio`	string	No	Número de factura
`condiciones_pago`	string	No	Condiciones de pago
`relaciones`	array	No	CFDIs relacionados
`auto_timbrar`	bool	No	Por defecto: `true`

Objeto Concepto:

Campo	Tipo	Requerido	Descripción
`producto`	string	No	ID de producto — hereda valores por defecto
`cantidad`	string	Sí	Cantidad
`clave_prod_serv`	string	Condicional	Código del SAT (requerido si no hay `producto`)
`clave_unidad`	string	Condicional	Código de unidad del SAT
`descripcion`	string	Condicional	Descripción
`valor_unitario`	string	Condicional	Precio unitario
`descuento`	string	No	Monto de descuento
`objeto_imp`	string	Condicional	`"01"`, `"02"`, `"03"`
`impuestos`	object	No	Desglose de impuestos

curl -X POST 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"}
    ]
  }'

Listar facturas

GET /v1/facturas

Parámetro	Tipo	Descripción
`organizacion`	string	Filtrar por organización
`cliente`	string	Filtrar por cliente
`estado`	string	Filtrar por estado
`tipo`	string	Filtrar por tipo
`paginacion.limite`	int	Tamaño de página (por defecto: 20)
`paginacion.cursor_inicio`	string	Cursor de la página anterior

Obtener una factura

GET /v1/facturas/{id}

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

Timbrar un borrador

POST /v1/facturas/{id}/timbrar

Envía un borrador de factura al PAC para timbrado. Solo funciona cuando estado es "borrador".

Cancelar una factura

POST /v1/facturas/{id}/cancelar

Campo	Tipo	Requerido	Descripción
`motivo`	string	Sí	`"01"`, `"02"`, `"03"` o `"04"`
`uuid_sustitucion`	string	Condicional	Requerido cuando `motivo` es `"01"`

Descargar XML

GET /v1/facturas/{id}/xml

Devuelve Content-Type: application/xml.

Descargar PDF

GET /v1/facturas/{id}/pdf

Devuelve Content-Type: application/pdf.

Clientes

Administra los datos fiscales de tus clientes.

Crear un cliente

POST /v1/clientes

Campo	Tipo	Requerido	Descripción
`organizacion`	string	Sí	ID de organización
`rfc`	string	Sí	12 o 13 caracteres
`nombre`	string	Sí	Razón social (debe coincidir con el SAT)
`regimen_fiscal`	string	Sí	Código de régimen del SAT
`domicilio_fiscal`	string	Sí	Código postal (debe coincidir con el SAT)
`uso_cfdi`	string	Sí	Debe ser compatible con `regimen_fiscal`
`correo`	string	No	Dirección de correo electrónico

Listar clientes

GET /v1/clientes

Parámetro	Descripción
`organizacion`	Filtrar por organización
`q`	Buscar por RFC o nombre

Obtener un cliente

GET /v1/clientes/{id}

Actualizar un cliente

PATCH /v1/clientes/{id}

Eliminar un cliente

DELETE /v1/clientes/{id}

Productos

Catálogo de productos con mapeo de códigos del SAT e impuestos por defecto.

Crear un producto

POST /v1/productos

Campo	Tipo	Requerido	Descripción
`organizacion`	string	Sí	ID de organización
`descripcion`	string	Sí	Descripción del producto
`valor_unitario`	string	Sí	Precio unitario (6 decimales)
`clave_prod_serv`	string	Sí	Código de producto del SAT
`clave_unidad`	string	Sí	Código de unidad del SAT
`unidad`	string	No	Nombre de la unidad (texto libre)
`no_identificacion`	string	No	SKU interno
`objeto_imp`	string	Sí	`"01"`, `"02"`, `"03"`
`impuestos_default`	object	No	Impuestos por defecto aplicados en facturas

Listar / Buscar / Obtener / Actualizar / Eliminar

Mismos patrones que Clientes. Busca con el parámetro q en descripcion y no_identificacion.

Organizaciones

Administra tus entidades de negocio (soporte multi-RFC).

Crear una organización

POST /v1/organizaciones

Campo	Tipo	Requerido
`rfc`	string	Sí
`nombre`	string	Sí
`regimen_fiscal`	string	Sí
`codigo_postal`	string	Sí
`color_acento`	string	No

Listar / Obtener / Actualizar

CRUD estándar con paginación.

Certificados

Carga y administra Certificados de Sello Digital (CSD).

Cargar un certificado

POST /v1/certificados

Campo	Tipo	Requerido	Descripción
`organizacion`	string	Sí	ID o RFC de la organización
`cer`	bytes	Sí	Archivo de certificado (.cer)
`llave`	bytes	Sí	Archivo de llave privada (.key)
`contrasena`	string	Sí	Contraseña de la llave privada

Acepta multipart/form-data (archivos vía curl -F) o JSON (archivos en base64).

Listar / Obtener / Activar-Desactivar

CRUD estándar. El endpoint PATCH alterna la bandera activo.

Pagos

Registra pagos contra facturas PPD. Genera Complemento de Pagos 2.0.

Crear un pago

POST /v1/pagos

Campo	Tipo	Requerido	Descripción
`organizacion`	string	Sí	ID de organización
`fecha_pago`	timestamp	Sí	Fecha de pago
`forma_pago`	string	Sí	Código de forma de pago del SAT
`moneda`	string	No	Por defecto: `"MXN"`
`monto`	string	Sí	Monto total del pago
`facturas_pagadas`	array	Sí	Facturas que se están pagando

Elemento de facturas_pagadas:

Campo	Tipo	Requerido
`factura`	string	Sí
`imp_pagado`	string	Sí

Listar / Obtener

Filtra por organizacion y opcionalmente por factura.

Catálogos SAT

Busca en los catálogos de referencia del SAT de solo lectura. No se requiere autenticación para los endpoints de catálogos.

Endpoint	Descripción	Buscable
`GET /v1/catalogos/claves_prod_serv?q=...`	Códigos de productos/servicios (55K+)	Sí
`GET /v1/catalogos/claves_unidad?q=...`	Códigos de unidad	Sí
`GET /v1/catalogos/codigos_postales?q=...`	Códigos postales	Sí
`GET /v1/catalogos/regimenes_fiscales`	Regímenes fiscales	No
`GET /v1/catalogos/usos_cfdi`	Usos de CFDI	No
`GET /v1/catalogos/formas_pago`	Formas de pago	No
`GET /v1/catalogos/metodos_pago`	Métodos de pago	No
`GET /v1/catalogos/monedas`	Monedas	No
`GET /v1/catalogos/exportaciones`	Tipos de exportación	No
`GET /v1/catalogos/objetos_imp`	Objetos de impuesto	No
`GET /v1/catalogos/tipos_relacion`	Tipos de relación	No

Los catálogos buscables aceptan los parámetros q (consulta) y limite.

Webhooks

Registra URLs para recibir notificaciones de eventos.

Crear / Listar / Obtener / Actualizar / Eliminar

POST /v1/webhooks · GET /v1/webhooks · GET /v1/webhooks/{id} · PATCH /v1/webhooks/{id} · DELETE /v1/webhooks/{id}

Consulta la guía de Webhooks para ver los tipos de eventos y la verificación de firmas.

Eventos

Registro inmutable de todos los eventos en tu cuenta.

Listar eventos

GET /v1/eventos

Parámetro	Descripción
`tipo`	Filtrar por tipo de evento (ej., `"factura.timbrada"`)

Obtener un evento

GET /v1/eventos/{id}

Cuenta & Llaves API

Cuenta

POST /v1/cuenta · GET /v1/cuenta · PATCH /v1/cuenta

Llaves de API

POST /v1/llaves_api · GET /v1/llaves_api · DELETE /v1/llaves_api/{id}

Consulta la guía de Autenticación para más detalles.

Patrones comunes

Paginación

Todos los endpoints de listado usan paginación basada en cursor:

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

Pasa siguiente_cursor como paginacion.cursor_inicio en la siguiente solicitud.

Idempotencia

Incluye un encabezado Clave-Idempotencia en cualquier solicitud POST para reintentar de forma segura:

curl -X POST https://api.facturacion.srs-ngr.com/v1/facturas \
  -H "Clave-Idempotencia: pedido_12345" \
  -u sk_test_xxx: \
  -d '{...}'

Misma clave + mismo cuerpo = misma respuesta. Las claves expiran después de 24 horas.