Sincronización de Notas de Crédito

Sección para sincronizar notas de crédito (NC) desde el ERP externo. Las NCs son documentos contables y se diferencian de las devoluciones (returns), que son movimientos físicos.

Una NC puede o no requerir devolución física (requires_physical_return). Si la requiere, el ERP debe vincular la NC a una returns existente vía related_return_ref / related_return_code.

1. Crear / actualizar NC desde ERP

POST/transportes/sync/credit-notes

Crea una NC nueva o actualiza una existente. Idempotente por (tenant_id, source_system, source_id).

Reglas de matching

source_id + source_system: clave de idempotencia. Re-enviar el mismo par actualiza la NC existente y reemplaza sus líneas.
receipt_ref, receipt_id, receipt_code: al menos uno requerido para localizar la factura asociada. Búsqueda en orden: source_id+source_system, receipt_code, receipt_id numérico, receipt_code por fallback.
related_return_ref / related_return_code: si la NC implica devolución física, el backend localiza la returns correspondiente y persiste el cruce simétrico (returns.credit_note_id y credit_notes.related_return_id).
lines[*].product_code: requerido. receipt_line_id se resuelve por product_code contra la factura si no se envía.

Respuesta

200 OK

{
  "result": {
    "credit_note_id": "99"
  },
  "meta": {
    "route": "/transportes/sync/credit-notes",
    "method": "PostCreditNoteSync"
  }
}

credit_note_id es string (BigInt serializado).

2. Devoluciones vinculadas a NC

El endpoint existente POST /transportes/sync/returns ahora acepta vínculos opcionales con una NC.

POST/transportes/sync/returns

Sincroniza devoluciones físicas. Acepta vínculo con NC vía credit_note_ref o credit_note_code.

Si la NC no existe en el momento del sync, el campo se ignora; basta con re-enviar la NC después y se vinculará al re-procesar la devolución.

200 OK

{
  "result": 55,
  "meta": {
    "route": "/transportes/sync/returns",
    "method": "PostReturnSync",
    "upsert_action": "created",
    "credit_note_id": 99
  }
}

3. Lectura por ERP (polling / verificación)

GET/transportes/sync/credit-notes/getAll

Listado paginado de NCs sincronizadas. Acepta `page`, `page_size`, `searchQuery`, `source_system`.

GET/transportes/sync/credit-notes/{sourceId}

Detalle de una NC por su source_id externo.

Respuesta getAll:

200 OK

{
  "result": {
    "data": [
      {
        "credit_note_id": "99",
        "tenant_id": "340e4da8-42c1-44da-9285-7410402e1e32",
        "receipt_id": 1234,
        "credit_note_code": "NC-2026-0001",
        "source_id": "account.move:8821",
        "source_system": "odoo",
        "status_id": 2,
        "total_quantity": "5.00000000000000",
        "requires_physical_return": false,
        "related_return_id": null,
        "issued_at": "2026-04-28T15:00:00.000Z",
        "is_active": true
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 100
  }
}

4. Errores comunes

Código	Causa
`Receipt not found` (sync_missing_dependencies)	`receipt_ref`/`receipt_code` no resuelve a una factura activa. Reintentar tras sincronizar la factura.
`Validation error: lines is required.`	Body sin `lines` o array vacío.
`credit_notes_tenant_id_code_uk`	Conflicto de `credit_note_code`. Usar otro código o sobrescribir vía `source_id`.

5. Trazabilidad

Cada NC sincronizada actualiza credit_notes.last_event_at y conserva source_id + source_system para auditoría. Cuando se vincula a una devolución, ambas tablas reflejan el cruce y la incidencia de entrega asociada se evalúa automáticamente por el cron de auto-resolución.

Incidencias — resolución automática Consultas GET