Saltar a contenido

Referencia

CSPlug ofrece un modulo REST con algunas funcionalidades extras al modulo SOAP:

  • Consulta de CFDI
  • Catálogos SAT
  • Emisión de CFDI
Migración REST

Se planea agregar todos los métodos de CSPlug con la tecnología SOAP a su equivalente en REST. Aún no se tiene una fecha programada.

CFDI 4.0

Retenciones 2.0

API REST application/json

Credenciales de contratación vigente mediante Http Basic

CFDI

Emitir CFDI

/cfdi Emitir CFDI

Tipo

application/json

Petición

Notas

  • Cuerpo en application/json con el objeto CFDI 4.0.
  • Ambiente de demo: https://csplug.csfacturacion.com/demo/cfdi.
  • Ambiente de producción: https://csplug.csfacturacion.com/cfdi.
Ejemplo de petición (HTTP)
POST /cfdi HTTP/1.1
Host: csplug.csfacturacion.com
Accept: application/json
Content-Type: application/json
Authorization: Basic {usuario:contraseña en base64}

{
  "Version": "4.0",
  "Serie": "A",
  "Folio": "137",
  "FormaPago": "01",
  "Moneda": "MXN",
  "TipoDeComprobante": "I",
  "Exportacion": "01",
  "MetodoPago": "PUE",
  "LugarExpedicion": "XXXXX",
  "Receptor": {
    "Rfc": "XAXX010101000",
    "Nombre": "AL PUBLICO EN GENERAL",
    "DomicilioFiscalReceptor": "XXXXX",
    "RegimenFiscalReceptor": "616",
    "UsoCFDI": "S01",
    "Email": "example@gmail.com",
    "Domicilio": {
      "Calle": "Domicilio",
      "NoExterior": "1",
      "NoInterior": "1",
      "Colonia": "Colonia",
      "Localidad": "Localidad",
      "Referencia": "Referencia",
      "Municipio": "Municipio",
      "Estado": "Estado",
      "Pais": "Pais",
      "CodigoPostal": "XXXXX"
    }
  },
  "Emisor": {
    "Nombre": "EMPRESA DE PRUEBA",
    "RegimenFiscal": "601",
    "Rfc": "AAA010101AAA",
    "Domicilio": {
      "Calle": "Domicilio",
      "NoExterior": "1",
      "NoInterior": "1",
      "Colonia": "Colonia",
      "Localidad": "Localidad",
      "Referencia": "Referencia",
      "Municipio": "Municipio",
      "Estado": "Estado",
      "Pais": "Pais",
      "CodigoPostal": "XXXXX"
    }
  },
  "Conceptos": {
    "Concepto": {
      "0": {
        "ClaveProdServ": "72153000",
        "NoIdentificacion": "72153000",
        "Cantidad": "1.00",
        "ClaveUnidad": "E48",
        "Descripcion": "SERVICIOS DE VIDRIOS EN GENERAL",
        "ValorUnitario": "200.00",
        "Importe": "200.00",
        "ObjetoImp": "02",
        "Impuestos": {
          "Traslados": {
            "Traslado": [
              {
                "Base": "200.00",
                "Impuesto": "002",
                "TipoFactor": "Tasa",
                "TasaOCuota": "0.160000",
                "Importe": "32.00"
              }
            ]
          },
          "Retenciones": {
            "Retencion": []
          }
        },
        "ACuentaTerceros": {
          "RfcACuentaTerceros": "XAXX010101000",
          "NombreACuentaTerceros": "EMPRESA DE TERCEROS DE PRUEBA",
          "RegimenFiscalACuentaTerceros": "601",
          "DomicilioFiscalACuentaTerceros": "XXXXX"
        }
      }
    }
  },
  "DatosOperacion": {
    "CalcularImpuestosGlobales": true
  }
}

Response

201 Created

application/json

Ejemplo
{
  "message": "Factura timbrada correctamente",
  "data": {
    "xml": "{BASE_64_XML}",
    "pdf": "{BASE_64_PDF}",
    "qr": "{BASE_64_QR}"
  }
}
  • xml: String — CFDI XML en Base64.
  • pdf: String — Representación impresa en Base64.
  • qr: String — Código QR en Base64.
