Consultar Documentos

Pruebas
Producción

Dominio: https://test-api-factura.edw-dev.com

Documentación para la consulta de documentos electrónicos existentes, incluyendo búsqueda por ID, listado con filtros y obtención de archivos PDF/XML.

Consultar Documento por ID

Obtiene los detalles completos de un documento específico por su ID.

Endpoint

GET /api/v1/documents/{id}

Headers requeridos

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

Parámetros de ruta

id (requerido): ID único del documento

Respuesta exitosa (200 OK)

{
  "message": "Documento encontrado",
  "status": "OK",
  "payload": {
    "id": 61247344,
    "environment": "TEST",
    "number": 1,
    "date": "2024-10-09",
    "due_date": null,
    "discount_amount": "12.33",
    "subtotal": "12.33",
    "tax_amount": "1.85",
    "tip": "0.00",
    "total": "14.18",
    "payment_date": null,
    "notes": null,
    "terms": null,
    "status": "draft",
    "type": "invoice",
    "parent_id": null,
    "customer": {
      "id": 61247344,
      "full_name": "Consumidor Final",
      "email": "[email protected]",
      "identification_type": "cedula",
      "identification_number": "9999999999"
    },
    "sri": {
      "access_key": "0910202401095261517700110010040000000301234567916",
      "key_where_generated": "local",
      "status": null,
      "has_been_sent": false,
      "has_pdf": false,
      "sequential_doc": "000000030",
      "establishment": "001",
      "point_emi": "004",
      "number_document": "001-004-000000030",
      "type_document": "FACTURA",
      "title_document": "Factura",
      "code_document": "01",
      "date_sent": null,
      "authorization_date": null,
      "send_automatic": true
    },
    "support": {
      "code_document": null,
      "document_number": null,
      "document_title": null,
      "date": null,
      "reason": null,
      "access_key": null,
      "transfer_plate": null,
      "transfer_route": null,
      "transfer_address": null,
      "transfer_customs_document": null,
      "transfer_departure_address": null
    },
    "items": [
      {
        "position": 1,
        "code": "ABC-001",
        "description": "ITEM PRUEBAS",
        "rate": "12.33",
        "unit": null,
        "quantity": "2.00",
        "rate_before_discount": "24.66",
        "discount_percent": "50.0",
        "discount_value": "12.33",
        "subtotal": "12.33",
        "total_tax": "1.85",
        "total": "14.18",
        "taxes": [
          {
            "type": "IVA",
            "name": "15%",
            "code": "2",
            "percentaje_code": "4",
            "rate_before_tax": "12.33",
            "percentaje_tax": "15.00",
            "total_tax": "1.85",
            "rate_after_tax": "14.18"
          }
        ]
      }
    ],
    "taxes": [
      {
        "tax_type": "IVA",
        "tax_name": "15%",
        "tax_rate": "1.85",
        "tax_subtotal": "12.33",
        "tax_code": "2",
        "tax_code_sri": "4"
      }
    ],
    "warnings_sri": [
      {
        "message": "ARCHIVO NO CUMPLE ESTRUCTURA XML",
        "description": "Se encontró el siguiente error en la estructura del comprobante: cvc-complex-type.2.4.a: Invalid content was found starting with element 'baseImponible'. One of '{tarifa}' is expected..",
        "status_sri": "DEVUELTA"
      }
    ]
  }
}

Respuesta de error (404 Not Found)

{
  "message": "Registro no encontrado",
  "status": "ERROR",
  "payload": null,
  "error": "Registro no encontrado"
}

Ejemplos de Implementación

curl -X GET "https://dev-facturacion.e-dinky.test/api/v1/documents/61247344" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {token}"

<?php

use Illuminate\Support\Facades\Http;

$documentId = '61247344';
$token = 'your-api-token';

$response = Http::withHeaders([
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer ' . $token,
])->get("https://dev-facturacion.e-dinky.test/api/v1/documents/{$documentId}");

if ($response->successful()) {
    $document = $response->json();
    echo "Documento encontrado: " . $document['payload']['id'];
    echo "Estado: " . $document['payload']['status'];
    echo "Total: $" . $document['payload']['total'];
} else {
    echo "Error: " . $response->body();
}

const axios = require('axios');

