SaveRates

Envía tarifas al borrador de un tarifario, desde su sistema de valoración o la hoja de tarifas de un proveedor, sin abrir la página. Es uno de los canales de tarifas del tarifario, junto con el correo electrónico y SFTP. Envíe las tarifas como archivo, un archivo Excel o CSV que se lee como lo lee Subir un archivo, o como líneas en JSON.

TrakIT comprueba primero cada línea, y solo las escribe en el borrador cuando todas son correctas; si una tiene un problema, no se escribe nada. Las tarifas no están en uso hasta que alguien publica el borrador en la página del tarifario: SaveRates nunca publica.

Cómo iniciar sesión y leer la respuesta: Autenticación, Respuestas.

POST /api/v1/SaveRates
Token: your-token
Content-Type: application/json

Con líneas:

{
  "Card": "VR-0012",
  "ReplaceAll": false,
  "Lines": [
    {
      "Leg": "Freight",
      "FromCode": "CNSHA",
      "ToCode": "KEMBA",
      "Charge": "Ocean Freight",
      "Basis": "Container",
      "Curr": "USD",
      "Values": { "20DV": 1200, "40HC": 2100 },
      "Transit": 28
    },
    {
      "Leg": "Destination",
      "FromCode": "KEMBA",
      "Charge": "Terminal Handling",
      "Values": { "20DV": 150, "40HC": 220 }
    }
  ]
}

Con un archivo:

{
  "Card": "VR-0012",
  "ReplaceAll": true,
  "FileName": "VR-0012 November.xlsx",
  "File": "UEsDBBQABgAIAAAAIQBi7p1oXgEAAJAEAAATAAgCW0NvbnRlbnRfVHlwZXNd..."
}

Campo	Obligatorio	Significado
Card	Sí	El Code del tarifario, por ejemplo VR-0012.
Lines	Uno de los dos	Las tarifas como líneas: consulte Líneas.
File	Uno de los dos	Las tarifas como archivo, un .xlsx o .csv, codificado en base64: consulte Archivo. Si también envía Lines, File no se utiliza.
FileName	No	El nombre del archivo, por ejemplo VR-0012 November.xlsx. Se muestra en la pestaña Feeds del tarifario.
ReplaceAll	No	true para eliminar las líneas del borrador con las que no coincide ninguna de las líneas o filas enviadas. El valor predeterminado, false, las conserva.

Los nombres de los campos no distinguen entre mayúsculas y minúsculas.

Líneas

Cada línea es una línea de tarifa completa, con los campos de Detalles de la línea:

Campo	Significado
Leg	Pre-carriage, Origin, Freight, Destination u On-carriage. Si se omite, Freight.
FromCode	Dónde empieza la línea o, para los cargos en origen y en destino, el lugar en el que se aplican. El código de un lugar, un UN/LOCODE como CNSHA, o un nombre exacto que solo tiene un lugar. Si se omite, cualquier lugar.
ToCode	Dónde termina la línea, de la misma forma. Omítalo para los cargos en origen y en destino.
ViaCode	El puerto de enrutamiento o de transbordo, a título informativo. No para los cargos en origen y en destino.
Charge	Obligatorio. El nombre del concepto, o un código que solo tiene ese concepto. En el tarifario de una empresa, un concepto activo de esa empresa: un concepto de ingreso o de suplido en un tarifario de venta, un concepto de gasto o de suplido en un tarifario de compra. En un tarifario para todas las empresas, un nombre de concepto que tenga alguna empresa.
Detail	Se muestra con el concepto, hasta 300 caracteres.
Basis	Shipment, Container, TEU, Kg, Chg kg, Ton, CBM, W/M, Trip, % o Unit. También sirven otros nombres habituales, como Per container. Si se omite, la base de cálculo habitual del modo.
PctOf	Solo para la base de cálculo %: el concepto del que esta línea es un porcentaje.
Curr	La moneda de los precios de la línea. Si se omite, la moneda del tarifario.
Values	Los precios: consulte Precios. Al menos uno.
Min, Max	El importe mínimo y el importe máximo. El mínimo no puede ser negativo.
CargoTypes, Services, JobTypes	Los tipos de mercancía, los servicios y los tipos de expediente a los que se aplica la línea, por su nombre, separados por comas. Si se omiten, cualquiera.
WtFrom, WtTo	Los pesos en kg a los que se aplica la línea: desde el primero hasta el segundo, sin incluirlo.
Ratio	La relación peso/volumen en kg por CBM, para esta línea en lugar de la del tarifario: de 1 a 10 000.
VFrom, VTo	Las fechas en que la línea es válida, cuando lo es durante menos tiempo que su versión, con el formato yyyy-MM-dd.
Transit, FreeDays	Los días de tránsito y los días libres, números enteros hasta 999.
Notes	Hasta 300 caracteres.
RLID	El identificador de una línea del borrador, de la columna ID de un archivo descargado del borrador. La línea sustituye a esa.

