Overview The Customers API allows you to create, retrieve, update, and delete customer records in the inventory management system. Customers can have various payment conditions and document types.
Base URL: /api/v1/customersAuthentication All endpoints require JWT authentication via Bearer token in the Authorization header.
Create Customer Create a new customer record.
Required Roles: admin, gestorRequest Body Request Example import requests url = "http://localhost:5000/api/v1/customers/" headers = { "Authorization" : "Bearer YOUR_JWT_TOKEN" , "Content-Type" : "application/json" } payload = { "nombre" : "Juan Pérez" , "tipo_documento" : "DNI" , "numero_documento" : "12345678" , "direccion" : "Av. Principal 123, Lima" , "telefono" : "+51 987654321" , "email" : "[email protected] " , "condicion_pago" : "CREDITO_30" } response = requests.post(url, json = payload, headers = headers) print (response.json())
Response 201 Created
400 Bad Request
409 Conflict
{ "id" : "550e8400-e29b-41d4-a716-446655440000" , "nombre" : "Juan Pérez" , "tipo_documento" : "DNI" , "numero_documento" : "12345678" , "direccion" : "Av. Principal 123, Lima" , "telefono" : "+51 987654321" , "email" : "[email protected] " , "condicion_pago" : "CREDITO_30" }
List Customers Retrieve a list of all customers with optional search and pagination.
Required Roles: admin, gestor, consultorQuery Parameters Request Example import requests url = "http://localhost:5000/api/v1/customers/" headers = { "Authorization" : "Bearer YOUR_JWT_TOKEN" } params = { "skip" : 0 , "limit" : 10 , "q" : "Juan" } response = requests.get(url, params = params, headers = headers) print (response.json())
Response [ { "id" : "550e8400-e29b-41d4-a716-446655440000" , "nombre" : "Juan Pérez" , "tipo_documento" : "DNI" , "numero_documento" : "12345678" , "direccion" : "Av. Principal 123, Lima" , "telefono" : "+51 987654321" , "email" : "[email protected] " , "condicion_pago" : "CREDITO_30" }, { "id" : "660e8400-e29b-41d4-a716-446655440001" , "nombre" : "María García" , "tipo_documento" : "DNI" , "numero_documento" : "87654321" , "direccion" : "Jr. Comercio 456, Lima" , "telefono" : "+51 912345678" , "email" : "[email protected] " , "condicion_pago" : "CONTADO" } ]
Get Customer Retrieve details of a specific customer by ID.
Required Roles: admin, gestor, consultorPath Parameters Request Example import requests customer_id = "550e8400-e29b-41d4-a716-446655440000" url = f "http://localhost:5000/api/v1/customers/ { customer_id } " headers = { "Authorization" : "Bearer YOUR_JWT_TOKEN" } response = requests.get(url, headers = headers) print (response.json())
Response { "id" : "550e8400-e29b-41d4-a716-446655440000" , "nombre" : "Juan Pérez" , "tipo_documento" : "DNI" , "numero_documento" : "12345678" , "direccion" : "Av. Principal 123, Lima" , "telefono" : "+51 987654321" , "email" : "[email protected] " , "condicion_pago" : "CREDITO_30" }
Update Customer Update an existing customer’s information. Both PUT and PATCH methods are supported for partial updates.
Required Roles: admin, gestorPath Parameters Request Body All fields are optional. Only include fields you want to update.
Request Example import requests customer_id = "550e8400-e29b-41d4-a716-446655440000" url = f "http://localhost:5000/api/v1/customers/ { customer_id } " headers = { "Authorization" : "Bearer YOUR_JWT_TOKEN" , "Content-Type" : "application/json" } payload = { "telefono" : "+51 999888777" , "condicion_pago" : "CREDITO_15" } response = requests.put(url, json = payload, headers = headers) print (response.json())
Response 200 OK
404 Not Found
409 Conflict
{ "id" : "550e8400-e29b-41d4-a716-446655440000" , "nombre" : "Juan Pérez" , "tipo_documento" : "DNI" , "numero_documento" : "12345678" , "direccion" : "Av. Principal 123, Lima" , "telefono" : "+51 999888777" , "email" : "[email protected] " , "condicion_pago" : "CREDITO_15" }
Delete Customer Delete a customer from the system.
Required Roles: admin, gestorPath Parameters Request Example import requests customer_id = "550e8400-e29b-41d4-a716-446655440000" url = f "http://localhost:5000/api/v1/customers/ { customer_id } " headers = { "Authorization" : "Bearer YOUR_JWT_TOKEN" } response = requests.delete(url, headers = headers) print (response.json())
Response 200 OK
404 Not Found
409 Conflict
{ "message" : "Customer deleted successfully" }
Customers with existing transactions (sales, invoices, etc.) cannot be deleted due to referential integrity constraints. Consider marking them as inactive instead if your business logic supports it.
Error Codes Status Code Description 200 Success 201 Created 400 Bad Request - Missing required fields or validation error 401 Unauthorized - Invalid or missing JWT token 403 Forbidden - Insufficient permissions for the operation 404 Not Found - Customer does not exist 409 Conflict - Duplicate document number or email, or integrity constraint violation
Data Models Customer Object Field Type Description id string (UUID) Unique identifier nombre string Customer name tipo_documento string Document type (DNI, RUC, CE, etc.) numero_documento string Document number (unique) direccion string Physical address telefono string Contact phone number email string Email address (unique) condicion_pago string Payment terms (CONTADO, CREDITO_15, CREDITO_30, etc.)