const getDocument = async (documentId) => {
    const token = 'your-api-token';

    const config = {
        method: 'get',
        url: `https://dev-facturacion.e-dinky.test/api/v1/documents/${documentId}`,
        headers: {
            'Content-Type': 'application/json',
            'Accept': 'application/json',
            'Authorization': `Bearer ${token}`
        }
    };

    try {
        const response = await axios(config);
        console.log('Documento encontrado:', response.data.payload.id);
        console.log('Estado:', response.data.payload.status);
        console.log('Total: $', response.data.payload.total);
        return response.data;
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
        throw error;
    }
};

// Uso
getDocument('61247344')
    .then(result => console.log('Éxito:', result))
    .catch(error => console.error('Error:', error));

Obtener Mis Documentos

Obtiene una lista paginada de todos los documentos del usuario autenticado.

Endpoint

GET /api/v1/documents

Headers requeridos

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

Parámetros de consulta (opcionales)

page: Número de página (por defecto: 1)
per_page: Elementos por página (por defecto: 15, máximo: 100)
filters: Filtros avanzados en formato JSON (ver Sistema de Filtros)

Ejemplo de consulta con filtros avanzados

GET /api/v1/documents?page=1&per_page=20&filters=[{"field":"type","condition":"eq","value":"invoice"},{"field":"status","condition":"eq","value":"authorized"},{"field":"created_at","condition":"ge","value":"2024-01-01"},{"field":"created_at","condition":"le","value":"2024-12-31"}]

Filtros disponibles para documentos

Campo	Descripción	Ejemplo
`type`	Tipo de documento	`{"field":"type","condition":"eq","value":"invoice"}`
`status`	Estado del documento	`{"field":"status","condition":"eq","value":"authorized"}`
`created_at`	Fecha de creación	`{"field":"created_at","condition":"ge","value":"2024-01-01"}`
`total`	Total del documento	`{"field":"total","condition":"gt","value":"100"}`
`number_document`	Número del documento	`{"field":"number_document","condition":"sw","value":"001"}`
`access_key`	Clave de acceso	`{"field":"access_key","condition":"ew","value":"123"}`
`customer_id`	ID del cliente	`{"field":"customer_id","condition":"eq","value":"12345"}`

Para más información sobre el sistema de filtros, consulta la documentación completa de filtros.

Ejemplos de Implementación

# Obtener todos los documentos (página 1)
curl -X GET "https://dev-facturacion.e-dinky.test/api/v1/documents?page=1&per_page=15" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {token}"

# Obtener documentos con filtros
curl -X GET "https://dev-facturacion.e-dinky.test/api/v1/documents?page=1&per_page=20&filters=[{\"field\":\"type\",\"condition\":\"eq\",\"value\":\"invoice\"},{\"field\":\"status\",\"condition\":\"eq\",\"value\":\"authorized\"}]" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {token}"

<?php

use Illuminate\Support\Facades\Http;

$token = 'your-api-token';

// Obtener todos los documentos
$response = Http::withHeaders([
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer ' . $token,
])->get('https://dev-facturacion.e-dinky.test/api/v1/documents', [
    'page' => 1,
    'per_page' => 15
]);

// Obtener documentos con filtros
$filters = [
    ['field' => 'type', 'condition' => 'eq', 'value' => 'invoice'],
    ['field' => 'status', 'condition' => 'eq', 'value' => 'authorized'],
    ['field' => 'created_at', 'condition' => 'ge', 'value' => '2024-01-01']
];

$responseWithFilters = Http::withHeaders([
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer ' . $token,
])->get('https://dev-facturacion.e-dinky.test/api/v1/documents', [
    'page' => 1,
    'per_page' => 20,
    'filters' => json_encode($filters)
]);

if ($response->successful()) {
    $documents = $response->json();
    echo "Total de documentos: " . $documents['meta']['total'];
    foreach ($documents['data'] as $document) {
        echo "Documento: " . $document['id'] . " - Total: $" . $document['total'];
    }
} else {
    echo "Error: " . $response->body();
}

const axios = require('axios');

