Recursos para IA
Posibles errores
Al integrar Split de Pagos 1:N, la API puede devolver errores de validación con códigos y mensajes específicos. A continuación se describen los errores por tema y el formato de respuesta.
Todas las validaciones se realizan en secuencia; la primera validación que falla detiene el proceso.
Mapeo de códigos de error
Los errores utilizan tipos base que se traducen en códigos de estado HTTP:
| Tipo de error base | Código de estado HTTP | Descripción |
| TypeErrorClient | 400 | Bad Request. Errores del cliente con mensajes específicos para problemas corregibles. |
| TypeErrorInvalidInput | 400 | Bad Request. Datos de entrada inválidos. |
| TypeErrorUnprocessable | 422 | Unprocessable Entity. Errores de validación (validación de usuario, validación de compliance). Se utiliza para distinguir estos errores de los errores del cliente (400). |
| TypeErrorNotFound | 404 | Not Found. Recurso no encontrado. |
| TypeErrorInternal | 500 | Internal Server Error. Errores del lado del servidor. |
| TypeErrorUnavailable | 503 | Service Unavailable. Se devuelve cuando los servicios externos (Búsqueda de Usuarios, KYC) no están disponibles. |
Validaciones de receptores
Validaciones relacionadas con los receptores (vendedores) en el split.
| Nombre de validación | Código de error | Estado HTTP | Mensaje de error | Descripción |
| Falta receptor primario | TypeErrorClient | 400 | "primary receiver must be present in the split" | Al menos un receptor debe estar marcado como primario (generalmente el vendedor que inició el split). El receptor primario (vendedor primario) es el dueño de la aplicación usada en la integración. |
| Mínimo de receptores secundarios | TypeErrorClient | 400 | "minimum of 1 secondary receiver is required" | Se requiere al menos un receptor secundario. |
| Receptores duplicados | TypeErrorClient | 400 | "there are users duplicated" | Ningún ID de usuario puede aparecer más de una vez en la lista de receptores. |
| Límite de vendedores excedido | TypeErrorClient | 400 | "split contains more sellers than allowed" | El número total de receptores no puede exceder el máximo configurado (cuando MaxSplitSellers está configurado). El máximo permitido es de 10 vendedores secundarios por order. |
Validaciones de monto
Validaciones para montos del split. Algunas se aplican solo a splits por porcentaje y otras solo a splits fijos.
| Nombre de validación | Código de error | Estado HTTP | Mensaje de error | Descripción |
| Rango de porcentaje inválido | TypeErrorClient | 400 | "percentage must be between 1 and 100" | El porcentaje de cada receptor debe estar entre 1 y 100 (solo para splits por porcentaje). |
| Suma de porcentaje inválida | TypeErrorClient | 400 | "percentages must add up to 100.00" | La suma de todos los porcentajes de los receptores debe ser exactamente 100.00 (solo para splits por porcentaje). |
| Suma de monto fijo inválida | TypeErrorClient | 400 | "the sum of the amounts for the receivers must be equal to the total amount of the split" | La suma de todos los montos de los receptores debe ser igual al monto total del split (solo para splits fijos). |
Validaciones de pago
Validaciones que se aplican a los métodos de pago.
| Nombre de validación | Código de error | Estado HTTP | Mensaje de error | Descripción |
| Tipo de método de pago inválido | TypeErrorClient | 400 | "invalid payment method type" | El tipo de método de pago debe estar en la lista permitida configurada en el sistema. Los medios de pago permitidos son tarjeta de crédito y débito. |
Validaciones de ítems
Validaciones que solo aplican cuando el split incluye ítems.
| Nombre de validación | Código de error | Estado HTTP | Mensaje de error | Descripción |
| Códigos externos de ítems duplicados | TypeErrorClient | 400 | "items list contains duplicate external code" | No puede haber dos ítems con el mismo external_code. |
| Referencia de ítem inválida | TypeErrorClient | 400 | "receiver references non-existent item" | Todas las referencias de ítems en los receptores deben corresponder a ítems existentes en el split. |
Validaciones de usuario
Validaciones externas realizadas contra el servicio de Búsqueda de Usuarios.
| Nombre de validación | Código de error | Estado HTTP | Mensaje de error | Descripción |
| Usuario no encontrado | TypeErrorUnprocessable | 422 | "user validation error" | El ID de usuario no existe en el sistema (el servicio de usuario devuelve 404). |
| Usuario no activo | TypeErrorUnprocessable | 422 | "user validation error" | El usuario existe, pero no está en estado "activo" (guest, deactive, pending o vacío). |
| Sitio del usuario no coincide | TypeErrorUnprocessable | 422 | "user validation error" | El ID del sitio del usuario no coincide con el ID del sitio del vendedor. |
| Servicio de usuario no disponible | TypeErrorUnavailable | 503 | "service unavailable" | Errores de red o timeout al llamar al servicio de usuario. |
| Vendedor usando modo PNF | TypeErrorUnprocessable | 422 | "seller is using pnf mode, blocked" | Se bloquea la transacción si el vendedor está operando en modo PNF (Pago No Flujo). |
Validaciones de cumplimiento KYC
Validaciones externas realizadas contra el servicio de Cumplimiento KYC.
| Nombre de validación | Código de error | Estado HTTP | Mensaje de error | Descripción |
| Fallo de verificación de cumplimiento KYC | TypeErrorUnprocessable | 422 | "compliance validation error" | El usuario no cumple (el estado no es "compliant" ni "skip_compliance"). |
| Servicio KYC no disponible | TypeErrorUnavailable | 503 | "service unavailable" | Errores de red o timeout al llamar al servicio de KYC. |
Errores internos
| Nombre de validación | Código de error | Estado HTTP | Mensaje de error | Descripción |
| Error interno del servidor | TypeErrorInternal | 500 | "internal server error" | Error inesperado del lado del servidor. |
Formato de respuesta de error
Los errores retornan en el siguiente formato, con el campo errors como array (puede estar vacío cuando el contexto del error está descrito en el message principal):
Error del cliente (400)
json
{ "status": 400, "message": "percentages must add up to 100.00", "errors": [] }
Error de validación (422)
json
{ "status": 422, "message": "user validation error", "errors": [] }
Servicio no disponible (503)
json
{ "status": 503, "message": "service unavailable", "errors": [] }
Error interno (500)
json
{ "status": 500, "message": "internal server error", "errors": [] }