422 Unprocessable Entity

application/json

Ejemplo de error de validación
{
  "message": "The given data was invalid.",
  "errors": {
    "Receptor.Rfc": [
      "El RFC del receptor es requerido o inválido."
    ]
  },
  "internal-code": "101"
}

Emitir retención

/retenciones Emitir retención

Tipo

application/json

Petición

Notas

  • Cuerpo en application/json conforme al esquema de Retenciones 2.0.
  • Ambiente de demo: https://csplug.csfacturacion.com/demo/retenciones.
  • Ambiente de producción: https://csplug.csfacturacion.com/retenciones.
Ejemplo de petición (HTTP)
POST /retenciones HTTP/1.1
Host: csplug.csfacturacion.com
Accept: application/json
Content-Type: application/json
Authorization: Basic {usuario:contraseña en base64}

{
  "Version": "2.0",
  "Serie": "PRUEBA",
  "LugarExpRetenc": "36257",
  "CveRetenc": "01",
  "Emisor": {
    "RfcE": "AAA010101AAA",
    "NomDenRazSocE": "XOCHILT CASAS CHAVEZ",
    "RegimenFiscalE": "601"
  },
  "Receptor": {
    "Email": "example@gmail.com",
    "NacionalidadR": "Nacional",
    "Nacional": {
      "RfcR": "XAXX010101000",
      "NomDenRazSocR": "EMPRESA DE PRUEBA",
      "DomicilioFiscalR": "XXXXX"
    }
  },
  "Periodo": {
    "MesIni": "01",
    "MesFin": "01",
    "Ejercicio": "2023"
  },
  "Totales": {
    "MontoTotOperacion": "2000.00",
    "MontoTotGrav": "1000.00",
    "MontoTotExent": "1000.00",
    "MontoTotRet": 0
  }
}

Response

201 Created

application/json

Ejemplo
{
  "message": "Factura timbrada correctamente",
  "data": {
    "xml": "{BASE_64_XML}",
    "pdf": "{BASE_64_PDF}",
    "qr": "{BASE_64_QR}"
  }
}
  • xml: String — XML de la retención en Base64.
  • pdf: String — Representación impresa en Base64.
  • qr: String — Código QR en Base64.
422 Unprocessable Entity

application/json

Ejemplo de error de validación
{
  "message": "The given data was invalid.",
  "errors": {
    "Receptor.Nacional.RfcR": [
      "El RFC del receptor es requerido o inválido."
    ]
  },
  "internal-code": "101"
}

Consultar Por UUID

/cfdi/{uuid} Obtener CFDI

Tipo

application/json

Petición

URL-Param Descripción Requerido
uuid El UUID de la factura a consultar Sí

Ejemplo
GET /cfdi/4AA1138B-BF2E-0143-B7D0-CC2AA44E1DC2 HTTP/1.1
Content-Type: application/json
Host: csplug.csfacturacion.com
Authorization: Basic QUFBMDEwMTAxQUFBOnBhc3N3b3Jk

Response

200 OK

application/json

Ejemplo
{
    "message": "Exito",
    "data": {
        "xml": "{BASE_64_XML}",
        "pdf": "{BASE_64_PDF}",
        "qr": "{BASE_64_QR}",
        "cfdi": {
            "uuid": "4AA1138B-BF2E-0143-B7D0-CC2AA44E1DC2",
            "id": 1,
            "serie": "R1",
            "folio": "0102",
            "fecha": "2023-04-25T17:56:23",
            "subtotal": "2815.26",
            "total": "2472.30"
        }
    }
}

Scheme

  • message: String
    Mensaje descriptivo de la operación

  • data: Object
    Objeto que contiene una estructura de datos

  • xml: String XML del CFDI codificado en Base64

  • pdf: String Representación impresa del CFDI codificada en Base64
  • cfdi: Object UUID, id, serie, folio, fecha, subtotal, total
  • qr: String Código QR del PDF
404 Factura no encontrada

