📁 API de Facturación Electrónica SRI - Complete Documentación

Postman Collection Ready • Developer Friendly • Ecuador 2025 Compliant

🚀 Quick Start

1. Get Your API Token

# Register user
curl -X POST "{{ url('/api/register') }}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Your Name",
    "email": "[email protected]",
    "password": "YourSecurePassword123!",
    "password_confirmation": "YourSecurePassword123!"
  }'

# Get API token
curl -X POST "{{ url('/api/login') }}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "YourSecurePassword123!"
  }'

2. Use API Token in Headers

Authorization: Bearer YOUR_API_TOKEN_HERE
Content-Type: application/json

3. Idempotency Header for Create Endpoints

For document creation endpoints you must also send:

Idempotency-Key: 2f5d7fc4-0ce8-4b44-9730-a29cd5b7f3f8

Rules:

• New operation -> new key
• Retry same operation -> same key
• Same key with different payload -> 409 Conflict
• Same key still processing -> 409 Conflict

📊 API Overview

📁 Endpoint Categories

🔐 Autenticación

• 🔑 Inicio de Sesión
• 🚪 Cerrar Sesión

🏢 Company Management

• 🏢 Register Company
• 📝 Update Company
• 📜 Upload Certificate
• 🖼️ Upload Logo

📁 Document Management

• 📄 Create Document - Factura, Nota de Crédito, Retención
• 📦 Create Documents in Batch
• 📊 Consultar Estado del Documento
• 📥 Descargar PDF RIDE

🔄 Document Annulment

• 🚫 Request Annulment
• 📋 Check Annulment Estado
• 📋 List Annulments

---

🔐 Autenticación

🔑 Inicio de Sesión

Endpoint: POST /api/login

Autentica al usuario y obtiene un token de API para solicitudes posteriores.

#### Parámetros de Solicitud

Base URL	Authentication	Rate Limit	Estado
----------	--------------	------------	---------
{{ url('/api') }}	Bearer Token	1000 requests/hour	✅ Operational
Parámetro	Tipo	Requerido	Descripción	Validación
-----------	------	----------	-------------	------------
email	string	✅	Correo electrónico del usuario	`required	email`
password	string	✅	Contraseña del usuario	`required	string`

#### Cuerpo de la solicitud (JSON)

{
  "email": "[email protected]",
  "password": "SecurePass123!"
}

#### Comando cURL

curl -X POST "{{ url('/api/login') }}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123!"
  }'

#### Respuesta exitosa (200 OK)

{
  "status": "ok",
  "code": 200,
  "message": "Inicio de sesión exitoso",
  "data": {
    "user": {
      "id": 1,
      "name": "Juan Pérez",
      "email": "[email protected]"
    },
    "token": "1|abc123def456789012345678901234567890xyz",
    "token_type": "Bearer",
    "expires_in": 1440
  }
}

#### Respuestas de error

Credenciales inválidas (401)

{
  "status": "info",
  "code": 404,
  "message": "Credenciales inválidas",
  "error_code": "AUTH_001"
}

Cuenta inactiva (403)

{
  "status": "info",
  "code": 403,
  "message": "La cuenta está inactiva. Por favor contacta al administrador.",
  "error_code": "AUTH_002"
}

🚪 Cerrar Sesión

Endpoint: POST /api/logout

Invalida el token de API actual.

#### Encabezados de Solicitud

Header	Value	Descripción
--------	-------	-------------
Authorization	Bearer {token}	Token de API válido
Content-Type	application/json	Tipo de contenido

#### Comando cURL

curl -X POST "{{ url('/api/logout') }}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

#### Respuesta exitosa (200 OK)

{
  "status": "ok",
  "code": 200,
  "message": "Sesión cerrada correctamente",
  "data": []
}

#### Respuestas de error

Token inválido (401)

{
  "status": "error",
  "code": 401,
  "message": "Token inválido o expirado",
  "error_code": "AUTH_003"
}

---

📊 Estado Códigos Reference

HTTP Estado Códigos

Business Error Códigos

Estado Código	Meaning	When It Occurs
-------------	---------	-----------------
200 OK	Success	Request processed éxitofully
201 Created	Created	Resource created éxitofully
400 Bad Request	Invalid Request	Malformed JSON or invalid parameters
401 Unauthorized	Authentication Failed	Invalid or missing API token
403 Forbidden	Access Denied	User doesn't have permission
404 Not Found	Resource Not Found	Requested resource doesn't exist
422 Unprocessable Entity	Validation Error	Request validation failed
429 Too Many Requests	Rate Limited	Too many requests in time period
500 Internal Server Error	Server Error	Unexpected server error
Error Código	Descripción	Resolution
-------------	-------------	------------
AUTH_001	Invalid credentials	Check email/password
AUTH_002	Account inactive	Contact administrator
AUTH_003	Token expired	Login again
COMP_001	Company not found	Verify company RUC
COMP_002	Company inactive	Activate company account
DOC_001	Document sequence exists	Use next sequential number
DOC_002	Total amount mismatch	Verify calculations
DOC_003	Invalid customer type	Check identification datos
SRI_001	Certificate invalid	Upload valid certificate
SRI_002	Document not authorized	Wait for authorization
ANN_001	Annulment deadline passed	Check SRI rules

---

🚀 Best Practices

Autenticación

• Almacena los tokens de API de forma segura (nunca en código cliente)
• Usa HTTPS en todas las solicitudes
• Implementa un mecanismo de renovación de token
• Maneja los tokens expirados correctamente

Rate Limiting

• Implementa una estrategia de reintentos progresivos para fallos
• Cachea respuestas no sensibles
• Usa códigos HTTP apropiados

Manejo de Errores

• Verifica primero el campo status
• Maneja el objeto errores para fallas de validación
• Implementa reintentos para errores recuperables
• Registra errores para depuración

Seguridad

• Valida todos los parámetros de entrada
• Nunca expongas datos sensibles en las respuestas
• Usa encabezados de autenticación correctos
• Implementa CORS si es necesario

---

🔧 Postman Collection

Import Collection

• Download this collection: Descargar colección Postman
• Open Postman
• Click Import → Select File
• Upload the downloaded JSON file from docs/FactusEasy.postman_collection.json
• Set environment variables for base_url, email, password

Environment Variables

{
  "base_url": "{{ url('/api') }}",
  "token": "",
  "company_ruc": "1712345678001",
  "external_id": "TEST-001"
}

---

📚 Additional Resources

• 📘 Complete API Examples
• ✅ Validation Rules
• 📋 Factura Examples
• 📝 Nota de Crédito Examples
• 🧾 Retention Examples
• 📋 SRI Annulment Rules 2025

---

🤝 Soporte

• 📧 Email: [email protected]
• 📚 Documentación: {{ url('/docs') }}
• 🧪 API Demo: {{ url('/api/demo') }}
• 🐛 Issues: GitHub Issues

---

Last updated: January 2025 API Version: 1.0.0