Documentación API TMS

Esta documentación describe los endpoints disponibles de la API de TMS (FastTrack) para la gestión de operaciones logísticas.

URL Base: https://fasttrack.proteus.com.ar/api/tms

Esta URL es el punto de entrada para todas las APIs de TMS.

Convención de parámetros:
  • Los campos indicados con el comentario // Requerido son obligatorios y deben enviarse en la solicitud.
  • Los campos indicados con el comentario // Opcional pueden omitirse o enviarse vacíos según corresponda.

Estructura de la URL y el ambiente

La estructura general de la URL para los endpoints de TMS es:

https://fasttrack.proteus.com.ar/api/{ambiente}/tms/{endpoint}

Donde:

  1. {ambiente}:
    • Es un segmento OPCIONAL que identifica un ambiente específico de FastTrack (ej: "prod/").
    • Si se usa, DEBE terminar con una barra (/).
    • Ejemplo: prod/
  2. {endpoint}:
    • Es el path específico del endpoint de FastTrack al que se desea acceder, tal como lo define la API original.
    • Ejemplos: v2/guias, v2/seguimiento, v2/unigis-estados.

Ejemplos de URL completas:

A. Sin especificar ambiente (usa el ambiente por defecto y):

  • Crear Guía: https://fasttrack.proteus.com.ar/api/tms/v2/guias
  • Consultar Localidades: https://fasttrack.proteus.com.ar/api/tms/v2/localidades

B. Especificando ambiente (ejemplo: "prod/"):

  • Crear Guía: https://fasttrack.proteus.com.ar/api/prod/tms/v2/guias
  • Consultar Provincias: https://fasttrack.proteus.com.ar/api/prod/tms/v2/provincias

Uso del Token de Autenticación (Bearer Token)

Para acceder a los endpoints de TMS, DEBES autenticarte con un Bearer Token generado por nuestro sistema, no con el api_token de FastTrack.

El sistema se encargará de inyectar el api_token de FastTrack correspondiente a tu usuario en la solicitud antes de enviarla a la API original.

  1. Obtención del Token:
    • Realiza una solicitud POST a nuestro endpoint de autenticación: https://fasttrack.proteus.com.ar/api/auth/login (o con prefijo de ambiente si aplica).
    • Envía username y password en el cuerpo de la solicitud (como application/x-www-form-urlencoded).
    • Si las credenciales son válidas, la respuesta JSON contendrá un access_token dentro del objeto result.
  2. Uso del Token en Solicitudes Posteriores:
    • Para TODAS las solicitudes a los endpoints de TMS, DEBES incluir el access_token obtenido.
  3. Método de Inclusión (Encabezado Authorization):
    • La forma estándar y requerida es incluir el token en el encabezado (Header) Authorization de la solicitud HTTP, utilizando el esquema Bearer.
    • Formato del encabezado: 
      Authorization: Bearer {tu_access_token_obtenido}
      (Reemplaza {tu_access_token_obtenido} con el token real).
Importante:

Si no incluyes un access_token válido en el encabezado Authorization, la API responderá con un error de "No autorizado" (generalmente código de estado HTTP 401).

Asegúrate de que el usuario asociado a tu Bearer Token tenga configurado un tms_api_token válido en nuestro sistema para que las llamadas a FastTrack sean exitosas.

Endpoints de TMS

Información Base

POST /v1/public/servicios.json

Consulta el catálogo de servicios de entrega habilitados y disponibles para la cuenta según la sucursal de origen y el código postal de destino.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "sucursal": "9001", // Requerido: Código de sucursal del cliente
    "servicio": "", // Requerido: Código específico o vacío para listar todos
    "cp_entrega": "1884", // Opcional: Código postal del comprador
    "tiempo": "", // Opcional: Tiempo de entrega a filtrar
    "destino": "" // Opcional: Destino a filtrar
}
Response (éxito): 
[
    {
        "id": 16,
        "cod_serv": "007",
        "descripcion": "00HS"
    },
    {
        "id": 9,
        "cod_serv": "003",
        "descripcion": "72HS"
    },
    {
        "id": 11,
        "cod_serv": "004",
        "descripcion": "STD"
    }
]
Response (error): 
{
    "message": "Error al consultar servicios"
}
200: Éxito 400: Parámetro inválido 401: No autorizado 500: Usuario no encontrado

POST /v1/public/precios.json