Tipo

application/json

Cuerpo

Factura no encontrada
{
    "message": "Factura no encontrada",
    "errors": [],
    "internal-code": "107"
}

Paginado

/cfdi Paginar CFDI

Tipo

application/json

Petición

Query String Descripción Requerido
page No. De pagina a consultar. Pag. 1 por defecto No
start_date Fecha de inicio a consultar. Formato YYYY-MM-DD Sí
end_date Fecha de final a consultar. Fecha actual por defecto No
page_size No. De resultados a consultar. 10 por defecto No

Ejemplo
GET /cfdi?page=1&start_date=2023-05-18&end_date=2023-05-23&page_size=10 HTTP/2
Host: csplug.csfacturacion.com
Accept: application/json
Authorization: Basic QUFBMDEwMTAxQUFBOnBhc3N3b3Jk

Response

200 OK

application/json

Ejemplo con resultados
{
    "current_page": 1,
    "data": [
        {
            "UUID": "CE9D3027-FFE9-D746-B1CD-8ACDB5483717",
            "FECHA": "2023-05-18",
            "TOTAL": "1078.00",
            "ESTATUS": 1, // (1)
            "FOLIO": "A-103"
        },
        // se omite el resto de nodos por fines de demostración
    ],
    "next_page_url": "http:\/\/csplug.csfacturacion.com\/cfdi?page=2",
    "path": "http:\/\/csplug.csfacturacion.com\/cfdi",
    "per_page": 20,
    "prev_page_url": null,
    "to": 20,
    "total": 25
}
  1. ✅ 1: Vigente. 2: Cancelado. 3: En Proceso. 4: Cancelación Rechazada
200 OK Sin Resultados

application/json

Ejemplo sin resultados
{
    "current_page": 1,
    "data": [],
    "first_page_url": "http:\/\/csplug.csfacturacion.com\/cfdi?page=1",
    "from": null,
    "last_page": 1,
    "last_page_url": "http:\/\/csplug.csfacturacion.com\/cfdi?page=1",
    "links": [
        {
            "url": null,
            "label": "pagination.previous",
            "active": false
        },
        {
            "url": "http:\/\/csplug.csfacturacion.com\/cfdi?page=1",
            "label": "1",
            "active": true
        },
        {
            "url": null,
            "label": "pagination.next",
            "active": false
        }
    ],
    "next_page_url": null,
    "path": "http:\/\/csplug.csfacturacion.com\/cfdi",
    "per_page": "10",
    "prev_page_url": null,
    "to": null,
    "total": 0
}

Catálagos SAT

Lista de catálogos disponibles

/catalogos Lista de catálogos disponibles

Lista de Catalogos
GET /catalogos HTTP/1.1
Content-Type: application/json
Host: csplug.csfacturacion.com
Authorization: Basic QUFBMDEwMTAxQUFBOnBhc3N3b3Jk

Response

200 OK

application/json

Example
{
    "message": "Lista de catalogos",
    "data": {
        "catalogos": [
            "cce_20_claves_pedimentos",
            "cce_20_colonias",
            "cce_20_estados"
            // resto de catalogos
            // ..
            // ..
        ]
    }
}
/catalogos/{cat} Detalle de catálogo

Tipo

application/json

Petición

URL-Param Descripción Requerido
cat Nombre del catálogo a consultar Sí

Detalle de catálogo
GET /catalogos/nomina_tipos_horas HTTP/1.1
Content-Type: application/json
Host: csplug.csfacturacion.com
Authorization: Basic QUFBMDEwMTAxQUFBOnBhc3N3b3Jk

Response

200 OK

application/json

Example
{
    "message": "Catalogos",
    "data": [
        {
            "id": "01",
            "texto": "Dobles"
        },
        {
            "id": "02",
            "texto": "Triples"
        },
        {
            "id": "03",
            "texto": "Simples"
        }
    ]
}

Filtros

/catalogos/{cat}?filter[{field}]={value} Filtrar por valores

Tipo

application/json

Petición

