API de Integración - ADN Nómina | Documentación para Desarrolladores

Inicio Rápido

La API de ADN Nómina te permite integrar nuestro sistema de gestión de nóminas con tus aplicaciones empresariales. Utiliza autenticación basada en API keys y devuelve respuestas en formato JSON.

Requisitos Previos

Para usar la API necesitas una cuenta activa de ADN Nómina y generar una clave API desde tu panel de administración.

Autenticación

Todos los endpoints requieren autenticación mediante API key. Incluye tu clave API en el header X-Api-Key de cada solicitud.

Header de Autenticación

X-Api-Key: YOUR_API_KEY

URL Base

http://nominadn.test/integration

Nóminas

GET /nominas

Obtiene todas las nóminas cerradas que no han sido contabilizadas, agrupadas por período.

Ejemplo de Solicitud

cURL

curl -X GET http://nominadn.test/integration/nominas \
  -H "X-Api-Key: YOUR_API_KEY"

Respuesta Exitosa (200)

{
  "data": [
    {
      "id": 1,
      "numero": "20250101001",
      "tipodoc_codigo": "NOM",
      "periodo": "2025-01",
      "tipo_nomina_id": 1,
      "total": "45000.00",
      "total_cestaticket": "2500.00",
      "tipo_nomina": {
        "id": 1,
        "nombre": "NOMINA QUINCENAL",
        "codigo": "NQ",
        "descripcion": "Nomina quincenal de empleados",
        "created_at": "2024-12-20T14:30:00.000000Z",
        "updated_at": "2024-12-20T14:30:00.000000Z"
      }
    }
  ]
}

GET /nominas/{numeroDocumento}

Obtiene el detalle completo de una nómina específica incluyendo todos sus movimientos.

Parámetros de URL

Parámetro	Tipo	Descripción
`numeroDocumento`	string	Número del documento de nómina

Ejemplo de Solicitud

cURL

curl -X GET http://nominadn.test/integration/nominas/NOM-2025-001 \
  -H "X-Api-Key: YOUR_API_KEY"

Respuesta Exitosa (200)

{
  "data": [
    {
      "id": 1,
      "numero": "20250101001",
      "tipodoc_codigo": "NOM",
      "periodo": "2025-01",
      "trabajador_id": 1,
      "trabajador": {
        "id": 1,
        "numero_documento": "12345678",
        "nombres": "JUAN CARLOS",
        "apellidos": "PEREZ GONZALEZ",
        "email": "juan.perez@empresa.com",
        "telefono": "+58 276 123 4567",
        "cargo": "Desarrollador Senior",
        "departamento": "Tecnología",
        "fecha_ingreso": "2023-01-15",
        "salario_base": "1500.00",
        "status": "activo"
      },
      "movimientos": [
        {
          "id": 1,
          "concepto_codigo": "S001",
          "concepto_nombre": "SALARIO BASE",
          "monto": "1500.00",
          "tipo": "asignacion",
          "fecha": "2025-01-01",
          "descripcion": "Salario base mensual"
        },
        {
          "id": 2,
          "concepto_codigo": "D001",
          "concepto_nombre": "ISLR",
          "monto": "150.00",
          "tipo": "deduccion",
          "fecha": "2025-01-01",
          "descripcion": "Impuesto sobre la renta"
        },
        {
          "id": 3,
          "concepto_codigo": "A002",
          "concepto_nombre": "BONO ALIMENTACION",
          "monto": "200.00",
          "tipo": "asignacion",
          "fecha": "2025-01-01",
          "descripcion": "Bono de alimentación"
        }
      ],
      "total_asignaciones": "1700.00",
      "total_deducciones": "150.00",
      "neto_a_pagar": "1550.00"
    }
  ]
}

Respuesta de Error (404)

{
  "message": "No se encontraron trabajadores con ese documento.",
  "errors": {
    "documentos_abiertos": ["No se encontraron trabajadores con ese documento."]
  }
}

POST /nominas/contabilizar

Marca una o varias nóminas como contabilizadas en el sistema.

Parámetros del Body

