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://proteus.com.ar/api/tms

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

Estructura de la URL y el ambiente

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

https://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, unigis/modificarEstadoUnigis.

Ejemplos de URL completas:

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

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

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

  • Crear Guía: https://proteus.com.ar/api/prod/tms/v2/guias
  • Consultar Provincias: https://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://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 /v2/dummy-test

Verifica el estado de las APIs de FastTrack. No requiere parámetros adicionales más allá del `api_token` inyectado por el sistema.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "api_token": "awVWqBzRGpbVK18tEKWp5S5RquuhmeLRT7AYBNRzWOS0C6FIZrTcwDdkif4Z"
}
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": "awVWqBzRGpbVK18tEKWp5S5RquuhmeLRT7AYBNRzWOS0C6FIZrTcwDdkif4Z"
}
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": "awVWqBzRGpbVK18tEKWp5S5RquuhmeLRT7AYBNRzWOS0C6FIZrTcwDdkif4Z"
}
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

Crea una nueva guía de envío o de logística inversa. El `api_token` es inyectado por el sistema.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "codigo_sucursal": "1696873977",
    "codigo_servicio": "004",
    "tiempo": "",
    "destino": "",
    "fragil": false,
    "envio_segurizado": true,
    "palabra_clave": "",
    "remito": "001112",
    "guia_agente": "222",
    "fob": "",
    "internacional": false,
    "valor_declarado": 0,
    "isInversa": false,
    "observaciones": "prueba API V2",
    "codigo_ceco": "",
    "contrareembolso": 0,
    "cobro_efectivo": 0,
    "cobro_cheque": 0,
    "precinto": "",
    "pago_en": "ORIGEN",
    "tipo_operacion": "ENTREGA PAQUETERIA",
    "is_urgente": false,
    "valida_stock": false,
    "canal": "",
    "comprador": {
        "empresa": "Fasttrack",
        "destinatario": "Cristian Escudero",
        "horario": "",
        "calle": "Mariano Ferreyra",
        "altura": "302",
        "piso": "",
        "dpto": "",
        "localidad": "Aellaneda",
        "provincia": "BUENOS AIRES",
        "info_adicional_1": "obs1",
        "info_adicional_2": "obs2",
        "info_adicional_3": "obs3",
        "info_adicional_4": "obs4",
        "info_adicional_5": "observacion vieja",
        "cp": "1001",
        "email": "",
        "celular": "+5491111111111",
        "cuit": "",
        "contenido": "",
        "latitud": "",
        "longitud": ""
    },
    "productos": [
        {
            "bultos": 2,
            "peso": 2,
            "descripcion": "Caja de zapatos roja",
            "dimensiones": {
                "alto": 0.25,
                "largo": 0.25,
                "profundidad": 0.25
            }
        }
    ]
}
Response (éxito): 
{
    "success": true,
    "id": 101541361,
    "guia": "FTC123456789"
}
Response (error): 
{
    "success": false,
    "message": "Error al crear gu\u00eda",
    "errors": []
}
200: Éxito 400: Datos inválidos 401: No autorizado 403: api_token no configurado 500: Error interno

POST /v2/guias

Crea una guía para logística inversa (retiro). El `api_token` es inyectado por el sistema.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "tipo_operacion": "RETIRO",
    "pago_en": "ORIGEN",
    "is_urgente": 0,
    "codigo_sucursal": "7453",
    "cp": 1074,
    "codigo_servicio": "004",
    "fragil": 0,
    "franja": "tarde",
    "remito": "",
    "guiaAgente": "",
    "bultos": 1,
    "fob": 0,
    "internacional": false,
    "valorDeclarado": 0,
    "isInversa": true,
    "observaciones": "prueba para UPS",
    "ceco": "",
    "comprador": {
        "empresa": "fasttrack",
        "destinatario": "LEONARDO OLIBERA",
        "calle": "MARIANO FERREYRA",
        "altura": 302,
        "piso": "",
        "dpto": "",
        "localidad": "AVELLANEDA",
        "provincia": "BUENOS AIRES",
        "info_adicional_5": "DESESTIMAR",
        "cp": 1868,
        "email": "",
        "celular": "53746449",
        "cuit": "",
        "contenido": ""
    },
    "productos": [
        {
            "bultos": 2,
            "tipo": 4,
            "peso": 50,
            "descripcion": "",
            "dimensiones": {
                "alto": 310,
                "largo": 20,
                "profundidad": 50
            }
        }
    ]
}
Response (éxito): 
{
    "success": true,
    "id": 101541362,
    "guia": "FTC987654321"
}
Response (error): 
{
    "success": false,
    "message": "Error al crear gu\u00eda 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

Consulta el seguimiento de una guía por remito o número de guía de FastTrack. El `api_token` es inyectado por el sistema.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "remito": "S23094",
    "nro_guia": ""
}
Response (éxito): 
{
    "success": true,
    "seguimiento": []
}
Response (error): 
{
    "success": false,
    "message": "Gu\u00eda no encontrada",
    "error_details": "..."
}
200: Éxito 400: Datos inválidos 401: No autorizado 403: api_token no configurado 404: Guía no encontrada 500: Error interno