const getDocuments = async (page = 1, perPage = 15, filters = null) => {
    const token = 'your-api-token';

    const params = {
        page: page,
        per_page: perPage
    };

    if (filters) {
        params.filters = JSON.stringify(filters);
    }

    const config = {
        method: 'get',
        url: 'https://dev-facturacion.e-dinky.test/api/v1/documents',
        headers: {
            'Content-Type': 'application/json',
            'Accept': 'application/json',
            'Authorization': `Bearer ${token}`
        },
        params: params
    };

    try {
        const response = await axios(config);
        console.log('Total de documentos:', response.data.meta.total);
        console.log('Página actual:', response.data.meta.current_page);

        response.data.data.forEach(document => {
            console.log(`Documento: ${document.id} - Total: $${document.total}`);
        });

        return response.data;
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
        throw error;
    }
};

// Uso básico
getDocuments(1, 15)
    .then(result => console.log('Éxito:', result.meta))
    .catch(error => console.error('Error:', error));

// Uso con filtros
const filters = [
    { field: 'type', condition: 'eq', value: 'invoice' },
    { field: 'status', condition: 'eq', value: 'authorized' },
    { field: 'created_at', condition: 'ge', value: '2024-01-01' }
];

getDocuments(1, 20, filters)
    .then(result => console.log('Documentos filtrados:', result.data.length))
    .catch(error => console.error('Error:', error));

Obtener Documento XML o PDF

Descarga el archivo XML o PDF de un documento específico.

Endpoint

GET /api/v1/documents/{id}/download

Headers requeridos

Accept: application/xml, application/pdf
Authorization: Bearer {token}

Parámetros de consulta

format: Formato del archivo (xml, pdf)

Ejemplo

GET /api/v1/documents/61247344/download?format=pdf

Ejemplos de Implementación

# Descargar PDF
curl -X GET "https://dev-facturacion.e-dinky.test/api/v1/documents/61247344/download?format=pdf" \
  -H "Accept: application/pdf" \
  -H "Authorization: Bearer {token}" \
  --output documento.pdf

# Descargar XML
curl -X GET "https://dev-facturacion.e-dinky.test/api/v1/documents/61247344/download?format=xml" \
  -H "Accept: application/xml" \
  -H "Authorization: Bearer {token}" \
  --output documento.xml

<?php

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Storage;

$documentId = '61247344';
$token = 'your-api-token';

// Descargar PDF
$pdfResponse = Http::withHeaders([
    'Accept' => 'application/pdf',
    'Authorization' => 'Bearer ' . $token,
])->get("https://dev-facturacion.e-dinky.test/api/v1/documents/{$documentId}/download", [
    'format' => 'pdf'
]);

if ($pdfResponse->successful()) {
    // Guardar el archivo PDF
    Storage::put("documents/documento_{$documentId}.pdf", $pdfResponse->body());
    echo "PDF descargado exitosamente";
}

// Descargar XML
$xmlResponse = Http::withHeaders([
    'Accept' => 'application/xml',
    'Authorization' => 'Bearer ' . $token,
])->get("https://dev-facturacion.e-dinky.test/api/v1/documents/{$documentId}/download", [
    'format' => 'xml'
]);

if ($xmlResponse->successful()) {
    // Guardar el archivo XML
    Storage::put("documents/documento_{$documentId}.xml", $xmlResponse->body());
    echo "XML descargado exitosamente";
} else {
    echo "Error: " . $xmlResponse->body();
}

const axios = require('axios');
const fs = require('fs');
const path = require('path');

const downloadDocument = async (documentId, format = 'pdf') => {
    const token = 'your-api-token';

    const config = {
        method: 'get',
        url: `https://dev-facturacion.e-dinky.test/api/v1/documents/${documentId}/download`,
        headers: {
            'Accept': format === 'pdf' ? 'application/pdf' : 'application/xml',
            'Authorization': `Bearer ${token}`
        },
        params: {
            format: format
        },
        responseType: 'stream'
    };

    try {
        const response = await axios(config);

        // Crear el nombre del archivo
        const fileName = `documento_${documentId}.${format}`;
        const filePath = path.join(__dirname, 'downloads', fileName);

        // Crear el directorio si no existe
        const dir = path.dirname(filePath);
        if (!fs.existsSync(dir)) {
            fs.mkdirSync(dir, { recursive: true });
        }

        // Guardar el archivo
        const writer = fs.createWriteStream(filePath);
        response.data.pipe(writer);

        return new Promise((resolve, reject) => {
            writer.on('finish', () => {
                console.log(`${format.toUpperCase()} descargado exitosamente: ${fileName}`);
                resolve(filePath);
            });
            writer.on('error', reject);
        });

    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
        throw error;
    }
};