Los números pueden ser números JSON o texto con un punto o una coma para los decimales. Las fechas también pueden escribirse como dd/MM/yyyy o dd MMM yyyy, pero yyyy-MM-dd es lo más seguro.

Cómo se emparejan las líneas

• Una línea con el RLID de una línea del borrador sustituye a esa línea.
• Si no, una línea sustituye a la línea del borrador con el mismo trayecto, los mismos lugares, el mismo concepto, el mismo detalle, los mismos tipos de mercancía, servicios y tipos de expediente, y los mismos pesos y fechas. Una línea que no coincide con ninguna se añade.
• Una línea es completa: un campo que omite queda en blanco en el borrador, o toma su valor predeterminado, aunque la línea del borrador tuviera un valor. Para cambiar un precio, vuelva a enviar la línea completa.
• Con ReplaceAll igual a true, se eliminan las líneas del borrador con las que no coincide ninguna línea.
• Dos líneas no pueden valorar el mismo trayecto, los mismos lugares, el mismo concepto, el mismo detalle y las mismas condiciones para pesos o fechas que se solapen, tanto si ambas están en la solicitud como si una es una línea del borrador que se conserva.

Precios

Values contiene un precio por cada columna de precio del borrador, con la columna como clave. Las columnas del borrador son sus tipos de equipo o sus escalas de peso (consulte Dates & columns), o un solo precio:

El tarifario se valora	Clave de cada precio	Por ejemplo
Por tipo de equipo, por ejemplo marítimo FCL o por carretera	El código de equipo de la columna. Los espacios y las mayúsculas no importan. Si el borrador solo tiene una columna, también sirve Rate.	{ "20DV": 1200, "40HC": 2100 }
Por escala de peso, por ejemplo aéreo	El peso en el que empieza la franja, con o sin + y kg. La primera franja también puede tener como clave su encabezado, - y la escala siguiente.	{ "-45": 4.10, "+45": 3.20, "+100": 2.90 }
Con un solo precio, por ejemplo marítimo LCL	Rate, Price, Amount, Value, Tariff, Cost, Sell o Buy.	{ "Rate": 38 }

Un precio con una clave que no es una columna del borrador es un problema: '...' is not a price column of this version. Un precio vacío se omite.

Archivo

Un archivo se lee como lo lee Subir un archivo en la página del tarifario:

• un libro de Excel (.xlsx) o un archivo CSV, de hasta 10 MB y 20 000 filas; guarde antes un archivo .xls como .xlsx o .csv;
• en un libro, la hoja llamada Rates o, si no, la primera hoja visible; la fila de encabezados puede estar en cualquier lugar de las 20 primeras filas; un archivo CSV puede estar separado por comas, puntos y comas o tabulaciones;
• las columnas se emparejan por su encabezado, como en la página, o tal como se recordaron para el tarifario o para su cliente o su proveedor. Una presentación que TrakIT no puede emparejar debe subirse una vez en la página del tarifario, con Remember this marcado; después, los archivos con esa presentación se leen de la misma forma;
• una fila actualiza la línea del borrador que tiene su ID o, si no, la línea con el mismo trayecto, los mismos lugares, el mismo concepto, el mismo detalle, las mismas condiciones, los mismos pesos y las mismas fechas. Los campos para los que el archivo no tiene columna conservan sus valores. Las demás filas se añaden.

Envíe el contenido del archivo en base64, sin el prefijo data:. TrakIT reconoce un archivo Excel por su contenido, por lo que FileName es opcional; un nombre que termina en .xls se rechaza.

Reglas

Las comprobaciones siguientes se hacen en este orden. Hasta la comprobación de File, una comprobación que falla devuelve RetInfo null; a partir de la comprobación de Card, RetInfo es el resultado, con Status 3 cuando una comprobación falla.

