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.

Swagger Scalar

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)

Swagger Scalar

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.

Swagger Scalar

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

Swagger Scalar

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

Swagger Scalar

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.

¿Primera vez con Azure? Sigue la guía paso a paso →

Desde crear la suscripción hasta registrar la llave: crear el Key Vault, autorizar a SatGo e importar tu FIEL. Sin conocimientos previos.

GET

/api/v1/secretprovider/identity

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

Swagger Scalar

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)

Swagger Scalar

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)

Swagger Scalar

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.

Swagger Scalar

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

Swagger Scalar

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.

Swagger Scalar

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.

Swagger Scalar

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.

Swagger Scalar

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

Swagger Scalar

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"
}

Cifrado de la FIEL (JWE)

GET

/api/v1/secretprovider/fiel-encryption-key

Devuelve la llave pública para cifrar la FIEL antes de enviarla (modalidad opcional)

Con esta llave pública el cliente cifra la llave privada (.key/.pfx) y la contraseña como JWE (RSA-OAEP-256 + A256GCM) y las envía con el header X-Fiel-Encryption: JWE. El .cer va en claro.

Swagger Scalar

Modalidad opcional de seguridad extra: SatGo descifra en memoria con una llave RSA que vive en su Key Vault (cargada una sola vez al arrancar). Aplica a todos los endpoints FIEL de /consultar y de /SatWebService. Si la feature no está habilitada en el entorno, responde 503. Guía práctica para generar los JWE (desde el navegador o por línea de comandos): /cifrar-efirma.

Respuestas

200 object (JWK + PEM + instrucciones)401503

Ejemplo 200 OK

{
  "description": "Cifra cada campo sensible de la FIEL como un JWE compacto independiente...",
  "algorithm": { "alg": "RSA-OAEP-256", "enc": "A256GCM" },
  "header": { "name": "X-Fiel-Encryption", "value": "JWE" },
  "fields": [
    "llavePrivada: JWE cuyo plaintext son los bytes crudos del .key (sube el JWE como contenido del archivo).",
    "Pfx: JWE cuyo plaintext son los bytes crudos del .pfx.",
    "Contrasena: JWE cuyo plaintext es la contraseña (string).",
    "Certificado (.cer): SIEMPRE en claro; es material público."
  ],
  "kid": "0059F2C6AA62FB6BFC64902C52DFA7CB56B2F217",
  "jwk": { "kty": "RSA", "use": "enc", "alg": "RSA-OAEP-256", "enc": "A256GCM", "kid": "...", "n": "...", "e": "AQAB" },
  "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n"
}

503: "El cifrado JWE de la FIEL no está habilitado en este entorno."

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.
Opcionalmente puedes cifrar la llave y la contraseña (JWE RSA-OAEP-256 + A256GCM) con el header X-Fiel-Encryption: JWE — ver Cómo cifrar tu e.firma.
Reutilizar la sesión (requestId): sólo es válido para la misma cuenta que lo generó y el mismo RFC del header; de lo contrario la API responde 404 RequestId no encontrado.

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).

Swagger Scalar

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)

Swagger Scalar

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)

Swagger Scalar

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