Calcula el precio de un envío en base a sucursal, CP de entrega, servicio y dimensiones de bultos.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "sucursal": "9999", // Requerido: Código de sucursal
    "servicio": "004", // Requerido: Código del servicio a cotizar
    "cp_entrega": "1001", // Opcional: CP destino
    "tiempo": "", // Opcional
    "destino": "", // Opcional
    "productos": [
        {
            "bultos": "1", // Requerido: Cantidad de bultos
            "peso": "1.5", // Requerido: Peso en kg
            "descripcion": "prueba precios", // Requerido: Descripción de la carga
            "dimensiones": {
                "alto": 0.25,
                "largo": 0.25,
                "profundidad": 0.25
            }
        }
    ]
}
Response (éxito): 
{
    "total": 200
}
Response (error): 
{
    "message": "Error al calcular precio"
}
200: Éxito 400: Parámetro inválido 401: No autorizado 500: Error interno

POST /v1/public/solicitarRetiro.json

Registra la solicitud de recolección en una sucursal para envíos generados previamente.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "sucursal": "75", // Requerido: Código de sucursal
    "fecha": "06/01/2026", // Requerido: Fecha de retiro (DD/MM/YYYY)
    "calle": "Mariano Ferreyra", // Requerido: Calle del retiro
    "altura": "302", // Requerido: Altura de la calle
    "piso": "PB", // Opcional: Piso
    "dpto": "-", // Opcional: Departamento
    "localidad": "Avellaneda", // Requerido: Localidad
    "provincia": "Buenos Aires", // Requerido: Provincia
    "cp": "1870", // Requerido: Código postal numérico
    "contacto": "expediciones", // Requerido: Persona de contacto
    "telefono": "08108883278", // Opcional: Teléfono de contacto
    "mail": "expediciones@fasttrack.com.ar", // Opcional: Correo de contacto
    "franja": "POR LA TARDE", // Requerido: POR LA MAÑANA / TODO EL DIA / POR LA TARDE
    "peso": "10", // Requerido: Peso total aproximado
    "bultos": "9", // Requerido: Total de bultos a retirar
    "observaciones": "Prueba solicitud retiro" // Opcional: Aclaraciones sobre la carga
}
Response (éxito): 
{
    "status": "ok",
    "message": "Retiro guardado Correctamente. Fecha de Retiro: 06/01/2026 POR LA TARDE Nro Retiro: 178632"
}
Response (error): 
{
    "message": "Error al procesar solicitud de retiro"
}
200: Éxito 400: Datos incompletos o inválidos 500: Error interno

POST /v2/dummy-test

Verifica el estado y conectividad con la API externa de FastTrack.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "api_token": "aca va el valor token" // Requerido
}
Response (éxito): 
{
    "success": true,
    "message": "API is working"
}
Response (error): 
{
    "success": false,
    "message": "Error en la API",
    "error_details": "..."
}
200: Éxito 401: No autorizado 403: api_token no configurado 500: Error interno

POST /v2/localidades

Consulta la base de códigos postales (CP) y localidades.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "api_token": "aca va el valor token" // Requerido
}
Response (éxito): 
{
    "success": true,
    "localidades": []
}
Response (error): 
{
    "success": false,
    "message": "Error al consultar localidades",
    "error_details": "..."
}
200: Éxito 401: No autorizado 403: api_token no configurado 500: Error interno

POST /v2/provincias

Consulta la base de provincias.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "api_token": "aca va el valor token" // Requerido
}
Response (éxito): 
{
    "success": true,
    "provincias": []
}
Response (error): 
{
    "success": false,
    "message": "Error al consultar provincias",
    "error_details": "..."
}
200: Éxito 401: No autorizado 403: api_token no configurado 500: Error interno
Gestión de Guías

POST /v2/guias.json

