Documentación API

1.Autenticación

/api/auth · Sin versión · AllowAnonymous

Flujo: 1) Inicia sesión en web.sat-go.com → 2) Llama POST /api/v1/users/CreateKey para obtener tu API Key → 3) Usa esa key aquí para obtener el JWT que irá en Authorization: Bearer <token>.

POST

/api/auth/token

Obtiene el JWT usando la API Key (query param)

Si no tienes la key, ve a web.sat-go.com, inicia sesión y ejecuta /api/v1/users/CreateKey primero.

Parámetro	En	Tipo	Req.	Descripción
key	Query	string	✓	API Key generada con /users/CreateKey

Respuestas

200 TokenResponse401 string

Ejemplo 200 OK

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiIxMjMiLCJlbWFpbCI6InVzZXJAc2F0LWdvLmNvbSIsImV4cCI6MTc4MDAwMDAwMH0.signature",
  "expiresAt": "2026-12-31T00:00:00Z",
  "tokenType": "Bearer"
}

401: "Invalid key"

POST

/api/auth/token-json

Obtiene el JWT usando la API Key (body JSON)

Parámetro	En	Tipo	Req.	Descripción
key	Body JSON	string	✓	API Key generada con /users/CreateKey

Respuestas

200 TokenResponse400 string401 string

Ejemplo 200 OK

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2026-12-31T00:00:00Z",
  "tokenType": "Bearer"
}

400: "Key is required"

401: "Invalid key"

2.Usuarios

/api/v1/users · Requiere: Authorization: Bearer <token>

POST

/api/v1/users/CreateKey

Genera la API Key del usuario autenticado

La key generada se usa en /api/auth/token para obtener un JWT de larga duración.

Sin parámetros. La identidad se toma del JWT del header Authorization.

Respuestas

200 { key: string }400 string

Ejemplo 200 OK

{ "key": "hW3kP9mQzR7vXnL2cE5tYuA4sBjDfGhIoJkLmNp==" }

400: "Invalid token claims"

GET

/api/v1/users/fiscal-data

Obtiene los datos fiscales del usuario autenticado

Sin parámetros adicionales.

Respuestas

200 UserFiscalDataDto401 string500 string

Ejemplo 200 OK

{
  "rfc": "XAXX010101ABC",
  "razonSocial": "Mi Empresa SA de CV",
  "codigoPostal": "06600",
  "regimenFiscal": "612",
  "emailFacturacion": "facturacion@miempresa.com"
}

401: "UserUuid not found in token."

500: "Internal server error: Connection timeout"

PUT

/api/v1/users/fiscal-data

Guarda o actualiza los datos fiscales del usuario autenticado

Parámetro	En	Tipo	Req.	Descripción
rfc	Body JSON	string	–	RFC del usuario
razonSocial	Body JSON	string	–	Nombre o razón social
codigoPostal	Body JSON	string	–	Código postal fiscal
regimenFiscal	Body JSON	string	–	Clave del régimen fiscal (ej. "612")
emailFacturacion	Body JSON	string	–	Correo para recibir facturas

Respuestas

200 UserFiscalDataDto401 string500 string

Ejemplo 200 OK (devuelve el objeto actualizado)

{
  "rfc": "XAXX010101ABC",
  "razonSocial": "Mi Empresa SA de CV",
  "codigoPostal": "06600",
  "regimenFiscal": "612",
  "emailFacturacion": "nuevo@miempresa.com"
}

401: "UserUuid not found in token."

3.Proveedor de Secretos

/api/v1/secretprovider · Requiere: Authorization: Bearer <token>

Permite guardar la CIEC y/o la FIEL en un Key Vault propio del cliente (CrossTenant) o gestionado por SatGo (SatGoManaged). Una vez configurado, los endpoints del SAT no requieren el header Secret ni los archivos FIEL.

GET

/api/v1/secretprovider/identity

Devuelve las opciones de configuración disponibles (CrossTenant y SatGoManaged)

Respuestas

200 object (guía)

Ejemplo 200 OK

{
  "options": {
    "CrossTenant": "Registra tu propio Azure Key Vault. SatGo necesita acceso de lectura.",
    "SatGoManaged": "SatGo almacena el secreto cifrado en su propio vault."
  },
  "secretEndpoints": { "crossTenant": "POST /secret/register", "satGoManaged": "POST /secret/store" },
  "signingKeyEndpoints": { "crossTenant": "POST /signing-key/register", "satGoManaged": "POST /signing-key/store" }
}

CIEC — Secreto

POST

/api/v1/secretprovider/secret/register

Registra la referencia a la CIEC en el vault propio del cliente (CrossTenant)

Parámetro	En	Tipo	Req.	Descripción
rfc	Body JSON	string	✓	RFC del contribuyente
providerType	Body JSON	string	✓	AzureKeyVault \| AwsSecretsManager \| HashiCorpVault
providerUri	Body JSON	string (HTTPS)	✓	URI del vault. Ej: https://mi-vault.vault.azure.net/
secretName	Body JSON	string	✓	Nombre del secreto dentro del vault
providerOptions	Body JSON	string (JSON)	–	Opciones adicionales. Ej: {"tenantId":"..."}

Respuestas

200 object400401404

