Gestión de Referidos

Pruebas
Producción

Dominio: https://test-api-factura.edw-dev.com

Este módulo permite gestionar el sistema de referidos y licencias, incluyendo la solicitud, confirmación, consulta y cancelación de licencias de referidos.

Endpoints Disponibles

1. Solicitar Licencia de Referido

POST /api/v1/referral/request-licence

Permite solicitar una nueva licencia de referido.

Headers Requeridos

Accept: application/json
Authorization: Bearer {token}
Content-Type: application/json

Cuerpo de la Solicitud

{
  "plan_code": "REFERIDO--11",
  "new_amount": "30.00",
  "transaction_bank": "BANCO_PICHINCHA",
  "payment_method": "transaction",
  "count_allow": 1,
  "file": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
}

Parámetros Disponibles

Campo	Tipo	Requerido	Descripción
`plan_code`	string	Sí	Código del plan de referido
`new_amount`	string	Sí	Nuevo monto para la licencia
`transaction_bank`	string	Condicional	Banco para transferencia (requerido si payment_method es “transaction”)
`payment_method`	string	Sí	Método de pago: “transaction”, “card”, “crypto”
`count_allow`	integer	Sí	Número de activaciones permitidas
`file`	string	Condicional	Comprobante en base64 (requerido para transferencias)

Ejemplos de Implementación

curl -X POST "https://dev-facturacion.e-dinky.test/api/v1/referral/request-licence" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_code": "REFERIDO--11",
    "new_amount": "30.00",
    "transaction_bank": "BANCO_PICHINCHA",
    "payment_method": "transaction",
    "count_allow": 1,
    "file": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
  }'

use Illuminate\Support\Facades\Http;

class ReferralController extends Controller
{
    public function requestLicence(Request $request)
    {
        $data = [
            'plan_code' => $request->plan_code,
            'new_amount' => $request->new_amount,
            'transaction_bank' => $request->transaction_bank,
            'payment_method' => $request->payment_method,
            'count_allow' => $request->count_allow,
            'file' => $request->file // Base64 encoded file
        ];

        $response = Http::withHeaders([
            'Authorization' => 'Bearer ' . $this->getToken(),
            'Content-Type' => 'application/json',
            'Accept' => 'application/json'
        ])->post('https://dev-facturacion.e-dinky.test/api/v1/referral/request-licence', $data);

        if ($response->successful()) {
            return $response->json();
        }

        return response()->json(['error' => 'Error al solicitar licencia'], 400);
    }
}

const axios = require('axios');

async function requestReferralLicence(licenceData, token) {
    try {
        const response = await axios.post(
            'https://dev-facturacion.e-dinky.test/api/v1/referral/request-licence',
            {
                plan_code: licenceData.plan_code,
                new_amount: licenceData.new_amount,
                transaction_bank: licenceData.transaction_bank,
                payment_method: licenceData.payment_method,
                count_allow: licenceData.count_allow,
                file: licenceData.file // Base64 encoded file
            },
            {
                headers: {
                    'Authorization': `Bearer ${token}`,
                    'Content-Type': 'application/json',
                    'Accept': 'application/json'
                }
            }
        );

        return response.data;
    } catch (error) {
        console.error('Error al solicitar licencia de referido:', error.response?.data);
        throw error;
    }
}

Respuesta Exitosa (200 OK)

{
  "message": "Solicitud de licencia creada exitosamente",
  "status": "OK",
  "payload": {
    "licence_code": null,
    "transaction_code": "TXN_20250717_6879768E59368",
    "email": null,
    "count_activations": 0,
    "count_allow": 1,
    "original_total": "23.00",
    "new_total": "0.00",
    "new_amount": "30.00",
    "original_amount": "23.00",
    "payment_method": "transaction",
    "status": "processing",
    "message": "Transferencia bancaria pendiente de verificación",
    "expired_at": null,
    "approved_at": null,
    "anulled_at": null,
    "destroy_at": null,
    "reprocessed_attempts": 0,
    "reprocessed_at": null,
    "is_approved": false,
    "is_anulled": false,
    "is_destroyed": false,
    "is_expired": false,
    "created_at": "2025-07-17 17:17:50",
    "id": 1783700761
  }
}

