Integrar Partner API

Esta guía está dirigida al equipo de desarrollo y arquitectura de Wuzi que se integrará directamente con la plataforma a través de la Partner API (partner-integration-api).

La Partner API es una capa unificada y estable de integración externa que consolida las operaciones de comercios, afiliaciones a procesadores, consulta de transacciones, contracargos y liquidaciones sin exponer directamente los microservicios internos del cluster.

1. Arquitectura y Flujo de Integración

El flujo de comunicación opera estrictamente de servidor a servidor (Backend-to-Backend):

Frontend / Apps Wuzi  ──►  Backend Wuzi  ──►  Partner Integration API  ──►  Servicios Internos Payment Nexus

Comunicación segura

Las peticiones deben originarse siempre desde los servidores de Wuzi. Nunca llames a la Partner API directamente desde un navegador web o aplicación móvil cliente para evitar la exposición del token de integración.

2. Ambientes y URLs Base

Ambiente	Host / URL Base
Dev / Staging	`https://dev-partner-api-wuzi.paymentnexus.com.mx`
Producción	`https://partner-api-wuzi.paymentnexus.com.mx`

3. Autenticación y Seguridad

Todas las peticiones a la API deben incluir el encabezado HTTP Authorization con un Bearer Token estático aprovisionado para el partner:

Authorization: Bearer <TU_PARTNER_TOKEN>
Content-Type: application/json

Control de Alcance (Tenant y Merchant Scoping)

Cada token de partner está vinculado a un perfil que delimita:

Los tenant_ids autorizados (por ejemplo, tenant_wuzi).
Los merchant_ids permitidos (o * para todos los comercios del tenant).

Si intentas consultar o modificar un recurso fuera del alcance autorizado, la API rechazará la petición con un error 403 Forbidden.

4. Convenciones Generales de la API

Formato: JSON en todas las peticiones y respuestas (Content-Type: application/json).
Montos: Siempre números enteros en unidades menores (centavos). Nunca utilices números flotantes o decimales en valores monetarios.
- Ejemplo: $150.00 MXN se envía y recibe como 15000.
Moneda: Operaciones en MXN.
Fechas y Tiempos: Formato estándar ISO 8601 / RFC 3339 en UTC (YYYY-MM-DDTHH:MM:SSZ).
Estructura Envelope: Todas las respuestas exitosas siguen una estructura unificada:
```
{
  "data": { ... },
  "meta": { ... }
}
```
(En consultas de listados, data es un arreglo []).

5. Gestión de Comercios (Merchants)

A. Crear Comercio Unificado

Crea la identidad base del comercio en la plataforma junto con su perfil enriquecido y sus afiliaciones iniciales.

Método: POST
Ruta: /v1/merchants
Headers: Authorization: Bearer <TOKEN>, Content-Type: application/json

Ejemplo de Solicitud (Request Body):

{
  "merchant_id": "comercio_wuzi_001",
  "tenant_id": "tenant_wuzi",
  "name": "Tienda Wuzi Reforma",
  "status": "active",
  "profile": {
    "environment": "production",
    "business_line": "retail",
    "phone": "5555555555",
    "email": "operaciones@tiendawuzi.mx",
    "support_email": "soporte@tiendawuzi.mx",
    "mcc": "5999",
    "processing_config": {
      "tpv_passcode": "123456",
      "promotions": {
        "tpv": {
          "3": { "enabled": true, "rate": 0, "min_amount": 3000 },
          "6": { "enabled": true, "rate": 0, "min_amount": 5000 }
        }
      }
    }
  },
  "processor_affiliations": [
    {
      "channel": "tpv",
      "processor_code": "blumon-tpv",
      "affiliation_id": "AFI-BLUMON-001",
      "status": "active"
    }
  ]
}

Ejemplo de Respuesta (Response Body):

{
  "data": {
    "merchant_id": "comercio_wuzi_001",
    "tenant_id": "tenant_wuzi",
    "name": "Tienda Wuzi Reforma",
    "status": "active",
    "profile": {
      "business_line": "retail",
      "email": "operaciones@tiendawuzi.mx",
      "phone": "5555555555",
      "support_email": "soporte@tiendawuzi.mx",
      "mcc": "5999"
    },
    "created_at": "2026-09-18T20:00:00Z",
    "updated_at": "2026-09-18T20:00:00Z"
  }
}

B. Obtener Comercio

Consulta la información consolidada de un comercio.

Método: GET
Ruta: /v1/merchants/{merchant_id}?tenant_id={tenant_id}

