Endpoint de Estado de Documentos API

Detalles del Endpoint

• URL: GET /api/document/status
• Autenticación: Requerida (Bearer token vía Sanctum)
• Content-Type: application/json

Parámetros de Solicitud

Parámetros Obligatorios

• ruc (string, obligatorio): RUC de la empresa (13 dígitos)

Parámetros Opcionales

• external_id (string): ID externo del documento
• access_key (string): Clave de acceso SRI (49 dígitos)
• status (string): Filtro de estado del documento
- Valores válidos: GENERATED, SIGNED, RECEIVED, AUTHORIZED, REJECTED, ERROR, RETURNED
• date_from (date, formato: Y-m-d): Filtrar documentos desde esta fecha
• date_to (date, formato: Y-m-d): Filtrar documentos hasta esta fecha
• include_xml (boolean): Incluir contenido XML en la respuesta (default: false)
• per_page (integer): Elementos por página (1-100, default: 20)
• page (integer): Número de página (default: 1)

Ejemplos de Solicitud

1. Obtener Todos los Documentos de la Empresa

curl -X GET "http://localhost/api/document/status?ruc=1234567890123" \
     -H "Authorization: Bearer YOUR_TOKEN"

2. Obtener Documento Específico por ID Externo

curl -X GET "http://localhost/api/document/status?ruc=1234567890123&external_id=DOC-001&include_xml=true" \
     -H "Authorization: Bearer YOUR_TOKEN"

3. Obtener Documento por Clave de Acceso

curl -X GET "http://localhost/api/document/status?ruc=1234567890123&access_key=2712345678901234567890123456789012345678901234567890&include_xml=true" \
     -H "Authorization: Bearer YOUR_TOKEN"

4. Filtrar por Estado y Rango de Fechas

curl -X GET "http://localhost/api/document/status?ruc=1234567890123&status=AUTHORIZED&date_from=2025-12-01&date_to=2025-12-31" \
     -H "Authorization: Bearer YOUR_TOKEN"

5. Resultados Paginados

curl -X GET "http://localhost/api/document/status?ruc=1234567890123&per_page=10&page=2" \
     -H "Authorization: Bearer YOUR_TOKEN"

Formato de Respuesta

Respuesta de Éxito

{
  "status": "ok",
  "code": 200,
  "message": "Documents status retrieved successfully",
  "data": {
    "documents": [
      {
        "external_id": "DOC-001",
        "access_key": "2712345678901234567890123456789012345678901234567890",
        "document_type": "01",
        "series": "001001",
        "sequential": "000001234",
        "issue_date": "2025-12-28",
        "status": "AUTHORIZED",
        "document_status": "AUTORIZADO",
        "authorization_number": "2712345678901234567890123456789012345678901234567890",
        "authorization_date": "28/12/2025 14:30:45",
        "authorization_attempts": 2,
        "last_authorization_attempt_at": "2025-12-28 14:32:10",
        "message": "Autorizado satisfactoriamente",
        "code": "00",
        "notification_email": "[email protected]",
        "webhook_url": "https://example.com/webhook",
        "created_at": "2025-12-28T14:25:00.000000Z",
        "updated_at": "2025-12-28T14:32:10.000000Z",
        "status_info": {
          "is_finalized": true,
          "is_processing": false,
          "has_xml": true,
          "can_query_sri": false,
          "next_expected_action": "Document fully authorized and complete"
        },
        "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>..." // Solo si include_xml=true
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 1,
      "last_page": 1,
      "has_more": false
    },
    "summary": {
      "total_documents": 1,
      "by_status": {
        "GENERATED": 0,
        "SIGNED": 0,
        "RECEIVED": 0,
        "AUTHORIZED": 1,
        "REJECTED": 0,
        "ERROR": 0,
        "RETURNED": 0
      },
      "finalized_documents": 1,
      "processing_documents": 0
    },
    "filters_applied": {
      "ruc": {
        "label": "RUC",
        "value": "1234567890123"
      },
      "include_xml": {
        "label": "Include XML",
        "value": true
      }
    }
  }
}

Respuesta de Documento Único (cuando se usa external_id o access_key)

{
  "status": "ok",
  "code": 200,
  "message": "Document status retrieved successfully",
  "data": {
    "external_id": "DOC-001",
    "access_key": "2712345678901234567890123456789012345678901234567890",
    // ... mismos campos del documento que arriba
  }
}

Respuestas de Error

#### Empresa No Encontrada

{
  "status": "error",
  "code": 404,
  "message": "Company not found"
}

#### Documento No Encontrado

{
  "status": "error",
  "code": 404,
  "message": "Document not found"
}

#### Error de Validación

{
  "status": "error",
  "code": 422,
  "message": "The given data was invalid.",
  "errors": {
    "ruc": ["The RUC field is required."],
    "access_key": ["The access key must be exactly 49 characters."]
  }
}

Lógica de Inclusión de XML

El endpoint incluye contenido XML basado en el estado del documento cuando include_xml=true:

Campos de Información de Estado

El objeto status_info proporciona contexto adicional:

• is_finalized: El documento está en estado final (sin procesamiento adicional)
• is_processing: El documento está siendo procesado actualmente
• has_xml: El contenido XML está disponible para este estado
• can_query_sri: El documento puede consultarse al SRI para estado de autorización
• next_expected_action: Descripción legible del siguiente paso esperado

Paginación

Al consultar múltiples documentos:

• Tamaño de página por defecto: 20 elementos
• Tamaño máximo de página: 100 elementos
• Página por defecto: 1
• La respuesta incluye metadatos de paginación para navegación

Limitación de Velocidad

• El endpoint respects los requisitos de autenticación
• Los documentos solo pueden ser accedidos por la empresa propietaria
• No hay limitación de velocidad adicional implementada (agregar según sea necesario)

Consideraciones de Seguridad

• Autenticación: Se requiere token Sanctum válido
• Autorización: Los usuarios solo pueden acceder a los documentos de su propia empresa
• Validación de Entrada: Todos los parámetros son validados
• Protección contra Inyección SQL: Usa ORM de Laravel con binding de parámetros
• Protección XSS: El contenido XML se escapa correctamente en la respuesta JSON