Respuesta de Error (404 Not Found)

{
  "message": "Plan no encontrado",
  "status": "NOT_FOUND",
  "payload": null
}

2. Confirmar Licencia de Referido

POST /api/v1/referral/confirm-licence

Permite confirmar una licencia de referido previamente solicitada.

Headers Requeridos

Accept: application/json
Authorization: Bearer {token}
Content-Type: application/json

Cuerpo de la Solicitud

{
  "transaction_code": "TXN_20250717_6879768E59368",
  "uuid": "550e8400-e29b-41d4-a716-446655440000"
}

Parámetros Disponibles

Campo	Tipo	Requerido	Descripción
`transaction_code`	string	Sí	Código de transacción de la licencia
`uuid`	string	Sí	UUID único para la confirmación

Ejemplos de Implementación

curl -X POST "https://dev-facturacion.e-dinky.test/api/v1/referral/confirm-licence" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_code": "TXN_20250717_6879768E59368",
    "uuid": "550e8400-e29b-41d4-a716-446655440000"
  }'

use Illuminate\Support\Facades\Http;

class ReferralController extends Controller
{
    public function confirmLicence(Request $request)
    {
        $data = [
            'transaction_code' => $request->transaction_code,
            'uuid' => $request->uuid
        ];

        $response = Http::withHeaders([
            'Authorization' => 'Bearer ' . $this->getToken(),
            'Content-Type' => 'application/json',
            'Accept' => 'application/json'
        ])->post('https://dev-facturacion.e-dinky.test/api/v1/referral/confirm-licence', $data);

        if ($response->successful()) {
            return $response->json();
        }

        return response()->json(['error' => 'Error al confirmar licencia'], 400);
    }
}

const axios = require('axios');

async function confirmReferralLicence(transactionCode, uuid, token) {
    try {
        const response = await axios.post(
            'https://dev-facturacion.e-dinky.test/api/v1/referral/confirm-licence',
            {
                transaction_code: transactionCode,
                uuid: uuid
            },
            {
                headers: {
                    'Authorization': `Bearer ${token}`,
                    'Content-Type': 'application/json',
                    'Accept': 'application/json'
                }
            }
        );

        return response.data;
    } catch (error) {
        console.error('Error al confirmar licencia de referido:', error.response?.data);
        throw error;
    }
}

Respuesta de Error (404 Not Found)

{
  "message": "Licencia con código TXN_20250717_6879768E59368 no encontrada",
  "status": "NOT_FOUND",
  "payload": null
}

3. Consultar Todas las Licencias

GET /api/v1/referral/licences

Obtiene todas las licencias de referidos del usuario autenticado.

Headers Requeridos

Accept: application/json
Authorization: Bearer {token}

Ejemplos de Implementación

curl -X GET "https://dev-facturacion.e-dinky.test/api/v1/referral/licences" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"

use Illuminate\Support\Facades\Http;

class ReferralController extends Controller
{
    public function getAllLicences(Request $request)
    {
        $response = Http::withHeaders([
            'Authorization' => 'Bearer ' . $this->getToken(),
            'Accept' => 'application/json'
        ])->get('https://dev-facturacion.e-dinky.test/api/v1/referral/licences');

        if ($response->successful()) {
            return $response->json();
        }

        return response()->json(['error' => 'Error al consultar licencias'], 400);
    }
}

const axios = require('axios');

