Gestión de Cuentas

Pruebas
Producción

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

Esta sección documenta los endpoints relacionados con la gestión de cuentas empresariales, incluyendo la actualización de información de cuentas y la finalización del proceso de configuración.

Actualizar Cuenta

Información General

Endpoint: PUT /api/v1/companies/update-account
Método: PUT
Autenticación: Bearer Token requerido
Descripción: Permite actualizar la información de una cuenta empresarial específica

Headers Requeridos

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

Parámetros del Request Body

Campo	Tipo	Requerido	Descripción
`account_id`	string	Sí	ID de la cuenta a actualizar
`ruc`	string	No	RUC de la empresa
`razon_social`	string	No	Razón social de la empresa
`nombre_comercial`	string	No	Nombre comercial
`direccion_matriz`	string	No	Dirección de la matriz
`environment`	string	No	Ambiente: “TEST” o “PRODUCTION”
`mail_cc`	string	No	Correo electrónico en copia
`is_rimpe`	integer	No	Indica si es RIMPE (1 = sí, 0 = no)
`retention_agent`	integer	No	Código de agente de retención
`currency`	string	No	Moneda: “DOLAR” o “PESO”
`is_contable`	string	No	Indica si es contable: “SI” o “NO”

Ejemplo de Request

{
    "account_id": "61247344",
    "ruc": "0952615177001",
    "razon_social": "EMPRESA ACTUALIZADA S.A.",
    "nombre_comercial": "EMPRESA ACTUALIZADA",
    "direccion_matriz": "Av. Principal 123, Quito",
    "environment": "PRODUCTION",
    "mail_cc": "[email protected]",
    "is_rimpe": 0,
    "retention_agent": 1234,
    "currency": "DOLAR",
    "is_contable": "SI"
}

Respuesta Exitosa (200 OK)

{
    "message": "Cuenta actualizada exitosamente",
    "status": "UPDATED",
    "payload": {
        "uuid": 61247344,
        "ruc": "0952615177001",
        "name": "EMPRESA ACTUALIZADA S.A.",
        "commercial_name": "EMPRESA ACTUALIZADA",
        "matriz_address": "Av. Principal 123, Quito",
        "environment": "PRODUCTION",
        "status_process": "active",
        "warnings": null,
        "is_contable": "SI",
        "currency": "DOLAR",
        "has_configured": true,
        "has_mysign": true,
        "mail_cc": "[email protected]",
        "is_rimpe": false,
        "retention_agent": 1234,
        "updated_at": "2024-01-15T10:30:00Z"
    }
}

Ejemplos de Código

curl -X PUT \
  {{apiFacEcDev}}/api/v1/companies/update-account \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {{bearerToken}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_id": "61247344",
    "ruc": "0952615177001",
    "razon_social": "EMPRESA ACTUALIZADA S.A.",
    "nombre_comercial": "EMPRESA ACTUALIZADA",
    "direccion_matriz": "Av. Principal 123, Quito",
    "environment": "PRODUCTION"
}'

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'Authorization' => 'Bearer ' . $bearerToken,
    'Accept' => 'application/json',
])->put($apiUrl . '/api/v1/companies/update-account', [
    'account_id' => '61247344',
    'ruc' => '0952615177001',
    'razon_social' => 'EMPRESA ACTUALIZADA S.A.',
    'nombre_comercial' => 'EMPRESA ACTUALIZADA',
    'direccion_matriz' => 'Av. Principal 123, Quito',
    'environment' => 'PRODUCTION',
    'mail_cc' => '[email protected]',
    'is_rimpe' => 0,
    'currency' => 'DOLAR'
]);

$data = $response->json();

const axios = require('axios');

const updateAccount = async (accountData) => {
    try {
        const response = await axios.put(
            `${apiUrl}/api/v1/companies/update-account`,
            accountData,
            {
                headers: {
                    'Authorization': `Bearer ${bearerToken}`,
                    'Content-Type': 'application/json',
                    'Accept': 'application/json'
                }
            }
        );

        console.log('Cuenta actualizada:', response.data);
        return response.data;
    } catch (error) {
        console.error('Error:', error.response.data);
        throw error;
    }
};

Completar Configuración

Información General

Endpoint: POST /api/v1/companies/complete-configuration
Método: POST
Autenticación: Bearer Token requerido
Descripción: Finaliza el proceso de configuración inicial de una empresa

Headers Requeridos

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

Parámetros del Request Body

Campo	Tipo	Requerido	Descripción
`account_id`	string	Sí	ID de la cuenta a configurar
`confirm_configuration`	boolean	Sí	Confirmación de configuración completa
`terms_accepted`	boolean	No	Aceptación de términos y condiciones
`notifications_enabled`	boolean	No	Habilitar notificaciones

Ejemplo de Request

{
    "account_id": "61247344",
    "confirm_configuration": true,
    "terms_accepted": true,
    "notifications_enabled": true
}

Respuesta Exitosa (200 OK)

{
    "message": "Configuración completada exitosamente",
    "status": "CONFIGURED",
    "payload": {
        "uuid": 61247344,
        "ruc": "0952615177001",
        "name": "EMPRESA CONFIGURADA S.A.",
        "commercial_name": "EMPRESA CONFIGURADA",
        "has_configured": true,
        "configuration_completed_at": "2024-01-15T10:30:00Z",
        "status_process": "active",
        "next_steps": [
            "Configurar establecimientos",
            "Crear puntos de emisión",
            "Realizar primera facturación"
        ]
    }
}

