Documentación API de AeroFan

Bienvenido a la documentación de la API de AeroFan Digital Courier. Esta API te permite integrar nuestros servicios de courier internacional directamente en tu aplicación, sitio web o sistema de gestión.

Gestión de envíos

Crea, consulta y gestiona envíos internacionales desde tu aplicación.

Validación de identidad

Verifica la identidad de tus usuarios para cumplir con requisitos aduaneros.

Cotizaciones en tiempo real

Obtén cotizaciones instantáneas para envíos internacionales.

Versiones de la API

La versión actual de la API es v1. Todas las URLs comienzan con https://api.aerofan.com.ar/v1/.

Base URL

https://api.aerofan.com.ar/v1/

Autenticación

La API de AeroFan utiliza claves API para autenticar las solicitudes. Puedes obtener tu clave API desde el panel de control de tu cuenta.

Autenticación mediante Bearer Token

Incluye tu clave API en el encabezado Authorization de todas tus solicitudes:

Header de autenticación

Authorization: Bearer YOUR_API_KEY

Seguridad de la API Key

Mantén tu clave API segura y no la incluyas en código del lado del cliente. Utiliza variables de entorno o servicios de gestión de secretos para almacenarla.

Envíos

Los endpoints de envíos te permiten crear, consultar y gestionar envíos internacionales.

POST/shipments

Crea un nuevo envío internacional

Parámetros

Nombre	Tipo	Requerido	Descripción
origin	string	Sí	Código ISO del país de origen (ej. US, CN)
destination	string	Sí	Código ISO del país de destino (ej. AR)
packages	array	Sí	Array de objetos con información de los paquetes
recipient	object	Sí	Información del destinatario
service_type	string	No	Tipo de servicio (standard, express, priority)

Respuestas

201Envío creado exitosamente

Ejemplo de respuesta

{
  "id": "ship_12345678",
  "status": "created",
  "tracking_number": "AF123456789AR",
  "estimated_delivery": "2025-04-15T00:00:00Z",
  "origin": "US",
  "destination": "AR",
  "packages": [
    {
      "id": "pkg_87654321",
      "weight": 1.5,
      "dimensions": {
        "length": 30,
        "width": 20,
        "height": 10
      },
      "description": "Productos electrónicos"
    }
  ],
  "recipient": {
    "name": "Juan Pérez",
    "document": "30123456",
    "address": "Av. Corrientes 1234",
    "city": "Buenos Aires",
    "postal_code": "1043"
  },
  "created_at": "2025-04-08T12:00:00Z"
}

400Datos inválidos

Ejemplo de respuesta

{
  "error": {
    "code": "invalid_request",
    "message": "Los datos proporcionados son inválidos",
    "details": [
      {
        "field": "packages",
        "message": "Se requiere al menos un paquete"
      }
    ]
  }
}

GET/shipments/{id}

Obtiene información detallada de un envío

Parámetros

Nombre	Tipo	Requerido	Descripción
id	string	Sí	ID único del envío

Respuestas

200Información del envío

Ejemplo de respuesta

{
  "id": "ship_12345678",
  "status": "in_transit",
  "tracking_number": "AF123456789AR",
  "estimated_delivery": "2025-04-15T00:00:00Z",
  "origin": "US",
  "destination": "AR",
  "packages": [
    {
      "id": "pkg_87654321",
      "weight": 1.5,
      "dimensions": {
        "length": 30,
        "width": 20,
        "height": 10
      },
      "description": "Productos electrónicos"
    }
  ],
  "recipient": {
    "name": "Juan Pérez",
    "document": "30123456",
    "address": "Av. Corrientes 1234",
    "city": "Buenos Aires",
    "postal_code": "1043"
  },
  "tracking_events": [
    {
      "status": "created",
      "location": "Miami, FL",
      "timestamp": "2025-04-08T12:00:00Z",
      "description": "Envío creado"
    },
    {
      "status": "in_transit",
      "location": "Miami International Airport",
      "timestamp": "2025-04-09T08:30:00Z",
      "description": "En tránsito hacia Argentina"
    }
  ],
  "created_at": "2025-04-08T12:00:00Z",
  "updated_at": "2025-04-09T08:30:00Z"
}

404Envío no encontrado

Ejemplo de respuesta

{
  "error": {
    "code": "not_found",
    "message": "El envío solicitado no existe"
  }
}

GET/shipments

Lista todos los envíos

Parámetros

Nombre	Tipo	Requerido	Descripción
limit	integer	No	Número máximo de resultados (default: 20, max: 100)
offset	integer	No	Número de resultados a omitir (para paginación)
status	string	No	Filtrar por estado (created, in_transit, delivered, etc.)

Respuestas

200Lista de envíos

Ejemplo de respuesta