async function getAllReferralLicences(token) {
    try {
        const response = await axios.get(
            'https://dev-facturacion.e-dinky.test/api/v1/referral/licences',
            {
                headers: {
                    'Authorization': `Bearer ${token}`,
                    'Accept': 'application/json'
                }
            }
        );

        return response.data;
    } catch (error) {
        console.error('Error al consultar licencias de referido:', error.response?.data);
        throw error;
    }
}

Respuesta Exitosa (200 OK)

{
  "message": "Licencias obtenidas exitosamente",
  "status": "OK",
  "payload": {
    "items": [
      {
        "licence_code": null,
        "transaction_code": "TXN_20250717_6879768E59368",
        "email": null,
        "count_activations": 0,
        "count_allow": 1,
        "original_total": "23.00",
        "new_total": "0.00",
        "new_amount": "30.00",
        "original_amount": "23.00",
        "payment_method": "transaction",
        "status": "processing",
        "message": "Transferencia bancaria pendiente de verificación",
        "expired_at": null,
        "approved_at": null,
        "anulled_at": null,
        "destroy_at": null,
        "reprocessed_attempts": 0,
        "reprocessed_at": null,
        "is_approved": false,
        "is_anulled": false,
        "is_destroyed": false,
        "is_expired": false,
        "created_at": "2025-07-17 17:17:50",
        "id": 1783700761,
        "plan_id": 1945886872,
        "creator_user_id": null,
        "creator_company_id": 61247344,
        "beneficiary_user_id": null,
        "beneficiary_company_id": null,
        "approved_by": null,
        "destroy_by": null,
        "creator_company": {
          "id": 61247344,
          "company_name": "EDWARD REYES",
          "company_ruc": "0952615177001"
        },
        "plan": {
          "subject": "Plan referido",
          "code": "REFERIDO--11",
          "description": "adsfd dsfdv",
          "price": "23.00",
          "color": "#256e6e",
          "order": 1,
          "status": "draft",
          "free_acc": 0,
          "periodicity_type": null,
          "periodicity_lang": "lang.periodicityType.",
          "periodicity_singular": "lang.periodicitytype.",
          "periodicity": null
        }
      }
    ],
    "count_items": 3,
    "current_page": 1,
    "number_paginate": 25,
    "last_page": 1
  }
}

4. Consultar Licencia Específica

GET /api/v1/referral/licences/show/{transaction_code}

Obtiene los detalles de una licencia específica por su código de transacción.

Headers Requeridos

Accept: application/json
Authorization: Bearer {token}

Parámetros de Ruta

Parámetro	Tipo	Descripción
`transaction_code`	string	Código de transacción de la licencia

Ejemplos de Implementación

curl -X GET "https://dev-facturacion.e-dinky.test/api/v1/referral/licences/show/TXN_20250717_6879768E59368" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"

use Illuminate\Support\Facades\Http;

class ReferralController extends Controller
{
    public function getLicenceDetails($transactionCode)
    {
        $response = Http::withHeaders([
            'Authorization' => 'Bearer ' . $this->getToken(),
            'Accept' => 'application/json'
        ])->get("https://dev-facturacion.e-dinky.test/api/v1/referral/licences/show/{$transactionCode}");

        if ($response->successful()) {
            return $response->json();
        }

        return response()->json(['error' => 'Licencia no encontrada'], 404);
    }
}

const axios = require('axios');

async function getReferralLicenceDetails(transactionCode, token) {
    try {
        const response = await axios.get(
            `https://dev-facturacion.e-dinky.test/api/v1/referral/licences/show/${transactionCode}`,
            {
                headers: {
                    'Authorization': `Bearer ${token}`,
                    'Accept': 'application/json'
                }
            }
        );

        return response.data;
    } catch (error) {
        console.error('Error al consultar detalles de licencia:', error.response?.data);
        throw error;
    }
}

5. Cancelar Licencia

POST /api/v1/referral/cancel-licence/{transaction_code}

Cancela una licencia de referido específica.

Headers Requeridos

Accept: application/json
Authorization: Bearer {token}

