Capítulo 1 - "Consulta de Facturación SAT"

Paso 1: Obtener el token de autenticación

Para poder realizar consultas, primero necesitamos autenticarnos en la API de Moffin y obtener un token de acceso.

Llamada a la API:

curl -i -X POST \
  https://solutions-api.moffin.mx/api/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grantType": "client_credentials",
    "clientId": "MOFFIN_cccccccc-aaaa-5555-aa33-11111111111",
    "clientSecret": "eeeee111-aa221-2313-1111-a15aa15c15aa"
  }'

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "accessTokenExpiresAt": 1737686951,
  "refreshTokenExpiresAt": 1738205351
}

Paso 2: Crear el perfil SAT

• Antes de realizar consultas, debes registrar un perfil utilizando el RFC y la CIEC del contribuyente.
• Guarda el rfc que recibirás en la respuesta, ya que será necesario para futuras consultas.

Ejemplo de solicitud API:

curl -i -X POST \
  https://solutions-api.moffin.mx/api/query/sat/profile \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "rfc": "MOCKRFC123456",
    "ciec": "12345678"
  }'

{
  "message": "Perfil creado satisfactoriamente",
  "rfc": "MOCKRFC123456",
  "profileId": 27287
}

Ejemplo de respuesta de la API:

{
  "message": "Perfil creado satisfactoriamente",
  "rfc": "MOCKRFC123456",
  "profileId": 27287
}

Paso 3: Solicitar la facturación del RFC

• Con el perfil SAT creado, ahora puedes consultar la facturación enviando el RFC y el periodo de consulta.
• Períodos válidos: 1M, 3M, 6M, 1Y, 2Y, 3Y.

Ejemplo de solicitud API:

curl -i -X POST \
  https://solutions-api.moffin.mx/api/query/sat/invoice \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "rfc": "MOCKRFC123456",
    "period": "1Y"
  }'

{
  "_id": "1234567890abcdef12345678",
  "service": "invoices",
  "status": "SUCCESS",
  "authentication": "MOCK_AUTH",
  "metadata": {
    "clientType": "PM",
    "query": { … }
  },
  "query": {
    "rfc": "ABC123456T89"
  },
  "response": {
    "periodo": "2025-01",
    "totalEmitidas": "$100,000.00",
    "totalRecibidas": "$50,000.00",
    "totalDiferencia": "$50,000.00",
    "facturasEmitidas": [ … ],
    "facturasRecibidas": [ … ],
    "codigoValidacion": "mock123456789",
    "message": null
  },
  "state": {
    "invoices": { … }
  },
  "organizationId": 99,
  "organizationSlug": "mock-organization",
  "profileId": 55555,
  "createdAt": "2025-01-23T10:00:00.000Z",
  "updatedAt": "2025-01-23T10:05:00.000Z"
}

Ejemplo de respuesta inicial de la API:

{
  "message": "Solicitud de facturación procesada exitosamente",
  "queryId": "6791b216ddf6a1c971a08624"
}

Paso 4: Recepción de los datos de facturación vía Webhook

• Una vez que la consulta ha sido procesada, recibirás los resultados en tu webhook configurado.
• La respuesta incluirá detalles de facturas emitidas y recibidas, junto con los montos totales.

Ejemplo de respuesta Webhook:

{
  "_id": "6791b216ddf6a1c971a08624",
  "service": "invoices",
  "status": "SUCCESS",
  "authentication": "MOFFIN",
  "metadata": {
    "clientType": "PM",
    "query": {
      "rfc": "MOCKRFC123456"
    }
  },
  "query": {
    "rfc": "MOCKRFC123456"
  },
  "response": {
    "periodo": "2025-01",
    "totalEmitidas": "$100,000.00",
    "totalRecibidas": "$50,000.00",
    "totalDiferencia": "$50,000.00",
    "facturasEmitidas": [
      {
        "folio": "MOCK1234-5678-ABCD-EFGH",
        "rfcEmisor": "MOCKRFC123456",
        "razonSocialEmisor": "EMPRESA MOCK",
        "monto": "$10,000.00",
        "estado": "Vigente"
      }
    ]
  },
  "createdAt": "2025-01-23T10:00:00.000Z",
  "updatedAt": "2025-01-23T10:05:00.000Z"
}

Paso 5: Manejo de errores comunes

• La API puede devolver errores en caso de datos incorrectos o perfiles inexistentes.
• Asegúrate de validar las respuestas para manejar posibles errores de manera efectiva.

Ejemplo de error 400:

{
  "message": "El perfil no existe. Primero debe crear un perfil con CIEC utilizando el endpoint POST /api/query/sat/profile"
}

Ejemplo de error 403:

{
  "message": "CIEC y/o RFC inválidos",
  "rfc": null,
  "profileId": null
}