Parámetro	Tipo	Requerido	Descripción
`documentos`	array	Sí	Array de documentos a contabilizar
`documentos.*.numero`	string	Sí	Número del documento
`documentos.*.tipodoc_codigo`	string	Sí	Código del tipo de documento

Ejemplo de Solicitud

cURL

curl -X POST http://nominadn.test/integration/nominas/contabilizar \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "documentos": [
      {
        "numero": "20250101001",
        "tipodoc_codigo": "NOM"
      },
      {
        "numero": "20250101002",
        "tipodoc_codigo": "NOM"
      }
    ]
  }'

Respuesta Exitosa (200)

{
  "message": "Proceso completado.",
  "actualizados": 2,
  "no_encontrados": 0,
  "detalles_no_encontrados": []
}

Respuesta con Errores (200)

{
  "message": "Proceso completado.",
  "actualizados": 1,
  "no_encontrados": 1,
  "detalles_no_encontrados": [
    {
      "numero": "NOM-2025-999",
      "tipodoc_codigo": "NOM"
    }
  ]
}

Ejemplos de Integración

JavaScript/Node.js

JavaScript

const API_BASE = 'http://nominadn.test/integration';
const API_KEY = 'your-api-key-here';

async function obtenerNominas() {
  try {
    const response = await fetch(`${API_BASE}/nominas`, {
      headers: {
        'X-Api-Key': API_KEY,
        'Content-Type': 'application/json'
      }
    });
    
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    
    const data = await response.json();
    console.log('Nóminas:', data.data);
    return data.data;
  } catch (error) {
    console.error('Error al obtener nóminas:', error);
  }
}

async function contabilizarNominas(documentos) {
  try {
    const response = await fetch(`${API_BASE}/nominas/contabilizar`, {
      method: 'POST',
      headers: {
        'X-Api-Key': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ documentos })
    });
    
    const result = await response.json();
    console.log('Resultado:', result);
    return result;
  } catch (error) {
    console.error('Error al contabilizar:', error);
  }
}

PHP

apiKey = $apiKey;
    }
    
    private function makeRequest($endpoint, $method = 'GET', $data = null) {
        $ch = curl_init();
        
        curl_setopt_array($ch, [
            CURLOPT_URL => $this->baseUrl . $endpoint,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => [
                'X-Api-Key: ' . $this->apiKey,
                'Content-Type: application/json'
            ]
        ]);
        
        if ($method === 'POST' && $data) {
            curl_setopt($ch, CURLOPT_POST, true);
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        }
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        
        return [
            'code' => $httpCode,
            'data' => json_decode($response, true)
        ];
    }
    
    public function obtenerNominas() {
        return $this->makeRequest('/nominas');
    }
    
    public function obtenerNomina($numeroDocumento) {
        return $this->makeRequest('/nominas/' . $numeroDocumento);
    }
    
    public function contabilizarNominas($documentos) {
        return $this->makeRequest('/nominas/contabilizar', 'POST', [
            'documentos' => $documentos
        ]);
    }
}

// Uso
$api = new ADNNominaAPI('your-api-key-here');
$nominas = $api->obtenerNominas();
?>

Códigos de Error

La API utiliza códigos de estado HTTP estándar para indicar el éxito o fallo de las solicitudes.

200

OK

La solicitud fue exitosa.

201

Created

El recurso fue creado exitosamente.

401

Unauthorized

API key inválida o faltante.

404

Not Found

El recurso solicitado no fue encontrado.

422

Unprocessable Entity

Los datos enviados no son válidos.

500

Internal Server Error

Error interno del servidor.

Formato de Respuesta de Error

{
  "message": "Error al procesar la solicitud.",
  "errors": {
    "campo": ["Descripción del error específico"]
  }
}

Soporte

Si necesitas ayuda con la integración de la API, nuestro equipo técnico está disponible para asistirte.

Email de Soporte

soporte@sistemasadn.com

Teléfono

+58 276 356 0389

Horario de Atención

Lunes a Viernes: 8:00 AM - 6:00 PM (GMT-4)