Parámetros de Ruta

Parámetro	Tipo	Descripción
`transaction_code`	string	Código de transacción de la licencia a cancelar

Ejemplos de Implementación

curl -X POST "https://dev-facturacion.e-dinky.test/api/v1/referral/cancel-licence/CARD_687981159968F" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"

use Illuminate\Support\Facades\Http;

class ReferralController extends Controller
{
    public function cancelLicence($transactionCode)
    {
        $response = Http::withHeaders([
            'Authorization' => 'Bearer ' . $this->getToken(),
            'Accept' => 'application/json'
        ])->post("https://dev-facturacion.e-dinky.test/api/v1/referral/cancel-licence/{$transactionCode}");

        if ($response->successful()) {
            return $response->json();
        }

        return response()->json(['error' => 'Error al cancelar licencia'], 400);
    }
}

const axios = require('axios');

async function cancelReferralLicence(transactionCode, token) {
    try {
        const response = await axios.post(
            `https://dev-facturacion.e-dinky.test/api/v1/referral/cancel-licence/${transactionCode}`,
            {},
            {
                headers: {
                    'Authorization': `Bearer ${token}`,
                    'Accept': 'application/json'
                }
            }
        );

        return response.data;
    } catch (error) {
        console.error('Error al cancelar licencia de referido:', error.response?.data);
        throw error;
    }
}

Respuesta Exitosa (200 OK)

{
  "message": "Licencia eliminada exitosamente",
  "status": "OK",
  "payload": {
    "licence_code": "c94ac72c-5032-42bc-8e42-8ac866c2482d",
    "transaction_code": "CARD_687981159968F",
    "email": null,
    "count_activations": 0,
    "count_allow": 1,
    "original_total": "23.00",
    "new_total": "0.00",
    "new_amount": "30.00",
    "original_amount": "23.00",
    "payment_method": "card",
    "status": "destroy",
    "message": "Licencia aprobada",
    "expired_at": null,
    "approved_at": "2025-07-18 18:29:24",
    "anulled_at": null,
    "destroy_at": "2025-07-18 18:29:35",
    "reprocessed_attempts": 0,
    "reprocessed_at": null,
    "is_approved": true,
    "is_anulled": false,
    "is_destroyed": true,
    "is_expired": false,
    "created_at": "2025-07-17 18:02:45",
    "id": 968767947,
    "plan_id": 1945886872,
    "creator_user_id": 1783700761,
    "creator_company_id": 61247344,
    "beneficiary_user_id": null,
    "beneficiary_company_id": null,
    "approved_by": 1783700761,
    "destroy_by": 1783700761
  }
}

Estados de Licencia

Estado	Descripción
`processing`	Licencia en proceso de verificación
`approved`	Licencia aprobada y activa
`anulled`	Licencia anulada
`destroy`	Licencia eliminada
`expired`	Licencia expirada

Métodos de Pago

Método	Código	Descripción
Transferencia Bancaria	`transaction`	Pago mediante transferencia bancaria
Tarjeta de Crédito/Débito	`card`	Pago con tarjeta
Criptomoneda	`crypto`	Pago con criptomonedas

Códigos de Respuesta

Código	Descripción
200	Operación exitosa
201	Recurso creado exitosamente
404	Recurso no encontrado
422	Datos de entrada inválidos
401	No autorizado
500	Error interno del servidor

Notas Importantes

Autenticación: Todos los endpoints requieren un token Bearer válido
Formato de Archivo: Los comprobantes deben enviarse en formato base64 con el prefijo del tipo MIME
Validación de Planes: El código del plan debe existir y estar activo
Límites de Activación: Cada licencia tiene un límite de activaciones definido en count_allow
Seguimiento: Todas las operaciones quedan registradas con timestamps
Estados Booleanos: Se utilizan flags como is_approved, is_anulled, is_destroyed, is_expired para el control de estado