Genera una nueva guía de envío. Valida destino, comprador y composición de paquetes.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "codigo_sucursal": "1696873977", // Requerido: Código de sucursal
    "codigo_servicio": "004", // Requerido: Código de servicio
    "tiempo": "", // Opcional: Tiempo estimado
    "destino": "", // Opcional: Destino
    "fragil": "false", // Requerido: true / false
    "envio_segurizado": "true", // Opcional: Código de seguridad en entrega
    "palabra_clave": "", // Opcional: Palabra clave para entrega
    "remito": "001112", // Opcional: Número de remito
    "guia_agente": "222", // Opcional: Segundo remito / guía externa
    "fob": "", // Opcional: Valor FOB para aduana
    "internacional": "false", // Requerido: Si el origen es exterior
    "valor_declarado": "0", // Requerido: Valor declarado para el seguro
    "volumetrico_estimado": "16290.70", // Opcional: Volumen estimado
    "isInversa": "false", // Requerido: false para entrega normal
    "observaciones": "prueba API V2", // Opcional: Comentarios adicionales
    "codigo_ceco": "", // Opcional: Centro de costo
    "contrareembolso": "0", // Opcional: Monto a cobrar en entrega
    "cobro_efectivo": "0", // Opcional: Importe efectivo
    "cobro_cheque": "0", // Opcional: Importe cheque
    "precinto": "", // Opcional: Número de precinto
    "pago_en": "ORIGEN", // Requerido: "ORIGEN" o "DESTINO"
    "tipo_operacion": "ENTREGA PAQUETERIA", // Requerido: ENTREGA, RETIRO, ENTREGA PAQUETERIA, etc.
    "is_urgente": "false", // Requerido: Indica urgencia
    "valida_stock": "false", // Opcional: No disponible por el momento
    "canal": "", // Opcional: Canal de venta
    "comprador": {
        "empresa": "Fasttrack", // Requerido: Razón social o "Particular"
        "destinatario": "Cristian Escudero", // Requerido: Nombre y apellido destinatario
        "horario": "", // Opcional: Rango horario
        "calle": "Mariano Ferreyra", // Requerido: Calle de destino
        "altura": "302", // Requerido: Altura / número
        "piso": "", // Opcional: Piso
        "dpto": "", // Opcional: Departamento
        "localidad": "Avellaneda", // Requerido: Localidad
        "provincia": "BUENOS AIRES", // Requerido: Provincia
        "info_adicional_1": "obs1", // Opcional: Observación 1
        "info_adicional_2": "obs2", // Opcional: Observación 2
        "info_adicional_3": "obs3", // Opcional: Observación 3
        "info_adicional_4": "obs4", // Opcional: Observación 4
        "info_adicional_5": "observacion vieja", // Opcional: Observación 5
        "cp": "1001", // Requerido: Código postal destino
        "email": "", // Opcional: Email destinatario
        "celular": "+5491111111111", // Opcional: Teléfono celular
        "cuit": "", // Opcional: CUIT/DNI
        "contenido": "", // Opcional: Contenido
        "latitud": "", // Opcional: Coordenadas
        "longitud": "" // Opcional: Coordenadas
    },
    "productos": [
        {
            "bultos": "2", // Requerido: Cantidad de bultos
            "peso": "2", // Requerido: Peso en kg
            "descripcion": "Caja de zapatos roja", // Requerido: Descripción del producto
            "dimensiones": {
                "alto": "0.25", // Opcional: Alto
                "largo": "0.25", // Opcional: Largo
                "profundidad": "0.25" // Opcional: Profundidad
            }
        }
    ]
}
Response (éxito): 
{
    "guia": 101851884,
    "importe": 500,
    "sub_zona_destino": "CABA",
    "remito": "0019",
    "zona": "ZONA A"
}
Response (error): 
{
    "message": "Error al crear la guía o parámetros inválidos"
}
200: Éxito 400: Datos inválidos 401: No autorizado 403: api_token no configurado 500: Error interno

POST /v2/guias.json (Inversa)

Crea una guía de Logística Inversa (recolección en el domicilio del comprador para devolver al vendedor). Aclaración: Debe enviarse isInversa=true, tipo_operacion="RETIRO" y diferenciar el remito para no duplicar el original (ej: "D0011250819").

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "tipo_operacion": "RETIRO", // Requerido
    "pago_en": "ORIGEN", // Requerido
    "is_urgente": "0", // Requerido
    "codigo_sucursal": "7453", // Requerido
    "cp": "1074", // Opcional
    "codigo_servicio": "004", // Requerido
    "fragil": "0", // Requerido
    "franja": "tarde", // Opcional
    "remito": "", // Opcional
    "guiaAgente": "", // Opcional
    "bultos": "1", // Opcional
    "fob": "0", // Opcional
    "internacional": "false", // Requerido
    "valorDeclarado": "0", // Requerido
    "isInversa": "true", // Requerido
    "observaciones": "prueba para UPS", // Opcional
    "ceco": "", // Opcional
    "comprador": {
        "empresa": "fasttrack", // Opcional
        "destinatario": "LEONARDO OLIBERA", // Opcional
        "calle": "MARIANO FERREYRA", // Requerido
        "altura": "302", // Requerido
        "piso": "", // Opcional
        "dpto": "", // Opcional
        "localidad": "AVELLANEDA", // Requerido
        "provincia": "BUENOS AIRES", // Requerido
        "info_adicional_5": "DESESTIMAR", // Opcional
        "cp": "1868", // Requerido
        "email": "", // Opcional
        "celular": "53746449", // Opcional
        "cuit": "", // Opcional
        "contenido": "" // Opcional
    },
    "productos": [
        {
            "bultos": "2", // Requerido
            "tipo": "4", // Opcional
            "peso": "50", // Requerido
            "descripcion": "", // Requerido
            "dimensiones": {
                "alto": "310", // Opcional
                "largo": "20", // Opcional
                "profundidad": "50" // Opcional
            }
        }
    ]
}
Response (éxito): 
{
    "guia": 101851885,
    "importe": 500,
    "remito": "D0019",
    "zona": "ZONA A"
}
Response (error): 
{
    "success": false,
    "message": "Error al crear guía inversa",
    "errors": []
}
200: Éxito 400: Datos inválidos 401: No autorizado 403: api_token no configurado 500: Error interno
Seguimiento y Estados