Regla	Info si no se cumple
La solicitud tiene un encabezado Token.	Token missing in header
El cuerpo es JSON.	Incorrect Json syntax or rates missing
El token es válido.	Token invalid or expired, u otra respuesta indicada en Token de inicio de sesión
El usuario es un administrador del sistema con acceso a la API.	API User must be SysAdmin with API Access
Los canales de tarifas están configurados en su TrakIT.	Rate feeds are not set up on this system
El cuerpo tiene Lines o un File.	Send the rates as File (an .xlsx or .csv, base64) or as Lines
File está en base64.	File is not base64
Se indica Card.	Name the rate card by its code, e.g. VR-0012
Un tarifario tiene ese código.	No rate card has the code ..., or ... cannot see it
El tarifario está activo.	The card is inactive - reactivate it to take new rates
Lines tiene de 1 a 20 000 líneas.	There are no lines to upload, Send up to 20,000 lines at a time
El archivo no está vacío y ocupa como máximo 10 MB.	The file is empty, The file is larger than 10 MB - split it
Se puede abrir un borrador del tarifario, si no tiene ninguno.	Unable to open a draft
El archivo se puede leer.	Save the file as .xlsx (Excel Workbook) or .csv and upload it again, The file could not be read as an Excel workbook, The workbook has no data, The file could not be read at line ... - check for an unclosed quote, The file has more than 20,000 rows - split it
El archivo tiene una fila de encabezados, y filas debajo de ella.	No heading row was found - the file needs a row of column headings such as From, To, Charge and the prices, The file has headings but no rows
TrakIT puede emparejar las columnas del archivo: una columna de concepto, al menos una columna de precio, y ningún campo procedente de dos columnas.	Choose the column that holds the charge, Choose the columns that hold the prices o Two columns are matched to ... - choose one, seguido de cómo corregirlo
Cada línea o fila es correcta: consulte Problemas.	... of ... row(s) have problems, so nothing was written. Fix them and send the rates again., con Code 1 y Status 2
El borrador no ha cambiado entretanto de forma que las tarifas ya no encajen.	The draft this file was uploaded into was published or discarded meanwhile - upload the file again, The draft changed since the file was uploaded and some rows no longer fit - upload the file again

Problemas

Cada línea o fila se comprueba como en la página. Una fila puede tener varios problemas, separados por ; . Rows en la respuesta lista las 200 primeras filas con problemas. Los problemas son, por campo:

Campo	Problemas
Leg	Leg '...' is not one of Pre-carriage, Origin, Freight, Destination, On-carriage
FromCode, ToCode, ViaCode	No place has the code or name '...', '...' matches ... places by ... - use the place's code, Origin and destination charges are for one place - put it in From and leave To empty, Origin and destination charges have no routing
Charge, PctOf	Enter the charge, '...' is not an active ... charge of ..., No company has an active ... charge named '...', ... charges are named '...' in this company - rename them in the charge master, Code '...' is shared by ... charges (...) - use the charge name, Say which charge the percentage is of (% of), A charge cannot be a percentage of itself, '% of' is only for a percentage basis
Basis	Basis '...' is not one of Shipment, Container, TEU, Kg, Chg kg, Ton, CBM, W/M, Trip, %, Unit
Curr	Currency '...' is not set up
Values	'...' is not a price column of this version, This card prices by column - put the price under its column, Rate '...' is not a number (o el nombre de la columna), A percentage must be between -100 and 1000, A price is too large, Enter at least one price
Min, Max	Min '...' is not a number, The minimum charge cannot be negative, The maximum charge is below the minimum
CargoTypes, Services, JobTypes	'...' is not a cargo type, '...' is not a service, '...' is not a job type, Too many ...s on one line
WtFrom, WtTo, Ratio	Weight from cannot be negative, Weight to must be above weight from, Weight to is too large, The volume ratio is the kg charged per CBM - between 1 and 10,000
VFrom, VTo	Valid from '...' is not a date - use yyyy-mm-dd, Valid from is out of range, The line cannot end before it starts
Transit, FreeDays	Transit days must be a whole number of days up to 999, Free days must be a whole number of days up to 999
Detail, Notes	Detail can have up to 300 characters, Notes can have up to 300 characters
La línea completa	Prices the same line as row ..., Prices the same charge, places and conditions as row ... for overlapping weights or dates (o as a line of the draft the file does not change en lugar de la fila)

Un archivo también puede tener Could be any of ... lines of the draft for this lane and charge (they differ by conditions, weights or dates) - add those columns to the file.

Respuesta

