API de Consulta Laboral y Financiera

Este documento describe la especificación técnica de la API para consulta de información laboral y financiera. La API proporciona dos módulos independientes:

• Visor Laboral: Consulta de información laboral de las plataformas IMSS e ISSSTE
• Visor Financiero: Consulta de información fiscal y financiera de la plataforma SAT

Endpoint: Create Request

Descripción

Permite crear una nueva solicitud de consulta en el sistema. Este endpoint acepta solicitudes para las plataformas IMSS, ISSSTE y SAT, requiriendo información del cliente y del sistema origen que genera la solicitud.

Procesamiento Asíncrono: Las consultas se procesan de forma asíncrona. Al crear una solicitud, el sistema retorna inmediatamente un requestId y el estado "in_progress". El procesamiento de la consulta se ejecuta en segundo plano. Una vez recibida la notificación mediante webhook, debe consultar el estado y resultados de la solicitud utilizando el método GET con el requestId proporcionado.

Endpoint Unificado: El endpoint POST es único para ambos módulos (laboral y financiero). La consulta de resultados se realiza mediante endpoints GET específicos según el tipo de plataforma y el tipo de información solicitada.

Método: POST
URL: /api/v1/requests

Headers:

Content-Type: application/json
Authorization: Bearer {token}

Request Body

Estructura

{
  "platform": "imss",
  "requestType": "external",
  "externalId": "SYS-2026-ABC123",
  "customer": {
    "personType": "individual",
    "fullName": "Juan Pérez García",
    "businessName": null,
    "rfc": "PERG800101HDF",
    "curp": "PERG800101HDFRZN01",
    "contact": {
      "email": "usuario@ejemplo.com",
      "phone": "+525512345678"
    }
  },
  "sourceSystem": {
    "system": "MiSistema",
    "folio": "FOL-2026-001",
    "product": "ProductoX"
  }
}

Campos del Request

Nivel Raíz

Objeto customer

Notas sobre campos:

• † fullName y businessName son mutuamente excluyentes según el personType
• ‡ RFC:
  • Persona física: Opcional para IMSS e ISSSTE, obligatorio para SAT
  • Persona moral: Obligatorio para SAT (no aplica para IMSS/ISSSTE)
• § CURP:
  • Persona física: Obligatorio para IMSS e ISSSTE, opcional para SAT
  • Persona moral: No se requiere para SAT (no aplica para IMSS/ISSSTE)

Restricción de plataforma: Las personas morales (personType: "organization") únicamente pueden consultar la plataforma SAT. No es posible realizar consultas en IMSS ni ISSSTE para personas morales.

Objeto customer.contact

Objeto sourceSystem

Response

Respuesta Exitosa (200 OK)

{
  "result": {
    "status": "in_progress",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "platform": "imss"
  },
  "correlationId": "123e4567-e89b-12d3-a456-426614174002"
}

Campos de Respuesta Exitosa

El estado "in_progress" indica que la solicitud fue creada exitosamente y se encuentra en proceso de forma asíncrona. Una vez recibida la notificación mediante webhook, utilice el requestId para consultar el estado y resultados mediante el método GET.

Respuesta de Error (400 Bad Request / 500 Internal Server Error)

{
  "result": {
    "status": "error",
    "error": "Mensaje de error descriptivo",
    "platform": "imss"
  },
  "correlationId": "123e4567-e89b-12d3-a456-426614174003"
}

Campos de Respuesta de Error

Códigos de Estado HTTP

Visor Laboral

Endpoint: Get Request Status - Laboral

Descripción

Permite consultar el estado y los resultados de una solicitud laboral previamente creada mediante el requestId obtenido en la creación de la solicitud.

La estructura de la respuesta varía según la plataforma consultada (IMSS o ISSSTE). Cada plataforma retorna información específica relacionada con su dominio laboral.

Método: GET

URL: /api/v1/labor/{requestId}

Headers:

Authorization: Bearer {token}

Parámetros de URL

Response - IMSS

Respuesta Exitosa (200 OK)

La respuesta para consultas IMSS contiene información laboral del participante, incluyendo detalles de empleadores, movimientos históricos y resumen de seguridad social.

Estructura de Respuesta IMSS

{
  "date": "2019-01-05T00:00:00",
  "quoteStatus": "Empleado",
  "participantDetails": [...],
  "participantMovements": [...],
  "participantSocialSecuritySummary": {...}
}

Campos de Respuesta IMSS

Objeto participantDetails[]

Objeto participantMovements[]

Objeto participantSocialSecuritySummary

Respuesta de Error (400 Bad Request / 404 Not Found / 500 Internal Server Error)