URL-Param Descripción Requerido
cat Nombre del catálogo a filtrar Sí
field Nombre del campo por el cual filtrar Sí
value Valor del campo por el cual filtrar Sí

Filtrar por texto Gasolina
GET /catalogos/cfdi_40_productos_servicios?filter[texto]=gasolina HTTP/1.1
Content-Type: application/json
Host: csplug.csfacturacion.com
Authorization: Basic QUFBMDEwMTAxQUFBOnBhc3N3b3Jk

Response

200 OK

application/json

Example
{
    "message": "Catalogos",
    "data": [
        {
            "id": "15101514",
            "texto": "Gasolina regular menor a 91 octanos",
            "iva_trasladado": "",
            "ieps_trasladado": "",
            "complemento": "",
            "vigencia_desde": "2022-01-01",
            "vigencia_hasta": "",
            "estimulo_frontera": "1",
            "similares": ""
        },
        // salida truncada para efectos de prueba
    ]
}

Emisores Hijos

Obtener la lista de emisores hijos

/emisores-hijos?page={n} Obtener Emisores Hijos

Tipo

application/json

Petición

Query Param Descripción Requerido
page Número de página a consultar (opcional) No
Ejemplo de petición
GET /emisores-hijos?page=1 HTTP/1.1
Host: csplug.csfacturacion.com
Authorization: Basic <credenciales>
200 OK

application/json

Ejemplo de respuesta
{
    "current_page": 1,
    "data": [
        {
            "RFC": "EKU9003173C9",
            "RAZONSOCIAL": "ESCUELA KEMPER URGATE",
            "DOMICILIOFISCAL": "91919",
            "CONFIGURACION": {
                "CALLE": "",
                "NEXT": "",
                "NINT": "",
                "COLONIA": "",
                "LOCALIDAD": "",
                "MUNICIPIO": "",
                "ESTADO": "",
                "PAIS": "",
                "CIEC": "",
                "automatizacion:csf": false,
                "automatizacion:c32d": false
            }
        }
    ],
    "first_page_url": "https://csplug.csfacturacion.com/emisores-hijos?page=1",
    "from": 1,
    "last_page": 1,
    "last_page_url": "https://csplug.csfacturacion.com/emisores-hijos?page=1",
    "links": [
        {
            "url": null,
            "label": "pagination.previous",
            "active": false
        },
        {
            "url": "https://csplug.csfacturacion.com/emisores-hijos?page=1",
            "label": "1",
            "active": true
        },
        {
            "url": null,
            "label": "pagination.next",
            "active": false
        }
    ],
    "next_page_url": null,
    "path": "https://csplug.csfacturacion.com/emisores-hijos",
    "per_page": 15,
    "prev_page_url": null,
    "to": 1,
    "total": 1
}
401 Unauthorized

application/json

Ejemplo de respuesta no autorizada
{
    "message": "Credenciales inválidas. Contratacion: CSO1304138Z0",
    "errors": [],
    "internal-code": "106"
}

Crear un nuevo emisor hijo

/emisores-hijos Crear Emisor Hijo

Tipo

application/json

Petición

JSON-Param Descripción Requerido
rfc RFC de la empresa emisora Sí
razon_social Razón social de la empresa emisora Sí
domicilio_fiscal Domicilio Fiscal de la empresa emisora Sí
config Objeto que aloja información adicional que puede representarse en el PDF de la factura No
config.calle Calle usada en la empresa No
config.numero_exterior Número exterior usado en la empresa No
config.numero_interior Número interior usado en la empresa No
config.colonia Colonia usada en la empresa No
config.localidad Localidad usada en la empresa No
config.municipio Municipio usada en la empresa No
config.estado Estado usada en la empresa No
config.pais País usado en la empresa No

Cuerpo de la solicitud:

Ejemplo de petición
{
    "rfc": "EKU9003173C9",
    "razon_social": "ESCUELA KEMPER URGATE",
    "domicilio_fiscal": "91919",
    "config": {
        "calle": "",
        "numero_exterior": "",
        "numero_interior": "",
        "colonia": "",
        "localidad": "",
        "municipio": "",
        "estado": "",
        "pais": ""
    }
}
201 Created

