API Overview

Introduction

The Tambo360 API is a RESTful API that enables you to manage dairy farm production data programmatically. Built on Express.js, the API provides comprehensive endpoints for managing establishments, batches, costs, products, waste tracking, and real-time alerts.

Base URL

All API requests should be made to:

https://api.tambo360.com/api

API Architecture

The Tambo360 API follows a modular architecture organized into functional domains:

Available Endpoints

Resource	Base Path	Description
Authentication	`/auth`	User registration, login, password recovery
Health	`/health`	API health checks and status
Establishments	`/establecimiento`	Farm establishment management
Batches	`/lote`	Production batch tracking
Waste	`/mermas`	Waste and loss tracking
Costs	`/costos`	Cost management and analysis
Products	`/productos`	Product catalog management
Alerts	`/alertas`	Real-time notification system
Dashboard	`/dashboard`	Aggregated metrics and analytics

Request Format

All requests should include the appropriate headers:

Content-Type

string

required

Set to application/json for all POST, PUT, and PATCH requests

Contains the JWT token for authenticated requests (automatically handled by browsers)

Example Request

curl -X POST https://api.tambo360.com/api/establecimiento/registrar \
  -H "Content-Type: application/json" \
  -b "token=your_jwt_token_here" \
  -d '{
    "nombre": "Establecimiento Norte",
    "localidad": "Rafaela",
    "provincia": "Santa Fe"
  }'

Response Format

All API responses follow a consistent structure:

Success Response

statusCode

integer

required

HTTP status code (200, 201, etc.)

message

string

required

Human-readable success message in Spanish

data

object

required

Response payload containing the requested data

success

boolean

Always true for successful responses

Success Response Example

{
  "statusCode": 201,
  "message": "Establecimiento creado correctamente",
  "data": {
    "idEstablecimiento": "c2b8e8a2-4f92-4f3f-b0c5-1a2b3c4d5e6f",
    "nombre": "Establecimiento Norte",
    "localidad": "Rafaela",
    "provincia": "Santa Fe",
    "idUsuario": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
  },
  "success": true
}

Error Response

statusCode

integer

required

HTTP error status code (400, 401, 404, 500, etc.)

message

string | array

required

Error message(s) describing what went wrong. Can be a string for single errors or an array for validation errors

success

boolean

Always false for error responses

Error Response Example

{
  "statusCode": 400,
  "message": "Todos los campos son obligatorios",
  "success": false
}

Validation Error Example

{
  "statusCode": 400,
  "message": [
    "correo es obligatorio",
    "contraseña debe tener al menos 8 caracteres"
  ],
  "success": false
}

HTTP Status Codes

The API uses standard HTTP status codes:

Status Code	Meaning
`200`	OK - Request succeeded
`201`	Created - Resource successfully created
`400`	Bad Request - Invalid input or validation error
`401`	Unauthorized - Authentication required or token invalid
`403`	Forbidden - Authenticated but not authorized
`404`	Not Found - Resource doesn’t exist
`500`	Internal Server Error - Something went wrong on the server

Rate Limiting

Currently, the Tambo360 API does not enforce rate limits. However, we recommend implementing exponential backoff in your client applications to handle potential future rate limiting.

CORS Configuration

The API supports Cross-Origin Resource Sharing (CORS) with credentials enabled. Allowed origins are configured via the CORS_ORIGIN environment variable. For authenticated requests from web browsers:

Set credentials: 'include' in fetch requests
Use withCredentials: true in Axios

Interactive API Documentation

Tambo360 provides an interactive Swagger UI for testing API endpoints:

https://api.tambo360.com/api-docs

The Swagger interface allows you to:

Explore all available endpoints
Test requests directly from your browser
View request/response schemas
Understand parameter requirements

Data Types

Common Field Types

idUsuario

string

User identifier in UUID v4 format

idEstablecimiento

string

Establishment identifier in UUID v4 format

fechaCreacion

string

ISO 8601 timestamp (e.g., 2024-03-15T10:30:00.000Z)

correo

string

Valid email address (5-50 characters)

Best Practices

1. Always Handle Errors

Implement comprehensive error handling for all API calls:

javascript

try {
  const response = await fetch('https://api.tambo360.com/api/auth/me', {
    credentials: 'include'
  });
  
  const result = await response.json();
  
  if (!response.ok) {
    // Handle error
    console.error(result.message);
    return;
  }
  
  // Process successful response
  console.log(result.data);
} catch (error) {
  // Handle network errors
  console.error('Network error:', error);
}

2. Include Credentials for Protected Routes

Most endpoints require authentication. Always include credentials:

javascript

fetch(url, {
  credentials: 'include',  // Critical for authenticated requests
  headers: {
    'Content-Type': 'application/json'
  }
})

3. Validate Input Before Sending

Reduce unnecessary API calls by validating data client-side:

Email format validation
Required field checks
Password strength requirements
Data type validation

4. Use TypeScript for Type Safety

typescript

interface ApiResponse<T> {
  statusCode: number;
  message: string;
  data: T;
  success: boolean;
}

interface Establecimiento {
  idEstablecimiento: string;
  nombre: string;
  localidad: string;
  provincia: string;
  idUsuario: string;
}

const response: ApiResponse<Establecimiento> = await fetchEstablishment();

Next Steps

Authentication

Learn how to authenticate users and manage sessions

Establishments

Manage farm establishments and their data

Batches

Track production batches and inventory

Dashboard

Access aggregated metrics and analytics

Overview

Endpoints

Data Models

Introduction

Base URL

API Architecture

Available Endpoints

Request Format

Example Request

Response Format

Success Response

Error Response

HTTP Status Codes

Rate Limiting

CORS Configuration

Interactive API Documentation

Data Types

Common Field Types

Best Practices

1. Always Handle Errors

2. Include Credentials for Protected Routes

3. Validate Input Before Sending

4. Use TypeScript for Type Safety

Next Steps

Authentication

Establishments

Batches

Dashboard

Build docs developers (and LLMs) love

Overview

Endpoints

Data Models

​Introduction

​Base URL

​API Architecture

​Available Endpoints

​Request Format

​Example Request

​Response Format

​Success Response

​Error Response

​HTTP Status Codes

​Rate Limiting

​CORS Configuration

​Interactive API Documentation

​Data Types

​Common Field Types

​Best Practices

​1. Always Handle Errors

​2. Include Credentials for Protected Routes

​3. Validate Input Before Sending

​4. Use TypeScript for Type Safety

​Next Steps

Authentication

Establishments

Batches

Dashboard

Build docs developers (and LLMs) love

Introduction

Base URL

API Architecture

Available Endpoints

Request Format

Example Request

Response Format

Success Response

Error Response

HTTP Status Codes

Rate Limiting

CORS Configuration

Interactive API Documentation

Data Types

Common Field Types

Best Practices

1. Always Handle Errors

2. Include Credentials for Protected Routes

3. Validate Input Before Sending

4. Use TypeScript for Type Safety

Next Steps