{
  "error": "Mensaje de error descriptivo",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Response - ISSSTE

Respuesta Exitosa (200 OK)

La respuesta para consultas ISSSTE mantiene la misma estructura que IMSS. Incluye información laboral del participante, detalles de empleadores, movimientos históricos y resumen de seguridad social.

Estructura de Respuesta ISSSTE

La estructura de respuesta es idéntica a la de IMSS:

{
  "date": "2014-11-16T00:00:00",
  "quoteStatus": "Empleado",
  "participantDetails": [...],
  "participantMovements": [...],
  "participantSocialSecuritySummary": {...}
}

Campos de Respuesta ISSSTE

Los campos son los mismos que en IMSS. Ver sección Response - IMSS para la documentación completa de campos.

Diferencias con IMSS

1. Tipos de eventos en participantMovements: Los valores de eventType pueden ser diferentes:

   • "DYE_CERTIFICATE" - Certificado de defunción y estado
   • "NORMAL" - Movimiento normal
   • "BDUTA_CERTIFICATE" - Certificado de baja definitiva y temporal
   • Nota: En IMSS se utilizan los valores "Ingreso", "Baja", "Modificación salarial"

2. Campos opcionales: Los campos employerId y state en participantDetails pueden estar vacíos ("") en algunas respuestas de ISSSTE.

Respuesta de Error (400 Bad Request / 404 Not Found / 500 Internal Server Error)

{
  "error": "Mensaje de error descriptivo",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Visor Financiero

El Visor Financiero proporciona múltiples endpoints para consultar información fiscal y financiera del SAT. Una vez creada una solicitud mediante el endpoint POST /api/v1/requests con platform: "sat", los resultados pueden consultarse utilizando los siguientes endpoints especializados.

Endpoint: Get Tax Status Information

Descripción

Permite obtener la información del estado fiscal (constancia de situación fiscal) en formato JSON. Retorna los datos estructurados del estado fiscal sin incluir el documento PDF.

Método: GET

URL: /api/v1/financial/status/info/{requestId}

Headers:

Authorization: Bearer {token}

Parámetros de URL

Respuesta Exitosa (200 OK)

Retorna un objeto TaxStatus con la información del estado fiscal:

Estructura de Respuesta

{
  "id": "string",
  "createdAt": "string | null",
  "idCif": "string",
  "address": {...},
  "regimes": [...],
  "obligations": [...],
  "collectedAt": "string | null",
  "digitalStamp": "string",
  "officialName": "string",
  "additionalData": {...},
  "economicActivity": [...],
  "digitalStampChain": "string",
  "legalRepresentatives": {...},
  "taxPayerInformation": {...},
  "placeAndDateOfIssuance": "string"
}

Objeto TaxStatus

Objeto Address

Objeto Regime

Objeto Obligation

Objeto EconomicActivity

Objeto TaxPayerInformation

Respuesta de Error (400 Bad Request / 404 Not Found / 500 Internal Server Error)

{
  "error": "Mensaje de error descriptivo",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Endpoint: Get Tax Status PDF

Descripción

Permite obtener el documento PDF de la constancia de situación fiscal correspondiente a la solicitud.

Método: GET

URL: /api/v1/financial/status/pdf/{requestId}

Headers:

Authorization: Bearer {token}

Parámetros de URL

Respuesta Exitosa (200 OK)

• Content-Type: application/pdf
• Content-Disposition: attachment; filename=constancia-situacion-fiscal-{requestId}.pdf
• Body: Contenido binario del archivo PDF

Respuesta de Error (400 Bad Request / 404 Not Found / 500 Internal Server Error)

{
  "error": "Mensaje de error descriptivo",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Endpoint: Get Compliance Opinion Information

Descripción

Permite obtener la información de la opinión de cumplimiento fiscal en formato JSON. Retorna los datos estructurados de la opinión de cumplimiento sin incluir el documento PDF.

Método: GET

URL: /api/v1/financial/compliance/info/{requestId}

Headers:

Authorization: Bearer {token}

Parámetros de URL

Respuesta Exitosa (200 OK)

Retorna un objeto TaxCompliance con la información de la opinión de cumplimiento fiscal:

Estructura de Respuesta

{
  "id": "string",
  "createdAt": "string",
  "rfc": "string",
  "outcome": "string",
  "outcomeValue": "string",
  "collectedAt": "string | null",
  "additionalData": {...},
  "internalIdentification": "string"
}

Objeto TaxCompliance

Mapeo de Valores de Outcome

Respuesta de Error (400 Bad Request / 404 Not Found / 500 Internal Server Error)

{
  "error": "Mensaje de error descriptivo",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Endpoint: Get Compliance Opinion PDF

Descripción

Permite obtener el documento PDF de la opinión de cumplimiento fiscal correspondiente a la solicitud.

Método: GET

URL: /api/v1/financial/compliance/pdf/{requestId}

Headers:

Authorization: Bearer {token}

Parámetros de URL

Respuesta Exitosa (200 OK)

• Content-Type: application/pdf
• Content-Disposition: attachment; filename=opinion-cumplimiento-fiscal-{requestId}.pdf
• Body: Contenido binario del archivo PDF

Respuesta de Error (400 Bad Request / 404 Not Found / 500 Internal Server Error)

{
  "error": "Mensaje de error descriptivo",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Endpoint: Get Invoices

Descripción

Permite obtener las facturas fiscales (CFDI) del contribuyente asociadas a una solicitud. Incluye facturas emitidas y recibidas: montos, impuestos, emisores, receptores y datos de pago. Los datos se retornan en el objeto pagedFinancialResult con paginación.

Método: GET

URL: /api/v1/financial/invoices/{requestId}/{pageNumber}/{pageSize}

Headers:

Authorization: Bearer {token}

Parámetros de URL

Límite: El número máximo de elementos por página (pageSize) es 1,000. Para calcular el total de páginas: totalPages = Math.Ceiling(totalItems / pageSize).

Respuesta Exitosa (200 OK)

Retorna el objeto pagedFinancialResult con el total de facturas disponibles y el array de facturas de la página solicitada.

Estructura de Respuesta

{
  "pagedFinancialResult": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
        "totalItems": 1250,
    "invoices": [
      {
        "id": "string",
        "link": "string",
        "createdAt": "string",
        "type": "I",
        "year": 2024,
        "serie": "A",
        "folio": "12345",
        "month": 1,
        "total": 1000.00,
        "usage": "G03",
        "status": "Vigente",
        "version": "4.0",
        "currency": "MXN",
        "subtotal": 862.07,
        "discounts": 0,
        "invoiceId": "string",
        "issueDate": "2024-01-15T00:00:00Z",
        "exportType": null,
        "issuerName": "string",
        "periodicity": null,
        "paymentForm": "03",
        "exchangeRate": 1,
        "issuerTaxId": "string",
        "receiverName": "string",
        "originalTotal": 1000.00,
        "paymentMethod": "PUE",
        "receiverTaxId": "string",
        "taxRetainedVat": 0,
        "cancellationDate": null,
        "issuerTaxRegime": "string",
        "originalSubtotal": 862.07,
        "certificationDate": "string",
        "originalDiscounts": 0,
        "taxRetainedTotal": 0,
        "receiverTaxRegime": "string",
        "taxRetainedIncome": 0,
        "verificationStatus": "string",
        "receiverPostalCode": "string",
        "relatedDocumentType": null,
        "taxTransferredLocal": 0,
        "taxTransferredTotal": 137.93,
        "internalIdentification": "uuid-cfdi",
        "stampValidationStatus": "string",
        "adjustedSubtotalForeign": null,
        "customsDeclarationNumber": null,
        "adjustedSubtotalVatExempt": null,
        "employerRegistrationNumber": null,
        "relatedDocumentInternalIds": [],
        "adjustedSubtotalVat0Percent": null,
        "adjustedSubtotalVat8Percent": null,
        "adjustedSubtotalVat16Percent": 862.07,
        "originalCurrency": "MXN",
        "adjustedSubtotalBase": 862.07,
        "taxTransferredVat": 137.93,
        "taxTransferredExcise": 0,
        "originalAdjustedSubtotalVat16Percent": null,
        "senderTaxFraudStatus": null,
        "receiverTaxFraudStatus": null
      }
    ]
  }
}

• pagedFinancialResult.totalItems: total de facturas disponibles (en todas las páginas).
• pagedFinancialResult.invoices: array de facturas de la página actual (hasta pageSize elementos).

Objeto pagedFinancialResult

Campos del elemento Invoice

Respuesta de Error (400 Bad Request / 404 Not Found / 500 Internal Server Error)

{
  "error": "Mensaje de error descriptivo",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Endpoint: Get Income Statement

Descripción

Permite obtener los estados de resultados (pérdidas y ganancias) del contribuyente por año asociados a una solicitud. Incluye ingresos, costos, gastos, EBITDA, utilidad neta, etc. Los datos se retornan en el objeto pagedFinancialResult con paginación.

Método: GET

URL: /api/v1/financial/statement/{requestId}/{pageNumber}/{pageSize}

Headers:

Authorization: Bearer {token}

Parámetros de URL

Límite: El número máximo de elementos por página (pageSize) es 1,000. Para calcular el total de páginas: totalPages = Math.Ceiling(totalItems / pageSize).

Respuesta Exitosa (200 OK)

Retorna el objeto pagedFinancialResult con el total de años con estados de resultados disponibles y el array de la página solicitada.

Estructura de Respuesta

{
  "pagedFinancialResult": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "totalItems": 5,
    "incomeStatement": [
      {
        "year": 2024,
        "netSales": 1000000.00,
        "totalRevenue": 1050000.00,
        "costOfSalesOrService": 400000.00,
        "directLabor": 80000.00,
        "contractManufacturingCosts": null,
        "indirectManufacturingExpenses": 50000.00,
        "totalCosts": 530000.00,
        "grossMargin": 520000.00,
        "otherOperatingExpenses": 120000.00,
        "totalExpenses": 120000.00,
        "ebitda": 400000.00,
        "financialIncome": 5000.00,
        "financialExpenses": 15000.00,
        "totalComprehensiveFinancingResult": -10000.00,
        "otherExpenses": null,
        "otherIncome": null,
        "shareOfProfitOfAssociatesAndSubsidiaries": null,
        "discontinuedAndExtraordinaryItems": null,
        "totalOtherExpensesAndIncome": null,
        "depreciationAndAmortization": 60000.00,
        "earningsBeforeTax": 330000.00,
        "workerProfitSharing": 33000.00,
        "incomeTaxExpense": 99000.00,
        "netIncome": 198000.00
      }
    ]
  }
}

• pagedFinancialResult.totalItems: total de años con estados de resultados disponibles (en todas las páginas).
• pagedFinancialResult.incomeStatement: array de estados de resultados de la página actual (hasta pageSize elementos).

Objeto pagedFinancialResult

Campos del elemento IncomeStatement

Respuesta de Error (400 Bad Request / 404 Not Found / 500 Internal Server Error)

{
  "error": "Mensaje de error descriptivo",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Endpoint: Get Balance Sheet

Descripción

Permite obtener los balances generales del contribuyente por año asociados a una solicitud. Incluye activos, pasivos y capital (efectivo, cuentas por cobrar, inventarios, proveedores, deuda, capital, etc.). Los datos se retornan en el objeto pagedFinancialResult con paginación.

Método: GET

URL: /api/v1/financial/balance/{requestId}/{pageNumber}/{pageSize}

Headers:

Authorization: Bearer {token}

Parámetros de URL

Límite: El número máximo de elementos por página (pageSize) es 1,000. Para calcular el total de páginas: totalPages = Math.Ceiling(totalItems / pageSize).

Respuesta Exitosa (200 OK)

Retorna el objeto pagedFinancialResult con el total de años con balances disponibles y el array de la página solicitada.

Estructura de Respuesta

{
  "pagedFinancialResult": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "totalItems": 5,
    "balanceSheet": [
      {
        "year": 2024,
        "cashAndCashEquivalents": 150000.00,
        "investments": null,
        "accountsReceivable": 200000.00,
        "accountsReceivableRelatedParties": null,
        "inventory": 180000.00,
        "creditableTaxes": 25000.00,
        "prepaidExpenses": 15000.00,
        "securityDeposits": null,
        "otherCurrentAssets": 30000.00,
        "totalCurrentAssets": 600000.00,
        "fixedAssets": 400000.00,
        "accumulatedDepreciation": -120000.00,
        "permanentInvestmentsInShares": null,
        "otherIntangibleAssets": null,
        "totalNonCurrentAssets": 280000.00,
        "totalAssets": 880000.00,
        "suppliers": 95000.00,
        "shortTermMiscellaneousCreditors": null,
        "bankLoansAndInterest": 80000.00,
        "otherCurrentLiabilities": 25000.00,
        "otherAccountsPayableAndRelatedInterest": null,
        "customerAdvances": 20000.00,
        "taxesPayable": 35000.00,
        "provisions": 10000.00,
        "totalCurrentLiabilities": 265000.00,
        "longTermOtherAccountsPayable": null,
        "longTermOtherAccountsPayableAndRelatedInterest": 50000.00,
        "deferredTaxes": null,
        "totalNonCurrentLiabilities": 50000.00,
        "otherLiabilities": null,
        "totalLiabilities": 315000.00,
        "capitalContributions": 300000.00,
        "capitalization": null,
        "restatement": null,
        "reserves": 50000.00,
        "netIncomeForThePeriod": 198000.00,
        "retainedEarningsPreviousPeriods": 117000.00,
        "otherEquity": null,
        "totalEquity": 565000.00
      }
    ]
  }
}

• pagedFinancialResult.totalItems: total de años con balances disponibles (en todas las páginas).
• pagedFinancialResult.balanceSheet: array de balances de la página actual (hasta pageSize elementos).

Objeto pagedFinancialResult

Campos del elemento BalanceSheet

Respuesta de Error (400 Bad Request / 404 Not Found / 500 Internal Server Error)

{
  "error": "Mensaje de error descriptivo",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Endpoint: Get Cash Flow

Descripción

Permite obtener los estados de flujo de efectivo del contribuyente por año asociados a una solicitud. Incluye actividades operativas, de inversión y financiamiento (orígenes y usos de efectivo). Los datos se retornan en el objeto pagedFinancialResult con paginación.

Método: GET

URL: /api/v1/financial/cashflow/{requestId}/{pageNumber}/{pageSize}

Headers:

Authorization: Bearer {token}

Parámetros de URL

Límite: El número máximo de elementos por página (pageSize) es 1,000. Para calcular el total de páginas: totalPages = Math.Ceiling(totalItems / pageSize).

Respuesta Exitosa (200 OK)

Retorna el objeto pagedFinancialResult con el total de años con estados de flujo de efectivo disponibles y el array de la página solicitada.

Estructura de Respuesta

{
  "pagedFinancialResult": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "totalItems": 5,
    "cashFlow": [
      {
        "year": 2024,
        "netIncome": 198000.00,
        "priorYearNetIncomeAdjustment": null,
        "depreciationAndAmortization": 60000.00,
        "totalGrossGeneration": 258000.00,
        "suppliers": 20000.00,
        "taxesPayable": -15000.00,
        "otherAccountsPayableRelatedInterest": null,
        "customerAdvances": 5000.00,
        "provisions": 3000.00,
        "totalOperatingSources": 271000.00,
        "accountsReceivable": -25000.00,
        "inventory": -18000.00,
        "creditableTaxes": -5000.00,
        "accountsReceivableRelatedParties": null,
        "prepaidExpenses": -2000.00,
        "totalOperatingUses": -50000.00,
        "shortTermMiscellaneousCreditors": null,
        "bankLoansAndInterest": 30000.00,
        "otherLiabilityAccounts": null,
        "deferredTaxes": null,
        "longTermOtherAccountsPayable": null,
        "longTermOtherAccountsPayableRelatedInterest": -5000.00,
        "restatement": null,
        "capitalization": null,
        "capitalContributions": null,
        "reserves": null,
        "otherEquityAccounts": null,
        "totalNonOperatingSources": 25000.00,
        "securityDeposits": null,
        "investments": -10000.00,
        "otherAssetAccounts": null,
        "fixedAssets": -80000.00,
        "permanentInvestmentsInShares": null,
        "otherIntangibleAssets": null,
        "totalNonOperatingUses": -90000.00,
        "cashAtBeginningOfPeriod": 120000.00,
        "cashAtEndOfPeriod": 176000.00,
        "totalChangeInCash": 56000.00
      }
    ]
  }
}

• pagedFinancialResult.totalItems: total de años con estados de flujo de efectivo disponibles (en todas las páginas).
• pagedFinancialResult.cashFlow: array de estados de flujo de efectivo de la página actual (hasta pageSize elementos).

Objeto pagedFinancialResult

Campos del elemento CashFlow

Respuesta de Error (400 Bad Request / 404 Not Found / 500 Internal Server Error)

{
  "error": "Mensaje de error descriptivo",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Endpoint: Get Financial Metrics

Descripción

Permite obtener las métricas financieras del contribuyente por año asociadas a una solicitud. Incluye ratios de liquidez, rentabilidad, eficiencia y apalancamiento (current ratio, ROE, ROA, margen operativo, etc.). Los datos se retornan en el objeto pagedFinancialResult con paginación.

Método: GET

URL: /api/v1/financial/metrics/{requestId}/{pageNumber}/{pageSize}

Headers:

Authorization: Bearer {token}

Parámetros de URL

Límite: El número máximo de elementos por página (pageSize) es 1,000. Para calcular el total de páginas: totalPages = Math.Ceiling(totalItems / pageSize).

Respuesta Exitosa (200 OK)

Retorna el objeto pagedFinancialResult con el total de años con métricas disponibles y el array de la página solicitada.

Estructura de Respuesta

{
  "pagedFinancialResult": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "totalItems": 5,
    "financialMetrics": [
      {
        "year": 2024,
        "leverage": 0.56,
        "interestCoverageRatio": 26.5,
        "operatingMargin": 38.1,
        "currentRatio": 2.26,
        "salesGrowth": 12.3,
        "quickRatio": 1.85,
        "workingCapital": 335000.00,
        "bookValue": 565000.00,
        "daysSalesOutstanding": 45.2,
        "daysPayablesOutstanding": 38.0,
        "operatingCycle": 83.2,
        "ebitda": 400000.00,
        "grossMarginPercentage": 49.4,
        "netProfitMargin": 18.9,
        "debtToEquityRatio": 0.56,
        "returnOnAssets": 22.5,
        "returnOnEquity": 35.0
      }
    ]
  }
}

• pagedFinancialResult.totalItems: total de años con métricas disponibles (en todas las páginas).
• pagedFinancialResult.financialMetrics: array de métricas financieras de la página actual (hasta pageSize elementos).

Objeto pagedFinancialResult

Campos del elemento FinancialMetrics

Respuesta de Error (400 Bad Request / 404 Not Found / 500 Internal Server Error)

{
  "error": "Mensaje de error descriptivo",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Endpoint: Get Monthly Sales

Descripción

Permite obtener las ventas mensuales del contribuyente asociadas a una solicitud. Incluye totales y subtotales de ingresos y egresos por mes (formato YYYY-MM). Los datos se retornan en el objeto pagedFinancialResult con paginación.

Método: GET

URL: /api/v1/financial/monthly-sales/{requestId}/{pageNumber}/{pageSize}

Headers:

Authorization: Bearer {token}

Parámetros de URL

Límite: El número máximo de elementos por página (pageSize) es 1,000. Para calcular el total de páginas: totalPages = Math.Ceiling(totalItems / pageSize).

Respuesta Exitosa (200 OK)

Retorna el objeto pagedFinancialResult con el total de meses con datos disponibles y el array de la página solicitada.

Estructura de Respuesta

{
  "pagedFinancialResult": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "totalItems": 24,
    "monthlySales": [
      {
        "month": "2024-01",
        "subtotalAdjusted": 850000.00,
        "subtotalIngreso": 920000.00,
        "subtotalEgreso": 72000.00,
        "totalAdjusted": 848000.00,
        "totalIngreso": 920000.00,
        "totalEgreso": 72000.00
      }
    ]
  }
}

• pagedFinancialResult.totalItems: total de meses con datos disponibles (en todas las páginas).
• pagedFinancialResult.monthlySales: array de ventas mensuales de la página actual (hasta pageSize elementos).

Objeto pagedFinancialResult

Campos del elemento MonthlySales

Respuesta de Error (400 Bad Request / 404 Not Found / 500 Internal Server Error)

{
  "error": "Mensaje de error descriptivo",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Endpoint: Get Clients

Descripción

Permite obtener los clientes del contribuyente asociados a una solicitud. Incluye facturación, pagos y métricas de pago por cliente (RFC, razón social, promedios y percentiles de días de pago, facturación por año). Los datos se retornan en el objeto pagedFinancialResult con paginación.

Método: GET

URL: /api/v1/financial/clients/{requestId}/{pageNumber}/{pageSize}

Headers:

Authorization: Bearer {token}

Parámetros de URL

Límite: El número máximo de elementos por página (pageSize) es 1,000. Para calcular el total de páginas: totalPages = Math.Ceiling(totalItems / pageSize).

Orden: La lista viene ordenada por año (descendente) y porcentaje del total (descendente) usando el primer elemento de yearlyInvoicedData.

Respuesta Exitosa (200 OK)

Retorna el objeto pagedFinancialResult con el total de clientes disponibles y el array de la página solicitada.

Estructura de Respuesta

{
  "pagedFinancialResult": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "totalItems": 150,
    "clients": [
      {
        "businessName": "ACME S.A. de C.V.",
        "taxId": "ACM850101XXX",
        "lastInvoiceDate": "2024-11-15",
        "lastPaymentReceivedDate": "2024-12-01",
        "paymentDaysAverage": 28.5,
        "paymentDaysP10Percentile": 15.0,
        "paymentDaysP90Percentile": 45.0,
        "yearlyInvoicedData": [
          { "year": 2024, "amountInvoicedPreTax": 1200000.00, "percentageOfTotal": 35.2 },
          { "year": 2023, "amountInvoicedPreTax": 980000.00, "percentageOfTotal": 32.1 }
        ]
      }
    ]
  }
}

• pagedFinancialResult.totalItems: total de clientes disponibles (en todas las páginas).
• pagedFinancialResult.clients: array de clientes de la página actual (hasta pageSize elementos).

Objeto pagedFinancialResult

Campos del elemento Client

Objeto YearlyInvoicedData

Respuesta de Error (400 Bad Request / 404 Not Found / 500 Internal Server Error)

{
  "error": "Mensaje de error descriptivo",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Endpoint: Get Suppliers

Descripción

Permite obtener los proveedores del contribuyente asociados a una solicitud. Incluye compras, pagos y métricas de pago por proveedor (RFC, razón social, promedios y percentiles de días de pago, datos por año). Los datos se retornan en el objeto pagedFinancialResult con paginación.

Método: GET

URL: /api/v1/financial/suppliers/{requestId}/{pageNumber}/{pageSize}

Headers:

Authorization: Bearer {token}

Parámetros de URL

Límite: El número máximo de elementos por página (pageSize) es 1,000. Para calcular el total de páginas: totalPages = Math.Ceiling(totalItems / pageSize).

Orden: La lista viene ordenada por año (descendente) y porcentaje del total (descendente) según el primer elemento de yearlyInvoicedData.

Respuesta Exitosa (200 OK)

Retorna el objeto pagedFinancialResult con el total de proveedores disponibles y el array de la página solicitada.

Estructura de Respuesta

{
  "pagedFinancialResult": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "totalItems": 85,
    "suppliers": [
      {
        "businessName": "Suministros Industriales S.A. de C.V.",
        "taxId": "SIN800101XXX",
        "lastInvoiceDate": "2024-11-20",
        "lastPaymentReceivedDate": "2024-12-05",
        "paymentDaysMetricsAverage": 32.0,
        "paymentDaysMetricsP10Percentile": 18.0,
        "paymentDaysMetricsP90Percentile": 50.0,
        "yearlyInvoicedData": [
          { "year": 2024, "amountInvoicedPreTax": 450000.00, "percentageOfTotal": 22.5 },
          { "year": 2023, "amountInvoicedPreTax": 380000.00, "percentageOfTotal": 20.1 }
        ]
      }
    ]
  }
}

• pagedFinancialResult.totalItems: total de proveedores disponibles (en todas las páginas).
• pagedFinancialResult.suppliers: array de proveedores de la página actual (hasta pageSize elementos).

Objeto pagedFinancialResult

Campos del elemento Supplier

Objeto YearlyInvoicedData (proveedores)

Respuesta de Error (400 Bad Request / 404 Not Found / 500 Internal Server Error)

{
  "error": "Mensaje de error descriptivo",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Endpoint: Get Payroll Employers

Descripción

Permite obtener la nómina desde la perspectiva del empleador por mes asociada a una solicitud. Incluye totales de nómina, salarios, otros pagos, ISR, seguridad social, otras deducciones y número de empleados (totales, nuevos, bajas). Los datos se retornan en el objeto pagedFinancialResult con paginación.

Método: GET

URL: /api/v1/financial/payroll-employers/{requestId}/{pageNumber}/{pageSize}

Headers:

Authorization: Bearer {token}

Parámetros de URL

Límite: El número máximo de elementos por página (pageSize) es 1,000. Para calcular el total de páginas: totalPages = Math.Ceiling(totalItems / pageSize).

Respuesta Exitosa (200 OK)

Retorna el objeto pagedFinancialResult con el total de meses con datos disponibles y el array de la página solicitada.

Estructura de Respuesta

{
  "pagedFinancialResult": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "totalItems": 24,
    "payrollEmployers": [
      {
        "month": "2024-11",
        "total": 450000.00,
        "salaryPayments": 380000.00,
        "otherPayments": 25000.00,
        "incomeTax": 42000.00,
        "socialSecurityContributions": 35000.00,
        "otherDeductions": 8000.00,
        "employeesTotal": 42,
        "employeesNew": 2,
        "employeesLost": 1
      }
    ]
  }
}

• pagedFinancialResult.totalItems: total de meses con datos disponibles (en todas las páginas).
• pagedFinancialResult.payrollEmployers: array de registros de nómina empleador de la página actual (hasta pageSize elementos).

Objeto pagedFinancialResult

Campos del elemento PayrollEmployer

Respuesta de Error (400 Bad Request / 404 Not Found / 500 Internal Server Error)

{
  "error": "Mensaje de error descriptivo",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Endpoint: Get Payroll Employees

Descripción

Permite obtener la nómina desde la perspectiva del empleado por mes asociada a una solicitud. Incluye totales, salario, otros pagos, ISR, seguridad social y otras deducciones. Los datos se retornan en el objeto pagedFinancialResult con paginación.

Método: GET

URL: /api/v1/financial/payroll-employees/{requestId}/{pageNumber}/{pageSize}

Headers:

Authorization: Bearer {token}

Parámetros de URL

Límite: El número máximo de elementos por página (pageSize) es 1,000. Para calcular el total de páginas: totalPages = Math.Ceiling(totalItems / pageSize).

Respuesta Exitosa (200 OK)

Retorna el objeto pagedFinancialResult con el total de meses con datos disponibles y el array de la página solicitada.

Estructura de Respuesta

{
  "pagedFinancialResult": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "totalItems": 24,
    "payrollEmployees": [
      {
        "month": "2024-11",
        "total": 10714.29,
        "salary": 9000.00,
        "otherPayments": 500.00,
        "incomeTax": 1000.00,
        "socialSecurityContributions": 833.33,
        "otherDeductions": 52.96
      }
    ]
  }
}

• pagedFinancialResult.totalItems: total de meses con datos disponibles (en todas las páginas).
• pagedFinancialResult.payrollEmployees: array de registros de nómina empleado de la página actual (hasta pageSize elementos).

Objeto pagedFinancialResult

Campos del elemento PayrollEmployee

Respuesta de Error (400 Bad Request / 404 Not Found / 500 Internal Server Error)

{
  "error": "Mensaje de error descriptivo",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Endpoint: Get Product Sales

Descripción

Permite obtener las ventas por producto del contribuyente asociadas a una solicitud. Incluye clave, descripción, categoría, subcategoría y totales de ventas por año. Los datos se retornan en el objeto pagedFinancialResult con paginación.

Método: GET

URL: /api/v1/financial/product-sales/{requestId}/{pageNumber}/{pageSize}

Headers:

Authorization: Bearer {token}

Parámetros de URL

Límite: El número máximo de elementos por página (pageSize) es 1,000. Para calcular el total de páginas: totalPages = Math.Ceiling(totalItems / pageSize).

Respuesta Exitosa (200 OK)

Retorna el objeto pagedFinancialResult con el total de productos disponibles y el array de la página solicitada.

Estructura de Respuesta

{
  "pagedFinancialResult": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "totalItems": 120,
    "productSales": [
      {
        "productKey": "PROD-001",
        "productDescription": "Producto ejemplo",
        "productCategory": "Electrónica",
        "productSubcategory": "Componentes",
        "yearlySalesTotal": [
          { "year": 2024, "amount": 250000.00 },
          { "year": 2023, "amount": 180000.00 }
        ]
      }
    ]
  }
}

• pagedFinancialResult.totalItems: total de productos disponibles (en todas las páginas).
• pagedFinancialResult.productSales: array de ventas por producto de la página actual (hasta pageSize elementos).

Objeto pagedFinancialResult

Campos del elemento ProductSale

Objeto YearlySalesTotal

Respuesta de Error (400 Bad Request / 404 Not Found / 500 Internal Server Error)

{
  "error": "Mensaje de error descriptivo",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Endpoint: Get Product Costs

Descripción

Permite obtener los costos por producto del contribuyente asociados a una solicitud. Incluye clave, descripción, categoría, subcategoría y totales de costos por año. Los datos se retornan en el objeto pagedFinancialResult con paginación.

Método: GET

URL: /api/v1/financial/product-costs/{requestId}/{pageNumber}/{pageSize}

Headers:

Authorization: Bearer {token}

Parámetros de URL

Límite: El número máximo de elementos por página (pageSize) es 1,000. Para calcular el total de páginas: totalPages = Math.Ceiling(totalItems / pageSize).

Respuesta Exitosa (200 OK)

Retorna el objeto pagedFinancialResult con el total de productos disponibles y el array de la página solicitada.

Estructura de Respuesta

{
  "pagedFinancialResult": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "totalItems": 95,
    "productCosts": [
      {
        "productKey": "PROD-001",
        "productDescription": "Producto ejemplo",
        "productCategory": "Electrónica",
        "productSubcategory": "Componentes",
        "yearlyCostsTotal": [
          { "year": 2024, "amount": 120000.00 },
          { "year": 2023, "amount": 95000.00 }
        ]
      }
    ]
  }
}

• pagedFinancialResult.totalItems: total de productos disponibles (en todas las páginas).
• pagedFinancialResult.productCosts: array de costos por producto de la página actual (hasta pageSize elementos).

Objeto pagedFinancialResult

Campos del elemento ProductCost

Objeto YearlyCostsTotal

Respuesta de Error (400 Bad Request / 404 Not Found / 500 Internal Server Error)

{
  "error": "Mensaje de error descriptivo",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Endpoint: Get Line Items

Descripción

Permite obtener los conceptos (partidas) detallados de las facturas del contribuyente asociados a una solicitud: línea por línea por factura (productos/servicios, cantidades, precios, impuestos, emisor/receptor). Los datos se retornan en el objeto pagedFinancialResult con paginación.

Método: GET

URL: /api/v1/financial/line-items/{requestId}/{pageNumber}/{pageSize}

Headers:

Authorization: Bearer {token}

Parámetros de URL

Límite: El número máximo de elementos por página (pageSize) es 1,000. Para calcular el total de páginas: totalPages = Math.Ceiling(totalItems / pageSize).

Relación con facturas: Cuando hay line items, el sistema puede enriquecer con datos de facturas relacionadas mediante invoiceInternalIdentification (UUID de la factura).

Respuesta Exitosa (200 OK)

Retorna el objeto pagedFinancialResult con el total de conceptos disponibles y el array de la página solicitada.

Estructura de Respuesta

{
  "pagedFinancialResult": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "totalItems": 3500,
    "lineItems": [
      {
        "invoiceType": "I",
        "senderId": "RFC123",
        "senderName": "Emisor S.A.",
        "receiverId": "RFC456",
        "receiverName": "Receptor S.A.",
        "serie": "A",
        "folio": "12345",
        "invoiceDate": "2024-11-15",
        "invoiceInternalIdentification": "uuid-factura",
        "description": "Concepto ejemplo",
        "productServiceCode": "84111506",
        "productServiceCodeDescription": "Servicios de cómputo",
        "quantity": 1.0,
        "unitCode": "E48",
        "unitDescription": "Unidad de servicio",
        "unitAmount": 10000.00,
        "currencyOriginal": "MXN",
        "unitPriceOriginal": 10000.00,
        "unitPrice": 10000.00,
        "amountBeforeTaxOriginal": 10000.00,
        "amountBeforeTax": 10000.00,
        "lastPaymentDate": "2024-12-01",
        "discounts": 0,
        "taxObject": "02",
        "customsDeclarationNumber": null,
        "taxRetainedIncome": null,
        "taxRetainedVat": null,
        "taxRetainedExcise": null,
        "taxTransferredIncome": null,
        "taxTransferredTotal": 1600.00,
        "taxTransferredLocal": null,
        "transferredIncomeTax": null,
        "transferredVat": 1600.00,
        "transferredSpecialTax": null,
        "verificationStatus": "Vigente",
        "paymentMethod": "PUE",
        "originalTotal": 11600.00,
        "subtotal": 10000.00,
        "total": 11600.00,
        "paymentCondition": "Contado",
        "taxRetainedTotal": null,
        "usage": "G03",
        "category": null,
        "paymentForm": "03",
        "issuerTaxRegime": "601",
        "issuerAddress": "Dirección fiscal",
        "receiverTaxRegime": "601",
        "receiverAddress": "Dirección fiscal",
        "cancellationDate": null,
        "exchangeRate": 1,
        "version": "4.0",
        "exportType": null,
        "relatedDocumentType": null,
        "relatedDocumentInternalIds": null
      }
    ]
  }
}

• pagedFinancialResult.totalItems: total de conceptos disponibles (en todas las páginas).
• pagedFinancialResult.lineItems: array de partidas de la página actual (hasta pageSize elementos).

Objeto pagedFinancialResult

Campos del elemento LineItem

Respuesta de Error (400 Bad Request / 404 Not Found / 500 Internal Server Error)

{
  "error": "Mensaje de error descriptivo",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Endpoint: Get Tax Returns List

Descripción

Permite obtener el listado de declaraciones disponibles para una solicitud. Retorna únicamente el array taxReturnsInformation con los identificadores y datos básicos de cada declaración.

Flujo de uso: Este endpoint debe utilizarse primero para obtener el listado de declaraciones disponibles. Una vez obtenido el taxReturnId de cada declaración en el listado, puede utilizarse para consultar la información detallada o el PDF mediante los endpoints correspondientes.

Método: GET

URL: /api/v1/financial/tax-returns/list/{requestId}

Headers:

Authorization: Bearer {token}

Parámetros de URL

Respuesta Exitosa (200 OK)

Retorna un array de objetos TaxReturnsDetailSummary con la información básica de cada declaración:

Estructura de Respuesta

{
  "taxReturnsInformation": [
    {
      "taxReturnId": "123e4567-e89b-12d3-a456-426614174000",
      "period": "ANUAL 2023",
      "declarationType": "Normal"
    }
  ]
}

Objeto TaxReturnsDetailSummary

Respuesta de Error (400 Bad Request / 404 Not Found / 500 Internal Server Error)

{
  "error": "Mensaje de error descriptivo",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

Endpoint: Get Tax Return Information

Descripción

Permite obtener la información detallada de una declaración específica utilizando su taxReturnId. Retorna todos los datos estructurados de la declaración incluyendo ingresos, deducciones, determinación de impuestos y estados financieros.

Identificador requerido: El taxReturnId utilizado en este endpoint debe obtenerse previamente del campo taxReturnId del listado retornado por el endpoint /api/v1/financial/tax-returns/list/{requestId}.

Método: GET

URL: /api/v1/financial/tax-returns/info/{taxReturnId}

Headers:

Authorization: Bearer {token}

Parámetros de URL

Respuesta Exitosa (200 OK)

Retorna un objeto TaxReturnsDetailInfo con la información completa de la declaración:

Estructura de Respuesta

{
  "id": "string",
  "createdAt": "string | null",
  "type": "string",
  "income": {...},
  "collectedAt": "string | null",
  "determination": {...},
  "integrityKeys": [...],
  "additionalData": {...},
  "additionalStructuredData": {...},
  "incomeStatement": {...},
  "generalInformation": {...},
  "fiscalYearClosingFigures": {...},
  "authorizedDeductions": {...},
  "financialPositionBalance": {...},
  "r1IsrLegalEntitiesPaymentDetail": {...},
  "distributedDividendsOrProfits": {...},
  "incomeTaxDetermination": {...}
}

Objeto TaxReturnsDetailInfo

Objeto Income

Objeto DetailedNominalIncome

Objeto AnnualInflationAdjustmentDetails

Objeto Determination

Objeto GeneralInformation

Objetos adicionales: La respuesta incluye objetos adicionales como AdditionalStructuredData, IncomeStatement, FiscalYearClosingFigures, AuthorizedDeductions, FinancialPositionBalance, R1IsrLegalEntitiesPaymentDetail, y IncomeTaxDetermination que contienen información detallada específica de cada tipo de declaración. La estructura completa puede variar según el tipo de declaración.

Respuesta de Error (400 Bad Request / 404 Not Found / 500 Internal Server Error)

{
  "error": "Mensaje de error descriptivo",
  "taxReturnId": "123e4567-e89b-12d3-a456-426614174000"
}

Endpoint: Get Tax Return PDF

Descripción

Permite obtener el documento PDF de una declaración específica utilizando su taxReturnId.

Identificador requerido: El taxReturnId utilizado en este endpoint debe obtenerse previamente del campo taxReturnId del listado retornado por el endpoint /api/v1/financial/tax-returns/list/{requestId}.

Método: GET

URL: /api/v1/financial/tax-returns/pdf/{taxReturnId}

Headers:

Authorization: Bearer {token}

Parámetros de URL

Respuesta Exitosa (200 OK)

• Content-Type: application/pdf
• Content-Disposition: attachment; filename=declaracion-{taxReturnId}.pdf
• Body: Contenido binario del archivo PDF

Respuesta de Error (400 Bad Request / 404 Not Found / 500 Internal Server Error)

{
  "error": "Mensaje de error descriptivo",
  "taxReturnId": "123e4567-e89b-12d3-a456-426614174000"
}

Códigos de Estado HTTP - GET Financiero

Códigos de Estado HTTP - GET Laboral

Ejemplo de Uso - GET Laboral

Consultar Estado de Solicitud IMSS

Request:

GET /api/v1/labor/123e4567-e89b-12d3-a456-426614174000
Authorization: Bearer {token}

Response (200 OK):

{
  "date": "2019-01-05T00:00:00",
  "quoteStatus": "Empleado",
  "participantDetails": [
    {
      "id": "8248a852-2712-4205-8fb3-4f5bfc99bb5a",
      "employeeStatus": "ACTIVO",
      "employer": "PROVEEDORA DE ABARROTES RIVERA",
      "employerId": "E066313010",
      "state": "PUEBLA",
      "registeredWeeks": 370,
      "monthlySalary": 23518.17,
      "startDate": "2019-01-05T00:00:00",
      "endDate": null,
      "baseSalary": 773.2
    }
  ],
  "participantMovements": [
    {
      "id": "3691c203-0f3a-46b8-b81c-b35521b5142b",
      "eventType": "Modificación salarial",
      "eventDate": "2026-01-01T00:00:00",
      "baseSalary": 773.2,
      "employer": "PROVEEDORA DE ABARROTES RIVERA"
    }
  ],
  "participantSocialSecuritySummary": {
    "weeksRedeemed": 0,
    "weeksReinstated": 0,
    "weeksContributed": 393
  }
}

Consultar Estado de Solicitud ISSSTE

Request:

GET /api/v1/labor/123e4567-e89b-12d3-a456-426614174001
Authorization: Bearer {token}

Response (200 OK):

{
  "date": "2014-11-16T00:00:00",
  "quoteStatus": "Empleado",
  "participantDetails": [
    {
      "id": "c3f1545d-1438-4822-9206-2e0715d59c88",
      "employeeStatus": "ACTIVO",
      "employer": "PODER JUDICIAL DE LA FEDERACION (PJF) ; PJF. CONSEJO DE LA JUDICATURA FEDERAL, PACHUCA, HGO.",
      "employerId": "",
      "state": "",
      "registeredWeeks": 98,
      "monthlySalary": 34413.42,
      "startDate": "2024-02-01T00:00:00",
      "endDate": null,
      "baseSalary": 1131.4
    }
  ],
  "participantMovements": [
    {
      "id": "64cd0260-be34-4239-a26d-4aa435b2afb0",
      "eventType": "DYE_CERTIFICATE",
      "eventDate": "2025-09-01T00:00:00",
      "baseSalary": 1131.4,
      "employer": "PJF. ORGANO DE ADMINISTRACION JUDICIAL, PACHUCA, HGO."
    },
    {
      "id": "cdfcfc56-bb57-4ce1-9cbe-5cf1b62e220b",
      "eventType": "NORMAL",
      "eventDate": "2019-02-01T00:00:00",
      "baseSalary": 844.9,
      "employer": "PJF. CONSEJO DE LA JUDICATURA FEDERAL, PACHUCA, HGO."
    }
  ],
  "participantSocialSecuritySummary": {
    "weeksRedeemed": 0,
    "weeksReinstated": 0,
    "weeksContributed": 0
  }
}

Ejemplos de Uso

Ejemplos de Uso - Laboral

Ejemplo 1: Persona Física - IMSS

Request:

POST /api/v1/requests
Authorization: Bearer {token}
Content-Type: application/json

{
  "platform": "imss",
  "requestType": "external",
  "externalId": "REQ-2026-XYZ789",
  "customer": {
    "personType": "individual",
    "fullName": "Juan Pérez García",
    "businessName": null,
    "rfc": "PERG800101HDF",
    "curp": "PERG800101HDFRZN01",
    "contact": {
      "email": "juan.perez@ejemplo.com",
      "phone": "+525512345678"
    }
  },
  "sourceSystem": {
    "system": "SistemaCredito",
    "folio": "CRED-2026-001",
    "product": "Evaluación Crediticia"
  }
}

Response:

{
  "result": {
    "status": "in_progress",
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "platform": "imss"
  },
  "correlationId": "123e4567-e89b-12d3-a456-426614174002"
}

Ejemplo 2: Persona Física - ISSSTE

Request:

POST /api/v1/requests
Authorization: Bearer {token}
Content-Type: application/json

{
  "platform": "issste",
  "requestType": "external",
  "externalId": "REQ-2026-ISS001",
  "customer": {
    "personType": "individual",
    "fullName": "María González López",
    "businessName": null,
    "rfc": "GOLM850315ABC",
    "curp": "GOLM850315MDFRZN02",
    "contact": {
      "email": "maria.gonzalez@ejemplo.com",
      "phone": "+525555555555"
    }
  },
  "sourceSystem": {
    "system": "SistemaCredito",
    "folio": "CRED-2026-002",
    "product": "Evaluación Crediticia"
  }
}

Ejemplo 3: Error de Validación - Visor Laboral

Request (con datos inválidos para demostración de validación):

POST /api/v1/requests
Authorization: Bearer {token}
Content-Type: application/json

{
  "platform": "issste",
  "requestType": "external",
  "externalId": "ERR-2026-TEST001",
  "customer": {
    "personType": "individual",
    "fullName": null,
    "businessName": null,
    "rfc": "INVALID",
    "contact": {
      "email": "email-invalido",
      "phone": "123"
    }
  },
  "sourceSystem": {
    "system": "MiSistema",
    "folio": "FOL-2026-001",
    "product": "ProductoX"
  }
}

Response:

{
  "result": {
    "status": "error",
    "error": "RFC inválido. El campo 'fullName' es requerido para personType 'individual'",
    "platform": "issste"
  },
  "correlationId": "123e4567-e89b-12d3-a456-426614174003"
}

Ejemplos de Uso - Financiero

Ejemplo 1: Persona Física - SAT

Request:

POST /api/v1/requests
Authorization: Bearer {token}
Content-Type: application/json

{
  "platform": "sat",
  "requestType": "external",
  "externalId": "REQ-2026-SAT001",
  "customer": {
    "personType": "individual",
    "fullName": "María González López",
    "businessName": null,
    "rfc": "GOLM850315ABC",
    "curp": null,
    "contact": {
      "email": "maria.gonzalez@ejemplo.com",
      "phone": "+525555555555"
    }
  },
  "sourceSystem": {
    "system": "SistemaFiscal",
    "folio": "FISC-2026-050",
    "product": "Verificación Fiscal"
  }
}

Response:

{
  "result": {
    "status": "in_progress",
    "requestId": "123e4567-e89b-12d3-a456-426614174010",
    "platform": "sat"
  },
  "correlationId": "123e4567-e89b-12d3-a456-426614174011"
}

Ejemplo 2: Persona Moral - SAT

Request:

POST /api/v1/requests
Authorization: Bearer {token}
Content-Type: application/json

{
  "platform": "sat",
  "requestType": "external",
  "externalId": "TRX-2026-DEF456",
  "customer": {
    "personType": "organization",
    "fullName": null,
    "businessName": "Mi Empresa SA de CV",
    "rfc": "MEM850101ABC",
    "curp": null,
    "contact": {
      "email": "contacto@miempresa.com",
      "phone": "+525598765432"
    }
  },
  "sourceSystem": {
    "system": "SistemaFiscal",
    "folio": "FISC-2026-042",
    "product": "Verificación Fiscal"
  }
}

Response:

{
  "result": {
    "status": "in_progress",
    "requestId": "123e4567-e89b-12d3-a456-426614174020",
    "platform": "sat"
  },
  "correlationId": "123e4567-e89b-12d3-a456-426614174021"
}

Ejemplo 3: Consultar Estado Fiscal - Información Estructurada

Request:

GET /api/v1/financial/status/info/123e4567-e89b-12d3-a456-426614174010
Authorization: Bearer {token}

Response (200 OK):

{
  "id": "abc123-def456-ghi789",
  "createdAt": "2026-02-17T10:30:00Z",
  "idCif": "CIF123456",
  "officialName": "EMPRESA EJEMPLO SA DE CV",
  "digitalStamp": "sello-digital-123",
  "digitalStampChain": "cadena-sello-digital",
  "placeAndDateOfIssuance": "Ciudad de México, 17 de febrero de 2026",
  "address": {
    "state": "Ciudad de México",
    "street": "Av. Ejemplo",
    "suburb": "Colonia Ejemplo",
    "postalCode": "01234",
    "fullAddress": "Av. Ejemplo 123, Colonia Ejemplo, Ciudad de México, 01234"
  },
  "taxPayerInformation": {
    "rfc": "EEM850101ABC",
    "name": "EMPRESA EJEMPLO SA DE CV",
    "socialName": "EMPRESA EJEMPLO SA DE CV",
    "statusPadron": "Activo"
  },
  "regimes": [
    {
      "regimen": "601",
      "initialDate": "2020-01-01T00:00:00Z",
      "endDate": null
    }
  ],
  "obligations": [],
  "economicActivity": []
}

Ejemplo 4: Obtener Documento PDF de Constancia Fiscal

Request:

GET /api/v1/financial/status/pdf/123e4567-e89b-12d3-a456-426614174010
Authorization: Bearer {token}

Response (200 OK):

• Content-Type: application/pdf
• Content-Disposition: attachment; filename=constancia-situacion-fiscal-123e4567-e89b-12d3-a456-426614174010.pdf
• Body: Contenido binario del archivo PDF

Ejemplo 5: Consultar Opinión de Cumplimiento Fiscal - Información Estructurada

Request:

GET /api/v1/financial/compliance/info/123e4567-e89b-12d3-a456-426614174030
Authorization: Bearer {token}

Response (200 OK):

{
  "id": "xyz789-abc123-def456",
  "createdAt": "2026-02-17T14:20:00Z",
  "rfc": "EEM850101ABC",
  "outcome": "POSITIVE",
  "outcomeValue": "POSITIVO",
  "collectedAt": "2026-02-17T14:15:00Z",
  "additionalData": {},
  "internalIdentification": "INT-2026-001"
}

Ejemplo 6: Obtener Documento PDF de Opinión de Cumplimiento Fiscal

Request:

GET /api/v1/financial/compliance/pdf/123e4567-e89b-12d3-a456-426614174030
Authorization: Bearer {token}

Response (200 OK):

• Content-Type: application/pdf
• Content-Disposition: attachment; filename=opinion-cumplimiento-fiscal-123e4567-e89b-12d3-a456-426614174030.pdf
• Body: Contenido binario del archivo PDF

Ejemplo 7: Obtener Listado de Declaraciones

Request:

GET /api/v1/financial/tax-returns/list/123e4567-e89b-12d3-a456-426614174010
Authorization: Bearer {token}

Response (200 OK):

{
  "taxReturnsInformation": [
    {
      "taxReturnId": "abc123-def456-ghi789",
      "period": "ANUAL 2023",
      "declarationType": "Normal"
    },
    {
      "taxReturnId": "xyz789-abc123-def456",
      "period": "ANUAL 2022",
      "declarationType": "Complementaria"
    }
  ]
}

Ejemplo 8: Consultar Información Detallada de Declaración

Request:

GET /api/v1/financial/tax-returns/info/abc123-def456-ghi789
Authorization: Bearer {token}

Response (200 OK):

{
  "id": "abc123-def456-ghi789",
  "type": "Normal",
  "generalInformation": {
    "rfc": "EEM850101ABC",
    "name": "EMPRESA EJEMPLO SA DE CV",
    "fiscalYear": 2023,
    "declarationType": "Normal",
    "declarationPeriod": "ANUAL 2023",
    "presentationDateTime": "2024-04-15T10:30:00Z"
  },
  "income": {
    "nominalIncome": 5000000.00,
    "totalAccumulableIncome": 4800000.00,
    "exemptOrNonAccumulableIncome": 200000.00
  },
  "determination": {
    "fiscalProfitOfFiscalYear": 1200000.00,
    "incomeTaxOfFiscalYear": 360000.00,
    "provisionalPaymentsMade": 300000.00,
    "incomeTaxChargedToFiscalYear": 60000.00
  }
}

Ejemplo 9: Obtener Documento PDF de Declaración

Request:

GET /api/v1/financial/tax-returns/pdf/abc123-def456-ghi789
Authorization: Bearer {token}

Response (200 OK):

• Content-Type: application/pdf
• Content-Disposition: attachment; filename=declaracion-abc123-def456-ghi789.pdf
• Body: Contenido binario del archivo PDF

Ejemplo 10: Error de Validación - Visor Financiero

Request (con datos inválidos para demostración de validación):

POST /api/v1/requests
Authorization: Bearer {token}
Content-Type: application/json

{
  "platform": "sat",
  "requestType": "external",
  "externalId": "ERR-2026-FIN001",
  "customer": {
    "personType": "organization",
    "fullName": null,
    "businessName": null,
    "rfc": "INVALID",
    "curp": null,
    "contact": {
      "email": "email-invalido",
      "phone": "123"
    }
  },
  "sourceSystem": {
    "system": "MiSistema",
    "folio": "FOL-2026-001",
    "product": "ProductoX"
  }
}

Response:

{
  "result": {
    "status": "error",
    "error": "RFC inválido. El campo 'businessName' es requerido para personType 'organization'",
    "platform": "sat"
  },
  "correlationId": "123e4567-e89b-12d3-a456-426614174030"
}

Validaciones

Validaciones de Campos

1. platform: Debe ser uno de los valores permitidos: "imss", "issste", "sat"
   • Si personType es "organization", únicamente se permite "sat"
2. requestType: Debe ser "external"
3. externalId: Debe ser un identificador único proporcionado por el sistema origen. No puede estar vacío
4. personType: Debe ser "individual" o "organization"
5. RFC:
   • Debe cumplir con el formato válido de RFC mexicano
   • Persona física: Opcional para IMSS e ISSSTE, obligatorio para SAT
   • Persona moral: Obligatorio para SAT (no aplica para IMSS/ISSSTE)
6. CURP:
   • Si se proporciona, debe cumplir con el formato válido de CURP mexicano
   • Persona física: Obligatorio para IMSS e ISSSTE, opcional para SAT
   • Persona moral: No se requiere para SAT (no aplica para IMSS/ISSSTE)
7. email: Debe cumplir con el formato válido de correo electrónico
8. phone: Debe incluir código de país y cumplir con el formato válido
9. fullName: Requerido si personType es "individual", debe ser null si es "organization"
10. businessName: Requerido si personType es "organization", debe ser null si es "individual"

Notas de Implementación

Procesamiento Asíncrono

Las consultas se procesan de forma asíncrona. Al crear una solicitud, el sistema retorna inmediatamente un requestId y el estado "in_progress". El procesamiento de la consulta se ejecuta en segundo plano.

Identificadores

• El requestId generado es un UUID v4 único por solicitud y debe utilizarse para consultar el estado y resultados mediante el método GET una vez recibida la notificación mediante webhook.
• El correlationId permite rastrear la solicitud a través de diferentes sistemas y registros de logs.

Endpoints de Consulta Diferenciados

Según la plataforma consultada, deben utilizarse diferentes endpoints GET:

• Plataformas laborales (IMSS, ISSSTE): /api/v1/labor/{requestId}
• Plataforma financiera (SAT):
  • Estado fiscal (Constancia de situación fiscal):
    • Información estructurada: /api/v1/financial/status/info/{requestId}
    • Documento PDF de constancia: /api/v1/financial/status/pdf/{requestId}
  • Opinión de cumplimiento fiscal:
    • Información estructurada: /api/v1/financial/compliance/info/{requestId}
    • Documento PDF de opinión: /api/v1/financial/compliance/pdf/{requestId}
  • Facturas (CFDI):
    • Listado paginado: /api/v1/financial/invoices/{requestId}/{pageNumber}/{pageSize} (máximo 1,000 elementos por página)
  • Estado de resultados:
    • Listado paginado: /api/v1/financial/statement/{requestId}/{pageNumber}/{pageSize} (máximo 1,000 elementos por página)
  • Balance general:
    • Listado paginado: /api/v1/financial/balance/{requestId}/{pageNumber}/{pageSize} (máximo 1,000 elementos por página)
  • Flujo de efectivo:
    • Listado paginado: /api/v1/financial/cashflow/{requestId}/{pageNumber}/{pageSize} (máximo 1,000 elementos por página)
  • Métricas financieras:
    • Listado paginado: /api/v1/financial/metrics/{requestId}/{pageNumber}/{pageSize} (máximo 1,000 elementos por página)
  • Ventas mensuales:
    • Listado paginado: /api/v1/financial/monthly-sales/{requestId}/{pageNumber}/{pageSize} (máximo 1,000 elementos por página)
  • Clientes:
    • Listado paginado: /api/v1/financial/clients/{requestId}/{pageNumber}/{pageSize} (máximo 1,000 elementos por página)
  • Proveedores:
    • Listado paginado: /api/v1/financial/suppliers/{requestId}/{pageNumber}/{pageSize} (máximo 1,000 elementos por página)
  • Nómina (empleador):
    • Listado paginado: /api/v1/financial/payroll-employers/{requestId}/{pageNumber}/{pageSize} (máximo 1,000 elementos por página)
  • Nómina (empleado):
    • Listado paginado: /api/v1/financial/payroll-employees/{requestId}/{pageNumber}/{pageSize} (máximo 1,000 elementos por página)
  • Ventas por producto:
    • Listado paginado: /api/v1/financial/product-sales/{requestId}/{pageNumber}/{pageSize} (máximo 1,000 elementos por página)
  • Costos por producto:
    • Listado paginado: /api/v1/financial/product-costs/{requestId}/{pageNumber}/{pageSize} (máximo 1,000 elementos por página)
  • Partidas de facturas (line items):
    • Listado paginado: /api/v1/financial/line-items/{requestId}/{pageNumber}/{pageSize} (máximo 1,000 elementos por página)
  • Declaraciones:
    • Listado de declaraciones: /api/v1/financial/tax-returns/list/{requestId}
    • Información detallada: /api/v1/financial/tax-returns/info/{taxReturnId} (requiere taxReturnId del listado)
    • Documento PDF de declaración: /api/v1/financial/tax-returns/pdf/{taxReturnId} (requiere taxReturnId del listado)

Una vez recibida la notificación mediante webhook, debe realizarse una solicitud GET utilizando el requestId en el endpoint correspondiente según la plataforma y el tipo de consulta para obtener los resultados.

Formato de Datos

• El estado inicial de una solicitud creada exitosamente es "in_progress" debido al procesamiento asíncrono.
• Todas las fechas y timestamps se encuentran en formato ISO 8601 (UTC).