{
  "data": [
    {
      "id": "ship_12345678",
      "status": "in_transit",
      "tracking_number": "AF123456789AR",
      "origin": "US",
      "destination": "AR",
      "created_at": "2025-04-08T12:00:00Z"
    },
    {
      "id": "ship_87654321",
      "status": "delivered",
      "tracking_number": "AF987654321AR",
      "origin": "CN",
      "destination": "AR",
      "created_at": "2025-04-01T10:30:00Z"
    }
  ],
  "meta": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

Cotizaciones

Los endpoints de cotizaciones te permiten obtener precios estimados para envíos internacionales.

POST/quotes

Obtiene una cotización para un envío internacional

Parámetros

Nombre	Tipo	Requerido	Descripción
origin	string	Sí	Código ISO del país de origen (ej. US, CN)
destination	string	Sí	Código ISO del país de destino (ej. AR)
packages	array	Sí	Array de objetos con información de los paquetes
service_type	string	No	Tipo de servicio (standard, express, priority)

Respuestas

200Cotización obtenida exitosamente

Ejemplo de respuesta

{
  "price": 125.50,
  "currency": "USD",
  "estimated_delivery": "2025-04-18T00:00:00Z",
  "taxes": 15.25,
  "insurance": 2.50,
  "service_type": "express"
}

400Datos inválidos

Ejemplo de respuesta

{
  "error": {
    "code": "invalid_request",
    "message": "Los datos proporcionados son inválidos",
    "details": [
      {
        "field": "packages",
        "message": "Se requiere al menos un paquete"
      }
    ]
  }
}

Usuarios

Los endpoints de usuarios te permiten gestionar la información de tus clientes.

POST/users

Crea un nuevo usuario

Parámetros

Nombre	Tipo	Requerido	Descripción
first_name	string	Sí	Nombre del usuario
last_name	string	Sí	Apellido del usuario
email	string	Sí	Correo electrónico del usuario
document_type	string	Sí	Tipo de documento (DNI, PASSPORT, etc.)
document_number	string	Sí	Número de documento

Respuestas

201Usuario creado exitosamente

Ejemplo de respuesta

{
  "id": "user_12345678",
  "first_name": "Juan",
  "last_name": "Pérez",
  "email": "juan.perez@example.com",
  "document_type": "DNI",
  "document_number": "30123456",
  "created_at": "2025-04-08T12:00:00Z"
}

400Datos inválidos

Ejemplo de respuesta

{
  "error": {
    "code": "invalid_request",
    "message": "Los datos proporcionados son inválidos",
    "details": [
      {
        "field": "email",
        "message": "El correo electrónico no es válido"
      }
    ]
  }
}

GET/users/{id}

Obtiene información detallada de un usuario

Parámetros

Nombre	Tipo	Requerido	Descripción
id	string	Sí	ID único del usuario

Respuestas

200Información del usuario

Ejemplo de respuesta

{
  "id": "user_12345678",
  "first_name": "Juan",
  "last_name": "Pérez",
  "email": "juan.perez@example.com",
  "document_type": "DNI",
  "document_number": "30123456",
  "created_at": "2025-04-08T12:00:00Z"
}

404Usuario no encontrado

Ejemplo de respuesta

{
  "error": {
    "code": "not_found",
    "message": "El usuario solicitado no existe"
  }
}

Validación de Identidad

Los endpoints de validación de identidad te permiten verificar la identidad de tus usuarios mediante biometría facial y validación de documentos.

POST/identity/validate

Valida la identidad de un usuario mediante biometría facial y documento

Parámetros

Nombre	Tipo	Requerido	Descripción
document_type	string	Sí	Tipo de documento (DNI, PASSPORT, etc.)
document_number	string	Sí	Número de documento
first_name	string	Sí	Nombre del usuario
last_name	string	Sí	Apellido del usuario
selfie_image	string (base64)	Sí	Imagen selfie en formato base64
document_image	string (base64)	Sí	Imagen del documento en formato base64

Respuestas

200Validación exitosa

Ejemplo de respuesta

{
  "validation_id": "val_12345678",
  "status": "verified",
  "confidence_score": 0.98,
  "document_verified": true,
  "face_match": true,
  "official_record_match": true,
  "verification_timestamp": "2025-04-08T14:30:00Z"
}

400Datos inválidos

Ejemplo de respuesta

{
  "error": {
    "code": "invalid_request",
    "message": "Los datos proporcionados son inválidos",
    "details": [
      {
        "field": "selfie_image",
        "message": "La imagen no es válida o no contiene un rostro detectable"
      }
    ]
  }
}

403Validación fallida

Ejemplo de respuesta

{
  "validation_id": "val_12345678",
  "status": "failed",
  "confidence_score": 0.35,
  "document_verified": true,
  "face_match": false,
  "official_record_match": true,
  "verification_timestamp": "2025-04-08T14:30:00Z",
  "failure_reason": "face_mismatch"
}

GET/identity/validations/{id}

Obtiene el resultado de una validación de identidad previa

Parámetros

Nombre	Tipo	Requerido	Descripción
id	string	Sí	ID único de la validación

Respuestas

200Información de la validación

Ejemplo de respuesta

{
  "validation_id": "val_12345678",
  "status": "verified",
  "confidence_score": 0.98,
  "document_verified": true,
  "face_match": true,
  "official_record_match": true,
  "document_type": "DNI",
  "document_number": "30123456",
  "first_name": "Juan",
  "last_name": "Pérez",
  "verification_timestamp": "2025-04-08T14:30:00Z"
}

404Validación no encontrada

Ejemplo de respuesta

{
  "error": {
    "code": "not_found",
    "message": "La validación solicitada no existe"
  }
}