Gestión de Clientes

Pruebas
Producción

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

La API de gestión de clientes permite realizar operaciones CRUD completas sobre los clientes del sistema. Incluye funcionalidades para consultar, crear, actualizar y eliminar clientes, así como obtener información específica y eventos relacionados.

Endpoints Disponibles

1. Consultar Clientes

Endpoint: GET /api/v1/customers

Descripción: Obtiene una lista de todos los clientes registrados en el sistema.

Headers Requeridos

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

Parámetros de Consulta (Opcionales)

Parámetro	Tipo	Descripción	Ejemplo
`type_identification`	string	Filtrar por tipo de identificación	`ruc`, `cedula`, `pasaporte`
`page`	integer	Número de página para paginación	`1`
`per_page`	integer	Elementos por página	`15`

Ejemplos de Implementación

curl -X GET "https://dev-facturacion.e-dinky.test/api/v1/customers?type_identification=ruc" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token_here"

use Illuminate\Support\Facades\Http;

class CustomerController extends Controller
{
    public function getCustomers(Request $request)
    {
        $params = [];
        if ($request->has('type_identification')) {
            $params['type_identification'] = $request->type_identification;
        }
        if ($request->has('page')) {
            $params['page'] = $request->page;
        }
        if ($request->has('per_page')) {
            $params['per_page'] = $request->per_page;
        }

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

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

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

const axios = require('axios');

async function getCustomers(filters = {}, token) {
    try {
        const params = new URLSearchParams();

        if (filters.type_identification) {
            params.append('type_identification', filters.type_identification);
        }
        if (filters.page) {
            params.append('page', filters.page);
        }
        if (filters.per_page) {
            params.append('per_page', filters.per_page);
        }

        const response = await axios.get(
            `https://dev-facturacion.e-dinky.test/api/v1/customers?${params.toString()}`,
            {
                headers: {
                    'Accept': 'application/json',
                    'Content-Type': 'application/json',
                    'Authorization': `Bearer ${token}`
                }
            }
        );

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

Respuesta Exitosa (200 OK)

{
  "data": [
    {
      "id": 934666822,
      "full_name": "CARVAGU S.A.",
      "email": "[email protected]",
      "identification_type": "ruc",
      "identification_number": "0991434879001",
      "address": "Chongón km 24",
      "phone": null,
      "website": null,
      "is_business": true
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 1
  }
}

2. Crear Cliente

Endpoint: POST /api/v1/customers/create

Descripción: Crea un nuevo cliente en el sistema.

Headers Requeridos

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

Cuerpo de la Solicitud

Campo	Tipo	Requerido	Descripción
`identification_number`	string	Sí	Número de identificación del cliente
`name`	string	Sí	Nombre del cliente
`lastname`	string	No	Apellido del cliente (para personas naturales)
`identification_type`	string	Sí	Tipo de identificación: `RUC`, `CEDULA`, `PASAPORTE`
`email`	string	Sí	Correo electrónico del cliente
`address`	string	No	Dirección del cliente
`phone`	string	No	Teléfono del cliente
`website`	string	No	Sitio web del cliente
`is_business`	boolean	No	Indica si es un negocio (true) o persona natural (false)

Ejemplos de Solicitud

Cliente Empresa (RUC):

{
  "identification_number": "0991434879001",
  "name": "CARVAGU S.A.",
  "identification_type": "RUC",
  "email": "[email protected]",
  "address": "S/N",
  "is_business": true
}

Cliente Persona Natural (Cédula):

{
  "identification_number": "0921498846",
  "name": "HECTOR ANTONIO",
  "lastname": "REYES VILLON",
  "identification_type": "CEDULA",
  "email": "[email protected]",
  "address": "Cerecita Km 51"
}

Ejemplos de Implementación

curl -X POST "https://dev-facturacion.e-dinky.test/api/v1/customers/create" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token_here" \
  -d '{
    "identification_number": "0991434879001",
    "name": "CARVAGU S.A.",
    "identification_type": "RUC",
    "email": "[email protected]",
    "address": "S/N",
    "is_business": true
  }'

use Illuminate\Support\Facades\Http;

class CustomerController extends Controller
{
    public function createCustomer(Request $request)
    {
        $customerData = [
            'identification_number' => $request->identification_number,
            'name' => $request->name,
            'lastname' => $request->lastname,
            'identification_type' => $request->identification_type,
            'email' => $request->email,
            'address' => $request->address,
            'is_business' => $request->is_business ?? false
        ];

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

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

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

const axios = require('axios');

async function createCustomer(customerData, token) {
    try {
        const response = await axios.post(
            'https://dev-facturacion.e-dinky.test/api/v1/customers/create',
            {
                identification_number: customerData.identification_number,
                name: customerData.name,
                lastname: customerData.lastname,
                identification_type: customerData.identification_type,
                email: customerData.email,
                address: customerData.address,
                is_business: customerData.is_business || false
            },
            {
                headers: {
                    'Accept': 'application/json',
                    'Content-Type': 'application/json',
                    'Authorization': `Bearer ${token}`
                }
            }
        );

        return response.data;
    } catch (error) {
        console.error('Error al crear cliente:', error.response?.data);
        throw error;
    }
}

Respuesta Exitosa (201 Created)

{
  "message": "Registro creado",
  "status": "CREATED",
  "payload": {
    "id": 1617479572,
    "full_name": "CARVAGU S.A.",
    "email": "[email protected]",
    "identification_type": "ruc",
    "identification_number": "0991434879001"
  }
}

3. Actualizar Cliente

Endpoint: PUT /api/v1/customers/update

Descripción: Actualiza la información de un cliente existente.

Headers Requeridos

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

Cuerpo de la Solicitud

Utiliza los mismos campos que en la creación. El cliente se identifica por el identification_number.

Ejemplos de Implementación

curl -X PUT "https://dev-facturacion.e-dinky.test/api/v1/customers/update" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token_here" \
  -d '{
    "identification_number": "0991434879001",
    "name": "CARVAGU S.A.",
    "identification_type": "RUC",
    "email": "[email protected]",
    "address": "Chongón km 24",
    "is_business": true
  }'

use Illuminate\Support\Facades\Http;

class CustomerController extends Controller
{
    public function updateCustomer(Request $request)
    {
        $customerData = [
            'identification_number' => $request->identification_number,
            'name' => $request->name,
            'lastname' => $request->lastname,
            'identification_type' => $request->identification_type,
            'email' => $request->email,
            'address' => $request->address,
            'is_business' => $request->is_business ?? false
        ];

        $response = Http::withHeaders([
            'Accept' => 'application/json',
            'Content-Type' => 'application/json',
            'Authorization' => 'Bearer ' . $this->getToken()
        ])->put('https://dev-facturacion.e-dinky.test/api/v1/customers/update', $customerData);

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

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

const axios = require('axios');

async function updateCustomer(customerData, token) {
    try {
        const response = await axios.put(
            'https://dev-facturacion.e-dinky.test/api/v1/customers/update',
            {
                identification_number: customerData.identification_number,
                name: customerData.name,
                lastname: customerData.lastname,
                identification_type: customerData.identification_type,
                email: customerData.email,
                address: customerData.address,
                is_business: customerData.is_business || false
            },
            {
                headers: {
                    'Accept': 'application/json',
                    'Content-Type': 'application/json',
                    'Authorization': `Bearer ${token}`
                }
            }
        );

        return response.data;
    } catch (error) {
        console.error('Error al actualizar cliente:', error.response?.data);
        throw error;
    }
}

Respuesta Exitosa (201 Created)

{
  "message": "Registro Actualizado",
  "status": "UPDATED",
  "payload": {
    "id": 934666822,
    "full_name": "CARVAGU S.A.",
    "email": "[email protected]",
    "identification_type": "ruc",
    "identification_number": "0991434879001",
    "address": "Chongón km 24",
    "phone": null,
    "website": null,
    "is_business": true
  }
}

4. Eliminar Cliente

Endpoint: DELETE /api/v1/customers/{identificacion}

Descripción: Elimina un cliente del sistema.

Headers Requeridos

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

Parámetros de Ruta

Parámetro	Tipo	Descripción
`identificacion`	string	Número de identificación del cliente a eliminar

Ejemplo cURL

Ejemplos de Implementación

curl -X DELETE "https://dev-facturacion.e-dinky.test/api/v1/customers/0991434879001" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token_here"

use Illuminate\Support\Facades\Http;

class CustomerController extends Controller
{
    public function deleteCustomer($identification)
    {
        $response = Http::withHeaders([
            'Accept' => 'application/json',
            'Content-Type' => 'application/json',
            'Authorization' => 'Bearer ' . $this->getToken()
        ])->delete("https://dev-facturacion.e-dinky.test/api/v1/customers/{$identification}");

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

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

const axios = require('axios');

async function deleteCustomer(identification, token) {
    try {
        const response = await axios.delete(
            `https://dev-facturacion.e-dinky.test/api/v1/customers/${identification}`,
            {
                headers: {
                    'Accept': 'application/json',
                    'Content-Type': 'application/json',
                    'Authorization': `Bearer ${token}`
                }
            }
        );

        return response.data;
    } catch (error) {
        console.error('Error al eliminar cliente:', error.response?.data);
        throw error;
    }
}

5. Obtener Cliente por Identificación

Endpoint: GET /api/v1/customers/{identificacion}

Descripción: Obtiene la información detallada de un cliente específico.

Headers Requeridos

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

Parámetros de Ruta

Parámetro	Tipo	Descripción
`identificacion`	string	Número de identificación del cliente

Ejemplos de Implementación

curl -X GET "https://dev-facturacion.e-dinky.test/api/v1/customers/0991434879001" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token_here"

use Illuminate\Support\Facades\Http;

class CustomerController extends Controller
{
    public function getCustomerByIdentification($identification)
    {
        $response = Http::withHeaders([
            'Accept' => 'application/json',
            'Content-Type' => 'application/json',
            'Authorization' => 'Bearer ' . $this->getToken()
        ])->get("https://dev-facturacion.e-dinky.test/api/v1/customers/{$identification}");

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

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

const axios = require('axios');

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

        return response.data;
    } catch (error) {
        console.error('Error al obtener cliente:', error.response?.data);
        throw error;
    }
}

6. Obtener Eventos del Cliente

Endpoint: GET /api/v1/customers/{identificacion}/events

Descripción: Obtiene el historial de eventos relacionados con un cliente específico.

Headers Requeridos

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

Parámetros de Ruta

Parámetro	Tipo	Descripción
`identificacion`	string	Número de identificación del cliente

Ejemplos de Implementación

curl -X GET "https://dev-facturacion.e-dinky.test/api/v1/customers/0991434879001/events" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token_here"

use Illuminate\Support\Facades\Http;

class CustomerController extends Controller
{
    public function getCustomerEvents($identification)
    {
        $response = Http::withHeaders([
            'Accept' => 'application/json',
            'Content-Type' => 'application/json',
            'Authorization' => 'Bearer ' . $this->getToken()
        ])->get("https://dev-facturacion.e-dinky.test/api/v1/customers/{$identification}/events");

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

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

const axios = require('axios');

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

        return response.data;
    } catch (error) {
        console.error('Error al obtener eventos del cliente:', error.response?.data);
        throw error;
    }
}

7. Obtener Dataset del Cliente

Endpoint: GET /api/v1/customers/{identificacion}/dataset

Descripción: Obtiene información adicional y estadísticas del cliente.

Headers Requeridos

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

Parámetros de Ruta

Parámetro	Tipo	Descripción
`identificacion`	string	Número de identificación del cliente

Ejemplos de Implementación

curl -X GET "https://dev-facturacion.e-dinky.test/api/v1/customers/0991434879001/dataset" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token_here"

use Illuminate\Support\Facades\Http;

class CustomerController extends Controller
{
    public function getCustomerDataset($identification)
    {
        $response = Http::withHeaders([
            'Accept' => 'application/json',
            'Content-Type' => 'application/json',
            'Authorization' => 'Bearer ' . $this->getToken()
        ])->get("https://dev-facturacion.e-dinky.test/api/v1/customers/{$identification}/dataset");

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

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

const axios = require('axios');

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

        return response.data;
    } catch (error) {
        console.error('Error al obtener dataset del cliente:', error.response?.data);
        throw error;
    }
}

Filtros Avanzados

La API de clientes soporta el sistema de filtros avanzados. Para más información sobre cómo implementar filtros, consulta la documentación de filtros.

Campos Filtrables

Campo	Tipo	Descripción
`id`	integer	ID único del cliente
`full_name`	string	Nombre completo del cliente
`email`	string	Correo electrónico
`identification_type`	string	Tipo de identificación
`identification_number`	string	Número de identificación
`address`	string	Dirección
`phone`	string	Teléfono
`website`	string	Sitio web
`is_business`	boolean	Es negocio
`created_at`	datetime	Fecha de creación
`updated_at`	datetime	Fecha de actualización

Ejemplo de Filtro

{
  "filters": [
    {
      "field": "identification_type",
      "condition": "equals",
      "value": "ruc"
    },
    {
      "field": "is_business",
      "condition": "equals",
      "value": true
    }
  ],
  "logic": "and"
}

Tipos de Identificación

Código	Descripción
`RUC`	Registro Único de Contribuyentes
`CEDULA`	Cédula de Identidad
`PASAPORTE`	Pasaporte

Códigos de Respuesta

Código	Descripción
`200`	Consulta exitosa
`201`	Cliente creado/actualizado exitosamente
`400`	Error en los datos enviados
`401`	Token de autorización inválido
`404`	Cliente no encontrado
`422`	Error de validación
`500`	Error interno del servidor

Notas Importantes

El campo identification_number debe ser único en el sistema
Para clientes tipo empresa (is_business: true), se recomienda usar tipo de identificación RUC
Para personas naturales, usar CEDULA o PASAPORTE
El campo full_name se genera automáticamente combinando name y lastname
Los eventos del cliente incluyen historial de documentos, pagos y modificaciones
El dataset proporciona estadísticas y métricas del cliente