application/json

Ejemplo de respuesta
{
    "message": "Emisor hijo creado correctamente",
    "data": {
        "RFC": "EKU9003173C9",
        "RAZONSOCIAL": "ESCUELA KEMPER URGATE",
        "DOMICILIOFISCAL": "91919",
        "CONFIGURACION": {
            "CALLE": "",
            "NEXT": "",
            "NINT": "",
            "COLONIA": "",
            "LOCALIDAD": "",
            "MUNICIPIO": "",
            "ESTADO": "",
            "PAIS": "",
            "CIEC": "",
            "automatizacion:csf": false,
            "automatizacion:c32d": false
        }
    }
}
422 Unprocessable Entity

application/json

Ejemplo de respuesta
{
    "message": "The given data was invalid.",
    "errors": {
        "domicilio_fiscal": [
            "The domicilio fiscal field is required."
        ]
    },
    "internal-code": "101"
}

Certificados de Emisores Hijos

Obtener certificados de un emisor hijo

/emisores-hijos/{rfc}/certificados Obtener Certificados

Tipo

application/json

Petición

URL Param Descripción Requerido
rfc RFC del emisor hijo Sí
Ejemplo de petición
GET /emisores-hijos/EKU9003173C9/certificados HTTP/1.1
Host: csplug.csfacturacion.com
Authorization: Basic <credenciales>
200 OK

application/json

Ejemplo de respuesta
{
    "current_page": 1,
    "data": [
        {
            "SERIECERTIFICADO": "30001000000500003416",
            "INICIOVIGENCIA": "May 18 05:43:51 2023 CST",
            "FINVIGENCIA": "May 18 05:43:51 2027 CST",
            "FECHA": "2025-03-05",
            "TIPO": 0,
            "TIPOCERTIFICADO": 1,
            "ESTATUS": 1,
            "URL": null,
            "FECHAINICIAL": "2023-05-18 05:43:51",
            "FECHAFINAL": "2027-05-18 05:43:51",
            "RFCEMISOR": "EKU9003173C9"
        }
    ],
    "first_page_url": "https://csplug.csfacturacion.com/emisores-hijos/EKU9003173C9/certificados?page=1",
    "from": 1,
    "last_page": 1,
    "last_page_url": "https://csplug.csfacturacion.com/emisores-hijos/EKU9003173C9/certificados?page=1",
    "links": [
        {
            "url": null,
            "label": "pagination.previous",
            "active": false
        },
        {
            "url": "https://csplug.csfacturacion.com/emisores-hijos/EKU9003173C9/certificados?page=1",
            "label": "1",
            "active": true
        },
        {
            "url": null,
            "label": "pagination.next",
            "active": false
        }
    ],
    "next_page_url": null,
    "path": "https://csplug.csfacturacion.com/emisores-hijos/EKU9003173C9/certificados",
    "per_page": 15,
    "prev_page_url": null,
    "to": 1,
    "total": 1
}
401 Unauthorized

application/json

Ejemplo de respuesta no autorizada
{
    "message": "Credenciales inválidas. Contratacion: CSO1304138Z0",
    "errors": [],
    "internal-code": "106"
}

Crear un certificado de sello digital

/emisores-hijos/{rfc}/certificados Crear Certificado

Tipo

application/json

Petición

URL Param Descripción Requerido
rfc RFC del emisor hijo Sí
JSON Param Descripción Requerido
key Llave privada del CSD Sí
cer Certificado público del CSD Sí
password Contraseña de la llave privada Sí

Cuerpo de la solicitud:

Ejemplo de petición
{
    "key": "<clave_privada_en_base64>",
    "cer": "<certificado_en_base64>",
    "password": "12345678a"
}
201 Created

application/json