Ejemplo 200 OK

{
  "rfc": "XAXX010101ABC",
  "providerType": "AzureKeyVault",
  "providerUri": "https://mi-vault.vault.azure.net/",
  "secretName": "ciec-xaxx010101abc",
  "message": "Proveedor de secreto registrado correctamente."
}

400: "El campo 'providerUri' debe ser una URL HTTPS válida."

POST

/api/v1/secretprovider/secret/store

Guarda la CIEC en el vault gestionado por SatGo (SatGoManaged)

Parámetro	En	Tipo	Req.	Descripción
rfc	Body JSON	string	✓	RFC del contribuyente
secretValue	Body JSON	string	✓	Valor de la CIEC. Nunca se devuelve en ninguna respuesta.

Respuestas

200 object400401404503

Ejemplo 200 OK

{
  "rfc": "XAXX010101ABC",
  "providerType": "SatGoManaged",
  "secretName": "satgo-ciec-xaxx010101abc",
  "message": "CIEC almacenada correctamente en el vault de SatGo."
}

503: "El servicio de vault no está disponible en este momento."

DELETE

/api/v1/secretprovider/{rfc}

Elimina el proveedor de secretos de un RFC

Si era SatGoManaged, también elimina el secreto del vault de SatGo.

Parámetro	En	Tipo	Req.	Descripción
rfc	Route	string	✓	RFC del contribuyente

Respuestas

200 object400401404503

Ejemplo 200 OK

{ "rfc": "XAXX010101ABC", "message": "Proveedor de secreto eliminado correctamente." }

404: "No se encontró proveedor de secreto para el RFC especificado."

GET

/api/v1/secretprovider/{rfc}/status

Consulta el estado del proveedor de secretos de un RFC

Parámetro	En	Tipo	Req.	Descripción
rfc	Route	string	✓	RFC del contribuyente

Respuestas

200 object401404

Ejemplo 200 OK

{
  "rfc": "XAXX010101ABC",
  "isRegistered": true,
  "providerType": "SatGoManaged",
  "providerUri": null,
  "secretName": "satgo-ciec-xaxx010101abc",
  "updatedAt": "2024-03-15T10:30:00Z"
}

FIEL — Llave de Firma

POST

/api/v1/secretprovider/signing-key/register

Registra la llave RSA de la FIEL en el vault propio del cliente (CrossTenant)

Requiere rol 'Key Vault Crypto User'. Futuras peticiones solo necesitan el .cer.

Parámetro	En	Tipo	Req.	Descripción
rfc	Body JSON	string	✓	RFC del contribuyente
providerType	Body JSON	string	✓	AzureKeyVault \| AwsSecretsManager \| HashiCorpVault
providerUri	Body JSON	string	✓	URI del vault
keyName	Body JSON	string	✓	Nombre de la llave RSA en el vault
keyOptions	Body JSON	string (JSON)	–	Ej: {"tenantId":"..."}

Respuestas

200 object400401404

Ejemplo 200 OK

{
  "rfc": "XAXX010101ABC",
  "providerType": "AzureKeyVault",
  "providerUri": "https://mi-vault.vault.azure.net/",
  "keyName": "fiel-rsa-xaxx010101abc",
  "message": "Llave de firma registrada correctamente."
}

POST

/api/v1/secretprovider/signing-key/store

Importa la FIEL (.cer + .key en base64) al vault gestionado por SatGo

SatGo genera un PKCS12 y lo importa en su vault. Futuras peticiones solo necesitan el .cer.

