Tesorería y Cuentas por pagar
Cuando desarrollas integraciones con la API de Duemint, es fundamental manejar correctamente los errores que pueden surgir.
La API utiliza un sistema estructurado de códigos de error que facilita identificar y gestionar problemas.
Estructura de los códigos de error
Un código de error en Duemint está compuesto por:
- Grupo de error → indica la categoría general del error.
- Entidad → especifica a qué parte del sistema corresponde.
La combinación de ambos define el código único de error.
Grupos de errores
Grupos principales:
10000 – NotFound: recurso no encontrado.20000 – Forbidden: solicitud entendida pero denegada.30000 – BadRequest: error en los parámetros enviados.40000 – Unauthorized: falta de permisos para acceder.50000 – InternalServerError: fallo interno del servidor.
Entidades de errores
Entidades de errores — Tesorería y Cuentas por Pagar
| Entidad | Rango | Descripción |
|---|---|---|
| Auth | 100 | Autenticación y emisión/validación de tokens. |
| User | 200 | Gestión de usuarios (alta, estados, perfiles). |
| Company | 300 | Información y configuración de la compañía. |
| CompanyUser | 400 | Relación usuario–compañía, membresías y estados. |
| AccessRole | 500 | Roles de acceso disponibles en la plataforma. |
| Permission | 600 | Permisos finos asociados a roles/usuarios. |
| KYC | 700 | Verificación de identidad y cumplimiento (KYC). |
| Wallet | 800 | Billeteras: creación, saldos, restricciones. |
| Payment | 900 | Pagos salientes (payouts) y su ciclo de vida. |
| Transaction | 1000 | Movimientos contables/financieros asociados. |
| File | 1100 | Subida, lectura y validación de archivos. |
| Recipient | 1200 | Destinatarios (personas/empresas) de pagos. |
| RecipientAccount | 1300 | Cuentas bancarias o destino del destinatario. |
| Approval | 1400 | Procesos de aprobación de operaciones. |
| ApprovalUser | 1500 | Participación de usuarios en aprobaciones. |
| ApprovalSignature | 1600 | Firmas requeridas y validaciones de firma. |
| ApprovalOperation | 1700 | Operaciones sujetas a aprobación. |
| ApprovalFlow | 1800 | Definición y ejecución de flujos de aprobación. |
| Card | 1900 | Tarjetas (emisión, validación, límites). |
| Charges | 2000 | Cargos/comisiones y su liquidación. |
| Income | 2100 | Ingresos (payments in) y conciliación. |
| Notification | 2200 | Notificaciones internas/salientes. |
| NotificationEnvelope | 2300 | Estructura y empaquetado de notificaciones. |
| NotificationConfiguration | 2400 | Preferencias y canales de notificación. |
| PSPIntegration | 2500 | Integración con proveedores de pago (PSP). |
| Security | 2600 | Controles de seguridad, firmas y políticas. |
| Subscription | 2700 | Suscripciones/planes y facturación asociada. |
| Webhook | 2800 | Entrega y validación de webhooks. |
| Register | 2900 | Alta/registro inicial de usuarios/empresas. |
| RegisterInvitation | 3000 | Invitaciones de registro y su gestión. |
| BankIntegration | 3100 | Conexiones bancarias y errores de canal. |
| Shinkansen | 3200 | Orquestación/colas internas (motor Shinkansen). |
| ChargesIntent | 3300 | Intentos de cobro (charge intents) y validaciones. |
| PaymentMethod | 3400 | Métodos de pago admitidos y estados. |
| AutoWithdrawal | 3500 | Retiros automáticos/automatizados. |
| Integration | 3600 | Integraciones de API y credenciales. |
| Credential | 3700 | Credenciales/secretos y su ciclo de vida. |
| AssignableDocument | 3800 | Documentos asignables (asociaciones/etiquetas). |
| PayableDocument | 3900 | Documentos por pagar (CxP) y validaciones. |
| PayableProvider | 4000 | Proveedores de CxP y su vinculación. |
| BankAccountIntegration | 4100 | Vinculación de cuentas bancarias externas. |
| BankPayment | 4200 | Ejecución de pagos bancarios (transferencias). |
| Client | 4300 | Clientes (CRM) y estados relacionados. |
| Contact | 4400 | Contactos y datos de contacto. |
| AuxInvoice | 4500 | Facturas auxiliares (importadas/temporales). |
| InvoiceImport | 4600 | Importación de facturas y validaciones. |
| Field | 4700 | Campos personalizados definidos por el usuario. |
| FieldOpt | 4800 | Opciones de campos personalizados. |
| FieldEntity | 4900 | Asociación campo ↔ entidad. |
| FieldOptEntity | 5000 | Asociación opción ↔ entidad. |
| PaymentImport | 5100 | Importación de |
| Invoice | 5300 | Facturas y su gestión. |
| Division | 5400 | Divisiones de negocio. |
| Role | 5600 | Roles organizacionales y su asignación. |
| PayrollTemplate | 5700 | Plantillas de nómina y configuraciones. |
| FintocLink | 5800 | Enlaces de integración y sincronización bancaria. |
| TimeZone | 5900 | Husos horarios y conversión de fechas. |
| WalletRequest | 6000 | Solicitudes sobre billetera. |
| Industry | 6100 | Clasificación industrial de la empresa. |
| EconomicActivity | 6200 | Actividades económicas (giros). |
| Restriction | 6300 | Limitaciones operativas. |
| WalletCard | 6400 | Tarjetas asociadas a la billetera. |
| BankCard | 6500 | Tarjetas bancarias. |
| WalletTicket | 6600 | Tickets de wallet (internos). |
| BankTicket | 6700 | Tickets bancarios (externos). |
💡 Duemint define 67 entidades para clasificar errores. Úsalas como referencia en integraciones de Tesorería y Cuentas por Pagar.
Ejemplo de código de error:
Un error en pagos podría verse así:
- Error: payment-invalid-due-date-card
- Grupo: Forbidden (20000)
- Entidad: Payment (900)
- Código específico: 2
- Código completo: 20902
Respuesta de error en la API
Ejemplo en JSON:
{
"errorCode": 20902,
"description": "Payment Invalid Due Date Card",
"details": "parámetro específico con error"
}Buenas prácticas
- Valida entradas: revisa los datos antes de enviarlos para evitar errores de
BadRequest. - Gestiona respuestas: implementa lógica para manejar cada tipo de error; muestra mensajes claros o intenta recuperación automática.
- Registra errores: mantén logs para diagnóstico y soporte.
- Reintentos inteligentes: usa backoff exponencial para errores de red temporales.
- Seguridad: no expongas detalles internos al usuario final; guarda la información sensible en el servidor.
Updated about 1 month ago