Ejemplo de respuesta
{
    "message": "Certificado de sello creado correctamente",
    "data": {
        "SERIECERTIFICADO": "30001000000500003416",
        "FECHAINICIAL": "2023-05-18 05:43:51",
        "FECHAFINAL": "2027-05-18 05:43:51",
        "INICIOVIGENCIA": "May 18 05:43:51 2023 CST",
        "FINVIGENCIA": "May 18 05:43:51 2027 CST",
        "FECHA": "2025-03-05",
        "TIPO": 0,
        "TIPOCERTIFICADO": 1,
        "ESTATUS": 1,
        "RFCEMISOR": "EKU9003173C9"
    }
}
422 Unprocessable Entity

application/json

Ejemplo de respuesta
{
    "message": "La contraseña de la llave privada es incorrecta",
    "errors": {
        "message": "Error al desencriptar la llave privada"
    },
    "internal-code": "101"
}

Series

Obtener lista de series

/series Obtener Series

Tipo

application/json

Petición

Ejemplo de petición
GET /series HTTP/1.1
Host: csplug.csfacturacion.com
Authorization: Basic <credenciales>
200 OK

application/json

Ejemplo de respuesta
{
    "current_page": 1,
    "data": [
        {
            "SERIE": "TESTFROMAPI",
            "RANGOINICIAL": 1,
            "FECHA": "2025-03-06",
            "DECIMALES": 2,
            "RFCEMISOR": null
        },
        {
            "SERIE": "PGCN",
            "RANGOINICIAL": 1,
            "FECHA": "2022-12-02",
            "DECIMALES": 2,
            "RFCEMISOR": null
        },
    ],
    "first_page_url": "https://csplug.csfacturacion.com/series?page=1",
    "from": 1,
    "last_page": 1,
    "last_page_url": "https://csplug.csfacturacion.com/series?page=1",
    "links": [
        {
            "url": null,
            "label": "pagination.previous",
            "active": false
        },
        {
            "url": "https://csplug.csfacturacion.com/series?page=1",
            "label": "1",
            "active": true
        },
        {
            "url": null,
            "label": "pagination.next",
            "active": false
        }
    ],
    "next_page_url": null,
    "path": "https://csplug.csfacturacion.com/series",
    "per_page": 15,
    "prev_page_url": null,
    "to": 15,
    "total": 15
}
401 Unauthorized

application/json

Ejemplo de respuesta no autorizada
{
    "message": "Credenciales inválidas. Contratacion: CSO1304138Z0",
    "errors": [],
    "internal-code": "106"
}

Crear una nueva serie

/series Crear Serie

Tipo

application/json

Petición

JSON Param Descripción Requerido
serie Nombre para la serie Sí
rango_inicial Número en el que empezará el contador del folio automático Sí
logo Base64 del logo en formato media "data:image/png;base64,..." No
cantidad_decimales Cantidad de decimales a representar en la versión impresa No

Cuerpo de la solicitud:

Ejemplo de petición
{
    "serie": "TESTFROMAPI",
    "rango_inicial": 1,
    "logo": "data:image/png;base64,...", // Logo en base64 con mediatype
    "cantidad_decimales": 2,
}
201 Created

application/json

Ejemplo de respuesta
{
    "message": "Serie creada",
    "data": {
        "SERIE": "TESTFROMAPI",
        "RANGOINICIAL": 1,
        "RUTALOGO": "logosplantillas/TESTFROMAPI_67d09a3317e78.png",
        "DECIMALES": 2,
        "TIPO": 1,
        "IDPLANTILLA": 78,
        "ESTATUS": 1,
        "VERSION": 2,
        "FECHA": "2025-03-11"
    }
}
422 Unprocessable Entity

application/json

Ejemplo de respuesta
{
    "message": "La serie ya existe",
    "errors": [],
    "internal-code": "409"
}

Consideraciones Finales

  • Todos los endpoints requieren autenticación mediante Authorization: Basic <credenciales>.
  • Las respuestas siguen el formato JSON.
  • En caso de errores, la API responderá con códigos HTTP y mensajes detallados.

Códigos de respuesta comunes:

  • 200 OK - Solicitud procesada correctamente.
  • 201 Created - Recurso creado exitosamente.
  • 400 Bad Request - Error en la solicitud.
  • 401 Unauthorized - Credenciales incorrectas.
  • 404 Not Found - Recurso no encontrado.