Skip to main content

​
Overview

The Stakeholder Search endpoint provides a unified search interface to find customers and suppliers simultaneously. This is useful for POS systems, quick lookups, and reporting where you need to search across both stakeholder types. Endpoint: GET /api/v1/stakeholders/search

​
Authentication

Requires JWT authentication via Bearer token. Required Roles: admin, gestor, consultor

​
Query Parameters

​
q
string
default:""
Search query string. Searches across name, document number, email, and other text fields. Empty query returns recent records.
​
type
string
default:"all"
Filter by stakeholder type. Options:
  • all - Search both customers and suppliers (default)
  • customer - Search only customers
  • supplier - Search only suppliers
​
limit
integer
default:"10"
Maximum number of results to return

​
Response

Returns an array of stakeholder objects with a type field indicating whether each result is a customer or supplier.

​
Response Fields

​
id
string
Unique identifier for the stakeholder
​
type
string
Stakeholder type: customer or supplier
​
nombre
string
Stakeholder name
​
numero_documento
string
Document number
​
tipo_documento
string
Document type (DNI, RUC, CE, etc.)
​
email
string
Email address (if provided)
​
telefono
string
Phone number (if provided)
​
direccion
string
Address (if provided)
​
condicion_pago
string
Payment condition (customers only)
​
plazo_entrega
string
Delivery terms (suppliers only)

​
Examples

​
Search all stakeholders

cURL
curl -X GET "http://localhost:5000/api/v1/stakeholders/search?q=juan" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Python
import requests

url = "http://localhost:5000/api/v1/stakeholders/search"
headers = {"Authorization": "Bearer YOUR_JWT_TOKEN"}
params = {"q": "juan", "limit": 10}

response = requests.get(url, headers=headers, params=params)
print(response.json())
200 OK
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "customer",
    "nombre": "Juan Pérez",
    "tipo_documento": "DNI",
    "numero_documento": "12345678",
    "email": "[email protected]",
    "telefono": "+51 987654321",
    "direccion": "Av. Principal 123",
    "condicion_pago": "CREDITO_30"
  },
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "type": "supplier",
    "nombre": "Juan Distribuciones SAC",
    "tipo_documento": "RUC",
    "numero_documento": "20123456789",
    "email": "[email protected]",
    "telefono": "+51 999888777",
    "direccion": "Av. Industrial 456",
    "plazo_entrega": "3-5 días"
  }
]

​
Search only customers

cURL
curl -X GET "http://localhost:5000/api/v1/stakeholders/search?q=garcia&type=customer" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Python
import requests

url = "http://localhost:5000/api/v1/stakeholders/search"
headers = {"Authorization": "Bearer YOUR_JWT_TOKEN"}
params = {"q": "garcia", "type": "customer", "limit": 5}

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

​
Search by document number

cURL
curl -X GET "http://localhost:5000/api/v1/stakeholders/search?q=20123456789" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
This will search across all text fields, including document numbers.

​
Get recent stakeholders

cURL
curl -X GET "http://localhost:5000/api/v1/stakeholders/search?limit=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Empty query returns the most recently created/updated records.

​
Use Cases

POS customer lookup

Quickly find customers during sales transactions without navigating between customer and supplier lists.

Unified reporting

Generate reports that include both customer and supplier data without multiple API calls.

Quick search UI

Implement autocomplete or type-ahead search boxes that search across all stakeholders.

Contact lookup

Find stakeholder contact information quickly by name, email, or document number.

​
Implementation Details

The search is implemented in stakeholder_service.py and performs a case-insensitive search across multiple fields:
  • Name (nombre)
  • Document number (numero_documento)
  • Email
  • Other text fields
Results are sorted by relevance and limited to the specified count.

​
Error Responses

​
400 Bad Request
{
  "error": "Invalid search parameters"
}
​
401 Unauthorized
{
  "error": "Missing or invalid authentication token"
}
​
403 Forbidden
{
  "error": "Insufficient permissions"
}

Customers API

Full CRUD operations for customer records

Suppliers API

Full CRUD operations for supplier records

Build docs developers (and LLMs) love

Get started for freeTalk to us