Code es 1 cuando las tarifas se han leído: o bien se han escrito en el borrador (Status 1), o bien se han rechazado porque algunas líneas tienen problemas (Status 2, no se escribe nada). Compruebe Status, no solo Code. Code es 0 cuando las tarifas no se han podido leer en absoluto. Info repite el Message del resultado.

{
  "Code": 1,
  "Info": "Written into draft v4: 1 added, 1 changed, 0 deleted, 38 unchanged. The draft is not in use until it is published.",
  "RetInfo": {
    "Status": 1,
    "StatusText": "Written into the draft",
    "CardCode": "VR-0012",
    "CardName": "Example Shipping Co FCL rates",
    "FileName": "API lines",
    "VerNo": 4,
    "Total": 40,
    "Added": 1,
    "Changed": 1,
    "Deleted": 0,
    "Unchanged": 38,
    "Problems": 0,
    "Message": "Written into draft v4: 1 added, 1 changed, 0 deleted, 38 unchanged. The draft is not in use until it is published.",
    "Rows": null
  },
  "RowsAffected": 0,
  "Scalar": null,
  "Identity": 0
}

Con problemas:

{
  "Code": 1,
  "Info": "1 of 40 row(s) have problems, so nothing was written. Fix them and send the rates again.",
  "RetInfo": {
    "Status": 2,
    "StatusText": "Has problems - nothing written",
    "CardCode": "VR-0012",
    "CardName": "Example Shipping Co FCL rates",
    "FileName": "API lines",
    "VerNo": 4,
    "Total": 40,
    "Added": 1,
    "Changed": 0,
    "Deleted": 0,
    "Unchanged": 38,
    "Problems": 1,
    "Message": "1 of 40 row(s) have problems, so nothing was written. Fix them and send the rates again.",
    "Rows": [
      { "Row": 2, "Problem": "No place has the code or name 'KEMBX'" }
    ]
  },
  "RowsAffected": 0,
  "Scalar": null,
  "Identity": 0
}

Campo	Significado
Status	1 escritas en el borrador, 2 hay problemas y no se ha escrito nada, 3 no leídas.
StatusText	Written into the draft, Has problems - nothing written o Not read.
CardCode, CardName	El código y el nombre del tarifario. CardName es null cuando ningún tarifario tiene el código.
FileName	FileName tal como se envió, o API lines o API file cuando no envió ninguno.
VerNo	El número de la versión en borrador a la que han ido las tarifas, como vn en el tarifario.
Total	El número de líneas o filas leídas.
Added, Changed, Deleted, Unchanged	Cuántas líneas se han añadido, modificado y dejado sin cambios, y cuántas líneas del borrador ha eliminado ReplaceAll. Con Status 2, lo que habrían hecho las filas sin problemas.
Problems	El número de líneas o filas con problemas.
Message	El resultado en palabras, como en Info.
Rows	Con Status 2, las 200 primeras líneas o filas con problemas: Row, la posición de la línea en Lines (desde 1) o el número de la fila en el archivo, y Problem. Si no, null.

Cuando todas las líneas ya coinciden con el borrador, no cambia nada y el mensaje es Nothing changed: the ... row(s) match draft v... already.

Ejemplo

Para enviar un archivo con curl desde un shell que tenga base64:

curl -H "Token: your-token" -H "Content-Type: application/json" \
  -d "{\"Card\":\"VR-0012\",\"FileName\":\"rates.xlsx\",\"File\":\"$(base64 -w0 rates.xlsx)\"}" \
  https://trakit.example.com/api/v1/SaveRates

Sustituya https://trakit.example.com por la dirección de su TrakIT. Para un archivo grande, escriba antes el JSON en un archivo y envíelo con -d @body.json.

Notas

• Si el tarifario no tiene borrador, SaveRates abre uno primero, con una copia de las líneas de la última versión publicada si la hay, como hace Edit en la página (consulte Modificar las tarifas). El borrador sigue abierto aunque no se escriba nada.
• Cada llamada para un tarifario existente se lista en la pestaña Feeds del tarifario, procedente de API, con su resultado, y la pestaña History del tarifario registra las tarifas recibidas y escritas. Los registros de los canales se conservan un año.
• Cuando se escriben tarifas y algo ha cambiado, TrakIT envía un correo electrónico al grupo de notificación del tarifario, con un libro que lista cada fila y lo que se hizo con ella.
• Volver a enviar las mismas tarifas no supone ningún riesgo: las líneas que ya coinciden con el borrador se cuentan como sin cambios.