POST /v2/seguimiento.json

Consulta el seguimiento de un paquete por remito de cliente o por número de guía FastTrack.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "remito": "", // Requerido (remito o nro_guia)
    "nro_guia": "101556064" // Requerido (remito o nro_guia)
}
Response (éxito): 
{
    "status": "ok",
    "guia": {
        "fechas": [
            {
                "fecha": "01/09/2022",
                "hora": "15:25",
                "estado": "Solicitud Confirmada",
                "codigo_estado": 41
            }
        ]
    }
}
Response (error): 
{
    "status": "error",
    "message": "Guía no encontrada"
}
200: Éxito 404: Pieza no encontrada 500: Error interno

POST /v1/public/tracking.json

Consulta el histórico de tracking por número de pieza/guía.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "tracking": "101556064" // Requerido: Número de pieza
}
Response (éxito): 
{
    "status": "ok",
    "data": {
        "tracker": {
            "historico": [
                {
                    "estado_codigo": "SC",
                    "estado": "Solicitud Confirmada",
                    "detalles": "INGRESO POR API"
                }
            ]
        }
    }
}
Response (error): 
{
    "message": "Error al consultar tracking"
}
200: Éxito 404: Guía no encontrada 500: Error interno

POST /v2/getInfoGuia

Obtiene la ficha técnica y comercial completa de un envío a partir de su número de guía FastTrack.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "nro_guia": "102070450" // Requerido: Número de guía
}
Response (éxito): 
{
    "guia": {
        "id": 102070450,
        "cliente": "EMPRESA PRUEBA IT",
        "remito": "R0013-00001284",
        "estado": "Guía Emitida",
        "peso": 6,
        "bultos": 2,
        "precio": 9048.7
    }
}
Response (error): 
{
    "message": "Guía no encontrada"
}
200: Éxito 404: Guía no encontrada 500: Error interno

POST /v2/getFullTracking.json

Devuelve el historial completo de entrega, datos del receptor, DNI, junto con la firma digital y la fotografía del comprobante de entrega.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "nro_guia": "102088855" // Requerido: Número de guía
}
Response (éxito): 
{
    "status": "ok",
    "datos": [
        {
            "estado_codigo": "POD",
            "estado": "Entregado",
            "receptor_nombre": "Martin Gattelet",
            "dni": "33880703"
        }
    ],
    "firma": "https://fasttracklv.epresis.com/uploadfirma/2024/04/102088855-662a7ca3c423f.jpg",
    "foto": "https://fasttracklv.epresis.com/fotos/2024/04/102088855-1714060449662a7ca1df479-(0)0.jpg"
}
Response (error): 
{
    "message": "Guía no encontrada o sin datos de entrega"
}
200: Éxito 404: No encontrado 500: Error interno

POST /v2/cambio-estado

Registra un cambio de estado manual para una guía o remito.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "receptor_fecha_hora": "23-10-2023", // Requerido
    "estado_id": "39", // Requerido
    "retiro_id": "", // Requerido (remito_nro o retiro_id)
    "remito_nro": "FTC141827", // Requerido (remito_nro o retiro_id)
    "receptor_fecha_hora_hora": "16:32:00", // Opcional
    "nombre": "Pepe", // Opcional
    "apellido": "Arduo", // Opcional
    "dni": "35694972", // Opcional
    "detalles": "prueba api estado", // Opcional
    "lat": "-32.9241431", // Opcional
    "lon": "-68.7951929", // Opcional
    "firma": "",
    "imagenes": [
        ""
    ]
}
Response (éxito): 
{
    "success": true,
    "message": "Estado actualizado correctamente"
}
Response (error): 
{
    "success": false,
    "message": "Error al cambiar estado",
    "errors": []
}
200: Éxito 400: Datos inválidos 401: No autorizado 403: api_token no configurado 500: Error interno
Impresión de Etiquetas

POST /v1/public/print_guias.json

