Credenciales de acceso

Para obtener sus credenciales de acceso (API_KEY y SIGNATURE_SECRET), contacte a Transagro.

Las credenciales son confidenciales y solo deben ser compartidas con personal autorizado de su empresa.

Ejemplo de autenticación

Método: GET
Endpoint: /conagro/sellout-data
Timestamp: 1757500443000
Body: {}

Payload para la firma:

GET/conagro/sellout-data1757500443000{}

Firma generada (HMAC-SHA256, hexadecimal):

6e2e359a2568f98041ba0728ddc6c5e3

Headers a enviar:

x-api-key: su-api-key-aqui
x-signature: 6e2e359a2568f98041ba0728ddc6c5e3
x-timestamp: 1757500443000
Content-Type: application/json

¿Qué información necesita para la integración?

  1. API_KEY (proporcionada por Transagro)
  2. SIGNATURE_SECRET (proporcionada por Transagro)
  3. URL base del API: https://apiconagro.hilagro.com.py
  4. Instrucciones para generar la firma y timestamp (ver ejemplos de código)

API Transagro - Guía Rápida de Integración

Acceso y Autenticación

x-api-key: SU_API_KEY
x-signature: FIRMA_GENERADA
x-timestamp: TIMESTAMP_UNIX_MS
Content-Type: application/json

Ejemplo de payload para firma:

GET/conagro/sellout-data1757500443000{}

Nota: El timestamp debe estar en milisegundos y sincronizado.

Endpoints Disponibles

Detalle: Ventas por mes y período (quincenal)

Método: GET
Endpoint: /conagro/sellout-data/{month}/{period}

Devuelve los datos de ventas facturados dentro de la quincena indicada. Los parámetros se envían en la ruta (no como query string).

Parámetro Tipo Valores permitidos Descripción
month Entero 1 a 12 Mes a consultar (1 = enero, 12 = diciembre)
period Entero 1 o 2 Quincena del mes: 1 = días 1 al 15, 2 = día 16 al último día del mes

Ejemplos:

Importante: la firma se calcula sobre la ruta completa, incluyendo los parámetros month y period. Si cambia el mes o el período, debe generar una firma nueva.

Payload para la firma (ejemplo para la primera quincena de marzo):

GET/conagro/sellout-data/3/11757500443000{}

Ejemplo con cURL:

curl -X GET \
  -H "x-api-key: SU_API_KEY" \
  -H "x-timestamp: 1757500443000" \
  -H "x-signature: FIRMA_GENERADA" \
  -H "Content-Type: application/json" \
  https://apiconagro.hilagro.com.py/conagro/sellout-data/3/1

Respuestas específicas de este endpoint:

Ejemplos de Código

Python

import requests, hmac, hashlib, time

api_key = "SU_API_KEY"
secret = "SU_SECRET_KEY"
base_url = "https://apiconagro.hilagro.com.py"

def request_api(endpoint):
    # La firma se calcula con la ruta del endpoint, NO con la URL completa
    timestamp = str(int(time.time() * 1000))
    payload = f"GET{endpoint}{timestamp}{{}}"
    signature = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()
    headers = {
        "x-api-key": api_key,
        "x-signature": signature,
        "x-timestamp": timestamp,
        "Content-Type": "application/json"
    }
    return requests.get(f"{base_url}{endpoint}", headers=headers)

# Todos los datos de ventas
resp = request_api("/conagro/sellout-data")
print(resp.status_code, resp.json())

# Ventas de la primera quincena de marzo (month=3, period=1)
month, period = 3, 1
resp = request_api(f"/conagro/sellout-data/{month}/{period}")
print(resp.status_code, resp.json())

# Datos de inventario
resp = request_api("/conagro/stock-data")
print(resp.status_code, resp.json())

Node.js

const axios = require('axios');
const crypto = require('crypto');

class TransagroApiClient {
  constructor(apiKey, secretKey, baseUrl = 'https://apiconagro.hilagro.com.py') {
    this.apiKey = apiKey;
    this.secretKey = secretKey;
    this.baseUrl = baseUrl;
    
    this.axiosInstance = axios.create({
      baseURL: this.baseUrl,
      timeout: 30000,
      headers: {
        'Content-Type': 'application/json'
      }
    });
  }

  generateSignature(method, endpoint, timestamp, body = '{}') {
    // La firma se calcula con la ruta del endpoint, NO con la URL completa
    const payload = `${method}${endpoint}${timestamp}${body}`;
    return crypto
      .createHmac('sha256', this.secretKey)
      .update(payload)
      .digest('hex');
  }

  async makeRequest(endpoint) {
    const timestamp = Date.now().toString();
    const signature = this.generateSignature('GET', endpoint, timestamp);

    try {
      const response = await this.axiosInstance.get(endpoint, {
        headers: {
          'x-api-key': this.apiKey,
          'x-signature': signature,
          'x-timestamp': timestamp
        }
      });

      return response.data;
    } catch (error) {
      if (error.response) {
        throw new Error(`Error en la solicitud: ${error.response.status} - ${error.response.statusText}`);
      }
      throw error;
    }
  }

  async getSelloutData() {
    return this.makeRequest('/conagro/sellout-data');
  }

  /**
   * Datos de ventas por mes y quincena
   * @param {number} month  - Mes a consultar (1 a 12)
   * @param {number} period - Quincena: 1 = días 1 al 15, 2 = día 16 al fin de mes
   */
  async getSelloutDataByMonthPeriod(month, period) {
    return this.makeRequest(`/conagro/sellout-data/${month}/${period}`);
  }

  async getStockData() {
    return this.makeRequest('/conagro/stock-data');
  }
}

// Ejemplo de uso
async function example() {
  const client = new TransagroApiClient('su-api-key', 'su-secret-key');
  try {
    const data = await client.getSelloutData();
    console.log(`Datos obtenidos: ${data.length} registros`);

    // Primera quincena de marzo
    const quincena = await client.getSelloutDataByMonthPeriod(3, 1);
    console.log(`Datos de la quincena: ${quincena.length} registros`);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

example();

Códigos de Respuesta

Código Descripción
200 Solicitud exitosa
400 Solicitud incorrecta
401 No autorizado (API key inválida)
403 Prohibido (firma/timestamp inválido)
404 Endpoint no encontrado
429 Demasiadas solicitudes
500 Error interno del servidor

Buenas Prácticas

Soporte

© 2025 Transagro - API. Todos los derechos reservados.