Swagger Scalar

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`

🔒 Cifrado opcional (recomendado): puedes enviar llavePrivada / Pfx y Contrasena cifrados como JWE compacto (RSA-OAEP-256 + A256GCM) agregando el header X-Fiel-Encryption: JWE. El certificado .cer es público y siempre va en claro. Guía paso a paso (navegador o línea de comandos) en Cómo cifrar tu e.firma.

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.

Swagger Scalar

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)

Swagger Scalar

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

Swagger Scalar

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

Swagger Scalar

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",
      "fechaComunicado": "15/Mar/2024 10:30 hrs",
      "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).

Swagger Scalar

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 },
    { "folio": "NOT-2024-002", "autoridad": "SAT", "acto": "Resolución", "fecha": "12/03/2024", "pdfDescargado": true, "pdfFileName": "notificacion.pdf",
      "actoAdministrativoRow": { "pdfDescargado": true, "pdfFileName": "acto_administrativo.pdf" },
      "acuseRow": { "pdfDescargado": true, "pdfFileName": "acuse.pdf" } }
  ]
}

404: "El requestId no existe, ya expiró o no pertenece a tu cuenta y al RFC del header."

Información Fiscal

GET

/api/v2/consultar/informacionfiscal

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

Swagger Scalar

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

Swagger Scalar

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 no existe, ya expiró o no pertenece a tu cuenta y al RFC del header."

Facturas (CFDI)

GET

/api/v2/consultar/fac

Descarga facturas desde el portal del SAT (CIEC)

Swagger Scalar

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)

Swagger Scalar

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

Swagger Scalar

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)

Swagger Scalar

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)

Swagger Scalar

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

Swagger Scalar

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 \| acuse
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.

Swagger Scalar

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 \| acuse
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>

POST

/api/v2/consultar/decanualfiel

Descarga la declaración anual de personas físicas (o su acuse) usando la FIEL como ZIP

Consulta el portal de la Declaración Anual de Personas Físicas del SAT y devuelve todas las declaraciones presentadas del ejercicio (normales y complementarias; una por régimen), un PDF por declaración. El header de respuesta X-RequestId permite reusar la sesión SAT; una sesión de /dec o /decfiel no sirve aquí (es otro portal).

Swagger Scalar

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	✓	Ejercicio declarado. Ej: 2025
tipoDocumento	Query	string	–	declaracion (default) \| acuse
requestId	Query	string (GUID)	–	ID de sesión previa de este mismo endpoint

Respuestas

200 application/zip400404

📦

DeclaracionesAnuales_{ejercicio}_{rfc}.zip | AcusesAnuales_{ejercicio}_{rfc}.zip

Content-Type: application/zip

PDFs: Anual_{ejercicio}_{tipoDeclaracion}_{numeroOperacion}.pdf (acuse: AcuseAnual_...). Header de respuesta: X-RequestId: <guid>

404: "No se encontraron declaraciones (o acuses) para el ejercicio indicado."

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.

Swagger Scalar

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>

Consulta directa y síncrona contra el Padrón Público REPSE (STPS): una sola llamada busca la razón social y devuelve, en la misma respuesta, los candidatos encontrados y el detalle de registro de cada uno.

GET

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

Consulta REPSE por razón social

Busca la razón social en el padrón público de STPS y devuelve el detalle de registro (folio, RFC, vigencia, actividades) para cada coincidencia encontrada.

Swagger Scalar

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

Respuestas

200 RepseDirectoResult400500

Ejemplo 200 OK — con registro

{
  "success": true,
  "razonSocialBuscada": "AAA LINK",
  "candidatos": [
    { "id": "220822", "texto": "AAA LINK S A P I DE CV" }
  ],
  "registros": [
    {
      "candidatoId": "220822",
      "data": {
        "folio": 348611,
        "id": 143884,
        "razonSocial": "AAA LINK S A P I DE CV",
        "rfc": "AAL2502062R2",
        "entidad": null,
        "municipio": null,
        "abreviatura": null,
        "numEmi": null,
        "fechaRegistro": null,
        "fechaVencimientoRegistro": "2028-10-21 00:00:00"
      },
      "actividades": [
        { "descripcion": "Alquiler de maquinaria para construcción, minería y actividades forestales", "folio": "5e7136fd-e685-4be3-b779-40be14743484" }
      ]
    }
  ],
  "mensaje": null
}

Ejemplo 200 OK — sin coincidencias

{
  "success": false,
  "razonSocialBuscada": "EMPRESA QUE NO EXISTE",
  "candidatos": [],
  "registros": [],
  "mensaje": "No se encontraron coincidencias para la razón social proporcionada."
}

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

GET /consultar/razon-social (flujo asíncrono anterior, vía cola) fue descontinuado y ahora responde 410 Gone. Usa el endpoint directo de arriba.

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

Swagger Scalar

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/solicita-folio

Solicita la descarga de un CFDI específico por Folio Fiscal (UUID)

Alternativa a /solicita cuando ya conoces el UUID exacto del comprobante, sin necesidad de acotar por rango de fechas.

Swagger Scalar

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
folio	Query	string (UUID)	✓	Folio Fiscal (UUID) del CFDI. Formato XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Respuestas

200 RespuestaSolicitud400500

Ejemplo 200 OK (solicitud aceptada)

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

400: "El parámetro folio no tiene un formato de UUID válido"

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.

Swagger Scalar

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

Swagger Scalar

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.

Swagger Scalar

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."

GET

/api/v2/satwebservice/peticiones-pendientes

Consulta las solicitudes de cancelación pendientes de aprobar/rechazar

Vía el WS de Cancelación de SIFEI (distinto del WS de Timbrado). Devuelve los CFDI emitidos por el RFC del header que tienen una solicitud de cancelación esperando aceptación o rechazo. No requiere FIEL.

Swagger Scalar

Sin parámetros adicionales. El RFC se toma del header RFC.

Respuestas

200 PeticionesPendientesResult400500

Ejemplo 200 OK — con peticiones pendientes (CodEstatus 1100)

{
  "codigoEstatus": "1100",
  "mensaje": "Se obtuvo petición del RFC receptor de forma exitosa",
  "success": true,
  "errorMessage": null,
  "peticiones": [
    { "uuid": "A9CC98B1-39CE-465C-AEC0-51CA3335280A" }
  ]
}

Ejemplo 200 OK — sin peticiones pendientes (CodEstatus 1101)

{
  "codigoEstatus": "1101",
  "mensaje": "No existen peticiones para el RFC del receptor",
  "success": true,
  "errorMessage": null,
  "peticiones": []
}

500: "Error interno al consultar peticiones pendientes en SIFEI."

8.Términos y Condiciones

/api/v1/terminos · Bearer (vigente y aceptar-por-token son públicos)

Aceptación de los Términos y Condiciones por cuenta (el UserUuid del JWT). La cuenta consulta la versión vigente, su estado y su historial, y registra la aceptación por API. Los endpoints de administración (publicar versión, enviar enlaces) no forman parte de esta referencia.

GET

/api/v1/terminos/vigente

Devuelve la versión vigente de los Términos y Condiciones

Público (AllowAnonymous). Incluye versión, hash del documento y el texto/URL publicados.

Swagger Scalar

Sin parámetros. No requiere autenticación.

Respuestas

200 TermsCurrentDto404

Ejemplo 200 OK

{
  "version": "v2.0",
  "hash": "9f2c1e...a7",
  "effectiveAtUtc": "2026-08-13T00:00:00Z",
  "url": "https://sat-go.com/terminos",
  "text": "Términos y Condiciones de uso de SatGo..."
}

404: "No hay una versión vigente de Términos y Condiciones."

GET

/api/v1/terminos/estado

Estado de aceptación de la cuenta frente a la versión vigente

Swagger Scalar

Sin parámetros adicionales. La cuenta se toma del JWT.

Respuestas

200 TermsStatusDto401

Ejemplo 200 OK

{
  "enabled": true,
  "currentVersion": "v2.0",
  "acceptedVersion": "v1.1",
  "isCurrent": false,
  "pending": true,
  "acceptedAtUtc": "2026-08-01T18:22:10Z",
  "deadlineUtc": "2026-09-30T00:00:00Z"
}

GET

/api/v1/terminos/historial

Historial de aceptaciones de la cuenta (versión, fecha y canal)

Permite al Cliente consultar en cualquier momento la versión que aceptó y la fecha de aceptación.

Swagger Scalar

Sin parámetros adicionales. La cuenta se toma del JWT.

Respuestas

200 List<TermsAcceptanceHistoryItemDto>401

Ejemplo 200 OK (más reciente primero)

[
  { "version": "v2.0", "acceptedAtUtc": "2026-08-14T15:04:00Z", "channel": "Web" },
  { "version": "v1.1", "acceptedAtUtc": "2026-05-02T09:31:00Z", "channel": "Api" }
]

POST

/api/v1/terminos/aceptar

Acepta los Términos y Condiciones (canal web o API)

Valida que la versión enviada coincida con la vigente y registra la evidencia (cuenta, versión, hash, timestamp, IP, canal).

Swagger Scalar

Parámetro	En	Tipo	Req.	Descripción
version	Body JSON	string	✓	Versión a aceptar; debe coincidir con la vigente (GET /vigente)
channel	Body JSON	string	–	Canal de aceptación. Por defecto 'Api'.

Respuestas

200 TermsAcceptResult400 TermsAcceptResult401

Request

{ "version": "v2.0", "channel": "Api" }

Ejemplo 200 OK

{
  "success": true,
  "message": null,
  "acceptedVersion": "v2.0",
  "acceptedAtUtc": "2026-08-14T15:04:00Z"
}

400: "La versión enviada ('v1.1') no coincide con la versión vigente ('v2.0')."

POST

/api/v1/terminos/aceptar-por-token

Acepta los Términos mediante el token enviado por correo (sin sesión)

Público (AllowAnonymous). Para clientes integrados sin panel web: valida y consume un token de un solo uso.

Swagger Scalar

Parámetro	En	Tipo	Req.	Descripción
token	Body JSON	string	✓	Token de un solo uso recibido en el correo de aceptación

Respuestas

200 TermsAcceptResult400 TermsAcceptResult

Request

{ "token": "u1Qf...Zk" }

400: "El enlace de aceptación es inválido, ya fue usado o expiró."

9.Límites de frecuencia

Consultar (v1 y v2) y SatWebService · HTTP 429

Para proteger los portales del SAT/IMSS de ráfagas que provoquen bloqueos, las operaciones de Consultar y SatWebService tienen un límite de peticiones por minuto y de peticiones simultáneas, por cuenta (tu UserUuid) y por RFC (header Rfc). Los valores dependen de tu plan. El límite por RFC es común a todas las cuentas que operan ese RFC. Las cuotas diarias/mensuales de tu plan (respuesta 403) son un control distinto y siguen aplicando.

429 Too Many Requests

Cuando una petición excede un límite, la API responde 429 sin ejecutar la operación (no se contacta al SAT ni se consume la cuota del plan). Espera los segundos indicados en Retry-After y reintenta. Para límites de peticiones simultáneas, reintenta cuando termine alguna de tus peticiones en curso.

Parámetro	En	Tipo	Req.	Descripción
limitScope	Body JSON	string	–	'account' (tu cuenta) o 'rfc' (el RFC del header)
limitType	Body JSON	string	–	'frequency' (peticiones por minuto) o 'concurrency' (peticiones simultáneas)
retryAfterSeconds	Body JSON	int	–	Segundos sugeridos antes de reintentar (igual que el header Retry-After)
message	Body JSON	string	–	Descripción legible del límite alcanzado

Ejemplo 429

HTTP/1.1 429 Too Many Requests
Retry-After: 42
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1790000460
X-RateLimit-Rfc-Limit: 15

{
  "success": false,
  "message": "Se alcanzó el límite de peticiones por minuto de tu cuenta (30). Reintenta en 42 s.",
  "limitScope": "account",
  "limitType": "frequency",
  "retryAfterSeconds": 42
}

429: "El RFC alcanzó su límite de peticiones por minuto. Reintenta en 42 s."

Headers X-RateLimit-*

Si tu plan tiene límite de peticiones por minuto por cuenta, todas las respuestas de estos endpoints (exitosas o 429) incluyen los headers siguientes. Se refieren solo a tu cuenta; el uso del RFC no se expone porque lo comparten varias cuentas; de él solo se informa el tope que aplica a tu plan.

Parámetro	En	Tipo	Req.	Descripción
X-RateLimit-Limit	Header respuesta	int	–	Peticiones por minuto permitidas a tu cuenta
X-RateLimit-Remaining	Header respuesta	int	–	Peticiones que te quedan en el minuto en curso
X-RateLimit-Reset	Header respuesta	int	–	Unix epoch (segundos, UTC) en que se reinicia la ventana
X-RateLimit-Rfc-Limit	Header respuesta	int	–	Peticiones por minuto permitidas por RFC en tu plan (solo el tope, no su uso). Si recibes 429 con limitScope=rfc aunque X-RateLimit-Remaining sea mayor a 0, es este límite
Retry-After	Header respuesta	int	–	Solo en 429: segundos a esperar antes de reintentar

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

Cifrado de la FIEL (JWE)

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

Respuestas

5.EFOS — Lista Negra SAT 69-B

Respuestas

6.REPSE

Respuestas

7.SAT Web Service — Descarga Masiva

Respuestas

Respuestas

Respuestas

Respuestas

Respuestas

Respuestas

8.Términos y Condiciones

Respuestas

Respuestas

Respuestas

Respuestas

Respuestas

9.Límites de frecuencia

429 Too Many Requests

Headers X-RateLimit-*