POST /v2/getInfoGuia

Obtiene información detallada de una guía por su número de guía de FastTrack. El `api_token` es inyectado por el sistema.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "nro_guia": "102692200"
}
Response (éxito): 
{
    "success": true,
    "guia_info": []
}
Response (error): 
{
    "success": false,
    "message": "Gu\u00eda no encontrada",
    "error_details": "..."
}
200: Éxito 400: Datos inválidos 401: No autorizado 403: api_token no configurado 404: Guía no encontrada 500: Error interno

POST /v2/cambioEstado

Registra un cambio de estado para una guía. El `api_token` es inyectado por el sistema.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "receptor_fecha_hora": "23-10-2023",
    "estado_id": 39,
    "retiro_id": "",
    "remito_nro": "FTC141827",
    "receptor_fecha_hora_hora": "16:32:00",
    "nombre": "Pepe",
    "apellido": "Arduo",
    "dni": "35694972",
    "detalles": "prueba api estado",
    "lat": "-32.9241431",
    "lon": "-68.7951929",
    "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 /v2/print_etiquetas_base64

Genera etiquetas en formato Base64 (PDF) para una o varias guías. El `api_token` es inyectado por el sistema.

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

POST /v2/print-etiquetas-custom

Genera etiquetas personalizadas (PDF o HTML) para una o varias guías. El `api_token` es inyectado por el sistema. Nota: Este endpoint de FastTrack puede estar en un dominio diferente (`fasttracklv2.epresis.com`).

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "nombre": "ETIQUETA_10X15_FASTTRACK_PDF",
    "ides": [
        "1695851"
    ],
    "tipo": "fixed",
    "is_remito": true
}
Response (éxito): 
{
    "success": true,
    "pdf_base64": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSA8RkVGRjAwNDQwMDZGMDA2MzAwNzUwMDZ..."
}
Response (error): 
{
    "success": false,
    "message": "Error al generar etiquetas personalizadas",
    "error_details": "..."
}
200: Éxito 400: Datos inválidos 401: No autorizado 403: api_token no configurado 500: Error interno

POST /api/v1/public/print_etiquetas

Genera etiquetas (versión 1 de la API) para una o varias guías. El `api_token` es inyectado por el sistema.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "ids": 103632749
}
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

Configura un webhook para recibir notificaciones de eventos de FastTrack. El `api_token` es inyectado por el sistema.

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "url": "https:\/\/integraciones.lasmargaritas.com.ar\/api\/logisticas\/FastTrack\/actualizacion",
    "notificacion": true,
    "token": "Qmw0emNaeWswV3NrMQ==",
    "usuario": "Margaritas",
    "sucursal": "1720033759"
}
Response (éxito): 
{
    "success": true,
    "message": "Webhook configurado correctamente"
}
Response (error): 
{
    "success": false,
    "message": "Error al configurar webhook",
    "error_details": "..."
}
200: Éxito 400: Datos inválidos 401: No autorizado 403: api_token no configurado 500: Error interno

POST /unigis/modificarEstadoUnigis

Endpoint para la integración de estados con Unigis. Nota: Este endpoint de FastTrack puede estar en un dominio diferente (`fasttracklv2.epresis.com`).

Headers: 
{
    "Authorization": "Bearer {access_token}"
}
Request: 
{
    "Recorrido_ID": "115960",
    "Login": "it1@it1.com",
    "Password": "Fast2233",
    "Retiro_ID": "103448169",
    "estado_codigo": "POD",
    "FechaCreacion": "2025-01-07T19:13:36",
    "Latitud": "-34.6593",
    "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