Parámetro	En	Tipo	Req.	Descripción
rfc	Body JSON	string	✓	RFC del contribuyente
cerFileBase64	Body JSON	string (base64)	✓	Bytes del .cer (DER o PEM) codificados en base64
keyFileBase64	Body JSON	string (base64)	✓	Bytes del .key (PKCS#8 DER) en base64. Nunca se devuelve.
password	Body JSON	string	–	Contraseña del .key (omitir si no tiene contraseña)

Respuestas

200 object400401404503

Ejemplo 200 OK

{
  "rfc": "XAXX010101ABC",
  "providerType": "SatGoManaged",
  "certName": "satgo-fiel-xaxx010101abc",
  "message": "FIEL importada y almacenada correctamente en el vault de SatGo."
}

400: "El .cer proporcionado no es válido o está expirado."

DELETE

/api/v1/secretprovider/signing-key/{rfc}

Elimina el proveedor de firma de un RFC

Si era SatGoManaged, también elimina la llave del vault de SatGo.

Parámetro	En	Tipo	Req.	Descripción
rfc	Route	string	✓	RFC del contribuyente

Respuestas

200 object400401404503

Ejemplo 200 OK

{ "rfc": "XAXX010101ABC", "message": "Proveedor de firma eliminado correctamente." }

GET

/api/v1/secretprovider/signing-key/{rfc}/status

Consulta el estado del proveedor de firma de un RFC

Parámetro	En	Tipo	Req.	Descripción
rfc	Route	string	✓	RFC del contribuyente

Respuestas

200 object401404

Ejemplo 200 OK

{
  "rfc": "XAXX010101ABC",
  "isRegistered": true,
  "providerType": "SatGoManaged",
  "keyName": "satgo-fiel-xaxx010101abc",
  "updatedAt": "2024-03-15T10:30:00Z"
}

4.Consultar SAT (CIEC / FIEL)

/api/v2/consultar · Requiere: Authorization: Bearer <token> + RFC: <rfc>

Headers comunes: Authorization: Bearer <token> | RFC: XAXX010101ABC
Endpoints CIEC también requieren: Secret: <contraseña-ciec> (o configurar SecretProvider).
Endpoints FIEL reciben archivos como multipart/form-data: Pfx + Contrasena ó Certificado + llavePrivada + Contrasena.

Opinión de Cumplimiento

GET

/api/v2/consultar/imssoc

Obtiene la opinión de cumplimiento del IMSS

Se conecta directo al IMSS. Solo requiere RFC (no necesita CIEC).

Sin parámetros adicionales. Solo headers comunes (sin Secret).

Respuestas

200 application/pdf400 string

📄

OpinionCumplimientoIMSS.pdf

Content-Type: application/pdf

400: "No se pudo obtener la opinión de cumplimiento del IMSS. Verifique el RFC."

GET

/api/v2/consultar/oc

Obtiene la opinión de cumplimiento del SAT (CIEC)

Requiere header Secret (CIEC).

Respuestas

200 application/pdf400 string

📄

OpinionCumplimiento.pdf

Content-Type: application/pdf

400: "Error al autenticar con el SAT. Verifique su CIEC."

GET

/api/v2/consultar/ocpublico

Obtiene la opinión de cumplimiento pública del SAT (solo RFC)

Sin Secret. Solo header RFC.

Respuestas

200 application/pdf400 string

📄

OpinionCumplimientoPublico.pdf

Content-Type: application/pdf

POST

/api/v2/consultar/ocfiel

Obtiene la opinión de cumplimiento usando la FIEL

Body — multipart/form-data(elige una de las 3 opciones)

Opción A — PFX (PKCS#12)

Campo	Tipo	Descripción
Pfx	file	Archivo `.pfx` / `.p12` (PKCS#12 que incluye cert + llave privada)
Contrasena	string	Contraseña del archivo PFX

Opción B — Certificado + Llave privada

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer` del SAT (DER o PEM)
llavePrivada	file	Archivo `.key` del SAT (PKCS#8 DER)
Contrasena	string	Contraseña de la llave privada

Opción C — Solo certificado (llave en SecretProvider)

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer`. La llave privada se toma del Key Vault registrado en `/secretprovider/signing-key`

Respuestas

200 application/pdf400 string

📄

OpinionCumplimiento.pdf

Content-Type: application/pdf

Autenticación con FIEL. Mayor validez oficial que la consulta con CIEC.

400: "El certificado FIEL ha expirado o no coincide con el RFC."

POST

/api/v2/consultar/oc/validar-pdf

Valida la autenticidad de un PDF de Opinión de Cumplimiento

Extrae RFC, folio, sentido y URL del QR, consulta el validador del SAT y compara los datos.

Parámetro	En	Tipo	Req.	Descripción
Pdf	form-data	file (application/pdf)	✓	PDF de la Opinión de Cumplimiento a validar

Respuestas

200 OcPdfValidacionResult400 string

Ejemplo 200 OK

{
  "datosDelPdf": {
    "nombre": "JUAN PEREZ GARCIA",
    "rfc": "PEGJ800101ABC",
    "folio": "F2024001234",
    "fecha": "15/01/2024",
    "sentido": "POSITIVO",
    "qrUrl": "https://omawww.sat.gob.mx/.../validar.aspx?id=F2024001234"
  },
  "validacionSat": {
    "esValido": true,
    "folio": "F2024001234",
    "rfc": "PEGJ800101ABC",
    "sentido": "POSITIVO",
    "errorMessage": null
  },
  "datosCoinciden": true
}

400: "El archivo no es una Opinión de Cumplimiento del SAT válida."

Constancia de Situación Fiscal

GET

/api/v2/consultar/csf

Descarga la Constancia de Situación Fiscal (CIEC)

Requiere header Secret (CIEC). Reintenta hasta 3 veces automáticamente.

Respuestas

200 application/pdf400 string

📄

ConstanciaFiscal.pdf

Content-Type: application/pdf

Incluye datos de identificación y ubicación fiscal.

400: "CIEC incorrecta o sesión SAT expirada después de 3 intentos."

POST

/api/v2/consultar/csffiel

Descarga la Constancia de Situación Fiscal usando la FIEL

Body — multipart/form-data(elige una de las 3 opciones)

Opción A — PFX (PKCS#12)

Campo	Tipo	Descripción
Pfx	file	Archivo `.pfx` / `.p12` (PKCS#12 que incluye cert + llave privada)
Contrasena	string	Contraseña del archivo PFX

Opción B — Certificado + Llave privada

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer` del SAT (DER o PEM)
llavePrivada	file	Archivo `.key` del SAT (PKCS#8 DER)
Contrasena	string	Contraseña de la llave privada

Opción C — Solo certificado (llave en SecretProvider)

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer`. La llave privada se toma del Key Vault registrado en `/secretprovider/signing-key`

Respuestas

200 application/pdf400 string

📄

{rfc}-constancia_situacion_fiscal.pdf

Content-Type: application/pdf

Comunicados y Notificaciones

POST

/api/v2/consultar/comunicadosfiel

Obtiene los comunicados del portal del SAT usando la FIEL

Parámetro	En	Tipo	Req.	Descripción
descargar	Query	bool	–	true = descarga el PDF del acuse; false = solo devuelve el título (default: true)

Body — multipart/form-data(elige una de las 3 opciones)

Opción A — PFX (PKCS#12)

Campo	Tipo	Descripción
Pfx	file	Archivo `.pfx` / `.p12` (PKCS#12 que incluye cert + llave privada)
Contrasena	string	Contraseña del archivo PFX

Opción B — Certificado + Llave privada

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer` del SAT (DER o PEM)
llavePrivada	file	Archivo `.key` del SAT (PKCS#8 DER)
Contrasena	string	Contraseña de la llave privada

Opción C — Solo certificado (llave en SecretProvider)

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer`. La llave privada se toma del Key Vault registrado en `/secretprovider/signing-key`

Respuestas

200 ComunicadosResult400 string

Ejemplo 200 OK

{
  "success": true,
  "errorMessage": null,
  "totalComunicados": 2,
  "totalArchivosDescargados": 2,
  "comunicados": [
    {
      "id": "COM-2024-001",
      "titulo": "Actualización de datos en el RFC",
      "fileName": "comunicado_2024_001.pdf",
      "fechaDescarga": "2024-03-15T10:30:00",
      "descargaExitosa": true,
      "esLeido": false
    }
  ]
}

POST

/api/v2/consultar/notificacionesfiel

Obtiene las notificaciones del portal del SAT usando la FIEL

Soporta reutilizar sesión con requestId para no reautenticar en llamadas sucesivas (paginación).

Parámetro	En	Tipo	Req.	Descripción
requestId	Query	string (GUID)	–	ID de sesión previo. Omitir en la primera llamada.
tipoNotificacion	Query	string	–	notificadas \| pendientes (default: notificadas)
descargarNotificaciones	Query	bool	–	true = descarga PDFs; false = solo metadata (default: false)

Body — multipart/form-data(elige una de las 3 opciones)

Opción A — PFX (PKCS#12)

Campo	Tipo	Descripción
Pfx	file	Archivo `.pfx` / `.p12` (PKCS#12 que incluye cert + llave privada)
Contrasena	string	Contraseña del archivo PFX

Opción B — Certificado + Llave privada

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer` del SAT (DER o PEM)
llavePrivada	file	Archivo `.key` del SAT (PKCS#8 DER)
Contrasena	string	Contraseña de la llave privada

Opción C — Solo certificado (llave en SecretProvider)

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer`. La llave privada se toma del Key Vault registrado en `/secretprovider/signing-key`

Respuestas

200 NotificacionesResult400404

Ejemplo 200 OK

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "success": true,
  "totalRegistros": 5,
  "paginaActual": 1,
  "totalPaginas": 1,
  "registrosPorPagina": 10,
  "notificaciones": [
    { "folio": "NOT-2024-001", "autoridad": "SAT", "acto": "Requerimiento de información", "fecha": "10/03/2024", "pdfDescargado": false }
  ]
}

404: "El requestId especificado no existe o ya expiró."

Información Fiscal

GET

/api/v2/consultar/informacionfiscal

Obtiene la información fiscal del portal SAT (CIEC)

Parámetro	En	Tipo	Req.	Descripción
requestId	Query	string (GUID)	–	ID de sesión previa para reutilizar cookies del SAT

Respuestas

200 InformacionFiscalResult400 string

Ejemplo 200 OK

{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "datosIdentificacion": {
    "fecha": "15/03/2024", "hora": "10:30:45", "situacion": "ACTIVO",
    "rfc": "XAXX010101ABC", "nombre": "JUAN PEREZ GARCIA", "curp": "PEGJ800101HDFRZN01"
  },
  "ubicacionFiscal": {
    "entidadFederativa": "CIUDAD DE MEXICO", "municipioDemarcacionTerritorial": "CUAUHTEMOC",
    "codigoPostal": "06600", "colonia": "CENTRO", "nombreVialidad": "AV JUAREZ", "numeroExterior": "100"
  }
}

POST

/api/v2/consultar/informacionfiscalfiel

Obtiene la información fiscal usando la FIEL

Parámetro	En	Tipo	Req.	Descripción
requestId	Query	string (GUID)	–	ID de sesión previo para reutilizar cookies

Body — multipart/form-data(elige una de las 3 opciones)

Opción A — PFX (PKCS#12)

Campo	Tipo	Descripción
Pfx	file	Archivo `.pfx` / `.p12` (PKCS#12 que incluye cert + llave privada)
Contrasena	string	Contraseña del archivo PFX

Opción B — Certificado + Llave privada

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer` del SAT (DER o PEM)
llavePrivada	file	Archivo `.key` del SAT (PKCS#8 DER)
Contrasena	string	Contraseña de la llave privada

Opción C — Solo certificado (llave en SecretProvider)

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer`. La llave privada se toma del Key Vault registrado en `/secretprovider/signing-key`

Respuestas

200 InformacionFiscalResult400404

Ejemplo 200 OK (misma estructura que /informacionfiscal)

{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "datosIdentificacion": { "situacion": "ACTIVO", "rfc": "XAXX010101ABC", "nombre": "JUAN PEREZ GARCIA" },
  "ubicacionFiscal": { "entidadFederativa": "CIUDAD DE MEXICO", "codigoPostal": "06600" }
}

404: "El requestId especificado no existe o ya expiró."

Facturas (CFDI)

GET

/api/v2/consultar/fac

Descarga facturas desde el portal del SAT (CIEC)

Requiere header Secret (CIEC).

Parámetro	En	Tipo	Req.	Descripción
tipo	Query	string	✓	emitidos \| recibidos
tipoBusqueda	Query	TipoBusqueda	✓	UUID = 0 \| Fecha = 1
UUID	Query	string	–	UUID del CFDI (cuando tipoBusqueda = 0)
estatusFactura	Query	int	✓	-1 Todos \| 0 Cancelados \| 1 Vigentes
anio	Query	int	✓	Año de emisión
mes	Query	int	✓	Mes (1-12)
dia	Query	int	–	Día (0 = todos)
requestId	Query	string (GUID)	–	ID de sesión previa
descargaComprobantes	Query	bool	–	true = descarga XML
descargaPdfs	Query	bool	–	true = descarga PDF de cada CFDI
tipoComprobante	Query	TipoComprobante	–	Todos, Estandar, RecepcionPagos, CartaPorte...

Respuestas

200 ComprobanteResultV2400404

Ejemplo 200 OK

{
  "success": true,
  "count": 2,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "folioDescarga": null,
  "comprobantes": [
    {
      "uuid": "6128396f-c09b-4ec6-8699-43c5d7743b8f",
      "rfcEmisor": "XAXX010101ABC",
      "razonSocialEmisor": "Mi Empresa SA de CV",
      "rfcReceptor": "GODE561231GR8",
      "fechaEmision": "2024-03-15T10:00:00",
      "total": 11600.00,
      "estadoDeComprobante": "Vigente"
    }
  ]
}

POST

/api/v2/consultar/facfiel

Descarga facturas usando la FIEL con soporte de descarga masiva (solicitaMetadata)

Body — multipart/form-data(elige una de las 3 opciones)

Opción A — PFX (PKCS#12)

Campo	Tipo	Descripción
Pfx	file	Archivo `.pfx` / `.p12` (PKCS#12 que incluye cert + llave privada)
Contrasena	string	Contraseña del archivo PFX

Opción B — Certificado + Llave privada

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer` del SAT (DER o PEM)
llavePrivada	file	Archivo `.key` del SAT (PKCS#8 DER)
Contrasena	string	Contraseña de la llave privada

Opción C — Solo certificado (llave en SecretProvider)

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer`. La llave privada se toma del Key Vault registrado en `/secretprovider/signing-key`

Parámetro	En	Tipo	Req.	Descripción
tipo	Query	string	✓	emitidos \| recibidos
tipoBusqueda	Query	TipoBusqueda	✓	UUID = 0 \| Fecha = 1
solicitaMetadata	Query	bool	✓	true = solicita descarga masiva (devuelve FolioDescarga)
estatusFactura	Query	int	✓	-1 Todos \| 0 Cancelados \| 1 Vigentes
fecha_inicial / fecha_final	Query	string	–	Formato: yyyy-MM-dd HH:mm:ss
descargaComprobantes / descargaPdfs	Query	bool	–	true = descarga XML / PDF

Respuestas

200 ComprobanteResultV2400404

Ejemplo 200 OK (solicitaMetadata=true)

{
  "success": true,
  "count": 150,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "folioDescarga": "FOL_20240315_ABC_001",
  "comprobantes": []
}

POST

/api/v2/consultar/retencionfiel

Descarga comprobantes de retención usando la FIEL

Body — multipart/form-data(elige una de las 3 opciones)

Opción A — PFX (PKCS#12)

Campo	Tipo	Descripción
Pfx	file	Archivo `.pfx` / `.p12` (PKCS#12 que incluye cert + llave privada)
Contrasena	string	Contraseña del archivo PFX

Opción B — Certificado + Llave privada

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer` del SAT (DER o PEM)
llavePrivada	file	Archivo `.key` del SAT (PKCS#8 DER)
Contrasena	string	Contraseña de la llave privada

Opción C — Solo certificado (llave en SecretProvider)

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer`. La llave privada se toma del Key Vault registrado en `/secretprovider/signing-key`

Parámetros de query similares a /facfiel (sin tipoComprobante ni descargaPdfs).

Respuestas

200 RetencionResultV2400404

Ejemplo 200 OK

{
  "success": true,
  "count": 1,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "folioDescarga": null,
  "indices": [
    {
      "uuid": "6128396f-c09b-4ec6-8699-43c5d7743b8f",
      "rfcEmisor": "XAXX010101ABC",
      "rfcReceptor": "GODE561231GR8",
      "montoTotOperacion": 50000.00,
      "montoTotRetenido": 5000.00,
      "estado": "Vigente"
    }
  ]
}

POST

/api/v2/consultar/descargametadatafiel

Descarga el paquete de metadata de una solicitud masiva (FIEL)

Parámetro	En	Tipo	Req.	Descripción
folioDescarga	Query	string	✓	Folio devuelto por /facfiel cuando solicitaMetadata=true
requestId	Query	string (GUID)	–	ID de sesión previa

Body — multipart/form-data(elige una de las 3 opciones)

Opción A — PFX (PKCS#12)

Campo	Tipo	Descripción
Pfx	file	Archivo `.pfx` / `.p12` (PKCS#12 que incluye cert + llave privada)
Contrasena	string	Contraseña del archivo PFX

Opción B — Certificado + Llave privada

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer` del SAT (DER o PEM)
llavePrivada	file	Archivo `.key` del SAT (PKCS#8 DER)
Contrasena	string	Contraseña de la llave privada

Opción C — Solo certificado (llave en SecretProvider)

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer`. La llave privada se toma del Key Vault registrado en `/secretprovider/signing-key`

Respuestas

200 MetadataResult400404

Ejemplo 200 OK

{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "folioId": "FOL_20240315_ABC_001",
  "file": "UEsDBAoAAAAAAJNE7VgAAAAAAAAAAAAAAAAFAAAAQ0ZESXhQ..."
}

El campo file contiene el ZIP de metadata codificado en base64.

404: "El folio de descarga no existe o ya fue procesado."

POST

/api/v2/consultar/descargaretencionmetadatafiel

Descarga el paquete de metadata de retenciones (FIEL)

Parámetro	En	Tipo	Req.	Descripción
folioDescarga	Query	string	✓	Folio devuelto por /retencionfiel cuando solicitaMetadata=true
requestId	Query	string (GUID)	–	ID de sesión previa

Body — multipart/form-data(elige una de las 3 opciones)

Opción A — PFX (PKCS#12)

Campo	Tipo	Descripción
Pfx	file	Archivo `.pfx` / `.p12` (PKCS#12 que incluye cert + llave privada)
Contrasena	string	Contraseña del archivo PFX

Opción B — Certificado + Llave privada

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer` del SAT (DER o PEM)
llavePrivada	file	Archivo `.key` del SAT (PKCS#8 DER)
Contrasena	string	Contraseña de la llave privada

Opción C — Solo certificado (llave en SecretProvider)

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer`. La llave privada se toma del Key Vault registrado en `/secretprovider/signing-key`

Respuestas

200 MetadataResult400404

Ejemplo 200 OK

{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "folioId": "FOL_RET_20240315_001",
  "file": "UEsDBAoAAAAAAJNE7VgAAAAAAAAAAAAAAAAFAAAAUkVU..."
}

Declaraciones

GET

/api/v2/consultar/dec

Descarga declaraciones y pagos (CIEC) como ZIP

Requiere header Secret (CIEC).

Parámetro	En	Tipo	Req.	Descripción
ejercicio	Query	int	✓	Año fiscal. Ej: 2024
mes	Query	int	–	Mes (1-12). 0 = todo el año
tipoDocumento	Query	string	–	declaracion \| pago
requestId	Query	string (GUID)	–	ID de sesión previa

Respuestas

200 application/zip400 string

📦

Declaraciones.zip

Content-Type: application/zip

Header de respuesta: X-RequestId: <guid> (úsalo para reutilizar la sesión)

400: "CIEC incorrecta o no existen declaraciones para el ejercicio indicado."

POST

/api/v2/consultar/decfiel

Descarga declaraciones y pagos usando la FIEL como ZIP

Incluye declaraciones realizadas y pagos. El header de respuesta X-RequestId permite reusar la sesión SAT.

Body — multipart/form-data(elige una de las 3 opciones)

Opción A — PFX (PKCS#12)

Campo	Tipo	Descripción
Pfx	file	Archivo `.pfx` / `.p12` (PKCS#12 que incluye cert + llave privada)
Contrasena	string	Contraseña del archivo PFX

Opción B — Certificado + Llave privada

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer` del SAT (DER o PEM)
llavePrivada	file	Archivo `.key` del SAT (PKCS#8 DER)
Contrasena	string	Contraseña de la llave privada

Opción C — Solo certificado (llave en SecretProvider)

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer`. La llave privada se toma del Key Vault registrado en `/secretprovider/signing-key`

Parámetro	En	Tipo	Req.	Descripción
ejercicio	Query	int	✓	Año fiscal. Ej: 2025
mes	Query	int	–	Mes (1-12). 0 = todo el año
tipoDocumento	Query	string	–	declaracion \| pago
requestId	Query	string (GUID)	–	ID de sesión previa

Respuestas

200 application/zip400404

📦

Declaraciones_{ejercicio}_{rfc}.zip

Content-Type: application/zip

Header de respuesta: X-RequestId: <guid>

5.EFOS — Lista Negra SAT 69-B

/api/v2/efos · Requiere: Authorization: Bearer <token>

GET

/api/v2/efos/rfc/{rfc}

Busca un RFC en la lista negra 69-B del SAT

Si el RFC aparece en la lista devuelve los registros con situación y fecha de publicación. Si no aparece, devuelve 404.

Parámetro	En	Tipo	Req.	Descripción
rfc	Route	string	✓	RFC a consultar

Respuestas

200 List<EfosContribuyente>404 string500 string

Ejemplo 200 OK (RFC encontrado en lista 69-B)

[
  {
    "id": 12345,
    "rfc": "XAXX010101ABC",
    "nombreContribuyente": "EMPRESA FANTASMA SA DE CV",
    "situacionContribuyente": "Definitivo",
    "numeroOficioGlobalPresuncionSAT": "900-05-2020-00001",
    "publicacionPaginaSATPresuntos": "2020-01-15",
    "publicacionDOFPresuntos": "2020-01-20",
    "publicacionPaginaSATDefinitivos": "2020-07-15",
    "publicacionDOFDefinitivos": "2020-07-20"
  }
]

404: "RFC No encontrado"

500: "Servicio no disponible"

6.REPSE

/api/v2/repse · Requiere: Authorization: Bearer <token>

Flujo de 2 pasos: 1) GET /consultar/razon-social encola la búsqueda → devuelve un requestId. 2) GET /resultado/{requestId} consulta el resultado (pending → done | failed).

GET

/api/v2/repse/consultar/razon-social

Encola una consulta REPSE por razón social

Inicia la búsqueda de forma asíncrona. Usa el requestId devuelto para consultar el resultado.

Parámetro	En	Tipo	Req.	Descripción
razonSocial	Query	string	✓	Nombre o razón social a buscar (mínimo 3 caracteres)

Respuestas

200 RepseRequestResult400500

Ejemplo 200 OK

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "success": true,
  "message": "Consulta encolada exitosamente. Use el requestId para obtener el resultado."
}

400: "El parámetro 'razonSocial' debe tener al menos 3 caracteres."

GET

/api/v2/repse/resultado/{requestId}

Recupera el resultado de una consulta REPSE encolada

AllowAnonymous. Devuelve status (pending/done/failed), outcome, screenshotUrl y el registro si ya fue procesado.

Parámetro	En	Tipo	Req.	Descripción
requestId	Route	GUID	✓	RequestId devuelto por /consultar/razon-social

Respuestas

200 object (con status, registro)404 object

Ejemplo 200 OK — status: "done" (encontrado)

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "done",
  "outcome": "found",
  "success": true,
  "errorMessage": null,
  "screenshotUrl": "https://satgostorage.blob.core.windows.net/repse/a1b2c3d4.png",
  "registro": {
    "folio": "REPSE-12345",
    "nombre": "SERVICIOS INTEGRALES SA DE CV",
    "entidad": "CIUDAD DE MEXICO",
    "avisoRegistro": "A-2023-001",
    "vigencia": "2025-12-31",
    "servicios": ["Limpieza", "Vigilancia"]
  }
}

status: "pending" (aún procesando)

{ "requestId": "a1b2c3d4-...", "status": "pending", "outcome": null, "success": true, "registro": null }

404: "{ "requestId": "...", "success": false, "errorMessage": "Solicitud no encontrada." }"

7.SAT Web Service — Descarga Masiva

/api/v2/satwebservice · Requiere: Authorization: Bearer <token> + RFC: <rfc>

Flujo de 3 pasos: 1) POST /solicita → obtén IdSolicitud. 2) POST /verifica hasta EstadoSolicitud=3 → obtén IdsPaquetes. 3) POST /descarga → obtén paqueteBase64 (ZIP con XMLs).

POST

/api/v2/satwebservice/solicita

Solicita descarga masiva de CFDI o Metadata al SAT

Body — multipart/form-data(elige una de las 3 opciones)

Opción A — PFX (PKCS#12)

Campo	Tipo	Descripción
Pfx	file	Archivo `.pfx` / `.p12` (PKCS#12 que incluye cert + llave privada)
Contrasena	string	Contraseña del archivo PFX

Opción B — Certificado + Llave privada

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer` del SAT (DER o PEM)
llavePrivada	file	Archivo `.key` del SAT (PKCS#8 DER)
Contrasena	string	Contraseña de la llave privada

Opción C — Solo certificado (llave en SecretProvider)

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer`. La llave privada se toma del Key Vault registrado en `/secretprovider/signing-key`

Parámetro	En	Tipo	Req.	Descripción
tipo	Query	string	✓	emitidos \| recibidos
fecha_inicial	Query	string	✓	Formato: yyyy-MM-dd HH:mm:ss
fecha_final	Query	string	✓	Formato: yyyy-MM-dd HH:mm:ss
tipoBusqueda	Query	string	–	CFDI \| Metadata (default: CFDI)
estadoComprobante	Query	string	–	Vigente \| Cancelado \| Todos. Solo Vigente para CFDI. (default: Vigente)

Respuestas

200 RespuestaSolicitud400500

Ejemplo 200 OK (solicitud aceptada)

{
  "success": true,
  "errorMessage": null,
  "idSolicitud": "f7a2b3c4-d5e6-7890-abcd-ef1234567890",
  "codEstatus": "5000",
  "estadoSolicitud": "1",
  "idsPaquetes": [],
  "paqueteBase64": null
}

400: "Para la descarga de CFDI (XML) solo se permiten comprobantes Vigentes."

500: "Internal server error during authentication"

POST

/api/v2/satwebservice/verifica

Verifica el estado de una solicitud de descarga masiva

Llama repetidamente hasta que EstadoSolicitud = 3 (Terminada). El IdPaquete devuelto se usa en /descarga.

Body — multipart/form-data(elige una de las 3 opciones)

Opción A — PFX (PKCS#12)

Campo	Tipo	Descripción
Pfx	file	Archivo `.pfx` / `.p12` (PKCS#12 que incluye cert + llave privada)
Contrasena	string	Contraseña del archivo PFX

Opción B — Certificado + Llave privada

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer` del SAT (DER o PEM)
llavePrivada	file	Archivo `.key` del SAT (PKCS#8 DER)
Contrasena	string	Contraseña de la llave privada

Opción C — Solo certificado (llave en SecretProvider)

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer`. La llave privada se toma del Key Vault registrado en `/secretprovider/signing-key`

Parámetro	En	Tipo	Req.	Descripción
IdSolicitud	Query	string	✓	IdSolicitud devuelto por /solicita

Respuestas

200 RespuestaSolicitud400

Ejemplo 200 OK — EstadoSolicitud=3 (lista para descargar)

{
  "success": true,
  "idSolicitud": "f7a2b3c4-d5e6-7890-abcd-ef1234567890",
  "codEstatus": "5000",
  "estadoSolicitud": "3",
  "idsPaquetes": ["pkg-001-abcd1234", "pkg-002-efgh5678"],
  "paqueteBase64": null
}

EstadoSolicitud=2 (en proceso, reintentar)

{
  "success": true, "codEstatus": "5001", "estadoSolicitud": "2", "idsPaquetes": []
}

POST

/api/v2/satwebservice/descarga

Descarga el paquete ZIP de CFDIs o Metadata

Body — multipart/form-data(elige una de las 3 opciones)

Opción A — PFX (PKCS#12)

Campo	Tipo	Descripción
Pfx	file	Archivo `.pfx` / `.p12` (PKCS#12 que incluye cert + llave privada)
Contrasena	string	Contraseña del archivo PFX

Opción B — Certificado + Llave privada

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer` del SAT (DER o PEM)
llavePrivada	file	Archivo `.key` del SAT (PKCS#8 DER)
Contrasena	string	Contraseña de la llave privada

Opción C — Solo certificado (llave en SecretProvider)

Campo	Tipo	Descripción
Certificado	file	Archivo `.cer`. La llave privada se toma del Key Vault registrado en `/secretprovider/signing-key`

Parámetro	En	Tipo	Req.	Descripción
IdPaquete	Query	string	✓	IdPaquete devuelto por /verifica cuando EstadoSolicitud = 3

Respuestas

200 RespuestaSolicitud400

Ejemplo 200 OK (paqueteBase64 contiene el ZIP con los XMLs)

{
  "success": true,
  "errorMessage": null,
  "codEstatus": "5000",
  "estadoSolicitud": null,
  "idsPaquetes": [],
  "paqueteBase64": "UEsDBAoAAAAAAJNE7VgAAAAAAAAAAAAAAAAFAAAAQ0ZE..."
}

Decodifica paqueteBase64 con base64 para obtener el ZIP. El ZIP contiene un XML por cada CFDI.

GET

/api/v2/satwebservice/consulta-cfdi

Consulta el estado de un CFDI (Vigente/Cancelado) — Sin FIEL

Usa el servicio SOAP de consulta del SAT. No requiere certificado FIEL.

Parámetro	En	Tipo	Req.	Descripción
re	Query	string	✓	RFC del emisor
rr	Query	string	✓	RFC del receptor
tt	Query	string	✓	Total con 6 decimales. Ej: 1234.560000
id	Query	string	✓	UUID / Folio Fiscal del CFDI
fe	Query	string	–	Primeros 8 chars del sello digital (requerido en CFDI 4.0)

Respuestas

200 ConsultaCFDIResult400500

Ejemplo 200 OK

{
  "success": true,
  "codigoEstatus": "S - Comprobante obtenido satisfactoriamente.",
  "estado": "Vigente",
  "esCancelable": "Cancelable sin aceptación",
  "estatusCancelacion": "",
  "validacionEFOS": "200"
}

400: "El parámetro 're' (RFC emisor) es requerido."

500: "Error interno al consultar el CFDI en el SAT."

API Reference

1.Autenticación

Respuestas

Respuestas

2.Usuarios

Respuestas

Respuestas

Respuestas

3.Proveedor de Secretos

Respuestas

CIEC — Secreto

Respuestas

Respuestas

Respuestas

Respuestas

FIEL — Llave de Firma

Respuestas

Respuestas

Respuestas

Respuestas

4.Consultar SAT (CIEC / FIEL)

Opinión de Cumplimiento

Respuestas

Respuestas

Respuestas

Respuestas

Respuestas

Constancia de Situación Fiscal

Respuestas

Respuestas

Comunicados y Notificaciones

Respuestas

Respuestas

Información Fiscal

Respuestas

Respuestas

Facturas (CFDI)

Respuestas

Respuestas

Respuestas

Respuestas

Respuestas

Declaraciones

Respuestas

Respuestas

5.EFOS — Lista Negra SAT 69-B

Respuestas

6.REPSE

Respuestas

Respuestas

7.SAT Web Service — Descarga Masiva

Respuestas

Respuestas

Respuestas

Respuestas