API de liquidaciones

Revise liquidaciones mensuales, partidas e impugne discrepancias. Leer exige settlement:read; impugnar, settlement:dispute. Al manejar datos reales, solo acepta claves Production nsp_live_; Sandbox devuelve 403 production_key_required. El socio ve estados desde pending_review; draft y calculated internos quedan ocultos.

Endpoints

Método	Ruta	Ámbito	Finalidad
GET	`/settlements`	`settlement:read`	Lista liquidaciones filtrables por status y updated_since.
GET	`/settlements/{id}`	`settlement:read`	Detalle de liquidación.
GET	`/settlements/{id}/items`	`settlement:read`	Partidas por título, episodio y país.
POST	`/settlements/{id}/dispute`	`settlement:dispute`	Abre una impugnación.

Lista y detalle

curl "https://signal-partners.newunivers.ai/v1/settlements?status=approved&updated_since=2026-05-01T00:00:00Z" \
  -H "Authorization: Bearer nsp_live_xxx" -H "X-NU-Partner-Id: org_acme"

{
  "data": [
    {
      "settlement_id": "stl_2026_05",
      "period": "2026-05",
      "currency": "USD",
      "gross_revenue": 120000.00,
      "net_revenue": 76100.00,
      "nu_share": 49465.00,
      "partner_share": 26635.00,
      "status": "approved",
      "updated_at": "2026-06-24T00:00:00Z"
    }
  ]
}

La lista devuelve un resumen por liquidación. Consulte una para ver todas las deducciones.

{
  "data": {
    "settlement_id": "stl_2026_05",
    "period": "2026-05",
    "currency": "USD",
    "gross_revenue": 120000.00,
    "refunds": 1500.00,
    "platform_fee": 12000.00,
    "payment_processing_fee": 3400.00,
    "tax_withholding": 2000.00,
    "mg_recouped": 25000.00,
    "net_revenue": 76100.00,
    "nu_share": 49465.00,
    "partner_share": 26635.00,
    "rights_holder_share": 0.00,
    "status": "approved",
    "updated_at": "2026-06-24T00:00:00Z"
  }
}

Campos de liquidación

Campo	Significado
`gross_revenue`	Ingresos brutos de eventos elegibles
`refunds`	Reversiones de eventos de ingreso negativo
`platform_fee`	Tarifa de plataforma NU
`payment_processing_fee`	Costes de procesamiento
`tax_withholding`	Impuestos retenidos
`mg_recouped`	Garantía mínima recuperada en el periodo
`net_revenue`	Ingreso tras reembolsos, comisiones, impuestos y MG
`nu_share / partner_share`	Distribución de net_revenue según el reparto
`rights_holder_share`	Parte del titular de derechos sobre net_revenue; solo en detalle

Los campos de deducción (refunds, platform_fee, payment_processing_fee, tax_withholding, mg_recouped y rights_holder_share) solo aparecen en detalle, no en lista.

period usa el formato YYYY-MM.

Partidas de liquidación

curl "https://signal-partners.newunivers.ai/v1/settlements/stl_2026_05/items" \
  -H "Authorization: Bearer nsp_live_xxx" -H "X-NU-Partner-Id: org_acme"

{
  "data": [
    {
      "settlement_item_id": "sti_001",
      "title_id": "ttl_abc",
      "episode_id": "ep_001",
      "country": "KR",
      "revenue_type": "payment_completed",
      "gross_revenue": 4200.00,
      "net_revenue": 2730.00,
      "nu_share": 1774.50,
      "partner_share": 955.50,
      "rights_holder_share": 0.00
    }
  ]
}

Las partidas desglosan por title_id, episode_id, country y revenue_type para conciliar con sus eventos.

Flujo de impugnación

Solo puede impugnarse en pending_review, approved o invoiced antes del vencimiento. Otros estados devuelven 409 settlement_not_disputable.

curl -X POST "https://signal-partners.newunivers.ai/v1/settlements/stl_2026_05/dispute" \
  -H "Authorization: Bearer nsp_live_xxx" \
  -H "X-NU-Partner-Id: org_acme" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "KR PAYMENT_COMPLETED count differs from our ledger by ~3%",
    "disputed_amount": 820.00,
    "currency": "USD"
  }'

{
  "data": {
    "dispute_id": "dsp_001",
    "settlement_id": "stl_2026_05",
    "status": "open",
    "reason": "KR PAYMENT_COMPLETED count differs from our ledger by ~3%"
  }
}

NU revisa la impugnación y puede aplicar un ajuste posterior.

Mantener sincronización (polling)

No hay webhooks. Sondee GET /v1/settlements con updated_since y opcionalmente status para obtener liquidaciones nuevas o cambiadas. Cada elemento incluye updated_at como cursor.

curl "https://signal-partners.newunivers.ai/v1/settlements?updated_since=2026-06-01T00:00:00Z" \
  -H "Authorization: Bearer nsp_live_xxx" -H "X-NU-Partner-Id: org_acme"