API Interna - FactPy Docs

Endpoint para Consultar Estados

URL del Endpoint

https://api.factpy.com/facturacion-api/estadoDE.php

Método	URL	Content-Type
POST	`https://api.factpy.com/facturacion-api/estadoDE.php`	`multipart/form-data`

¿Para Qué Sirve?

Consultar Estado

Verificar si un documento fue aprobado, rechazado o está pendiente

Consultas Múltiples

Consultar el estado de varios documentos en una sola solicitud

Obtener CDC

Recuperar el CDC de documentos aprobados

Parámetros del Body

El cuerpo de la solicitud debe enviarse en formato multipart/form-data con los siguientes parámetros:

receiptid array Requerido

Array de strings con los receiptid de los documentos a consultar. Estos son los IDs únicos que asignaste al crear cada documento

recordID string Requerido

Identificador único del registro en el sistema. Este ID se encuentra en tu perfil de FactPy

Ejemplo de Solicitud JSON

JSON

{
  "receiptid": [
    "1",
    "2",
    "3",
    "4"
  ]
}

Sobre los receiptid

Los receiptid son los identificadores únicos que asignaste al crear cada documento en el campo receiptid del JSON de facturación

Ejemplo de Respuesta

JSON

[
  {
    "receiptid": "1",
    "cdc": "01",
    "estado": "Rechazado",
    "mensaje": "XML malformado: [El valor 01080654005900100006842229124091912850 del elemento: dCdcSeq es invalido, El valor 2855 del elemento: dCodSeq es invalido]",
    "documento": "001-001-0000084",
    "numero_tr": "0"
  },
  {
    "receiptid": "2",
    "cdc": "N/A",
    "estado": "No encontrado",
    "mensaje": "No se encontraron datos para el receiptid",
    "documento": "N/A",
    "numero_tr": ""
  },
  {
    "receiptid": "3",
    "cdc": "",
    "estado": "",
    "mensaje": "",
    "documento": "",
    "numero_tr": ""
  }
]

Campos de la Respuesta

Campo	Tipo	Descripción
`receiptid`	string	ID del documento consultado
`cdc`	string	Código de Control del documento (44 dígitos) o `"N/A"` si no se encontró
`estado`	string	Estado del documento: `"Aprobado"`, `"Rechazado"`, `"No encontrado"`, etc.
`mensaje`	string	Descripción detallada del estado o errores encontrados
`documento`	string	Número del documento en formato `001-001-0000084` o `"N/A"`
`numero_tr`	string	Número de transacción o tracking

Estados Posibles

Estado	Significado	Acción Recomendada
Aprobado	Documento aprobado por SIFEN	Guardar el CDC, documento listo para usar
Rechazado	Documento rechazado por SIFEN	Revisar el `mensaje` y corregir errores
No encontrado	No existe documento con ese receiptid	Verificar que el receiptid sea correcto
Procesando	Documento en proceso de validación	Esperar y consultar nuevamente

Ejemplo en JavaScript

JavaScript

const formData = new FormData();

// Array de receiptid a consultar
const receiptIds = {
  receiptid: ["1", "2", "3", "4"]
};

formData.append('receiptid', JSON.stringify(receiptIds));
formData.append('recordID', 'TU_RECORD_ID');

fetch('https://api.factpy.com/facturacion-api/estadoDE.php', {
  method: 'POST',
  body: formData
})
.then(response => response.json())
.then(data => {
  console.log('Estados de documentos:', data);
  
  data.forEach(doc => {
    console.log(`\n--- Documento ${doc.receiptid} ---`);
    console.log(`Estado: ${doc.estado}`);
    console.log(`CDC: ${doc.cdc}`);
    console.log(`Documento: ${doc.documento}`);
    console.log(`Mensaje: ${doc.mensaje}`);
    
    if (doc.estado === 'Aprobado') {
      console.log('✓ Documento aprobado exitosamente');
    } else if (doc.estado === 'Rechazado') {
      console.error('✗ Documento rechazado:', doc.mensaje);
    } else if (doc.estado === 'No encontrado') {
      console.warn('⚠ Documento no encontrado');
    }
  });
})
.catch(error => console.error('Error de red:', error));

Ejemplo cURL

bash

curl -X POST https://api.factpy.com/facturacion-api/estadoDE.php \
  -H "Content-Type: multipart/form-data" \
  -F "receiptid={\"receiptid\":[\"1\",\"2\",\"3\",\"4\"]}" \
  -F "recordID=TU_RECORD_ID"

Caso de Uso Práctico

JavaScript

// Función para verificar documentos pendientes
async function verificarDocumentosPendientes(receiptIds) {
  const formData = new FormData();
  
  formData.append('receiptid', JSON.stringify({ receiptid: receiptIds }));
  formData.append('recordID', 'TU_RECORD_ID');
  
  try {
    const response = await fetch('https://api.factpy.com/facturacion-api/estadoDE.php', {
      method: 'POST',
      body: formData
    });
    
    const documentos = await response.json();
    
    // Separar por estado
    const aprobados = documentos.filter(d => d.estado === 'Aprobado');
    const rechazados = documentos.filter(d => d.estado === 'Rechazado');
    const pendientes = documentos.filter(d => 
      d.estado !== 'Aprobado' && 
      d.estado !== 'Rechazado' && 
      d.estado !== 'No encontrado'
    );
    
    console.log(`✓ Aprobados: ${aprobados.length}`);
    console.log(`✗ Rechazados: ${rechazados.length}`);
    console.log(`⏳ Pendientes: ${pendientes.length}`);
    
    // Guardar CDCs de aprobados
    aprobados.forEach(doc => {
      console.log(`Guardar CDC: ${doc.cdc} para documento ${doc.documento}`);
      // Aquí guardarías en tu base de datos
    });
    
    // Reportar rechazados
    rechazados.forEach(doc => {
      console.error(`Error en ${doc.receiptid}: ${doc.mensaje}`);
      // Aquí podrías enviar notificación o registrar para corrección
    });
    
    return { aprobados, rechazados, pendientes };
    
  } catch (error) {
    console.error('Error al consultar estados:', error);
    throw error;
  }
}

// Uso
const receiptIds = ['factura_001', 'factura_002', 'factura_003'];
verificarDocumentosPendientes(receiptIds);

Notas Importantes

receiptid único

Asegúrate de que cada receiptid sea único en tu sistema para evitar confusiones

Documentos pendientes

Si un documento está "Procesando", espera unos segundos antes de consultar nuevamente

Guardar CDCs

Una vez que un documento está aprobado, guarda su CDC en tu base de datos para referencias futuras

Documentos rechazados

Lee cuidadosamente el mensaje de error para identificar qué corregir antes de reenviar

Próximos Pasos

Endpoints Facturación

Cómo crear documentos electrónicos

Crear Facturas

Aprende a generar documentos

Eventos

Cancelar, inutilizar y nominar

API Interna - Consultar Estados de Documentos