Genera e imprime el remito oficial en hoja A4 en formato PDF (codificado en Base64).

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "ids": "101556064" // Requerido: ID numérico de la guía
}
Response (éxito): 
{
    "pdf_base64": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSA8RkVGRjAwNDQwMDZGMDA2MzAwNzUwMDZ..."
}
Response (error): 
{
    "message": "Error al generar remito A4"
}
200: Éxito 400: Parámetro inválido 500: Error interno

POST /v1/public/print_etiquetas.json

Genera etiquetas estándar en formato 10x15 cm en PDF codificado en Base64.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "ids": "101556064" // Requerido: ID numérico de la guía
}
Response (éxito): 
{
    "pdf_base64": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSA8RkVGRjAwNDQwMDZGMDA2MzAwNzUwMDZ..."
}
Response (error): 
{
    "message": "Error al generar etiquetas"
}
200: Éxito 400: Datos inválidos 500: Error interno

POST /v2/print-etiquetas-custom

Imprime etiquetas térmicas 10x15 separadas por bulto (Bulto 1/X, 2/X) o asociadas al remito de cliente.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "nombre": "ETIQUETA_10X15_BULTOS_FASTTRACK", // Requerido: Nombre de la plantilla ("ETIQUETA_10X15_BULTOS_FASTTRACK" o "ETIQUETA_10X15_FASTTRACK_PDF")
    "ides": [
        "1383653015276-01" // Requerido: Array con número de guía o remito
    ],
    "tipo": "fixed", // Requerido: Tipo de formato
    "is_remito": "true" // Requerido: true si se envía remito, false si es ID guía
}
Response (éxito): 
{
    "pdf_base64": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSA8RkVGRjAwNDQwMDZGMDA2MzAwNzUwMDZ..."
}
Response (error): 
{
    "message": "Error al generar etiquetas personalizadas"
}
200: Éxito 400: Datos inválidos 500: Error interno

POST /api/v1/public/print-etiquetas

Genera etiquetas (versión 1 pública de la API).

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "ids": "103632749" // Requerido
}
Response (éxito): 
{
    "success": true,
    "pdf_base64": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSA8RkVGRjAwNDQwMDZGMDA2MzAwNzUwMDZ..."
}
Response (error): 
{
    "success": false,
    "message": "Error al generar etiquetas V1",
    "error_details": "..."
}
200: Éxito 400: Datos inválidos 401: No autorizado 403: api_token no configurado 500: Error interno
Integraciones y Webhooks

POST /v2/integracion.json

Registra o configura un webhook para recibir notificaciones automáticas por cada cambio de estado de las piezas. Tu servidor receptor debe responder con código HTTP 200.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "url": "https://help.epresis.com", // Requerido: URL donde recibir el callback
    "notificacion": "true", // Requerido: true para activar
    "usuario": "Presis", // Requerido: Nombre de usuario/integrador
    "sucursal": "SUCU225" // Requerido: Código de sucursal asociada
}
Response (éxito): 
{
    "success": true,
    "message": "Webhook configurado correctamente"
}
Response (error): 
{
    "message": "Error al configurar webhook"
}
200: Éxito 400: Datos inválidos 500: Error interno

POST /v2/unigis-estados

Endpoint para la integración de estados con el sistema Unigis.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "Recorrido_ID": "232122", // Requerido
    "Login": "test@test.com", // Requerido
    "Password": "test", // Requerido
    "Retiro_ID": "1034481692", // Requerido
    "estado_codigo": "POD", // Requerido
    "FechaCreacion": "2025-01-07T19:13:36", // Requerido
    "Latitud": "-34.6593", // Opcional
    "Longitud": "-58.379",
    "Nombre": "Nicolas",
    "Apellido": "Santoro",
    "DNI": "11111111",
    "Detalles": "asd",
    "Firma": "/9j/4AAQSkZJRgABAQAAAQABAAD/8bX53dnbBVbsxLyR2Wk//2Q==",
    "Fotografias": [
        "/9j/4AAQSkZJRgABAQAAAQABAAD/4gHYSUNDX1BST0ZJTEUAAQEAAAHIAAAAAAQwAABtbnRyUkdCIFhZWiAH4AABAAEAAAAAAABhY3NwAAAAAAAAAAAAAAAAAAAAA2Q=="
    ]
}
Response (éxito): 
{
    "success": true,
    "message": "Estado Unigis procesado"
}
Response (error): 
{
    "success": false,
    "message": "Error al procesar estado Unigis",
    "error_details": "..."
}
200: Éxito 400: Datos inválidos 401: No autorizado 403: api_token no configurado 500: Error interno