Saltar al contenido principal

Creación de movimientos

En esta página encontrarás una explicación sobre la creación de movimientos en la API de Koncili.

El proceso completo de conciliación financiera implica 3 etapas principales que garantizan la trazabilidad y la precisión de los movimientos:

1. Envío del pedido​

Envío inicial de la transacción con todos los detalles financieros. Esta etapa registra los componentes financieros extracts (tipos aceptados: COMISSION, SHIP, RETURN_COMISSION, RETURN_SHIP y SALE) que se conciliarán después.

2. Envío de la liquidación​

Agrupación lógica de múltiples pedidos para procesamiento por lotes. Define el período financiero y prepara el sistema para recibir los movimientos.

3. Ejecución de los movimientos​

Envío completo obligatorio

Todos los componentes financieros de un pedido deben enviarse en una única solicitud. No es posible agregar movimientos parciales o complementarios después.

Regla fundamental: Los movimientos financieros (releases) deben reproducir exactamente los valores y tipos prerregistrados en el pedido (extracts), manteniendo el identificador único (marketplaceCode).

Tipos de movimientos admitidos​

Los tipos de movimientos admitidos se detallan en la lista completa de tipos de movimientos. Los tipos principales incluyen:

  • SALE: Monto bruto de las ventas (siempre positivo)
  • COMISSION: Tarifas de comisión (siempre negativo)
  • SHIP: Costos de envío (positivo o negativo)
  • RETURN_COMISSION: Reversión de comisiones (siempre positivo)

Flujo completo: Pedido → Conciliación → Movimientos​

1. Envío del pedido​

El pedido contiene la estructura financiera completa a través del array extracts. Cada ítem representa un componente financiero distinto:

Pedido
{
  "marketplaceCode": "701-2798273-4005859",
  "channelName": "CHANNEL_NAME",
  "accountId": "19055",
  "status": "PAID_WAITING_DELIVERY",
  "createdDate": "2025-05-09T12:00:00Z",
  "approvedDate": "2025-05-09T12:00:00Z",
  "sendDate": "2025-05-09T12:00:00Z",
  "estimatedDeliveryDate": "2025-05-15T12:00:00Z",
  "deliveryDate": "2025-05-15T12:00:00Z",
  "cancelDate": null,
  "totalGrossValue": 203.63,
  // ... (se omitieron otros campos)
  "extracts": [
    {
      "marketplaceCode": "701-2798273-4005859",
      "type": "SALE",          // Venta bruta
      "value": 203.63,         // Siempre positivo
      "expectedDate": "2025-06-05T12:00:00Z"
    },
    {
      "marketplaceCode": "701-2798273-4005859",
      "type": "COMISSION",    // Tarifa de comisión
      "value": -24.44,         // Siempre negativo
      "percentage": 12         // 12% de comisión
    },
    {
      "marketplaceCode": "701-2798273-4005859",
      "type": "SHIP",          // Costo de envío
      "value": -27.95          // Negativo (costo)
    }
  ]
}

2. Envío de la liquidación​

La conciliación agrupa pedidos para procesamiento por lotes. El campo releasesQtd debe corresponder exactamente al número total de movimientos financieros de todos los pedidos incluidos:

Conciliación
{
  "channelName": "CHANNEL_NAME",
  "accountId": 19055,
  "periodInitDate": "2024-02-14T01:00:01Z",   // Inicio del período
  "periodEndDate": "2024-02-15T01:00:01Z",    // Fin del período
  "releasesQtd": 3,                           // Cantidad de movimientos financieros incluidos
  "totalNetValue": 203.63                     // Monto neto total de la conciliación
}

El envío de la liquidación debe devolver un JSON similar a este (el id devuelto es el reconciliationId):

Respuesta del envío
{
    "id": 237    // ID único de la conciliación
}
Importante

Se envía la cantidad de releases para un solo movimiento a la vez.

  • El reconciliationId devuelto es obligatorio para los movimientos
  • El período debe cubrir todas las fechas de releasedDate de los movimientos
  • El releasesQtd debe ser la suma exacta de todos los movimientos que se enviarán

3. Envío de movimiento​

Movimientos
{
  "reconciliationId": 237,
  "channelName": "CHANNEL_NAME",
  "accountId": 19055,
  "marketplaceCode": "701-2798273-4005859",
  "status": "CONCLUDED",
  "createdDate": "2024-02-10T12:12:12Z",
  "releasedDate": "2024-02-10T13:13:13Z",
  "releaseType": "IN_CASH",
  "installment": 1,
  "installmentQuantity": 1,
  "releases": [
    {
      "marketplaceCode": "701-2798273-4005859",
      "type": "SALE",
      "value": 203.63
      },
      {
      "marketplaceCode": "701-2798273-4005859",
      "type": "COMISSION",
      "value": -24.44
      },
      {
      "marketplaceCode": "701-2798273-4005859",
      "type": "SHIP",
      "value": -27.95
      }
  ]
}

Principio de reproducción de los movimientos​

  1. Correspondencia exacta de tipos: Los tipos en releases deben ser idénticos a los registrados en extracts
  2. Consistencia de valores: Los valores deben ser idénticos a los del prerregistro
  3. Misma cantidad: El número de ítems en releases debe ser igual al número de extracts
  4. Mismo marketplaceCode: El identificador único debe mantenerse en todos los niveles

Validación de errores comunes​

Validaciones automáticas​

Los campos mal formados en el payload de cualquier solicitud de los procesos mencionados se presentarán en la respuesta, con mensajes de error específicos y estado HTTP 400 (Bad Request).

Buenas prácticas de implementación​

  1. Mantén los valores originales:
    Nunca recalcules valores: usa exactamente los mismos valores del pedido original.

  2. Conserva el orden:
    Mantén la misma secuencia de movimientos entre el pedido y la conciliación.

  3. Valida con anticipación:
    Verifica los tipos de movimientos admitidos por el marketplace antes del envío.

  4. Gestiona los períodos:
    Asegúrate de que todas las fechas de los movimientos estén dentro del período definido en la conciliación.