Ejemplos de Código

curl -X POST \
  {{apiFacEcDev}}/api/v1/companies/complete-configuration \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {{bearerToken}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_id": "61247344",
    "confirm_configuration": true,
    "terms_accepted": true,
    "notifications_enabled": true
}'

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'Authorization' => 'Bearer ' . $bearerToken,
    'Accept' => 'application/json',
])->post($apiUrl . '/api/v1/companies/complete-configuration', [
    'account_id' => '61247344',
    'confirm_configuration' => true,
    'terms_accepted' => true,
    'notifications_enabled' => true
]);

$data = $response->json();

const axios = require('axios');

const completeConfiguration = async (accountId) => {
    try {
        const response = await axios.post(
            `${apiUrl}/api/v1/companies/complete-configuration`,
            {
                account_id: accountId,
                confirm_configuration: true,
                terms_accepted: true,
                notifications_enabled: true
            },
            {
                headers: {
                    'Authorization': `Bearer ${bearerToken}`,
                    'Content-Type': 'application/json',
                    'Accept': 'application/json'
                }
            }
        );

        console.log('Configuración completada:', response.data);
        return response.data;
    } catch (error) {
        console.error('Error:', error.response.data);
        throw error;
    }
};

Validaciones Avanzadas

Validación de RUC

const validateRUC = (ruc) => {
    // Validación básica de RUC ecuatoriano
    if (!/^\d{13}$/.test(ruc)) {
        throw new Error('RUC debe tener 13 dígitos');
    }

    // Validación de dígito verificador
    const digits = ruc.split('').map(Number);
    const coefficients = [2, 1, 2, 1, 2, 1, 2, 1, 2];

    let sum = 0;
    for (let i = 0; i < 9; i++) {
        let product = digits[i] * coefficients[i];
        if (product >= 10) {
            product = Math.floor(product / 10) + (product % 10);
        }
        sum += product;
    }

    const checkDigit = (10 - (sum % 10)) % 10;
    return checkDigit === digits[9];
};

Validación de Ambiente

class EnvironmentValidator
{
    const VALID_ENVIRONMENTS = ['TEST', 'PRODUCTION'];

    public static function validate($environment)
    {
        if (!in_array($environment, self::VALID_ENVIRONMENTS)) {
            throw new InvalidArgumentException(
                'Ambiente debe ser TEST o PRODUCTION'
            );
        }

        return true;
    }
}

Códigos de Respuesta

200 OK: Operación exitosa
201 Created: Configuración creada exitosamente
400 Bad Request: Datos inválidos en la solicitud
401 Unauthorized: Token de autorización inválido
404 Not Found: Cuenta no encontrada
422 Unprocessable Entity: Error de validación en los datos
500 Internal Server Error: Error interno del servidor

Mejores Prácticas

🔐 Seguridad

Valide todos los datos antes del envío
Use conexiones HTTPS exclusivamente
Implemente rate limiting para prevenir abuso
Registre todas las operaciones para auditoría

⚡ Rendimiento

Implemente caché para datos frecuentemente accedidos
Use paginación para listados extensos
Optimice consultas a base de datos
Considere operaciones asíncronas para procesos largos

🔄 Manejo de Errores

Implemente reintentos con backoff exponencial
Proporcione mensajes de error descriptivos
Registre errores para análisis posterior
Implemente circuit breakers para servicios externos

📊 Monitoreo

Registre métricas de rendimiento
Monitoree tasas de error
Implemente alertas para operaciones críticas
Use logging estructurado

Casos de Uso Específicos

📋 Migración de Datos

const migrateCompanyData = async (companies) => {
    const results = [];

    for (const company of companies) {
        try {
            // Validar datos antes de migración
            validateCompanyData(company);

            // Actualizar cuenta
            const result = await updateAccount(company);

            // Completar configuración si es necesario
            if (!result.payload.has_configured) {
                await completeConfiguration(company.account_id);
            }

            results.push({ success: true, company: company.name });
        } catch (error) {
            results.push({
                success: false,
                company: company.name,
                error: error.message
            });
        }
    }

    return results;
};

🔄 Sincronización Automática

class CompanySync
{
    public function syncWithExternalSystem($accountId)
    {
        try {
            // Obtener datos del sistema externo
            $externalData = $this->getExternalData($accountId);

            // Mapear datos al formato de la API
            $mappedData = $this->mapExternalData($externalData);

            // Actualizar cuenta
            $response = $this->updateAccount($mappedData);

            Log::info("Cuenta {$accountId} sincronizada exitosamente");

            return $response;
        } catch (Exception $e) {
            Log::error("Error sincronizando cuenta {$accountId}: {$e->getMessage()}");
            throw $e;
        }
    }
}

Notas Importantes

RUC: Debe ser válido según algoritmo de verificación ecuatoriano
Ambiente: Solo se permiten valores “TEST” y “PRODUCTION”
RIMPE: Régimen Impositivo para Microempresas (0 = No, 1 = Sí)
Moneda: Actualmente soporta “DOLAR” y “PESO”
Configuración: Una vez completada, algunos campos no pueden modificarse
Auditoría: Todas las operaciones quedan registradas en logs del sistema
Validaciones: Se aplican reglas fiscales ecuatorianas en tiempo real