C. Actualizar Comercio

Permite actualización parcial (patch/merge seguro). No necesitas enviar todo el documento, la Partner API se encarga de fusionar los cambios de forma consistente.

Método: PUT
Ruta: /v1/merchants/{merchant_id}

Ejemplo de Solicitud:

{
  "tenant_id": "tenant_wuzi",
  "name": "Tienda Wuzi Reforma Actualizada",
  "profile": {
    "phone": "5555559999",
    "support_email": "ayuda@tiendawuzi.mx"
  }
}

6. Afiliaciones a Procesadores

Concepto Clave

Un comercio no cuenta con un solo número de afiliación global. El modelo real de la plataforma soporta múltiples procesadores y canales. Por lo tanto, se gestiona una afiliación por cada combinación de (canal, procesador) (por ejemplo: una afiliación TPV para Blumon, otra TPV para Banorte, etc.).

A. Listar Afiliaciones de un Comercio

Método: GET
Ruta: /v1/merchants/{merchant_id}/processor-affiliations?tenant_id={tenant_id}

Ejemplo de Respuesta:

{
  "data": [
    {
      "tenant_id": "tenant_wuzi",
      "merchant_id": "comercio_wuzi_001",
      "channel": "tpv",
      "processor_code": "blumon-tpv",
      "affiliation_id": "AFI-BLUMON-001",
      "status": "active",
      "created_at": "2026-09-18T20:00:00Z",
      "updated_at": "2026-09-18T20:00:00Z"
    }
  ]
}

B. Crear o Actualizar Afiliación (Upsert)

Método: POST
Ruta: /v1/merchants/{merchant_id}/processor-affiliations?tenant_id={tenant_id}

Request Body:

{
  "channel": "tpv",
  "processor_code": "blumon-tpv",
  "affiliation_id": "AFI-BLUMON-002",
  "status": "active"
}

7. Catálogo y Descubrimiento Dinámico

Para evitar quemar en duro los procesadores en tu código, utiliza los endpoints de descubrimiento dinámico:

Endpoint	Descripción
`GET /v1/processors`	Catálogo global de procesadores y sus capacidades soportadas (`sync_payment`, `async_payment`, `refund`, etc.).
`GET /v1/channels`	Canales válidos de la plataforma (`tpv`, `ecommerce`, `link`, `moto`).
`GET /v1/merchants/{id}/available-processors?tenant_id={tenant_id}&channel=tpv`	Lista de procesadores disponibles y elegibles para un comercio específico en un canal determinado, indicando si ya tiene afiliación configurada o si cuenta con reglas de enrutamiento activas.

8. Transacciones y Reportería de Dashboard

Permite alimentar tu propio panel de control o sistema de reportería con datos procesados por el read-model de la plataforma.

A. Listar Transacciones

Método: GET
Ruta: /v1/transactions?tenant_id={tenant_id}&merchant_id={merchant_id}&limit=50&offset=0

Parámetros de Consulta (Query Params):

tenant_id (Obligatorio): ID del tenant (ej. tenant_wuzi).
merchant_id (Opcional): Filtrar por comercio.
transaction_id (Opcional): Filtrar por ID específico.
status (Opcional): approved, declined, cancelled, refunded, pending.
operation_type (Opcional): sale, refund, cancellation, etc.
channel (Opcional): tpv, ecommerce, link.
created_from / created_to (Opcional): Rango de fechas ISO 8601 UTC.
limit (Opcional): Cantidad de registros (default 50, máx 100).
offset (Opcional): Desplazamiento para paginación.

Ejemplo de Respuesta:

{
  "data": [
    {
      "transaction_id": "txn_a1b2c3d4e5",
      "tenant_id": "tenant_wuzi",
      "merchant_id": "comercio_wuzi_001",
      "terminal_id": "term_urovo_01",
      "operation_type": "sale",
      "channel": "tpv",
      "status": "approved",
      "amount": {
        "amount_minor": 15000,
        "currency": "MXN"
      },
      "processor_reference_id": "BLU-REF-998811",
      "fraud": {
        "final_decision": "approve",
        "plugin_enabled": true,
        "plugin_mode": "score",
        "plugin_decision": "approve",
        "plugin_score": 10
      },
      "fees": {
        "total_fee_minor": 450,
        "net_amount_minor": 14550
      },
      "created_at": "2026-09-18T18:30:00Z",
      "updated_at": "2026-09-18T18:30:05Z"
    }
  ],
  "meta": {
    "limit": 50,
    "offset": 0,
    "returned_count": 1,
    "total_count": 1,
    "has_next": false
  }
}