// Uso
downloadDocument('61247344', 'pdf')
    .then(filePath => console.log('Archivo guardado en:', filePath))
    .catch(error => console.error('Error:', error));

downloadDocument('61247344', 'xml')
    .then(filePath => console.log('Archivo guardado en:', filePath))
    .catch(error => console.error('Error:', error));

Campos de respuesta

Información básica del documento

id: ID único del documento
environment: Ambiente (TEST, PRODUCTION)
number: Número interno del documento
date: Fecha de emisión
due_date: Fecha de vencimiento
status: Estado del documento
type: Tipo de documento
total: Total del documento

Información del cliente

customer.id: ID del cliente
customer.full_name: Nombre completo
customer.email: Email del cliente
customer.identification_type: Tipo de identificación
customer.identification_number: Número de identificación

Información del SRI

sri.access_key: Clave de acceso del SRI
sri.status: Estado en el SRI
sri.sequential_doc: Secuencial del documento
sri.establishment: Establecimiento
sri.point_emi: Punto de emisión
sri.number_document: Número completo del documento
sri.authorization_date: Fecha de autorización del SRI

Items del documento

items[].code: Código del producto/servicio
items[].description: Descripción
items[].quantity: Cantidad
items[].rate: Precio unitario
items[].subtotal: Subtotal del item
items[].total_tax: Total de impuestos
items[].total: Total del item

Impuestos

taxes[].tax_type: Tipo de impuesto (IVA, ICE)
taxes[].tax_name: Nombre del impuesto
taxes[].tax_rate: Valor del impuesto
taxes[].tax_subtotal: Base imponible

Advertencias del SRI

warnings_sri[].message: Mensaje de advertencia
warnings_sri[].description: Descripción detallada
warnings_sri[].status_sri: Estado en el SRI

Estados de documentos

Estados internos

draft: Borrador, no enviado al SRI
published: Publicado, listo para enviar al SRI
sent: Enviado al SRI, esperando respuesta

Estados del SRI

AUTORIZADO: Documento autorizado por el SRI
DEVUELTA: Documento devuelto por errores
NO_AUTORIZADO: Documento no autorizado
RECIBIDA: Documento recibido por el SRI

Tipos de documentos

invoice: Factura (01)
credit_note: Nota de Crédito (04)
debit_note: Nota de Débito (05)
delivery_note: Guía de Remisión (06)
retention: Comprobante de Retención (07)
liquidacion_compras: Liquidación de Compras (03)

Filtros de búsqueda

Por fecha

?date_from=2024-01-01&date_to=2024-12-31

Por tipo de documento

?type=invoice

Por estado

?status=authorized

Por cliente

?customer_id=61247344

Búsqueda de texto

?search=001-004-000000030

Combinación de filtros

?type=invoice&status=authorized&date_from=2024-10-01&search=Consumidor

Paginación

La respuesta incluye metadatos de paginación:

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 15,
    "to": 15,
    "total": 75
  },
  "links": {
    "first": "https://dev-facturacion.e-dinky.test/documents?page=1",
    "last": "https://dev-facturacion.e-dinky.test/documents?page=5",
    "prev": null,
    "next": "https://dev-facturacion.e-dinky.test/documents?page=2"
  }
}

Códigos de error comunes

400: Parámetros de consulta inválidos
401: Token de autorización inválido
403: Sin permisos para consultar documentos
404: Documento no encontrado
422: Filtros de búsqueda inválidos
500: Error interno del servidor

Notas importantes

Los documentos solo son visibles para el usuario que los creó
Los filtros de fecha utilizan la fecha de emisión del documento
La búsqueda de texto funciona en número de documento y nombre del cliente
Los archivos PDF solo están disponibles para documentos autorizados
Los archivos XML están disponibles para todos los documentos enviados al SRI
La paginación es obligatoria para evitar respuestas muy grandes
Los documentos eliminados no aparecen en las consultas