Gestión de Pagos

Pruebas
Producción

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

Este módulo permite gestionar los pagos asociados a los documentos del sistema de facturación electrónica.

Endpoints

Actualizar Pagos de Documento

PUT /api/v1/documents/{id}/update-payments

Actualiza los pagos asociados a un documento específico.

Headers Requeridos

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

Parámetros de Ruta

Parámetro	Tipo	Descripción
`id`	string	ID del documento al cual actualizar los pagos

Cuerpo de la Solicitud

{
    "id": "948924864",
    "payments": [
        {
            "amount": "12.2",
            "code": "01"
        },
        {
            "amount": "30.34",
            "code": "01"
        }
    ]
}

Respuesta Exitosa (200 OK)

{
    "message": "Documento actualizado",
    "status": "UPDATED",
    "payload": true
}

Ejemplos de Implementación

curl -X PUT "https://dev-facturacion.e-dinky.test/api/v1/documents/948924864/update-payments" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "id": "948924864",
    "payments": [
      {
        "amount": "12.2",
        "code": "01"
      },
      {
        "amount": "30.34",
        "code": "01"
      }
    ]
  }'

<?php

use Illuminate\Support\Facades\Http;

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

$response = Http::withHeaders([
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer ' . $token,
])->put("https://dev-facturacion.e-dinky.test/api/v1/documents/{$documentId}/update-payments", [
    'id' => $documentId,
    'payments' => [
        [
            'amount' => '12.2',
            'code' => '01'
        ],
        [
            'amount' => '30.34',
            'code' => '01'
        ]
    ]
]);

if ($response->successful()) {
    $result = $response->json();
    echo "Estado: " . $result['status'];
    echo "Mensaje: " . $result['message'];
    echo "Actualizado: " . ($result['payload'] ? 'Sí' : 'No');
} else {
    echo "Error: " . $response->body();
}

const axios = require('axios');

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

    const config = {
        method: 'put',
        url: `https://dev-facturacion.e-dinky.test/api/v1/documents/${documentId}/update-payments`,
        headers: {
            'Content-Type': 'application/json',
            'Accept': 'application/json',
            'Authorization': `Bearer ${token}`
        },
        data: {
            id: documentId,
            payments: [
                {
                    amount: '12.2',
                    code: '01'
                },
                {
                    amount: '30.34',
                    code: '01'
                }
            ]
        }
    };

    try {
        const response = await axios(config);
        console.log('Estado:', response.data.status);
        console.log('Mensaje:', response.data.message);
        console.log('Actualizado:', response.data.payload ? 'Sí' : 'No');
        return response.data;
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
        throw error;
    }
};

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

Listar Todos los Pagos

GET /api/v1/payments

Obtiene la lista de todos los pagos del sistema.

Headers Requeridos

Accept: application/json
Authorization: Bearer {token}

Respuesta Exitosa (200 OK)

{
    "message": "Pagos obtenidos exitosamente",
    "status": "SUCCESS",
    "payload": {
        "data": [
            {
                "id": 1,
                "document_id": "948924864",
                "amount": "12.20",
                "method": "SIN UTILIZACIÓN DEL SISTEMA FINANCIERO",
                "code": "01",
                "date": "2024-10-27",
                "transaction_id": null,
                "status": "completed"
            }
        ],
        "pagination": {
            "current_page": 1,
            "per_page": 15,
            "total": 1,
            "last_page": 1
        }
    }
}

Ejemplos de Implementación

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

<?php

use Illuminate\Support\Facades\Http;

$token = 'your-api-token';

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

if ($response->successful()) {
    $result = $response->json();
    echo "Estado: " . $result['status'];
    echo "Mensaje: " . $result['message'];
    echo "Total de pagos: " . $result['payload']['pagination']['total'];

    foreach ($result['payload']['data'] as $payment) {
        echo "ID: " . $payment['id'];
        echo "Documento: " . $payment['document_id'];
        echo "Monto: $" . $payment['amount'];
        echo "Método: " . $payment['method'];
        echo "Fecha: " . $payment['date'];
        echo "Estado: " . $payment['status'];
        echo "---";
    }
} else {
    echo "Error: " . $response->body();
}

const axios = require('axios');

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

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

    try {
        const response = await axios(config);
        console.log('Estado:', response.data.status);
        console.log('Mensaje:', response.data.message);
        console.log('Total de pagos:', response.data.payload.pagination.total);

        response.data.payload.data.forEach(payment => {
            console.log('ID:', payment.id);
            console.log('Documento:', payment.document_id);
            console.log('Monto: $', payment.amount);
            console.log('Método:', payment.method);
            console.log('Fecha:', payment.date);
            console.log('Estado:', payment.status);
            console.log('---');
        });

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

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

Campos Requeridos

Actualizar Pagos

id: ID del documento (debe coincidir con el ID de la URL)
payments: Array de pagos a actualizar

Estructura de Pago

amount: Monto del pago (string con formato decimal)
code: Código del método de pago

Códigos de Métodos de Pago

Código	Descripción
`01`	SIN UTILIZACIÓN DEL SISTEMA FINANCIERO
`15`	COMPENSACIÓN DE DEUDAS
`16`	TARJETA DE DÉBITO
`17`	DINERO ELECTRÓNICO
`18`	TARJETA PREPAGO
`19`	TARJETA DE CRÉDITO
`20`	OTROS CON UTILIZACIÓN DEL SISTEMA FINANCIERO
`21`	ENDOSO DE TÍTULOS

Respuestas de Error

422 - Error de Validación

{
    "message": "El total no puede superar los $42.54 del documento, valor calculado [64.4]",
    "status": "ERROR",
    "payload": null,
    "error": "El total no puede superar los $42.54 del documento, valor calculado [64.4]"
}

404 - Documento No Encontrado

{
    "message": "Documento no encontrado",
    "status": "ERROR",
    "payload": null,
    "error": "El documento especificado no existe"
}

Validaciones Importantes

Total de Pagos: La suma de todos los pagos no puede superar el total del documento
ID Coincidente: El ID en la URL debe coincidir con el ID en el cuerpo de la solicitud
Formato de Monto: Los montos deben ser strings con formato decimal válido
Código de Pago: Debe ser un código válido según la tabla SRI
Autorización: Se requiere token de autenticación válido

Estados de Pago

Estado	Descripción
`pending`	Pago pendiente de procesamiento
`completed`	Pago completado exitosamente
`failed`	Pago fallido
`cancelled`	Pago cancelado

Códigos de Error Comunes

Código	Descripción
200	Pagos actualizados exitosamente
401	Token de autenticación inválido
404	Documento no encontrado
422	Error de validación (total excedido, formato inválido)
500	Error interno del servidor

Notas Importantes

Los pagos solo pueden actualizarse en documentos que no hayan sido enviados al SRI
El sistema valida automáticamente que la suma de pagos no exceda el total del documento
Se pueden registrar múltiples pagos para un mismo documento
Los códigos de método de pago deben cumplir con las regulaciones del SRI
Los montos deben especificarse como strings para mantener precisión decimal
El sistema mantiene un historial de todos los cambios en los pagos

Flujo Típico de Pagos

Crear Documento: Crear el documento con información básica
Registrar Pagos: Actualizar los pagos del documento usando este endpoint
Validación: El sistema valida que los pagos no excedan el total
Confirmación: Se confirma la actualización de pagos
Envío SRI: Una vez completados los pagos, el documento puede enviarse al SRI