Guía de Integración del Módulo Contactos

Esta guía detalla cómo consumir los endpoints de Contactos desde aplicaciones externas (CRMs, plataformas e-commerce, integradores o servicios en segundo plano).

---

1. Autenticación

Todas las peticiones deben incluir la cabecera X-Api-Key o el token JWT en Authorization.

X-Api-Key: tu-api-key-configurada-aqui

Límite de Peticiones (Rate Limiting)

La API cuenta con un límite estándar de 60 peticiones por minuto por cliente (con cola de espera de hasta 5 peticiones). Si supera este umbral, el servidor responderá con código HTTP 429 Too Many Requests.

---

2. Ejemplos de Código: Consultar Clientes

A continuación se muestran ejemplos para consultar el listado de clientes activos filtrando por el término "Construcciones":

C# (.NET)

using System.Net.Http.Json;
using System.Text.Json;

var httpClient = new HttpClient
{
    BaseAddress = new Uri("http://localhost:5000")
};

// Añadimos la clave de autenticación
httpClient.DefaultRequestHeaders.Add("X-Api-Key", "tu-api-key-secreta");

// Realizamos la consulta con paginación y búsqueda
var response = await httpClient.GetAsync("/customers?page=1&pageSize=50&search=Construcciones&IsActive=1");

if (response.IsSuccessStatusCode)
{
    var pagedResult = await response.Content.ReadFromJsonAsync<PagedResult<CustomerDto>>();
    Console.WriteLine($"Clientes recuperados: {pagedResult.Items.Count} de un total de {pagedResult.TotalCount}");
    
    foreach (var customer in pagedResult.Items)
    {
        Console.WriteLine($"[{customer.Code}] {customer.Name} - NIF: {customer.VatNumber}");
    }
}
else
{
    Console.WriteLine($"Error en la petición: {response.StatusCode}");
}

cURL

curl -X GET "http://localhost:5000/customers?page=1&pageSize=50&search=Construcciones&IsActive=1" \
     -H "Accept: application/json" \
     -H "X-Api-Key: tu-api-key-secreta"

Python

import requests

url = "http://localhost:5000/customers"
headers = {
    "X-Api-Key": "tu-api-key-secreta",
    "Accept": "application/json"
}
params = {
    "page": 1,
    "pageSize": 50,
    "search": "Construcciones",
    "IsActive": 1
}

response = requests.get(url, headers=headers, params=params)

if response.status_code == 200:
    data = response.json()
    print(f"Total registros: {data['totalCount']}")
    for cust in data["items"]:
        print(f"[{cust['code']}] {cust['name']} ({cust['vatNumber']})")
else:
    print(f"Error {response.status_code}: {response.text}")

---

3. Patrón de Sincronización Incremental (updatedAfter)

Para mantener sincronizada su base de datos externa sin sobrecargar el servidor de BaseGes:

1. Guardar marca temporal: Almacene en su sistema la fecha y hora UTC de la última sincronización ejecutada (ej. 2026-10-19T14:30:00Z).
2. Petición filtrada: En la siguiente ejecución, solicite únicamente los registros modificados a partir de esa fecha:

   GET /customers?updatedAfter=2026-10-19T14:30:00Z&page=1&pageSize=100

3. Paginación en bucle: Si hasNextPage es true, incremente page hasta completar la sincronización.
4. Actualizar marca temporal: Guarde la nueva hora de finalización para la próxima ronda.