B. Detalle de Transacción

Método: GET
Ruta: /v1/transactions/{transaction_id}?tenant_id={tenant_id}

9. Contracargos y Disputas

Listar disputas:

GET /v1/disputes?tenant_id={tenant_id}&merchant_id={merchant_id}

Detalle de una disputa:

GET /v1/disputes/{dispute_id}?tenant_id={tenant_id}

10. Liquidaciones (Settlements)

Consultar historial de liquidaciones:

GET /v1/settlements?tenant_id={tenant_id}&merchant_id={merchant_id}

Previsualizar liquidación acumulada:

GET /v1/settlements/preview?tenant_id={tenant_id}&merchant_id={merchant_id}&currency=MXN&limit=100

11. Manejo de Errores

En caso de error, la API responde con códigos de estado estándar y un objeto descriptivo:

{
  "error": "descripción del error"
}

Código HTTP	Causa típica
`400 Bad Request`	Solicitud malformada, falta de parámetros requeridos o error de validación en el JSON.
`401 Unauthorized`	Token Bearer faltante, inválido o expirado.
`403 Forbidden`	El token no tiene permisos para acceder al `tenant_id` o `merchant_id` especificado.
`404 Not Found`	El recurso solicitado (comercio, transacción, disputa) no existe.
`500 / 503`	Error interno o servicio backend no disponible temporalmente.

12. Ejemplos Rápidos con cURL

# Variables de entorno
export BASE_URL="https://dev-partner-api-wuzi.paymentnexus.com.mx"
export TOKEN="tu_token_aqui"
export TENANT_ID="tenant_wuzi"

# 1. Healthcheck
curl -sS "$BASE_URL/health"

# 2. Consultar transacciones aprobadas recientes
curl -sS "$BASE_URL/v1/transactions?tenant_id=$TENANT_ID&status=approved&limit=10" \
  -H "Authorization: Bearer $TOKEN"

# 3. Consultar afiliaciones de un comercio
curl -sS "$BASE_URL/v1/merchants/comercio_wuzi_001/processor-affiliations?tenant_id=$TENANT_ID" \
  -H "Authorization: Bearer $TOKEN"

1. Arquitectura y Flujo de Integración​

2. Ambientes y URLs Base​

3. Autenticación y Seguridad​

Control de Alcance (Tenant y Merchant Scoping)​

4. Convenciones Generales de la API​

5. Gestión de Comercios (Merchants)​

A. Crear Comercio Unificado​

Ejemplo de Solicitud (Request Body):​

Ejemplo de Respuesta (Response Body):​

B. Obtener Comercio​

C. Actualizar Comercio​

Ejemplo de Solicitud:​

6. Afiliaciones a Procesadores​

A. Listar Afiliaciones de un Comercio​

Ejemplo de Respuesta:​

B. Crear o Actualizar Afiliación (Upsert)​

Request Body:​

7. Catálogo y Descubrimiento Dinámico​

8. Transacciones y Reportería de Dashboard​

A. Listar Transacciones​

Parámetros de Consulta (Query Params):​

Ejemplo de Respuesta:​

B. Detalle de Transacción​

9. Contracargos y Disputas​

10. Liquidaciones (Settlements)​

11. Manejo de Errores​

12. Ejemplos Rápidos con cURL​

1. Arquitectura y Flujo de Integración

2. Ambientes y URLs Base

3. Autenticación y Seguridad

Control de Alcance (Tenant y Merchant Scoping)

4. Convenciones Generales de la API

5. Gestión de Comercios (Merchants)

A. Crear Comercio Unificado

Ejemplo de Solicitud (Request Body):

Ejemplo de Respuesta (Response Body):

B. Obtener Comercio

C. Actualizar Comercio

Ejemplo de Solicitud:

6. Afiliaciones a Procesadores

A. Listar Afiliaciones de un Comercio

Ejemplo de Respuesta:

B. Crear o Actualizar Afiliación (Upsert)

Request Body:

7. Catálogo y Descubrimiento Dinámico

8. Transacciones y Reportería de Dashboard

A. Listar Transacciones

Parámetros de Consulta (Query Params):

Ejemplo de Respuesta:

B. Detalle de Transacción

9. Contracargos y Disputas

10. Liquidaciones (Settlements)

11. Manejo de Errores

12. Ejemplos Rápidos con cURL