{ "generatedAt": "2026-05-14T14:29:58.705Z", "modules": [ "_common", "auth", "carta-porte", "catalogue", "cdys", "companies", "containers", "customer-portal", "data-carta-porte", "data-lookups", "datetime", "documents", "drayage", "drayage-group", "driver", "emails", "enums", "events", "geography", "identity", "integration-mexico", "integration-usa", "integrations", "lazex", "load-location", "locations", "mexico", "negotiations", "notifications", "pac", "packaging-type", "payments", "places", "points", "sat", "select-combo", "services", "smart-port", "status-setting", "tasks", "templates", "tracking", "user", "users", "vehicle", "vehicles" ], "endpoints": [ { "name": "changePassword", "module": "auth", "path": "/auth/changePassword", "method": "POST", "summary": "Authenticates the caller with the current password and updates the stored password hash, tracking failed attempts on the user document so the lockout survives restarts and is shared across instances.", "params": [ { "name": "body", "type": "{ newPassword: string; currentPassword: string }", "summary": "Payload containing the user's current password and the new password to set.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The updated user document after the password has been replaced and the failed-attempts blocker cleared." }, "errors": [ { "code": "Unauthorized", "when": "The user has reached the maximum number of consecutive failed password attempts within the lockout window; the account is disabled." }, { "code": "InvalidUsernameOrPassword", "when": "The provided current password does not match the stored hash, or the user has no stored password." }, { "code": "SameAsCurrentPassword", "when": "The new password is identical to the current password." } ], "references": { "valueObjects": [ "Password" ] } }, { "name": "codeCountry", "module": "auth", "path": "/auth/codeCountry", "method": "POST", "summary": "Returns the full country code catalogue used by the auth flows.", "params": [], "response": { "summary": "The complete catalogue of country codes available for auth flows." }, "errors": [], "references": {} }, { "name": "confirmAccount", "module": "auth", "path": "/auth/confirmAccount", "method": "POST", "summary": "Confirms an email-verification token, materializes the pending company and user, initializes company settings, and returns a fresh access token.", "params": [ { "name": "token", "type": "string", "summary": "Email confirmation token issued during signup.", "required": true } ], "response": { "summary": "An object containing a freshly issued access token for the confirmed user.", "type": "{ token: string }" }, "errors": [ { "code": "VerificationUserNotFound", "when": "The token is valid but no pending user exists for it, or the pending company referenced by the pending user cannot be found." } ], "references": { "models": [ "User", "Company", "PendingUser", "PendingCompany", "CompanySettings" ] } }, { "name": "createDriver", "module": "auth", "path": "/auth/createDriver", "method": "POST", "summary": "Creates a driver user directly from the provided payload and triggers the carrier verification email flow.", "params": [ { "name": "payload", "type": "any", "summary": "Driver signup payload including at least one of email or mobile, plus profile fields (fullname, phone, countryCode) and the carrier companyId.", "required": true } ], "response": { "summary": "The newly created driver user document." }, "errors": [ { "code": "EmailOrPhoneRequired", "when": "The payload provides neither an email nor a mobile number." }, { "code": "PhoneAlreadyExists", "when": "Another user is already registered with the same mobile number." }, { "code": "EmailAlreadyExists", "when": "Another user is already registered with the same email." } ], "references": { "models": [ "User" ], "valueObjects": [ "Email", "Phone" ] } }, { "name": "edit", "module": "auth", "path": "/auth/edit", "method": "POST", "summary": "Updates the authenticated user, or another user in the same company when the requester is an admin, restricted to the editable profile fields.", "params": [ { "name": "payload", "type": "any", "summary": "Object with the fields to update. May include `_id` to target another user; only keys listed in `EDITABLE_PROFILE_FIELDS` (`profile`, `settings`) are applied.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Object containing the updated values for each editable profile field (`profile`, `settings`).", "type": "any" }, "errors": [ { "code": "Unauthorized", "when": "The target user is not the requester and the requester is not an admin in the same company as the target." } ], "references": { "models": [ "User" ] } }, { "name": "editDriver", "module": "auth", "path": "/auth/editDriver", "method": "POST", "summary": "Updates a driver record belonging to the caller's company, including optional password, phone, and email changes.", "params": [ { "name": "_id", "type": "string", "summary": "Identifier of the driver user to update.", "required": true }, { "name": "data", "type": "any", "summary": "Driver fields to update. May include `email`, `password`, `zipCode`, and `profile` (with `mobile`, `countryCode`, etc.).", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "MongoDB update result for the driver document.", "type": "any" }, "errors": [ { "code": "Unauthorized", "when": "The target driver does not belong to the same company as the requester." }, { "code": "PhoneAlreadyExists", "when": "The new mobile number provided is already registered to another user." }, { "code": "EmailAlreadyExists", "when": "The new email provided is already registered to another user." } ], "references": { "models": [ "User" ], "valueObjects": [ "Email", "Password", "Phone" ] } }, { "name": "editMyEmployee", "module": "auth", "path": "/auth/editMyEmployee", "method": "POST", "summary": "Updates an employee record belonging to the caller's company; if a new password is supplied it is hashed and the user is notified by email.", "params": [ { "name": "_id", "type": "string", "summary": "Identifier of the employee user to update.", "required": true }, { "name": "data", "type": "any", "summary": "Employee fields to update. May include `password` and `role`. Email changes are ignored because `data.email` is removed before persistence.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "MongoDB update result for the employee document.", "type": "any" }, "errors": [ { "code": "Unauthorized", "when": "The target employee does not belong to the same company as the requester." } ], "references": { "models": [ "User" ], "valueObjects": [ "Password" ] } }, { "name": "exists", "module": "auth", "path": "/auth/exists", "method": "POST", "summary": "Normalizes an email address and reports whether a user is already registered with it.", "params": [ { "name": "email", "type": "string", "summary": "Email address to check; normalized through the `Email` value object before lookup.", "required": true } ], "response": { "summary": "True when a user exists for the normalized email, false otherwise.", "type": "Promise" }, "errors": [], "references": { "valueObjects": [ "Email" ] } }, { "name": "findMyEmployees", "module": "auth", "path": "/auth/findMyEmployees", "method": "POST", "summary": "Returns every employee that belongs to the authenticated admin's company along with simple count statistics.", "params": [ { "name": "_payload", "type": "any", "summary": "Reserved payload slot; currently ignored by the handler.", "required": false }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Object with `stats.count.all` / `stats.count.target` totals and a `results` array containing the employees of the requester's company.", "type": "{ stats: { count: { all: number, target: number } }, results: any[] }" }, "errors": [ { "code": "Unauthorized", "when": "The requester is not an admin user." } ], "references": { "models": [ "User" ] } }, { "name": "get", "module": "auth", "path": "/auth/get", "method": "POST", "summary": "Returns a public-facing projection of a user record by id, accepting either a user session token or an admin token with `Auth.get` access.", "params": [ { "name": "userId", "type": "ID", "summary": "Identifier of the user to fetch.", "required": true }, { "name": "token", "type": "UserToken | AdminToken", "summary": "User session token returned by /auth/login, or an admin token with `Auth.get` access.", "required": true } ], "response": { "summary": "Projected user payload exposing profile, identity, role, company, license and tracking flags. Sensitive fields such as password are excluded.", "type": "Promise" }, "errors": [ { "code": "Unauthorized", "when": "The token is neither a valid user session token nor an admin token with `Auth.get` access." }, { "code": "UserNotFound", "when": "No user exists for the supplied `userId`." } ], "references": { "interfaces": [ "UserGet" ], "types": [ "AdminToken", "ID", "UserToken" ] } }, { "name": "getUserByEmail", "module": "auth", "path": "/auth/getUserByEmail", "method": "POST", "summary": "Normalizes an email address, fetches the matching user, and returns a projected user payload.", "params": [ { "name": "email", "type": "Email", "summary": "Email address to look up; normalized through the Email value object before querying.", "required": true }, { "name": "_token", "type": "AdminToken", "summary": "Admin session token authorizing the lookup.", "required": true } ], "response": { "summary": "Projected user payload exposing profile, identity, role, company, license and tracking flags. Sensitive fields are excluded.", "type": "Promise" }, "errors": [ { "code": "UserNotFound", "when": "No user exists for the normalized email address." } ], "references": { "models": [ "User" ], "valueObjects": [ "Email" ], "interfaces": [ "UserGet" ], "types": [ "AdminToken", "Email" ] } }, { "name": "getUserByPhone", "module": "auth", "path": "/auth/getUserByPhone", "method": "POST", "summary": "Normalizes a phone number and returns the matching user record.", "params": [ { "name": "phone", "type": "string", "summary": "Phone number to look up; normalized through the Phone value object before querying.", "required": true }, { "name": "_token", "type": "AdminToken", "summary": "Admin session token authorizing the lookup.", "required": true } ], "response": { "summary": "The user document matching the normalized phone number, or null when no user is found.", "type": "Promise" }, "errors": [], "references": { "models": [ "User" ], "valueObjects": [ "Phone" ], "types": [ "AdminToken" ] } }, { "name": "login", "module": "auth", "path": "/auth/login", "method": "POST", "summary": "Authenticates a web user with username, email, or phone plus password and returns an access token payload.", "params": [ { "name": "username", "type": "UserName | Email | Phone", "summary": "Login identifier — username, email address, or phone number.", "required": true }, { "name": "password", "type": "string", "summary": "Plain-text user password to be validated against the stored credential.", "required": true } ], "response": { "summary": "Returns the user id, signed JWT access token, company id, and placeholder did/olpToken fields.", "type": "Promise<{ _id: ID; token: UserToken; companyId: string; did: string; olpToken: string }>" }, "errors": [ { "code": "InvalidUsernameOrPassword", "when": "No user matches the provided username/email/phone, or the supplied password does not match the stored hash." }, { "code": "UserNotVerified", "when": "The matched user account is disabled." } ], "references": { "models": [ "User" ], "valueObjects": [ "Password" ], "types": [ "UserName", "Email", "Phone", "UserToken", "ID" ] } }, { "name": "myDrivers", "module": "auth", "path": "/auth/myDrivers", "method": "POST", "summary": "Returns all driver users for the authenticated caller's company.", "params": [ { "name": "token", "type": "UserToken", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Array of driver users belonging to the caller's company.", "type": "Promise>" }, "errors": [], "references": { "models": [ "User" ], "types": [ "UserToken" ] } }, { "name": "newDriver", "module": "auth", "path": "/auth/newDriver", "method": "POST", "summary": "Creates a driver under the authenticated requester's carrier, optionally tying the new driver to a shipment for assignment-related side effects.", "params": [ { "name": "driver", "type": "any", "summary": "Driver payload to create (profile, contact, role and carrier-related fields).", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true }, { "name": "shipmentId", "type": "string", "summary": "Identifier of the shipment to associate with the newly created driver, when applicable.", "required": false }, { "name": "validation", "type": "string", "summary": "Validation mode controlling shipment-assignment side effects (for example `dry` or `ftl`).", "required": false } ], "response": { "summary": "Returns the result of the shared `newDriver` business module — the created driver record together with any shipment-assignment data produced by the validation mode." }, "errors": [], "references": { "flows": [] } }, { "name": "removeDriver", "module": "auth", "path": "/auth/removeDriver", "method": "POST", "summary": "Removes a driver from the requester's company, either by clearing the owner-operator flag for non-driver users or by scrubbing identifying fields for driver-role users.", "params": [ { "name": "_id", "type": "string", "summary": "Identifier of the user to remove.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Returns the targeted driver record as it was loaded prior to scrubbing, with `isOwnerOperator` set to false when the target was not a driver." }, "errors": [ { "code": "Unauthorized", "when": "The targeted user does not belong to the same company as the authenticated requester." } ], "references": { "models": [ "User" ] } }, { "name": "removeEmployee", "module": "auth", "path": "/auth/removeEmployee", "method": "POST", "summary": "Deletes an employee user record on behalf of an admin requester.", "params": [ { "name": "_id", "type": "string", "summary": "Identifier of the user to delete.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "No payload is returned; success indicates that the user was deleted.", "type": "void" }, "errors": [ { "code": "Unauthorized", "when": "The authenticated requester does not have an `admin` access level, or the target user belongs to a different company than the requester." }, { "code": "USER_NOT_FOUND", "when": "No user exists for the given `_id`." } ], "references": { "models": [ "User" ] } }, { "name": "resetPassword", "module": "auth", "path": "/auth/resetPassword", "method": "POST", "summary": "Verifies a reset-password JWT, resolves the target user by email, and replaces the stored password hash with a securely hashed new password.", "params": [ { "name": "resetPasswordToken", "type": "ActionToken", "summary": "Reset-password JWT issued via /auth/resetPasswordToken; must be signed with JWT_SECRET, carry `type: \"reset-password\"` and the target email, and equal the user's currently-stored `_resetPassword.token` (single-use).", "required": true }, { "name": "newPassword", "type": "string", "summary": "The new password to set; validated and strengthened by the Password value object before hashing.", "required": true } ], "response": { "summary": "The Mongoose updateOne result for the user whose password and reset-password state were updated." }, "errors": [ { "code": "InvalidResetPasswordToken", "when": "The JWT signature is invalid or expired, or its `type` claim is not `reset-password`, or the email claim does not map to a user, or the JWT does not equal the user's currently-stored `_resetPassword.token`." } ], "references": { "models": [ "User" ], "valueObjects": [ "Password" ], "types": [ "ActionToken" ] } }, { "name": "resetPasswordToken", "module": "auth", "path": "/auth/resetPasswordToken", "method": "POST", "summary": "Generates a reset-password token for the given user (or email) and triggers the reset-password email flow.", "params": [ { "name": "email", "type": "string | User", "summary": "Either the user's email address or the resolved user document for whom to generate the reset-password token.", "required": true } ], "response": { "summary": "The result of the underlying generateResetPasswordToken helper, which produces and dispatches the reset-password email." }, "errors": [], "references": { "models": [ "User" ] } }, { "name": "signup", "module": "auth", "path": "/auth/signup", "method": "POST", "summary": "Validates a signup request and routes it either to a pending join flow for an existing company (matched by RFC) or to a new-company pending registration flow.", "params": [ { "name": "email", "type": "string", "summary": "Signup email for the new user account.", "required": true }, { "name": "password", "type": "string", "summary": "Plain-text password to register; secured by the Password value object before storage.", "required": true }, { "name": "fullName", "type": "string", "summary": "Full name of the user being registered.", "required": true }, { "name": "company", "type": "SignupPayload['company']", "summary": "Company payload including razonSocial, rfc, role, and optional fiscal/address fields used to match an existing company by RFC or to create a new pending company.", "required": true } ], "response": { "summary": "For new-company signups, an httpOk envelope with the success message and (in development context) the issued token; for existing-company signups, no body is returned." }, "errors": [], "references": { "valueObjects": [ "RFC", "Password" ], "types": [ "SignupPayload" ] } }, { "name": "signupEmployee", "module": "auth", "path": "/auth/signupEmployee", "method": "POST", "summary": "Creates a new employee user under the authenticated admin's company through the shared silent-signup workflow, normalizing username and email values and ignoring caller-supplied privileged fields.", "params": [ { "name": "payload", "type": "any", "summary": "Employee signup payload. Only `email`, `username`, `password`, `confirmPassword`, and `profile` are forwarded to the silent-signup workflow. `role` (defaults to the admin's role) and `_accessLevel` (`'admin'` promotes to admin, anything else defaults to `'user'`) influence the created user. All other fields (including `companyId`, `workspace`, `disabled`, `verified`, `_resetPassword`) are ignored.", "required": true }, { "name": "_options", "type": "any", "summary": "Reserved options bag; not consumed by the handler.", "required": false }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The MongoDB `_id` of the newly created employee user.", "type": "ObjectId" }, "errors": [ { "code": "Unauthorized", "when": "The authenticated caller resolved from the token does not have `_accessLevel === 'admin'`." }, { "code": "INVALID_FORMAT", "when": "The provided `username` violates the Username value object (length out of [3,64] or contains whitespace)." }, { "code": "INVALID_EMAIL", "when": "The provided `email` violates the Email value object." } ], "references": { "valueObjects": [ "Email", "Username" ] } }, { "name": "toggleUserEnabled", "module": "auth", "path": "/auth/toggleUserEnabled", "method": "POST", "summary": "Validates that the caller is an admin and toggles the disabled flag for a user in the admin's company.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true }, { "name": "userId", "type": "string", "summary": "Identifier of the target user whose disabled flag will be toggled.", "required": true } ], "response": { "summary": "Returns the updated disabled state and id of the target user.", "type": "{ disabled: boolean, id: string }" }, "errors": [ { "code": "Unauthorized", "when": "The caller's access level is not 'admin', or the target user belongs to a different company." }, { "code": "CannotToggleSelf", "when": "The caller targets their own user id (admins cannot disable themselves)." }, { "code": "CannotToggleAdmin", "when": "The target user has the 'admin' access level (admins cannot toggle other admins)." }, { "code": "USER_NOT_FOUND", "when": "No user with the given userId exists (raised by getUser({ throws: true }))." }, { "code": "UserNotFound", "when": "Defensive fallback if the toggle update returns no document despite a successful preflight (race)." } ], "references": { "models": [ "User" ] } }, { "name": "user", "module": "auth", "path": "/auth/user", "method": "POST", "summary": "Verifies an access JWT, loads the owning user, strips sensitive fields, and returns the sanitized user object.", "params": [ { "name": "token", "type": "UserToken", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The sanitized user document, with password, _confirmedEmail, _resetPassword, emailAuthentication and _accountBlocker removed.", "type": "Promise" }, "errors": [ { "code": "InvalidTokenType", "when": "The decoded JWT's type is not 'access'." }, { "code": "MissingTokenOwner", "when": "The decoded JWT does not contain an owner field." }, { "code": "UserNotFound", "when": "No user exists for the owner id encoded in the token." }, { "code": "UserDisabled", "when": "The resolved user has disabled === true." } ], "references": { "models": [ "User" ], "types": [ "UserToken" ] } }, { "name": "getCartaPorteReadyStatus", "module": "carta-porte", "path": "/carta-porte/getCartaPorteReadyStatus", "method": "POST", "summary": "Returns whether a drayage has all the data required to issue its Carta Porte document, scoped to drayages owned by the authenticated user.", "params": [ { "name": "drayageId", "type": "string", "summary": "Identifier of the drayage to check.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "Readiness breakdown for the drayage's Carta Porte (commodity, container, and location readiness flags)." }, "errors": [ { "code": "MissingDrayageId", "when": "The drayageId argument is empty or missing." }, { "code": "MissingToken", "when": "The token argument is empty or missing." }, { "code": "DrayageNotFound", "when": "The authenticated user is not the owner of the requested drayage (treated as not found to avoid leaking existence)." } ], "references": {} }, { "name": "allHazmatClasses", "module": "catalogue", "path": "/catalogue/allHazmatClasses", "method": "POST", "summary": "Return the full in-memory list of hazardous-material classes.", "params": [], "response": { "summary": "Every hazardous-material class catalogue entry.", "type": "HazardousMaterial[]" }, "errors": [], "references": { "models": [ "HazardousMaterial" ], "enums": [ "HazmatType" ] } }, { "name": "allKeyUnits", "module": "catalogue", "path": "/catalogue/allKeyUnits", "method": "POST", "summary": "Return the full in-memory list of SAT key units.", "params": [], "response": { "summary": "Every SAT key-unit catalogue entry.", "type": "KeyUnits[]" }, "errors": [], "references": { "models": [ "KeyUnits" ] } }, { "name": "allProductKeys", "module": "catalogue", "path": "/catalogue/allProductKeys", "method": "POST", "summary": "Return the full in-memory list of SAT product keys.", "params": [], "response": { "summary": "Every SAT product key catalogue entry.", "type": "KeyProduct[]" }, "errors": [], "references": { "models": [ "KeyProduct" ] } }, { "name": "cpais", "module": "catalogue", "path": "/catalogue/cpais", "method": "POST", "summary": "List the full SAT countries catalogue.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "All country catalogue entries.", "type": "cpais[]" }, "errors": [ { "code": "InvalidToken", "when": "Thrown when the session token argument is not a string." } ], "references": { "models": [ "cpais" ] } }, { "name": "fiscalRegime", "module": "catalogue", "path": "/catalogue/fiscalRegime", "method": "POST", "summary": "Search SAT fiscal regime catalogue by substring on the regime code or description.", "params": [ { "name": "filter", "type": "string", "summary": "Substring matched against `fiscalRegime` and `description`.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "All fiscal regime catalogue entries matching the filter.", "type": "CFiscalRegime[]" }, "errors": [ { "code": "InvalidFilter", "when": "Thrown when the filter argument is not a string." }, { "code": "InvalidToken", "when": "Thrown when the session token argument is not a string." } ], "references": { "models": [ "CFiscalRegime" ] } }, { "name": "getPostalCode", "module": "catalogue", "path": "/catalogue/getPostalCode", "method": "POST", "summary": "Search ZIP codes by prefix and return each match enriched with its colonias, location, state, municipality, geo data and pre-formatted address strings.", "params": [ { "name": "filter", "type": "string", "summary": "ZIP code prefix to search. Case-insensitive, limited to 20 results.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Up to 20 ZIP-code records, each augmented with related catalogue rows and three pre-formatted address strings (`formattedAddress`, `formattedAddressWithOutLocation`, `formattedAddressWithOutColonia`).", "type": "Array" }, "errors": [ { "code": "InvalidFilter", "when": "Thrown when the filter argument is not a string." }, { "code": "InvalidToken", "when": "Thrown when the session token argument is not a string." } ], "references": { "models": [ "CPostalColonia", "Ccolonia", "Clocation", "CState", "Cmunicipality", "Geodata" ] } }, { "name": "getvalEntradaSalida", "module": "catalogue", "path": "/catalogue/getvalEntradaSalida", "method": "POST", "summary": "List the full SAT entry/exit transport key catalogue.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "All entry/exit transport key catalogue entries.", "type": "CCveTransport[]" }, "errors": [ { "code": "InvalidToken", "when": "Thrown when the session token argument is not a string." } ], "references": { "models": [ "CCveTransport" ] } }, { "name": "KeyMaterials", "module": "catalogue", "path": "/catalogue/KeyMaterials", "method": "POST", "summary": "Search hazardous materials catalogue by key prefix or description substring.", "params": [ { "name": "filters", "type": "string", "summary": "Search term matched as a prefix on `key` and as a substring on `description`.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Up to 20 hazardous material catalogue entries matching the filter.", "type": "HazardousMaterial[]" }, "errors": [ { "code": "InvalidFilter", "when": "Thrown when the filter argument is not a string." }, { "code": "InvalidToken", "when": "Thrown when the session token argument is not a string." } ], "references": { "models": [ "HazardousMaterial" ] } }, { "name": "KeyProduct", "module": "catalogue", "path": "/catalogue/KeyProduct", "method": "POST", "summary": "Search SAT product key catalogue by prefix on the product key or its name.", "params": [ { "name": "filters", "type": "string", "summary": "Prefix used to match against the product key or display name. Case-insensitive.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Up to 20 product key catalogue entries matching the prefix.", "type": "KeyProduct[]" }, "errors": [ { "code": "InvalidFilter", "when": "Thrown when the filter argument is not a string." }, { "code": "InvalidToken", "when": "Thrown when the session token argument is not a string." } ], "references": { "models": [ "KeyProduct" ] } }, { "name": "KeyUnits", "module": "catalogue", "path": "/catalogue/KeyUnits", "method": "POST", "summary": "Search SAT key units catalogue by prefix on the unit key or its name.", "params": [ { "name": "filters", "type": "string", "summary": "Prefix used to match against the unit key or display name. Case-insensitive.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Up to 20 key-unit catalogue entries matching the prefix.", "type": "KeyUnits[]" }, "errors": [ { "code": "InvalidFilter", "when": "Thrown when the filter argument is not a string." }, { "code": "InvalidToken", "when": "Thrown when the session token argument is not a string." } ], "references": { "models": [ "KeyUnits" ] } }, { "name": "postalColonia", "module": "catalogue", "path": "/catalogue/postalColonia", "method": "POST", "summary": "Search postal-colonia entries by ZIP code prefix.", "params": [ { "name": "filter", "type": "string", "summary": "ZIP code prefix used to match `zipCode`. Case-insensitive.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Up to 20 postal-colonia entries whose ZIP code starts with the filter.", "type": "CPostalColonia[]" }, "errors": [ { "code": "InvalidFilter", "when": "Thrown when the filter argument is not a string." }, { "code": "InvalidToken", "when": "Thrown when the session token argument is not a string." } ], "references": { "models": [ "CPostalColonia" ] } }, { "name": "selectData", "module": "catalogue", "path": "/catalogue/selectData", "method": "POST", "summary": "Resolve a Mexican address by ZIP code, returning matching colonias, locations, states, municipalities and geo data in one call.", "params": [ { "name": "payload", "type": "{ zipCode: string; estate?: string; location?: string; municipality?: string }", "summary": "Filter object. `zipCode` is the ZIP to resolve; `estate`, `location` and `municipality` further narrow the location/estate/municipality lookups.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Aggregated address resolution result.", "type": "{ colonia: Ccolonia[]; location: Clocation[]; estate: CState[]; municipality: Cmunicipality[]; geoData: Geodata; zipcode: CPostalColonia[] }" }, "errors": [ { "code": "InvalidPayload", "when": "Thrown when the payload argument is not an object." }, { "code": "InvalidToken", "when": "Thrown when the session token argument is not a string." }, { "code": "InvalidField", "when": "Thrown when any payload field (estate, location, municipality, zipCode) is present but not a string — prevents NoSQL operator injection." } ], "references": { "models": [ "Ccolonia", "Clocation", "CState", "Cmunicipality", "CPostalColonia", "Geodata" ] } }, { "name": "usoCfdi", "module": "catalogue", "path": "/catalogue/usoCfdi", "method": "POST", "summary": "Search SAT CFDI use catalogue by substring on the code or description.", "params": [ { "name": "filter", "type": "string", "summary": "Substring matched against `usoCfdi` and `description`.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "All CFDI use catalogue entries matching the filter.", "type": "CUsoCfdi[]" }, "errors": [ { "code": "InvalidFilter", "when": "Thrown when the filter argument is not a string." }, { "code": "InvalidToken", "when": "Thrown when the session token argument is not a string." } ], "references": { "models": [ "CUsoCfdi" ] } }, { "name": "addLocations", "module": "cdys", "path": "/cdys/addLocations", "method": "POST", "summary": "Upserts one or more load locations, tagging them as registered in CDYS and associating them with the authenticated user's company.", "params": [ { "name": "locations", "type": "LoadLocation[]", "summary": "Array of load locations to create or update. Each must satisfy CreateLoadLocationSchema (name, address, city, state, zipcode, country, colonia, rfc required).", "required": true }, { "name": "token", "type": "string", "summary": "User authentication token used to resolve companyId and userId.", "required": true } ], "response": { "summary": "Confirmation with a count of how many locations were processed.", "type": "{ success: boolean; message: string }" }, "errors": [], "references": { "models": [ "LoadLocation" ] } }, { "name": "addLocationsFromCSV", "module": "cdys", "path": "/cdys/addLocationsFromCSV", "method": "POST", "summary": "Parses a raw CSV string into load locations and upserts them associated with the authenticated user's company.", "params": [ { "name": "csv", "type": "string", "summary": "Raw CSV text containing location data to be parsed.", "required": true }, { "name": "token", "type": "string", "summary": "User authentication token used to resolve companyId and userId.", "required": true } ], "response": { "summary": "Confirmation with a count of how many locations were processed.", "type": "{ success: boolean; message: string }" }, "errors": [], "references": { "models": [ "LoadLocation" ] } }, { "name": "notifyDrayageRateUpdate", "module": "cdys", "path": "/cdys/notifyDrayageRateUpdate", "method": "POST", "summary": "Updates the rate on a drayage identified by its unique trip number. Only the drayage shipper (matched by company) is authorized to perform this operation.", "params": [ { "name": "tripNumber", "type": "string", "summary": "Unique trip number identifying the drayage. Validated as a non-empty DrayageTripNumber.", "required": true }, { "name": "containers", "type": "{ containerNumber: string; rate: string }[]", "summary": "List of containers with their individual rates as decimal strings. containerNumber is validated via ContainerNumber VO.", "required": true }, { "name": "token", "type": "string", "summary": "User authentication token used to resolve the caller's identity for authorization.", "required": true } ], "response": { "summary": "Confirmation that the rate was updated successfully.", "type": "{ success: boolean; message: string }" }, "errors": [ { "code": "DrayageNotFound", "when": "No drayage is found matching the provided trip number." }, { "code": "UserUnauthorizedOverDrayage", "when": "The authenticated user's company does not match the drayage's company (caller is not the shipper)." }, { "code": "InvalidRate", "when": "One of the container rate strings cannot be parsed as a valid decimal number." } ], "references": { "models": [ "Drayage" ], "valueObjects": [ "DrayageTripNumber", "ContainerNumber" ] } }, { "name": "companyInfo", "module": "companies", "path": "/companies/companyInfo", "method": "POST", "summary": "Returns a consolidated profile bundle for the authenticated user containing user info, company info, company settings, and Mexican tax documents.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Object with `infUser`, `setting`, `infCompany`, and `infoDocume` fields aggregating the user, company, settings, and Mexican-document data.", "type": "{ infUser: User, setting: Settings, infCompany: Company, infoDocume: unknown }" }, "errors": [], "references": { "models": [ "SettingsModel", "CompanyModel" ] } }, { "name": "edit", "module": "companies", "path": "/companies/edit", "method": "POST", "summary": "Merges the supplied identity, details, billing, payment, and Mexican-information sub-objects into the authenticated user's company and returns the updated document.", "params": [ { "name": "payload", "type": "any", "summary": "Object that may contain any subset of `identity`, `details`, `billToInfo`, `paymentInfo`, and `mexicoInformation` partial updates to merge into the company document.", "required": true }, { "name": "token", "type": "UserToken", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The freshly persisted company document for the authenticated user.", "type": "Company" }, "errors": [ { "code": "Unauthorized", "when": "The authenticated user is not an admin of their company." }, { "code": "CompanyNotFound", "when": "The authenticated user's company could not be found." } ], "references": { "models": [ "CompanyModel" ], "types": [ "UserToken" ] } }, { "name": "get", "module": "companies", "path": "/companies/get", "method": "POST", "summary": "Returns the full company document for the given company id along with a public URL to its logo asset.", "params": [ { "name": "_id", "type": "ID", "summary": "Identifier of the company to retrieve.", "required": true } ], "response": { "summary": "The company document plus a `logo` URL pointing to the public bucket asset.", "type": "Company & { logo: string }" }, "errors": [ { "code": "COMPANY_NOT_FOUND", "when": "No company exists with the supplied id." } ], "references": { "models": [ "CompanyModel" ], "types": [ "ID" ] } }, { "name": "getTimeZones", "module": "companies", "path": "/companies/getTimeZones", "method": "POST", "summary": "Returns the catalog of supported Mexican IANA time zones with their human-readable UTC offset labels.", "params": [ { "name": "token", "type": "UserToken", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Array of `{ label, value }` items where `value` is the IANA zone name and `label` includes the formatted UTC offset.", "type": "Array<{ label: string, value: string }>" }, "errors": [], "references": { "types": [ "UserToken" ] } }, { "name": "preRegistrationCompanyInfo", "module": "companies", "path": "/companies/preRegistrationCompanyInfo", "method": "POST", "summary": "Looks up an RFC against the local company database and the Mexican Master DB to determine whether the company is already registered, available for sign-up, or unknown.", "params": [ { "name": "rfc", "type": "string", "summary": "Mexican RFC (tax id); leading/trailing whitespace and non-alphanumerics are stripped and the value is uppercased before lookup.", "required": true } ], "response": { "summary": "Object with `status` (`existing` | `available` | `not-found`) and `company` (the local or Master DB record, or `null` when not found).", "type": "{ status: 'available' | 'existing' | 'not-found', company: { razonSocial: string, rfc: string, contacto: object } | null }" }, "errors": [], "references": { "models": [ "CompanyModel" ] } }, { "name": "removeLogo", "module": "companies", "path": "/companies/removeLogo", "method": "POST", "summary": "Deletes the authenticated user's company logo file from Google Cloud Storage and clears `logoProfile` on the company.", "params": [ { "name": "token", "type": "UserToken", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Returns `true` once the file has been removed and the company updated.", "type": "boolean" }, "errors": [ { "code": "ASSERTION_FAILED", "when": "The authenticated user's role is not one of `shipper`, `broker`, or `carrier`." } ], "references": { "models": [ "CompanyModel" ], "types": [ "UserToken" ] } }, { "name": "uploadLogo", "module": "companies", "path": "/companies/uploadLogo", "method": "POST", "summary": "Uploads a logo image to Google Cloud Storage for the given company and stores the resulting public URL on the company's `logoProfile`.", "params": [ { "name": "companyId", "type": "string", "summary": "Identifier of the company that the logo belongs to.", "required": true }, { "name": "docs", "type": "DocumentsUpload", "summary": "Document descriptor containing `file` (base64/dataURL), `extension`, and `name` of the logo to upload.", "required": true }, { "name": "token", "type": "UserToken", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Public URL of the uploaded logo file.", "type": "string" }, "errors": [ { "code": "Unauthorized", "when": "The authenticated user's role is not in `shipper`/`broker`/`carrier`, or the supplied `companyId` does not match the user's own company." }, { "code": "InvalidFileName", "when": "`docs.name` is missing or contains characters outside `[A-Za-z0-9_-]`." }, { "code": "InvalidExtension", "when": "`docs.extension` is missing or does not match `^[A-Za-z0-9]{1,8}$`." } ], "references": { "models": [ "CompanyModel" ], "interfaces": [ "DocumentsUpload" ], "types": [ "UserToken" ] } }, { "name": "EntityCSD_getEntityCSD", "module": "companies", "path": "/Company.EntityCSD.getEntityCSD", "method": "POST", "summary": "Returns the SAT digital seal (EntityCSD) document tied to the given company. Caller role must be shipper, broker or carrier.", "params": [ { "name": "idcompany", "type": "ID", "summary": "Identifier of the company whose CSD is being requested.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The EntityCSD document, or null if the company has none.", "type": "EntityCSD | null" }, "errors": [ { "code": "AssertionError", "when": "Caller's role is not 'shipper', 'broker' or 'carrier'." } ], "references": { "models": [ "EntityCSDModel" ] } }, { "name": "Settings_addAccesorials", "module": "companies", "path": "/Company.Settings.addAccesorials", "method": "POST", "summary": "Ensures a given accesorial (and its allowed unit list) is present in the caller's company settings, creating it if missing.", "params": [ { "name": "accessory", "type": "string", "summary": "Identifier of the accesorial to add.", "required": true }, { "name": "units", "type": "string[]", "summary": "Allowed measurement units for the accesorial.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Always `true` once the upsert completes.", "type": "boolean" }, "errors": [], "references": { "models": [ "SettingsModel" ] } }, { "name": "Settings_createSettingCompany", "module": "companies", "path": "/Company.Settings.createSettingCompany", "method": "POST", "summary": "Creates the initial Settings document for a new company, leaving every operational flag at its safe default. Pushes the 'Pago-Directo-Transportista' payment method as the default on the company document.", "params": [ { "name": "companyId", "type": "string", "summary": "Identifier of the company that will own the new settings.", "required": true } ], "response": { "summary": "The newly created Settings document.", "type": "Settings" }, "errors": [], "references": { "models": [ "SettingsModel", "__CompanyModel__" ] } }, { "name": "Settings_generateDefaultCompanySettings", "module": "companies", "path": "/Company.Settings.generateDefaultCompanySettings", "method": "POST", "summary": "Admin-only creator that inserts a fresh Settings document for a company with platform defaults.", "params": [ { "name": "companyId", "type": "ID", "summary": "Identifier of the company that will own the new settings document.", "required": true }, { "name": "token", "type": "string", "summary": "Admin session token.", "required": true } ], "response": { "summary": "The newly created Settings document.", "type": "Settings" }, "errors": [], "references": { "models": [ "SettingsModel" ] } }, { "name": "Settings_getCompanySettings", "module": "companies", "path": "/Company.Settings.getCompanySettings", "method": "POST", "summary": "Admin-only fetch of a company's settings document. If no settings exist for the company, generates and returns the default settings on the fly.", "params": [ { "name": "companyId", "type": "ID", "summary": "Identifier of the company whose settings are being read.", "required": true }, { "name": "token", "type": "string", "summary": "Admin session token.", "required": true } ], "response": { "summary": "Settings document for the company.", "type": "Settings" }, "errors": [], "references": { "models": [ "SettingsModel" ] } }, { "name": "Settings_getNearLocationStates", "module": "companies", "path": "/Company.Settings.getNearLocationStates", "method": "POST", "summary": "Geo-search that, for a given lat/lng pair and radius, returns the states within range and the carrier companies that list any of those states in `workingStates`. Each match is enriched with the carrier company document, its driver count and an offset coordinate so multiple results render side-by-side on a map.", "params": [ { "name": "lat", "type": "number", "summary": "Latitude of the search center.", "required": true }, { "name": "lng", "type": "number", "summary": "Longitude of the search center.", "required": true }, { "name": "distance", "type": "number", "summary": "Maximum distance in meters from the center used by the `$near` query.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Flat list of carrier matches with their company, working states, driver count and rendered map coordinates.", "type": "Array<{ lat: number, lng: number, location: any, company: object, startDate: any, endDate: any, workingStates: string[], totalDriver: number, deliveredDate: any }>" }, "errors": [], "references": { "models": [ "StatesModel", "SettingsModel", "__CompanyModel__", "UserModel" ] } }, { "name": "Settings_getSettings", "module": "companies", "path": "/Company.Settings.getSettings", "method": "POST", "summary": "Returns the calling user's company settings, with the internal `_shipperRate` field stripped from the payload. Falls back to default settings if none exist yet.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Settings document of the caller's company (without `_shipperRate`).", "type": "Settings" }, "errors": [], "references": { "models": [ "SettingsModel" ] } }, { "name": "Settings_removeCompanySettings", "module": "companies", "path": "/Company.Settings.removeCompanySettings", "method": "POST", "summary": "Admin-only delete that removes the Settings document for the specified company.", "params": [ { "name": "companyId", "type": "ID", "summary": "Identifier of the company whose settings document will be deleted.", "required": true }, { "name": "token", "type": "string", "summary": "Admin session token.", "required": true } ], "response": { "summary": "Mongoose deleteOne result.", "type": "{ n: number, deletedCount?: number, ok?: number }" }, "errors": [], "references": { "models": [ "SettingsModel" ] } }, { "name": "Settings_shipmentVisibilitySettings", "module": "companies", "path": "/Company.Settings.shipmentVisibilitySettings", "method": "POST", "summary": "Updates the caller's company-level shipment visibility flags `publicShipment` and `seeShipment` in a single call.", "params": [ { "name": "publicShipment", "type": "boolean", "summary": "Whether new shipments are public.", "required": true }, { "name": "seeShipment", "type": "boolean", "summary": "Whether the company can see other companies' shipments.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "`true` when the update completes successfully.", "type": "boolean" }, "errors": [], "references": { "models": [ "SettingsModel" ] } }, { "name": "get", "module": "containers", "path": "/containers/get", "method": "POST", "summary": "Returns a drayage container by id, but only if the caller (resolved from the auth token) owns the drayage that the container belongs to.", "params": [ { "name": "containerId", "type": "string", "summary": "Mongo id of the container to fetch.", "required": true }, { "name": "token", "type": "string", "summary": "Auth token used to resolve the calling user via MSAuth.", "required": true } ], "response": { "summary": "The container document associated with `containerId`.", "type": "Promise" }, "errors": [ { "code": "MissingContainerId", "when": "`containerId` is empty or falsy." }, { "code": "MissingToken", "when": "`token` is empty or falsy." }, { "code": "DrayageContainerNotFound", "when": "No container exists for `containerId`, the container's drayage cannot be loaded, or the authenticated user is not the owner of that drayage. The same code is used for all three cases to avoid existence enumeration." } ], "references": { "models": [ "Container", "Drayage" ] } }, { "name": "drayageList", "module": "customer-portal", "path": "/customer-portal/drayageList", "method": "POST", "summary": "Returns a paginated list of drayages associated with the authenticated customer's posted portal containers, optionally filtered by container number.", "params": [ { "name": "token", "type": "string", "summary": "Customer-portal session token of the requesting customer.", "required": true }, { "name": "skip", "type": "number", "summary": "Number of items to skip for pagination.", "required": false }, { "name": "limit", "type": "number", "summary": "Maximum number of items to return.", "required": false }, { "name": "search", "type": "string", "summary": "Optional case-insensitive regular expression matched against the container number.", "required": false } ], "response": { "summary": "Array of items pairing the portal container id with a projected drayage view that includes container, vehicle, driver and tracking status.", "type": "Array<{ _id: string; drayage: { _id: string; state: string; location: any; trackingStatus?: string; container: any; vehicle: any; driver: any } }>" }, "errors": [], "references": { "models": [ "CustomerPortalContainer", "Drayage", "User" ] } }, { "name": "editPostedContainer", "module": "customer-portal", "path": "/customer-portal/editPostedContainer", "method": "POST", "summary": "Updates pickup date, delivery and return data for an already Posted portal container and propagates the equivalent edits to its associated drayage.", "params": [ { "name": "containerId", "type": "string", "summary": "Identifier of the posted customer-portal container to edit.", "required": true }, { "name": "token", "type": "string", "summary": "Customer-portal session token of the requesting customer.", "required": true }, { "name": "pickupDate", "type": "string", "summary": "Optional new ISO pickup date for the container.", "required": false }, { "name": "deliveryInfo", "type": "SmartPortReleaseLocationInfo", "summary": "Optional new delivery location and contact information.", "required": false }, { "name": "returnInfo", "type": "SmartPortReleaseLocationInfo", "summary": "Optional new return location and contact information.", "required": false } ], "response": { "summary": "An httpOk envelope containing the updated container and drayage documents.", "type": "{ message: string; data: { container: CustomerPortalContainer; drayage: Drayage } }" }, "errors": [ { "code": "CUSTOMER_PORTAL_CONTAINER_NOT_FOUND", "when": "No customer-portal container exists with the provided id." }, { "code": "CUSTOMER_PORTAL_CONTAINER_UNAUTHORIZED_USER", "when": "The authenticated customer is not in the container's allowedCustomers list." }, { "code": "CUSTOMER_PORTAL_CONTAINER_NOT_POSTED", "when": "The container is not in the Posted status, so it cannot be edited through this endpoint." } ], "references": { "models": [ "CustomerPortalContainer", "Drayage", "User" ], "enums": [ "CustomerPortalContainerStatus" ], "types": [ "SmartPortReleaseLocationInfo" ] } }, { "name": "getContainerLocations", "module": "customer-portal", "path": "/customer-portal/getContainerLocations", "method": "POST", "summary": "Returns the full list of CDYS company locations associated with the carrier of a portal container that the authenticated customer is allowed to see.", "params": [ { "name": "containerId", "type": "string", "summary": "Identifier of the customer-portal container whose carrier locations are being requested.", "required": true }, { "name": "token", "type": "string", "summary": "Customer-portal session token of the requesting customer.", "required": true } ], "response": { "summary": "All CDYS-registered locations for the company that owns the container.", "type": "Location[]" }, "errors": [ { "code": "CUSTOMER_PORTAL_CONTAINER_NOT_FOUND", "when": "No customer-portal container exists with the provided id." }, { "code": "CUSTOMER_PORTAL_CONTAINER_UNAUTHORIZED_USER", "when": "The authenticated customer is not in the container's allowedCustomers list." } ], "references": { "models": [ "CustomerPortalContainer", "User" ] } }, { "name": "getPendingContainers", "module": "customer-portal", "path": "/customer-portal/getPendingContainers", "method": "POST", "summary": "Lists portal containers in the Pending status that the authenticated customer is allowed to see, paginated and decorated with the carrier company's load locations.", "params": [ { "name": "token", "type": "string", "summary": "Customer-portal session token of the requesting customer.", "required": true }, { "name": "skip", "type": "number", "summary": "Number of containers to skip for pagination. Defaults to 0.", "required": false }, { "name": "limit", "type": "number", "summary": "Maximum number of containers to return. Defaults to 25.", "required": false } ], "response": { "summary": "Array of pending portal containers, each paired with the carrier company's load locations.", "type": "Array<{ container: CustomerPortalContainer; locations?: Location[] }>" }, "errors": [], "references": { "models": [ "CustomerPortalContainer", "User" ], "enums": [ "CustomerPortalContainerStatus" ] } }, { "name": "getPostedContainers", "module": "customer-portal", "path": "/customer-portal/getPostedContainers", "method": "POST", "summary": "Lists portal containers already posted as drayages that the authenticated customer is allowed to see, decorated with their drayage and the carrier company's load locations.", "params": [ { "name": "skip", "type": "number", "summary": "Number of containers to skip for pagination. Defaults to 0.", "required": true }, { "name": "limit", "type": "number", "summary": "Maximum number of containers to return. Defaults to 25.", "required": true }, { "name": "token", "type": "string", "summary": "Customer-portal session token of the requesting customer.", "required": true } ], "response": { "summary": "Array of posted portal containers, each enriched with its drayage and the carrier company's load locations.", "type": "Array<{ container: CustomerPortalContainer; drayage?: Drayage; locations?: Location[] }>" }, "errors": [], "references": { "models": [ "CustomerPortalContainer", "Drayage", "User" ], "enums": [ "CustomerPortalContainerStatus" ] } }, { "name": "login", "module": "customer-portal", "path": "/customer-portal/login", "method": "POST", "summary": "Validates a customer's email authentication code, increments the retry counter, clears the code on success, and issues a new access token.", "params": [ { "name": "email", "type": "string", "summary": "Email address of the customer attempting to log in.", "required": true }, { "name": "code", "type": "string", "summary": "One-time authentication code previously delivered via requestAuthenticationCode.", "required": true } ], "response": { "summary": "Object containing the authenticated email and the issued access token.", "type": "{ email: string; token: string }" }, "errors": [ { "code": "USER_EMAIL_NOT_FOUND", "when": "No user is registered with the provided email address." }, { "code": "CUSTOMER_PORTAL_AUTHENTICATION_CODE_NOT_SENT", "when": "No authentication code has been requested or stored for this email." }, { "code": "CUSTOMER_PORTAL_AUTHENTICATION_CODE_RETRIES_EXCEEDED", "when": "The customer has already failed three or more verification attempts for the active code." }, { "code": "CUSTOMER_PORTAL_AUTHENTICATION_CODE_INVALID", "when": "The submitted code does not match the code stored for the customer." } ], "references": { "models": [ "User" ] } }, { "name": "loginOrCreateWithInvitationToken", "module": "customer-portal", "path": "/customer-portal/loginOrCreateWithInvitationToken", "method": "POST", "summary": "Decodes a customer-portal invitation token and either authenticates an existing portal user or provisions a new one with the supplied company and personal details, returning a fresh access token.", "params": [ { "name": "companyName", "type": "string", "summary": "Legal name of the company the new portal user belongs to.", "required": true }, { "name": "rfc", "type": "string", "summary": "Mexican RFC of the company the new portal user belongs to.", "required": true }, { "name": "email", "type": "string", "summary": "Email used purely for logging; the authoritative email is taken from the invitation token.", "required": true }, { "name": "firstName", "type": "string", "summary": "First name to assign to the new portal user.", "required": true }, { "name": "lastName", "type": "string", "summary": "Last name to assign to the new portal user.", "required": true }, { "name": "token", "type": "string", "summary": "Signed invitation token previously emailed to the customer.", "required": true } ], "response": { "summary": "An httpOk envelope containing the new access token for the invited customer.", "type": "{ message: string; data: { token: string } }" }, "errors": [], "references": { "models": [ "User", "Company" ] } }, { "name": "loginWithGoogleOAuthToken", "module": "customer-portal", "path": "/customer-portal/loginWithGoogleOAuthToken", "method": "POST", "summary": "Authenticates a customer-portal user via a verified Google OAuth ID token, ensuring a portal user exists for the email and returning a fresh access token.", "params": [ { "name": "token", "type": "string", "summary": "Google OAuth ID token issued to the user; verified server-side to extract the email.", "required": true } ], "response": { "summary": "An httpOk envelope containing the freshly minted access token for the portal customer.", "type": "{ message: string; data: { token: string } }" }, "errors": [ { "code": "GOOGLE_OAUTH_EMAIL_NOT_VERIFED", "when": "Google reports that the email associated with the OAuth token has not been verified." } ], "references": { "models": [ "User" ] } }, { "name": "loginWithInvitationToken", "module": "customer-portal", "path": "/customer-portal/loginWithInvitationToken", "method": "POST", "summary": "Decodes a customer-portal invitation token, ensures a portal user for the embedded email, and returns an access token for that user.", "params": [ { "name": "token", "type": "string", "summary": "Signed invitation token previously emailed to the customer; decodes to the invited email address.", "required": true } ], "response": { "summary": "An httpOk envelope containing the new access token for the invited customer.", "type": "{ message: string; data: { token: string } }" }, "errors": [], "references": { "models": [ "User" ] } }, { "name": "postContainer", "module": "customer-portal", "path": "/customer-portal/postContainer", "method": "POST", "summary": "Promotes a Pending portal container to Posted by setting pickup, delivery and (optional) return information, creating the matching drayage and linking it back to the container.", "params": [ { "name": "containerId", "type": "string", "summary": "Identifier of the customer-portal container to post.", "required": true }, { "name": "pickupDate", "type": "string", "summary": "ISO date string indicating when the container will be picked up.", "required": true }, { "name": "deliveryInfo", "type": "SmartPortReleaseLocationInfo", "summary": "Delivery location and contact info matching the SmartPortRelease pickup schema.", "required": true }, { "name": "returnInfo", "type": "SmartPortReleaseLocationInfo | undefined", "summary": "Optional return location and contact info matching the SmartPortRelease pickup schema.", "required": false }, { "name": "token", "type": "string", "summary": "Customer-portal session token of the requesting customer.", "required": true } ], "response": { "summary": "An httpOk envelope containing the id of the drayage that was created from the container.", "type": "{ message: string; data: { drayageId: string } }" }, "errors": [ { "code": "CUSTOMER_PORTAL_CONTAINER_NOT_FOUND", "when": "No customer-portal container exists with the provided id." }, { "code": "CUSTOMER_PORTAL_CONTAINER_UNAUTHORIZED_USER", "when": "The authenticated customer is not in the container's allowedCustomers list." }, { "code": "CUSTOMER_PORTAL_CONTAINER_NOT_PENDING", "when": "The container is not in the Pending status, so it cannot be posted again." } ], "references": { "models": [ "CustomerPortalContainer", "Drayage", "User" ], "enums": [ "CustomerPortalContainerStatus" ], "types": [ "SmartPortReleaseLocationInfo" ] } }, { "name": "requestAuthenticationCode", "module": "customer-portal", "path": "/customer-portal/requestAuthenticationCode", "method": "POST", "summary": "Generates a one-time email authentication code for a portal customer and sends it by email, throttled to one request per minute.", "params": [ { "name": "email", "type": "string", "summary": "Email address of the registered portal customer that should receive the authentication code.", "required": true } ], "response": { "summary": "An httpOk envelope confirming that the authentication code was sent to the email address.", "type": "{ message: string }" }, "errors": [ { "code": "USER_EMAIL_NOT_FOUND", "when": "No user is registered with the provided email address." }, { "code": "CUSTOMER_PORTAL_AUTHENTICATION_CODE_ALREADY_SENT", "when": "An authentication code was sent to the same email less than 60 seconds ago and the throttle window is still active." } ], "references": { "models": [ "User" ] } }, { "name": "documentoComplementoPago", "module": "data-carta-porte", "path": "/data-carta-porte/documentoComplementoPago", "method": "POST", "summary": "PAC callback that uploads the freshly stamped XML/PDF complemento de pago to GCS, updates the DocumentPago record, links the related Carta Porte rows, notifies the originating user via realtime and resolves or rejects the in-flight ComplementoDePagoPromise. Returns an httpOk envelope with the public XML/PDF URLs.", "params": [ { "name": "payload", "type": "any", "summary": "PAC callback payload (documentUniqueIdentifier, b64CfdiXml, b64CfdiPdf, status, errorLog).", "required": true }, { "name": "_userId", "type": "string", "summary": "Caller-supplied user id (legacy slot, currently unused inside the handler).", "required": false } ], "response": { "summary": "Returns { data: { status, errorLog } } when the PAC reports a stamping error, otherwise httpOk('Complemento de Pago generado exitosamente', { pdf, xml }).", "type": "Promise<{ data: { status, errorLog } } | ReturnType>" }, "errors": [ { "code": "CpagoNotFound", "when": "No DocumentPago exists for the supplied folio (documentUniqueIdentifier)." }, { "code": "PacDocumentStampFailed", "when": "Wrapped onto the rejected ComplementoDePagoPromise when the PAC reports an errorLog." } ], "references": { "models": [ "DocumentPago", "DataCartaPorte" ] } }, { "name": "getComplementoPago", "module": "data-carta-porte", "path": "/data-carta-porte/getComplementoPago", "method": "POST", "summary": "Aggregates DocumentPago records for the authenticated carrier (active statusData), optionally filtered by broker and dateCreation, exposing fechaPago and formaDePago from the first dataCartaPorte entry.", "params": [ { "name": "brokerId", "type": "string", "summary": "Optional broker company id used to filter the aggregation.", "required": false }, { "name": "dateFilt", "type": "string", "summary": "Optional ISO date matched against dateCreation.", "required": false }, { "name": "token", "type": "UserToken", "summary": "Authenticated user token resolved through MSAuth.", "required": true } ], "response": { "summary": "Array of DocumentPago aggregation rows enriched with fechaPago and formaDePago.", "type": "ReturnType" }, "errors": [ { "code": "InvalidDateFilter", "when": "dateFilt was provided but could not be parsed into a valid Date." } ], "references": { "models": [ "DocumentPago", "DataCartaPorte" ] } }, { "name": "getDataFactura", "module": "data-carta-porte", "path": "/data-carta-porte/getDataFactura", "method": "POST", "summary": "Returns signed Carta Porte data records for the authenticated carrier that have no associated complemento de pago, optionally filtered by broker and date, decorating each item with a synthetic factura payload when none has been generated yet.", "params": [ { "name": "brokerId", "type": "string", "summary": "Optional broker company id used to filter the result set.", "required": false }, { "name": "_carrierId", "type": "string", "summary": "Legacy slot retained for the public contract; matching is performed against the authenticated user's companyId.", "required": false }, { "name": "dateFilt", "type": "string", "summary": "Optional ISO date used as an upper bound (plus DATE_FACTURA_LOOKAHEAD_MS) on the Carta Porte emission date.", "required": false }, { "name": "token", "type": "UserToken", "summary": "Authenticated user token resolved through MSAuth.", "required": true } ], "response": { "summary": "Array of DataCartaPorte rows (lean), each enriched with a synthetic `payload` when not already generated.", "type": "ReturnType" }, "errors": [ { "code": "InvalidDateFilter", "when": "dateFilt was provided but could not be parsed into a valid Date." } ], "references": { "models": [ "DataCartaPorte" ] } }, { "name": "selectCliente", "module": "data-carta-porte", "path": "/data-carta-porte/selectCliente", "method": "POST", "summary": "Returns the distinct list of broker companies (id and identity name) that have ever been counterparties on the carrier's Carta Porte rows.", "params": [ { "name": "carrierId", "type": "ID", "summary": "Carrier company id whose broker counterparties are returned.", "required": true }, { "name": "token", "type": "UserToken", "summary": "Authenticated user token resolved through MSAuth.", "required": true } ], "response": { "summary": "Array of { _id, companyId, companyName } entries deduplicated by companyId.", "type": "ReturnType" }, "errors": [], "references": { "models": [ "DataCartaPorte" ] } }, { "name": "updateDataFactura", "module": "data-carta-porte", "path": "/data-carta-porte/updateDataFactura", "method": "POST", "summary": "Marks a batch of Carta Porte records as paid by writing payment metadata (date, form, amount, partial number) and flipping statusData off for each entry, requiring a valid user token.", "params": [ { "name": "payload", "type": "DataComplementoPago[]", "summary": "Payment entries keyed by Carta Porte uniqueId.", "required": true }, { "name": "token", "type": "UserToken", "summary": "Authenticated user token resolved through MSAuth.", "required": true } ], "response": { "summary": "Returns true once every entry has been persisted.", "type": "Promise" }, "errors": [], "references": { "models": [ "DataCartaPorte" ], "interfaces": [ "DataComplementoPago" ] } }, { "name": "dataInfo", "module": "data-lookups", "path": "/data-lookups/dataInfo", "method": "POST", "summary": "Return a static catalogue describing origin location types, destination location types, packing types, and container types used by drayage forms.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "Single-element array containing the static lookup tables for origin/destination location types, packing types, and container types.", "type": "Array<{ originLocationType: string[]; destinaLocationType: string[]; packingType: string[]; containerType: string[] }>" }, "errors": [ { "code": "InvalidToken", "when": "Token argument is not a string." } ], "references": {} }, { "name": "get", "module": "data-lookups", "path": "/data-lookups/get", "method": "POST", "summary": "Return the list of accessorial services available for the caller's company. Reads the SERVICES_DRAYAGE_MX lookup, merges in any company-specific accessorials, and orders the result with the well-known service-cost and fuel types first.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "Ordered list of accessorial service entries combining the SERVICES_DRAYAGE_MX lookup and the company's custom accessorials.", "type": "Array<{ type: string; [key: string]: unknown }>" }, "errors": [ { "code": "InvalidToken", "when": "Token argument is not a string." }, { "code": "DataLookupNotFound", "when": "The SERVICES_DRAYAGE_MX lookup record is missing from the data-lookups collection." } ], "references": { "models": [ "DataLookUp", "Settings" ] } }, { "name": "documentoComplementoPago", "module": "data-carta-porte", "path": "/DataCartaPorte.documentoComplementoPago", "method": "POST", "summary": "Persists the XML and PDF artifacts of a Complemento de Pago returned by the PAC, links it to its Carta Porte records, notifies the realtime channel, and resolves or rejects the pending stamp promise depending on whether the PAC reported an error.", "params": [ { "name": "payload", "type": "{ documentUniqueIdentifier: string; b64CfdiXml: string; b64CfdiPdf: string; status: string; errorLog?: string }", "summary": "PAC response containing the unique identifier, base64 XML and PDF, status, and optional error log.", "required": true }, { "name": "userId", "type": "string", "summary": "Identifier of the user that originated the stamping request.", "required": true } ], "response": { "summary": "An httpOk envelope with the public URLs of the generated PDF and XML when stamping succeeded.", "type": "{ message: string; data: { pdf: string; xml: string } } | { data: { status: 'Error'; errorLog: string } }" }, "errors": [ { "code": "CPAGO_NOT_FOUND", "when": "No DocumentPago exists with the supplied documentUniqueIdentifier when finalising the stamp." }, { "code": "PAC_DOCUMENT_STAMP_FAILED", "when": "The PAC reported an errorLog while stamping the Complemento de Pago; the pending stamp promise is rejected with this error." } ], "references": { "models": [ "DocumentPago", "DataCartaPorte" ] } }, { "name": "getComplementoPago", "module": "data-carta-porte", "path": "/DataCartaPorte.getComplementoPago", "method": "POST", "summary": "Lists the carrier's payment complements (DocumentPago) optionally filtered by broker and creation date, augmented with the first dataCartaPorte's payment date and form.", "params": [ { "name": "brokerId", "type": "string", "summary": "Optional broker company id used to filter the result set.", "required": true }, { "name": "dateFilt", "type": "string", "summary": "Optional ISO date matched against the creation date of the payment complement.", "required": true }, { "name": "token", "type": "UserToken", "summary": "Authenticated user token resolved through MSAuth.", "required": true } ], "response": { "summary": "Array of DocumentPago aggregates that include the first underlying Carta Porte's fechaPago and formaDePago.", "type": "Array" }, "errors": [], "references": { "models": [ "DocumentPago", "DataCartaPorte" ] } }, { "name": "getDataFactura", "module": "data-carta-porte", "path": "/DataCartaPorte.getDataFactura", "method": "POST", "summary": "Returns signed Carta Porte data records for the authenticated carrier that have no associated complemento de pago, optionally filtered by broker and date, decorating each item with a synthetic factura payload when none has been generated yet.", "params": [ { "name": "brokerId", "type": "string", "summary": "Optional broker company id used to filter the result set.", "required": true }, { "name": "carrierId", "type": "string", "summary": "Carrier identifier supplied by the legacy contract; matching is performed against the authenticated user's companyId.", "required": true }, { "name": "dateFilt", "type": "string", "summary": "Optional ISO date used as an upper bound (plus one day) on the Carta Porte emission date.", "required": true }, { "name": "token", "type": "UserToken", "summary": "Authenticated user token resolved through MSAuth.", "required": true } ], "response": { "summary": "Array of Carta Porte data records eligible for invoicing, each with a synthesised payload when one was not already stored.", "type": "Array" }, "errors": [], "references": { "models": [ "DataCartaPorte" ] } }, { "name": "selectCliente", "module": "data-carta-porte", "path": "/DataCartaPorte.selectCliente", "method": "POST", "summary": "Returns the unique list of broker companies that have appeared as the broker on any Carta Porte data record for the given carrier.", "params": [ { "name": "carrierId", "type": "ID", "summary": "Identifier of the carrier company whose related brokers are being requested.", "required": true }, { "name": "token", "type": "UserToken", "summary": "Authenticated user token resolved through MSAuth.", "required": true } ], "response": { "summary": "Deduplicated list of broker companies (id and name) related to the carrier.", "type": "Array<{ companyId: string; companyName: string }>" }, "errors": [], "references": { "models": [ "DataCartaPorte", "Company" ] } }, { "name": "updateComplementoPago", "module": "data-carta-porte", "path": "/DataCartaPorte.updateComplementoPago", "method": "POST", "summary": "Marks a payment complement (DocumentPago) as processed by setting its statusData flag to false.", "params": [ { "name": "dataId", "type": "ID", "summary": "Identifier of the DocumentPago whose status should be cleared.", "required": true }, { "name": "token", "type": "UserToken", "summary": "Authenticated user token resolved through MSAuth.", "required": true } ], "response": { "summary": "MongoDB updateOne result describing how many DocumentPago entries were affected.", "type": "{ acknowledged: boolean; modifiedCount: number; matchedCount: number; upsertedCount: number; upsertedId: string | null }" }, "errors": [], "references": { "models": [ "DocumentPago" ] } }, { "name": "updateDataFactura", "module": "data-carta-porte", "path": "/DataCartaPorte.updateDataFactura", "method": "POST", "summary": "Bulk-updates payment metadata (date, form, amount and partiality) on each Carta Porte data record matching the supplied uniqueIds and marks them as ready for the next stage.", "params": [ { "name": "payload", "type": "DataComplementoPago[]", "summary": "List of payment data items to apply, each identifying the target Carta Porte by uniqueId.", "required": true }, { "name": "token", "type": "UserToken", "summary": "Authenticated user token resolved through MSAuth.", "required": true } ], "response": { "summary": "Returns boolean true once every Carta Porte record has been updated.", "type": "boolean" }, "errors": [], "references": { "models": [ "DataCartaPorte" ], "interfaces": [ "DataComplementoPago" ] } }, { "name": "approve", "module": "documents", "path": "/documents/approve", "method": "POST", "summary": "Approves a single document of the given type on a drayage's document setup, persisting any signature/payload data supplied by the caller.", "params": [ { "name": "shipment_id", "type": "ID", "summary": "Identifier of the drayage whose document is being approved.", "required": true }, { "name": "document_type", "type": "DOCUMENT_TYPE", "summary": "Document type within the drayage setup to approve (e.g. agreement, rate_confirmation, w9).", "required": true }, { "name": "token", "type": "UserToken", "summary": "User session token returned by /auth/login", "required": true }, { "name": "data", "type": "any", "summary": "Optional signature / approval payload stored alongside the document entry.", "required": false } ], "response": { "summary": "Result returned by the approveDrayageDocument helper, typically the updated document setup." }, "errors": [], "references": { "enums": [ "DOCUMENT_TYPE" ] } }, { "name": "approveAll", "module": "documents", "path": "/documents/approveAll", "method": "POST", "summary": "Approves every pending document on a drayage's document setup in a single call.", "params": [ { "name": "shipment_id", "type": "ID", "summary": "Identifier of the drayage whose documents are being bulk-approved.", "required": true }, { "name": "token", "type": "UserToken", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Result returned by the approveAllDrayageDocuments helper, typically the updated document setup." }, "errors": [] }, { "name": "decline", "module": "documents", "path": "/documents/decline", "method": "POST", "summary": "Declines a document of the given type on a drayage's document setup, attaching an optional reviewer comment.", "params": [ { "name": "shipment_id", "type": "ID", "summary": "Identifier of the drayage whose document is being declined.", "required": true }, { "name": "document_type", "type": "DOCUMENT_TYPE", "summary": "Document type within the drayage setup to decline.", "required": true }, { "name": "comment", "type": "string | null", "summary": "Optional comment explaining why the document was declined.", "required": false }, { "name": "token", "type": "UserToken", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Result returned by the declineDrayageDocument helper, typically the updated document setup." }, "errors": [], "references": { "enums": [ "DOCUMENT_TYPE" ] } }, { "name": "getCompanyDocuments", "module": "documents", "path": "/documents/getCompanyDocuments", "method": "POST", "summary": "Returns the document hub for a company together with its document groups and the latest version of each document instance, joined in a single aggregation.", "params": [ { "name": "companyId", "type": "ID", "summary": "Identifier of the company whose document hub is requested.", "required": true }, { "name": "token", "type": "UserToken", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The company's DocumentHub with nested groups and each group's document instances ordered by version descending.", "type": "IDocumentHub" }, "errors": [], "references": { "models": [ "DocumentHub", "DocumentGroup", "DocumentInstance" ], "interfaces": [ "IDocumentHub" ] } }, { "name": "getDocumentSetup", "module": "documents", "path": "/documents/getDocumentSetup", "method": "POST", "summary": "Returns the DocumentSetup for a shipment, restricted to users whose company is either the shipper or the carrier on the setup.", "params": [ { "name": "shipmentId", "type": "ID", "summary": "Identifier of the shipment whose DocumentSetup is requested.", "required": true }, { "name": "token", "type": "UserToken", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The DocumentSetup document for the shipment, or null when none exists." }, "errors": [ { "code": "UNAUTHORIZED", "when": "The setup exists but the caller's company is neither the shipper nor the carrier on it." } ], "references": { "models": [ "DocumentSetup" ] } }, { "name": "hasDocument", "module": "documents", "path": "/documents/hasDocument", "method": "POST", "summary": "Checks whether a company has uploaded all the document types its role requires (`w9`, `insurance`, `authority`, `agreement` for brokers; `w9`, `insurance`, `authority` or `cp` for carriers).", "params": [ { "name": "companyId", "type": "string", "summary": "Identifier of the company whose mandatory documents are inspected.", "required": true }, { "name": "token", "type": "UserToken", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "true when every required document for the company's role has at least one active instance; otherwise false (errors during evaluation result in undefined).", "type": "boolean" }, "errors": [], "references": { "models": [ "Company", "DocumentHub", "DocumentGroup", "DocumentInstance" ] } }, { "name": "isSignedAgreementDrayage", "module": "documents", "path": "/documents/isSignedAgreementDrayage", "method": "POST", "summary": "Returns whether the carrier `agreement` document on a drayage's DocumentSetup is accepted.", "params": [ { "name": "shipment", "type": "string", "summary": "Identifier of the drayage whose agreement signature status is queried.", "required": true }, { "name": "token", "type": "UserToken", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "true when the DocumentSetup has an accepted `agreement` shipper doc, false otherwise.", "type": "Boolean" }, "errors": [ { "code": "AssertionError", "when": "The drayage referenced by shipment does not exist." } ], "references": { "models": [ "Drayage", "DocumentSetup" ] } }, { "name": "listDocumentMexico", "module": "documents", "path": "/documents/listDocumentMexico", "method": "POST", "summary": "Lists the latest version of each Mexican-compliance document instance for a company; falls back to admin-token access when the caller is not a regular user.", "params": [ { "name": "companyId", "type": "string", "summary": "Identifier of the company whose Mexican documents are requested.", "required": true }, { "name": "token", "type": "AdminToken | UserToken", "summary": "User or admin session token; if it is not a user token, the request is allowed when it has access to `Documents.listDocumentMexico`.", "required": true } ], "response": { "summary": "Deduplicated list of the highest-version document instances for the company." }, "errors": [ { "code": "AccessDenied", "when": "The token is neither a valid user token nor authorised for the `Documents.listDocumentMexico` capability." } ], "references": { "models": [ "DocumentHub", "DocumentGroup", "DocumentInstance", "Company" ] } }, { "name": "removeDocumentMexico", "module": "documents", "path": "/documents/removeDocumentMexico", "method": "POST", "summary": "Deletes a Mexican-compliance DocumentInstance and its underlying file in cloud storage for the caller's company.", "params": [ { "name": "documentId", "type": "ID", "summary": "Identifier of the DocumentInstance to delete.", "required": true }, { "name": "token", "type": "UserToken", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "true once the cloud-storage file and the DocumentInstance row have been removed.", "type": "boolean" }, "errors": [], "references": { "models": [ "DocumentInstance" ] } }, { "name": "removePreviousDoc", "module": "documents", "path": "/documents/removePreviousDoc", "method": "POST", "summary": "Soft-deletes a DocumentInstance owned by the caller's company and writes a History entry recording the removal.", "params": [ { "name": "docId", "type": "ID", "summary": "Identifier of the DocumentInstance to deactivate.", "required": true }, { "name": "token", "type": "UserToken", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "true when the document was deactivated and the history entry created, false when the update did not modify any record.", "type": "boolean" }, "errors": [ { "code": "USER_NOT_AUTHORIZED", "when": "The DocumentInstance does not belong to the caller's company." } ], "references": { "models": [ "DocumentInstance", "DocumentGroup", "DocumentHub", "Company", "History" ] } }, { "name": "uploadDocumentMexico", "module": "documents", "path": "/documents/uploadDocumentMexico", "method": "POST", "summary": "Uploads one or more Mexican-compliance company documents (PDFs) to the company's document hub, tagging them with the `mx` working rules and any additional validation metadata supplied by the caller.", "params": [ { "name": "document", "type": "Array<{ doc: { file: any; name: string }; typeDocument: string; nameDocument: string }>", "summary": "List of documents to upload, each carrying the file payload, the document type and the human-friendly name.", "required": true }, { "name": "companyId", "type": "ID", "summary": "Identifier of the company that owns the documents.", "required": true }, { "name": "token", "type": "UserToken", "summary": "User session token returned by /auth/login", "required": true }, { "name": "dataValidation", "type": "object", "summary": "Extra validation metadata merged into every uploaded document instance.", "required": false } ], "response": { "summary": "The result of the last uploadCompanyDocument call (typically the persisted document instance)." }, "errors": [], "references": { "models": [ "DocumentInstance" ] } }, { "name": "cancel", "module": "drayage-group", "path": "/drayage-group/cancel", "method": "POST", "summary": "Cancels every drayage attached to a drayage group. Each drayage must not already be Delivered or Cancelled before the cancellation begins. Caller's company must be the shipper or carrier of the group.", "params": [ { "name": "drayageGroupId", "type": "string", "summary": "Public identifier (`uniqueId`) of the drayage group.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Standard httpOk envelope confirming the cancellation.", "type": "{ ok: true, message: string }" }, "errors": [ { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage group was found with the supplied id." }, { "code": "DRAYAGE_GROUP_UNAUTHORIZED", "when": "Caller's company is neither the shipper nor the carrier of the drayage group." }, { "code": "DRAYAGE_GROUP_UNAUTHORIZED", "when": "At least one drayage in the group is already in `Delivered` or `Cancelled` state and cannot be cancelled." } ], "references": { "models": [ "DrayageGroupModel", "DrayageModel" ], "enums": [ "DrayageState" ] } }, { "name": "containers", "module": "drayage-group", "path": "/drayage-group/containers", "method": "POST", "summary": "Lists every container attached to a drayage group. Caller's company must be the shipper or carrier of the group.", "params": [ { "name": "drayageGroupId", "type": "string", "summary": "Public identifier (`uniqueId`) of the drayage group.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Array of DrayageGroupContainer documents.", "type": "DrayageGroupContainer[]" }, "errors": [ { "code": "DRAYAGE_GROUP_NOT_FOUND", "when": "No drayage group exists with the supplied id." }, { "code": "DRAYAGE_GROUP_UNAUTHORIZED", "when": "Caller's company is neither the shipper nor the carrier of the drayage group." } ], "references": { "models": [ "DrayageGroupModel" ] } }, { "name": "create", "module": "drayage-group", "path": "/drayage-group/create", "method": "POST", "summary": "Creates a new drayage group (a collection of related drayage shipments) for the caller's company using the supplied creation payload.", "params": [ { "name": "payload", "type": "DrayageGroupCreatePayload", "summary": "Drayage group creation payload (referenceId, overview, pickup, destination, return, etc.). Validated against DrayageGroupCreatePayloadSchema.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The newly created DrayageGroup document.", "type": "DrayageGroup" }, "errors": [], "references": { "models": [ "DrayageGroupModel" ], "types": [ "DrayageGroupCreatePayload" ] } }, { "name": "deleteDocument", "module": "drayage-group", "path": "/drayage-group/deleteDocument", "method": "POST", "summary": "Removes a previously uploaded document from a drayage group by name. Caller's company must be the shipper or carrier of the group.", "params": [ { "name": "drayageGroupId", "type": "string", "summary": "Public identifier (`uniqueId`) of the drayage group.", "required": true }, { "name": "documentName", "type": "string", "summary": "Name of the document to remove.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "No return value. The document is removed from storage.", "type": "void" }, "errors": [ { "code": "DRAYAGE_GROUP_UNAUTHORIZED", "when": "Caller's company is neither the shipper nor the carrier of the drayage group." } ], "references": { "models": [ "DrayageGroupModel" ] } }, { "name": "documents", "module": "drayage-group", "path": "/drayage-group/documents", "method": "POST", "summary": "Lists the documents attached to a drayage group. Caller's company must be the shipper or carrier of the group.", "params": [ { "name": "drayageGroupId", "type": "string", "summary": "Public identifier (`uniqueId`) of the drayage group.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Array of document descriptors attached to the drayage group.", "type": "any[]" }, "errors": [ { "code": "DRAYAGE_GROUP_UNAUTHORIZED", "when": "Caller's company is neither the shipper nor the carrier of the drayage group." } ], "references": { "models": [ "DrayageGroupModel" ] } }, { "name": "drayages", "module": "drayage-group", "path": "/drayage-group/drayages", "method": "POST", "summary": "Returns every drayage attached to a drayage group. Caller's company must be the shipper or carrier of the group.", "params": [ { "name": "drayageGroupId", "type": "string", "summary": "Public identifier (`uniqueId`) of the drayage group.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Array of Drayage documents linked to the group.", "type": "Drayage[]" }, "errors": [ { "code": "DRAYAGE_GROUP_UNAUTHORIZED", "when": "Caller's company is neither the shipper nor the carrier of the drayage group." } ], "references": { "models": [ "DrayageGroupModel", "DrayageModel" ] } }, { "name": "duplicate", "module": "drayage-group", "path": "/drayage-group/duplicate", "method": "POST", "summary": "Creates a copy of an existing drayage group (referenceId, overview, pickup, destination, return) and clones every non-cancelled drayage of the source group into the new group, preserving its containers.", "params": [ { "name": "drayageGroupId", "type": "string", "summary": "Public identifier (`uniqueId`) of the drayage group to clone.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The newly created DrayageGroup document.", "type": "DrayageGroup" }, "errors": [], "references": { "models": [ "DrayageGroupModel", "DrayageModel" ] } }, { "name": "edit", "module": "drayage-group", "path": "/drayage-group/edit", "method": "POST", "summary": "Patches an existing drayage group with a partial payload. Caller must be a broker or shipper that owns (acts as shipper of) the drayage group.", "params": [ { "name": "drayageGroupId", "type": "string", "summary": "Public identifier (`uniqueId`) of the drayage group to edit.", "required": true }, { "name": "payload", "type": "Partial", "summary": "Subset of the DrayageGroup fields to update.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Standard httpOk envelope including the `drayageGroupId`.", "type": "{ ok: true, message: string, drayageGroupId: string }" }, "errors": [ { "code": "AssertionError", "when": "Caller's role is not 'broker' or 'shipper'." }, { "code": "DRAYAGE_GROUP_UNAUTHORIZED", "when": "Caller's company is not the shipper of the drayage group." } ], "references": { "models": [ "DrayageGroupModel" ] } }, { "name": "find", "module": "drayage-group", "path": "/drayage-group/find", "method": "POST", "summary": "Paginated, filtered listing of the caller's drayage groups. Brokers see groups by `companyId`; carriers see them by `carrierCompanyId`. Joins each group with its drayages, containers, broker company, carrier company and users, and supports advanced filtering by drayage state (including in-transit substages), Carta Porte presence, carrier or shipper user.", "params": [ { "name": "filter", "type": "DrayageGroup & FilterDrayageGroup", "summary": "Filter object. Recognised special keys: `state` (drayage state or container substage), `cartaPorte` (boolean), `carrierCompanyId`, `userId`. Any other field is forwarded to a Mongo $match.", "required": true }, { "name": "skip", "type": "number", "summary": "Number of documents to skip (offset).", "required": true }, { "name": "limit", "type": "number", "summary": "Maximum number of documents to return.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Array of drayage groups with joined company/user/container metadata, plus computed `state`, `containerCount` and `totalRate` fields.", "type": "Array" }, "errors": [], "references": { "models": [ "DrayageGroupModel" ], "types": [ "FilterDrayageGroup" ] } }, { "name": "get", "module": "drayage-group", "path": "/drayage-group/get", "method": "POST", "summary": "Returns the active drayage group identified by `drayageGroupId` (matched against `uniqueId` and the caller's company), enriched with `totalRate` (the sum of the `payment.rate` of every non-cancelled drayage in the group).", "params": [ { "name": "drayageGroupId", "type": "string", "summary": "Public identifier (`uniqueId`) of the drayage group.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The drayage group document with an extra `totalRate` field, or undefined when no match is found.", "type": "DrayageGroup & { totalRate: number }" }, "errors": [], "references": { "models": [ "DrayageGroupModel" ] } }, { "name": "getDrayageGroupCarrier", "module": "drayage-group", "path": "/drayage-group/getDrayageGroupCarrier", "method": "POST", "summary": "Returns the company document for the carrier currently assigned to a drayage group. Caller's company must be the shipper or carrier of the group.", "params": [ { "name": "drayageGroupId", "type": "string", "summary": "Public identifier (`uniqueId`) of the drayage group.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The carrier company document.", "type": "Company" }, "errors": [ { "code": "DRAYAGE_GROUP_UNAUTHORIZED", "when": "Caller's company is neither the shipper nor the carrier of the drayage group." }, { "code": "DRAYAGE_GROUP_CARRIER_NOT_FOUND", "when": "The drayage group has no carrier assigned yet." } ], "references": { "models": [ "DrayageGroupModel", "CompanyModel" ] } }, { "name": "remove", "module": "drayage-group", "path": "/drayage-group/remove", "method": "POST", "summary": "Soft-deletes a drayage group (sets `isActive: false`). Drayages that are already past the new/open/awarded states are hard-deleted as part of the operation. Caller's company must be the shipper or carrier of the group.", "params": [ { "name": "drayageGroupId", "type": "string", "summary": "Public identifier (`uniqueId`) of the drayage group.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Standard httpOk envelope confirming the removal.", "type": "{ ok: true, message: string }" }, "errors": [ { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage group was found with the supplied id." }, { "code": "DRAYAGE_GROUP_UNAUTHORIZED", "when": "Caller's company is neither the shipper nor the carrier of the drayage group." } ], "references": { "models": [ "DrayageGroupModel", "DrayageModel" ] } }, { "name": "setCarrier", "module": "drayage-group", "path": "/drayage-group/setCarrier", "method": "POST", "summary": "Assigns a carrier user (and their company) to a drayage group together with the rates that should apply for full and single drayages. For each non-cancelled drayage in the group, schedules a `DrayageGroupSetCarrier` task that pushes the matching rate, notifies broker and carrier companies and forwards the payload to CDYS.", "params": [ { "name": "drayageGroupId", "type": "string", "summary": "Public identifier (`uniqueId`) of the drayage group.", "required": true }, { "name": "carrierId", "type": "string", "summary": "Identifier of the carrier user being awarded the group.", "required": true }, { "name": "rates", "type": "{ full?: string, single?: string }", "summary": "Optional rate identifiers to associate with full and single drayages of the group.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Array of task results, one per drayage that was awarded.", "type": "any[]" }, "errors": [ { "code": "USER_NOT_FOUND", "when": "No user exists with the supplied `carrierId`." }, { "code": "DRAYAGE_RATE_NOT_FOUND", "when": "`rates.full` was provided but no matching drayage rate was found between broker and carrier companies." }, { "code": "DRAYAGE_RATE_NOT_FOUND", "when": "`rates.single` was provided but no matching drayage rate was found between broker and carrier companies." } ], "references": { "models": [ "DrayageGroupModel" ], "enums": [ "TaskType", "DrayageTruckType", "TaskEntityType" ] } }, { "name": "setCommodities", "module": "drayage-group", "path": "/drayage-group/setCommodities", "method": "POST", "summary": "Replaces the list of commodities for a drayage group. Caller must act as shipper of the group.", "params": [ { "name": "drayageGroupId", "type": "string", "summary": "Public identifier (`uniqueId`) of the drayage group.", "required": true }, { "name": "commodities", "type": "DrayageGroupCommodityPayload[]", "summary": "Commodity payload array, validated against DrayageGroupCommodityPayloadSchema.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Standard httpOk envelope reporting the number of commodities that were updated.", "type": "{ ok: true, message: string }" }, "errors": [ { "code": "DRAYAGE_GROUP_UNAUTHORIZED", "when": "Caller's company is not the shipper of the drayage group." } ], "references": { "models": [ "DrayageGroupModel" ], "types": [ "DrayageGroupCommodityPayload" ] } }, { "name": "setContainers", "module": "drayage-group", "path": "/drayage-group/setContainers", "method": "POST", "summary": "Replaces the list of containers attached to a drayage group. Trims each `containerNumber` and, when the group already has a carrier, fires a `DrayageGroupUpdated` notification to the broker company. Caller must act as shipper of the group.", "params": [ { "name": "drayageGroupId", "type": "string", "summary": "Public identifier (`uniqueId`) of the drayage group.", "required": true }, { "name": "containers", "type": "DrayageGroupContainerPayload[]", "summary": "Container payload array, validated against DrayageGroupContainerPayloadSchema.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "No return value. Containers are persisted as a side effect.", "type": "void" }, "errors": [ { "code": "DRAYAGE_GROUP_UNAUTHORIZED", "when": "Caller's company is not the shipper of the drayage group." } ], "references": { "models": [ "DrayageGroupModel" ], "types": [ "DrayageGroupContainerPayload" ] } }, { "name": "universalSearch", "module": "drayage-group", "path": "/drayage-group/universalSearch", "method": "POST", "summary": "Cached (30s) search over the caller's drayage groups by uniqueId, folioid, folio, container number or drayage uniqueId. Returns the lightweight projection used by global search bars together with counts of single/full drayages per group.", "params": [ { "name": "search", "type": "string", "summary": "Search text. Trimmed before matching against multiple identifier fields with an OR clause.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Lightweight matching list with `uniqueId`, `single` and `full` drayage counts.", "type": "Array<{ uniqueId: string, single: number, full: number }>" }, "errors": [], "references": { "models": [ "DrayageGroupModel" ] } }, { "name": "uploadDocument", "module": "drayage-group", "path": "/drayage-group/uploadDocument", "method": "POST", "summary": "Uploads a document to a drayage group. Decodes the supplied base64 payload into a Buffer before storing. Caller's company must be the shipper or carrier of the group.", "params": [ { "name": "drayageGroupId", "type": "string", "summary": "Public identifier (`uniqueId`) of the drayage group.", "required": true }, { "name": "documentName", "type": "string", "summary": "Name to give the document inside the group.", "required": true }, { "name": "data", "type": "string", "summary": "Base64-encoded contents of the file.", "required": true }, { "name": "extension", "type": "string", "summary": "File extension without the dot (e.g. 'pdf').", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "No return value. The file is stored against the drayage group.", "type": "void" }, "errors": [ { "code": "DRAYAGE_GROUP_UNAUTHORIZED", "when": "Caller's company is neither the shipper nor the carrier of the drayage group." } ], "references": { "models": [ "DrayageGroupModel" ] } }, { "name": "acceptCarrierBidAsBroker", "module": "drayage", "path": "/drayage/acceptCarrierBidAsBroker", "method": "POST", "summary": "Accepts an automatic carrier bid on behalf of the broker/shipper. The caller must be a carrier whose own automatic bid is being booked against the shipper.", "params": [ { "name": "uniqueId", "type": "string", "summary": "Drayage uniqueId.", "required": true }, { "name": "bidId", "type": "string", "summary": "Identifier of the carrier negotiation entry stored on the drayage.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The acceptance response produced by the broker/shipper accept-rate flow." }, "errors": [ { "code": "USER NOT FOUND", "when": "The token does not resolve to a user." }, { "code": "UNAUTHORIZED ROLE", "when": "The caller is not a carrier." }, { "code": "DrayageNotFound", "when": "No drayage exists with the supplied uniqueId." }, { "code": "UNAUTHORIZED DRAYAGE STATUS", "when": "The drayage is not in 'open' or 'new' state." }, { "code": "BidNotFound", "when": "No negotiation entry with the supplied bidId exists on the drayage." }, { "code": "UNAUTHORIZED", "when": "The looked-up bid does not belong to the caller's company or it is not an automatic bid." } ], "references": { "models": [ "Drayage" ] } }, { "name": "acceptedService", "module": "drayage", "path": "/drayage/acceptedService", "method": "POST", "summary": "Accepts the queued newServices already on the drayage's payment.close.newServices, merging them into temporal/chargeable services, recomputing payment.rate and notifying both parties.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "No explicit return value." }, "errors": [ { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage exists with the supplied drayageId." }, { "code": "Unauthorized", "when": "The caller's company is neither the broker nor the carrier company on the drayage." }, { "code": "NotYourTurn", "when": "The caller's role does not match the drayage's current turn." } ], "references": { "models": [ "Drayage", "DocumentSetup", "Company" ] } }, { "name": "acceptRate", "module": "drayage", "path": "/drayage/acceptRate", "method": "POST", "summary": "Awards a drayage by accepting a negotiation bid by id. Behaviour differs by role: a carrier confirms the load (using their own bid or the open payment when bidId is null); a broker/shipper assigns the carrier looked up via the bidId, signs the agreement template and emails the carrier user.", "params": [ { "name": "uniqueId", "type": "string", "summary": "Drayage uniqueId or _id.", "required": true }, { "name": "bidId", "type": "string", "summary": "Identifier of the negotiation entry to accept; null for carrier auto-accept of the open payment terms.", "required": false }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true }, { "name": "rateProntoPago", "type": "number", "summary": "Optional prompt-payment rate; only stored when payment method is HutchisonPorts.", "required": false }, { "name": "sendToCdys", "type": "boolean", "summary": "Whether to forward the awarded drayage to CDYS (default true).", "required": false }, { "name": "overrides", "type": "object", "summary": "Optional services/otherServices/temporalServices arrays that override the looked-up bid's services on accept. Each entry is allowlisted to servicesInfo fields (units, type, rate, qty, accepted, declined, negotiation, service_type, active).", "required": false } ], "response": { "summary": "The acceptance response from the underlying carrier or broker/shipper script." }, "errors": [ { "code": "UserNotFound", "when": "The token does not resolve to a user." }, { "code": "DrayageNotFound", "when": "uniqueId resolves no drayage." }, { "code": "BidNotFound", "when": "No negotiation entry with the supplied bidId exists on the drayage." }, { "code": "BidIdRequired", "when": "Broker/shipper called acceptRate without a bidId." }, { "code": "BidCompanyMismatch", "when": "Carrier supplied a bidId whose companyId does not match their own companyId." } ], "references": { "models": [ "Drayage", "Company", "User" ], "enums": [ "DrayagePaymentMethod", "UserRole" ] } }, { "name": "addChargeablesServices", "module": "drayage", "path": "/drayage/addChargeablesServices", "method": "POST", "summary": "Promotes a temporal service to a chargeable one, moving it from payment.*.temporalServices to payment.*.services. Targets payment.open or payment.close depending on the drayage state.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "service", "type": "object", "summary": "Service definition (type, rate, qty, units, ...).", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Returns true on success.", "type": "boolean" }, "errors": [ { "code": "UserNotFound", "when": "The token does not resolve to a user." }, { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage exists with the supplied drayageId." }, { "code": "Unauthorized", "when": "The caller's company is neither the broker nor the carrier company on the drayage." } ], "references": { "models": [ "Drayage" ] } }, { "name": "addTemporalServices", "module": "drayage", "path": "/drayage/addTemporalServices", "method": "POST", "summary": "Adds an accessorial (temporal service) to either payment.open.temporalServices (when the drayage is new) or payment.close.temporalServices (otherwise).", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "service", "type": "object", "summary": "Service definition (type, rate, qty, units, ...).", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Returns true on success.", "type": "boolean" }, "errors": [ { "code": "UserNotFound", "when": "The token does not resolve to a user." }, { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage exists with the supplied drayageId." }, { "code": "Unauthorized", "when": "The caller's company is neither the broker nor the carrier company on the drayage." } ], "references": { "models": [ "Drayage" ] } }, { "name": "addTemporalServicesNegotiation", "module": "drayage", "path": "/drayage/addTemporalServicesNegotiation", "method": "POST", "summary": "Adds an accessorial to a specific carrier's negotiation entry on an open drayage.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "carrierCompanyId", "type": "string", "summary": "ObjectId of the carrier company whose bid receives the service.", "required": true }, { "name": "service", "type": "object", "summary": "Service definition (type, rate, qty, units, ...).", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Returns true on success.", "type": "boolean" }, "errors": [ { "code": "UserNotFound", "when": "The token does not resolve to a user." }, { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage exists with the supplied drayageId." }, { "code": "Unauthorized", "when": "The caller's company is not the broker company on the drayage." }, { "code": "BidNotFound", "when": "No negotiation entry exists for the supplied carrierCompanyId." } ], "references": { "models": [ "Drayage" ] } }, { "name": "assignCarrier", "module": "drayage", "path": "/drayage/assignCarrier", "method": "POST", "summary": "Shipper-only assignment of a carrier user to a drayage. Optionally references a previously agreed rate sheet.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "carrierId", "type": "string", "summary": "User ObjectId of the carrier to assign.", "required": true }, { "name": "rateId", "type": "string", "summary": "Optional rate id to record on the drayage. Pass null when not using an agreed rate.", "required": false }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "An httpOk message acknowledging the assignment." }, "errors": [ { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage matches drayageId." }, { "code": "USER_UNAUTHORIZED_OVER_DRAYAGE", "when": "The caller is not the shipper of the drayage." } ], "references": { "models": [ "Drayage", "User", "Company" ] } }, { "name": "boardingDetails", "module": "drayage", "path": "/drayage/boardingDetails", "method": "POST", "summary": "Carrier-only update of the Mexican boarding details of a drayage (insurer, permits, distance, dates) and propagates the carrier company defaults when blank.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "payload", "type": "DrayageBoardingDetails", "summary": "Boarding details payload (cargoInsurer, cargoInsurancePolicy, permitNumber, etc.).", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The updated drayage document." }, "errors": [], "references": { "models": [ "Drayage", "Company" ], "interfaces": [ "DrayageBoardingDetails" ] } }, { "name": "booking", "module": "drayage", "path": "/drayage/booking", "method": "POST", "summary": "Assigns a driver to a drayage. Updates booking status, evaluates booking completion and notifies the driver, optionally starting the chatbot if pickup is today.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "driverId", "type": "string", "summary": "ObjectId of the driver to assign.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Returns true when the driver was attached, false otherwise.", "type": "boolean" }, "errors": [], "references": { "models": [ "Drayage", "User", "Container" ], "enums": [ "DrayageState" ] } }, { "name": "calculateMilesInDrayage", "module": "drayage", "path": "/drayage/calculateMilesInDrayage", "method": "POST", "summary": "Estimates the total drayage distance in miles by summing Haversine distances along pickup, delivery, intermediate stops and return points. Cached for 2 hours.", "params": [ { "name": "_id", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Total estimated miles, rounded to the nearest integer.", "type": "number" }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "Shipment not found: Drayage.calculateMilesInDrayage", "when": "The drayage has no pickup location (likely missing or inactive)." } ], "references": { "models": [ "Drayage" ] } }, { "name": "cancelDrayage", "module": "drayage", "path": "/drayage/cancelDrayage", "method": "POST", "summary": "Cancels a drayage owned by the caller shipper, provided it has not been delivered or already cancelled.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "An httpOk message acknowledging the cancellation." }, "errors": [ { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage matches drayageId." }, { "code": "USER_UNAUTHORIZED_OVER_DRAYAGE", "when": "The caller is not the shipper of the drayage, or the drayage is delivered/cancelled." } ], "references": { "models": [ "Drayage" ], "enums": [ "DrayageState" ] } }, { "name": "changeStatusTrackingFromWebApp", "module": "drayage", "path": "/drayage/changeStatusTrackingFromWebApp", "method": "POST", "summary": "Web-app helper that advances the drayage's first container by one stage and ensures the drayage state is at least readyForPickup.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Returns true on success.", "type": "boolean" }, "errors": [ { "code": "UserNotFound", "when": "The token does not resolve to a user." }, { "code": "Unauthorized", "when": "The caller's role is not shipper, broker or carrier." }, { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage matches drayageId." }, { "code": "NotPermitted", "when": "The caller's company is neither the shipper nor the carrier company on the drayage." }, { "code": "ContainerMissing", "when": "The drayage has no container to advance." } ], "references": { "models": [ "Drayage", "Container" ] } }, { "name": "checkContainerNumber", "module": "drayage", "path": "/drayage/checkContainerNumber", "method": "POST", "summary": "Validates one or more container numbers using the configured container-check digit algorithm. Numbers must be exactly 11 characters long.", "params": [ { "name": "containerNum", "type": "string | string[]", "summary": "Container number or list of container numbers.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Array of booleans with the per-container validation result. Returns [false] when any input has the wrong length.", "type": "boolean[]" }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "User can not access to request.", "when": "The caller's role is not shipper, broker or driver." } ], "references": {} }, { "name": "confirmFinalCharges", "module": "drayage", "path": "/drayage/confirmFinalCharges", "method": "POST", "summary": "Marks the drayage's final charges as confirmed by the caller's company, notifying the counterparty.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Returns true on success.", "type": "boolean" }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "Shipment not found: Drayage.confirmFinalCharges", "when": "No drayage matches drayageId." }, { "code": "UNAUTHORIZED", "when": "The caller does not own the drayage." } ], "references": { "models": [ "Drayage", "Company" ] } }, { "name": "create", "module": "drayage", "path": "/drayage/create", "method": "POST", "summary": "Creates a new drayage shipment from a DrayageCreate payload, validating containers and pickup address before publishing.", "params": [ { "name": "payload", "type": "DrayageCreate", "summary": "Shipment creation payload including locations, containers, payment, etc.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true }, { "name": "duplicate", "type": "string", "summary": "Optional source drayage id when duplicating an existing shipment.", "required": false }, { "name": "commentText", "type": "string", "summary": "Optional comment text recorded with the creation.", "required": false } ], "response": { "summary": "The persisted Drayage document.", "type": "Drayage" }, "errors": [ { "code": "Container details is required.", "when": "payload.containerDetails is empty." }, { "code": "You are not authorized to create drayages.", "when": "The caller's role is neither shipper nor broker." }, { "code": "LOAD_LOCATION_ADDRESS_MAX_LENGTH", "when": "payload.location.pickup.address fails the street length validation." } ], "references": { "models": [ "Drayage", "Container" ], "interfaces": [ "DrayageCreate" ] } }, { "name": "createCostPresets", "module": "drayage", "path": "/drayage/createCostPresets", "method": "POST", "summary": "Creates a carrier cost preset (saved quote template) under the caller's company.", "params": [ { "name": "payload", "type": "CostPresetsCreate", "summary": "Preset payload (origin, destination, services, ...).", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The created CostPresets document.", "type": "CostPresets" }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "User not authorized", "when": "The caller is not a carrier." } ], "references": { "models": [ "CostPresets" ], "interfaces": [ "CostPresetsCreate" ] } }, { "name": "createDrayageRate", "module": "drayage", "path": "/drayage/createDrayageRate", "method": "POST", "summary": "Creates or appends a drayage rate sheet between the caller broker company and a carrier company, optionally uploading agreement documents.", "params": [ { "name": "payload", "type": "DrayageRateCreate", "summary": "Rate sheet payload including brokerCompanyId, carrierCompanyId, brokerId and the rates array.", "required": true }, { "name": "docs", "type": "DocumentsUpload[]", "summary": "Optional agreement documents to attach to the rate sheet.", "required": false }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Returns the created rates array (with assigned ObjectIds and isActive=true)." }, "errors": [ { "code": "UNAUTHORIZED", "when": "The caller's company does not match payload.brokerCompanyId." }, { "code": "DRAYAGE_RATE_SHOULD_HAVE_AT_LEAST_ONE_SERVICE", "when": "payload.rates is empty." } ], "references": { "models": [ "DrayageRate" ], "interfaces": [ "DrayageRateCreate", "DocumentsUpload" ] } }, { "name": "declineBid", "module": "drayage", "path": "/drayage/declineBid", "method": "POST", "summary": "Marks a negotiation bid as declined with a reason and the declining company's name. Reverts the drayage to 'new' when no active bids remain. Emails and notifies the bidder.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "bidId", "type": "string", "summary": "Negotiation entry id.", "required": true }, { "name": "reason", "type": "string", "summary": "Free-text reason for declining the bid.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "No explicit return value." }, "errors": [ { "code": "User is not authorized.", "when": "The caller's role is not shipper, broker or carrier." }, { "code": "Drayage not found.", "when": "No drayage matches drayageId / bidId." }, { "code": "Bid has not been declined.", "when": "The negotiation entry was not modified by the update." } ], "references": { "models": [ "Drayage", "Company", "User" ] } }, { "name": "declinedService", "module": "drayage", "path": "/drayage/declinedService", "method": "POST", "summary": "Removes a negotiated service from payment.close.services, payment.close.temporalServices or payment.close.newServices depending on the supplied type, and notifies both parties.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "service", "type": "object", "summary": "Service descriptor; only service.type is used to match.", "required": true }, { "name": "type", "type": "'temporal' | 'service' | 'newservice'", "summary": "Bucket to remove the service from.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "No explicit return value." }, "errors": [], "references": { "models": [ "Drayage" ] } }, { "name": "deleteAllDrayageRates", "module": "drayage", "path": "/drayage/deleteAllDrayageRates", "method": "POST", "summary": "Deletes an entire rate sheet and removes every attached document from Google Cloud Storage.", "params": [ { "name": "_id", "type": "string", "summary": "ObjectId of the rate sheet to remove.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Returns true on success." }, "errors": [], "references": { "models": [ "DrayageRate" ] } }, { "name": "deleteCSVRow", "module": "drayage", "path": "/drayage/deleteCSVRow", "method": "POST", "summary": "Removes a Success or Error CSV row from a CSV import owned by the caller's company.", "params": [ { "name": "csvRowId", "type": "string", "summary": "ObjectId of the CSV row.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "An httpOk message acknowledging the deletion." }, "errors": [ { "code": "DRAYAGE_CSV_ROW_NOT_FOUND", "when": "No CSV row matches csvRowId." }, { "code": "DRAYAGE_CSV_NOT_FOUND", "when": "The row's parent CSV does not belong to the caller's company." }, { "code": "DRAYAGE_CSV_ROW_NOT_REMOVABLE", "when": "The row status is not Success or Error." } ], "references": { "models": [ "DrayageCSV", "DrayageCSVRow" ], "enums": [ "DrayageCSVRowStatus" ] } }, { "name": "deleteDocumentDrayageExtra", "module": "drayage", "path": "/drayage/deleteDocumentDrayageExtra", "method": "POST", "summary": "Removes an extra document from the drayage's DocumentSetup, deleting the file from Google Cloud Storage and notifying both parties.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "documentId", "type": "string", "summary": "ObjectId of the document to remove.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Returns true on success.", "type": "boolean" }, "errors": [], "references": { "models": [ "Drayage", "DocumentSetup" ] } }, { "name": "deleteDrayageRate", "module": "drayage", "path": "/drayage/deleteDrayageRate", "method": "POST", "summary": "Removes a single rate entry from a rate sheet. If no rates remain, the whole sheet (and every attached document) is deleted.", "params": [ { "name": "_id", "type": "string", "summary": "ObjectId of the rate sheet.", "required": true }, { "name": "rateId", "type": "string", "summary": "ObjectId of the specific rate entry inside the sheet's rates array.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Returns true on success." }, "errors": [], "references": { "models": [ "DrayageRate" ] } }, { "name": "deleteUploadedDocumentFromDrayage", "module": "drayage", "path": "/drayage/deleteUploadedDocumentFromDrayage", "method": "POST", "summary": "Clears one of the four file-sharing slots on a drayage (urlpod, urladditional, urladditional_two, urlpod_delivery).", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "imgKey", "type": "string", "summary": "Slot to clear: urlpod, urladditional, urladditional_two or urlpod_delivery.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "No explicit return value." }, "errors": [ { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage matches drayageId." }, { "code": "UNAUTHORIZED", "when": "The caller is not the drayage owner." }, { "code": "DRAYAGE_DOCUMENT_KEY_INVALID", "when": "imgKey is not one of the supported slots." } ], "references": { "models": [ "Drayage" ] } }, { "name": "drayageMerge", "module": "drayage", "path": "/drayage/drayageMerge", "method": "POST", "summary": "Creates a new drayage cloned from a primary drayage, switches it to typeofTruck=full and reassigns containers from the primary and from the merged drayages to the new document.", "params": [ { "name": "data", "type": "object", "summary": "Object with drayagePrincipal (source drayage id) and drayageMerge (array of additional drayage ids whose containers are reassigned).", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Object with the newly created drayage document." }, "errors": [], "references": { "models": [ "Drayage", "Container" ] } }, { "name": "duplicate", "module": "drayage", "path": "/drayage/duplicate", "method": "POST", "summary": "Creates a new drayage cloned from an existing one owned by the caller, returning the new document with its containers.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the source drayage to duplicate.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The new drayage document plus its containers array.", "type": "Doc & { containers: Container[] }" }, "errors": [ { "code": "DRAYAGE_NOT_FOUND", "when": "The source drayage does not exist." }, { "code": "USER_UNAUTHORIZED_OVER_DRAYAGE", "when": "The caller did not create the source drayage." } ], "references": { "models": [ "Drayage", "Container" ] } }, { "name": "editContainer", "module": "drayage", "path": "/drayage/editContainer", "method": "POST", "summary": "Bulk-updates an array of containers and notifies the assigned carrier driver of the parent drayage.", "params": [ { "name": "payload", "type": "Container[]", "summary": "Array of container documents to update (each must carry its _id).", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Array with one boolean per input container indicating whether the write modified the document.", "type": "boolean[]" }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." } ], "references": { "models": [ "Drayage", "Container" ] } }, { "name": "editCostPresets", "module": "drayage", "path": "/drayage/editCostPresets", "method": "POST", "summary": "Updates an existing cost preset belonging to the caller carrier.", "params": [ { "name": "payload", "type": "CostPresetsCreate", "summary": "Preset fields to overwrite.", "required": true }, { "name": "_id", "type": "string", "summary": "ObjectId of the preset to update.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The result of the underlying editPresets script." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "User not authorized", "when": "The caller is not a carrier." } ], "references": { "models": [ "CostPresets" ], "interfaces": [ "CostPresetsCreate" ] } }, { "name": "editDetailDrayage", "module": "drayage", "path": "/drayage/editDetailDrayage", "method": "POST", "summary": "Updates a drayage's full detail including locations (pickup, delivery, return), Mexico-specific detail, the containers list and triggers rate confirmation regeneration plus realtime notifications.", "params": [ { "name": "drayageId", "type": "string", "summary": "Drayage uniqueId or _id.", "required": true }, { "name": "payload", "type": "object", "summary": "Object with optional drayage and detailMexico blocks. payload.drayage may include locations, container array, typeofTruck and other drayage fields.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The updated drayage document with containers attached." }, "errors": [ { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage matches drayageId." }, { "code": "USER_UNAUTHORIZED_OVER_DRAYAGE", "when": "The caller is not an owner of the drayage, or is not the shipper while the drayage is still open/new." } ], "references": { "models": [ "Drayage", "Container", "Company", "DocumentSetup" ], "enums": [ "DrayageState" ] } }, { "name": "editDrayagePilot", "module": "drayage", "path": "/drayage/editDrayagePilot", "method": "POST", "summary": "Generic shallow update of a drayage by _id, applying $set on the supplied payload fields. Used for ad-hoc 'pilot' edits.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "payload", "type": "object", "summary": "Object whose top-level keys are $set on the drayage.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The updated drayage document." }, "errors": [ { "code": "User not authorized", "when": "The caller's role is not shipper, broker or carrier." }, { "code": "Shipment not found: Drayage.editDrayagePilot", "when": "No drayage matches drayageId." } ], "references": { "models": [ "Drayage" ] } }, { "name": "editServices", "module": "drayage", "path": "/drayage/editServices", "method": "POST", "summary": "Updates the payment.open or payment.close block of a drayage depending on its state and the current turn (carrier vs broker), recording newServices to negotiate, optionally storing the prompt-payment rate and notifying both parties.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "payment", "type": "object", "summary": "Payment block update with services, otherServices, temporalServices and optional newServices.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true }, { "name": "rateProntoPago", "type": "number", "summary": "Optional prompt-payment rate; only stored when payment method is HutchisonPorts.", "required": false } ], "response": { "summary": "No explicit return value." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "Shipment not found: Drayage.editServices", "when": "No drayage matches drayageId." }, { "code": "UNAUTHORIZED", "when": "The caller does not own the drayage." } ], "references": { "models": [ "Drayage", "DocumentSetup" ] } }, { "name": "editShipmentInformation", "module": "drayage", "path": "/drayage/editShipmentInformation", "method": "POST", "summary": "Updates pickup, delivery and stops information for a drayage. Regenerates the rate confirmation preview when the drayage has progressed beyond open/new and notifies the carrier.", "params": [ { "name": "uniqueId", "type": "string", "summary": "Drayage uniqueId.", "required": true }, { "name": "payload", "type": "ShipmentInformation", "summary": "Updated location block (pickup, delivery, return, stops).", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Returns true when the location update succeeded.", "type": "boolean" }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "User not authorized.", "when": "The caller's role is not shipper/broker/carrier, the drayage is open/new and the caller is a carrier, or the caller's company is neither the shipper company nor the carrier company on the drayage." }, { "code": "Shipment not found: Drayage.editShipmentInformation", "when": "No drayage matches uniqueId." } ], "references": { "models": [ "Drayage" ], "interfaces": [ "ShipmentInformation" ] } }, { "name": "editSteamshipLine", "module": "drayage", "path": "/drayage/editSteamshipLine", "method": "POST", "summary": "Updates the shipping line information of a drayage (steamshipLine, bookingNumber, etc.) and notifies the carrier when the drayage is accepted.", "params": [ { "name": "uniqueId", "type": "string", "summary": "Drayage uniqueId.", "required": true }, { "name": "payload", "type": "ShippinglineInformation", "summary": "Updated shipping line fields.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Returns true on successful update.", "type": "boolean" }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "User not authorized", "when": "The caller is neither shipper nor broker, or the drayage belongs to another company." }, { "code": "Shipment not found: Drayage.editSteamshipLine", "when": "No drayage matches uniqueId." }, { "code": "Is required.", "when": "The drayage is in readyForPickup state and neither steamshipLine nor bookingNumber were provided." } ], "references": { "models": [ "Drayage" ], "interfaces": [ "ShippinglineInformation" ] } }, { "name": "get", "module": "drayage", "path": "/drayage/get", "method": "POST", "summary": "Convenience alias for getByUniqueId. Returns the drayage matching the supplied id, scoped to companies the caller can see.", "params": [ { "name": "shipmentId", "type": "string", "summary": "Drayage uniqueId or _id.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The visible Drayage document for the caller.", "type": "Drayage" }, "errors": [ { "code": "Shipment not found: Drayage.getByUniqueId", "when": "No drayage visible to the caller matches the id." } ], "references": { "models": [ "Drayage" ] } }, { "name": "getById", "module": "drayage", "path": "/drayage/getById", "method": "POST", "summary": "Returns a drayage by uniqueId or _id. Tries the user-token visibility rules first; if the caller is an admin, falls back to an admin lookup that bypasses company scoping.", "params": [ { "name": "shipmentId", "type": "string", "summary": "Drayage uniqueId or _id.", "required": true }, { "name": "token", "type": "string", "summary": "User or admin session token.", "required": true } ], "response": { "summary": "Drayage document with containers attached.", "type": "Drayage" }, "errors": [ { "code": "Shipment not found: Drayage.getById", "when": "Neither the user-scoped lookup nor the admin lookup found the drayage." } ], "references": { "models": [ "Drayage", "Container" ] } }, { "name": "getByIdDrayage", "module": "drayage", "path": "/drayage/getByIdDrayage", "method": "POST", "summary": "Returns a drayage by _id, optionally joined with its containers, the assigned driver and the assigned vehicle.", "params": [ { "name": "shipmentId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true }, { "name": "includeContainers", "type": "boolean", "summary": "Whether to attach the drayage containers (default true).", "required": false }, { "name": "includeDriver", "type": "boolean", "summary": "Whether to join the assigned driver document.", "required": false }, { "name": "includeVehicle", "type": "boolean", "summary": "Whether to join the assigned vehicle document.", "required": false } ], "response": { "summary": "Drayage document with optional containers, driver and vehicle attached." }, "errors": [ { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage matches shipmentId." } ], "references": { "models": [ "Drayage", "Container", "User" ] } }, { "name": "getByUniqueId", "module": "drayage", "path": "/drayage/getByUniqueId", "method": "POST", "summary": "Returns a drayage by uniqueId or _id, joined with its containers. For carriers, only public new/open drayages or those awarded to their company are visible, and negotiation history is filtered to their company.", "params": [ { "name": "uniqueId", "type": "string", "summary": "Drayage uniqueId or _id.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Drayage document with containers attached and invoiceId set to null.", "type": "Drayage" }, "errors": [ { "code": "Shipment not found: Drayage.getByUniqueId", "when": "No drayage visible to the caller matches the id." } ], "references": { "models": [ "Drayage", "Container" ] } }, { "name": "getCostPresets", "module": "drayage", "path": "/drayage/getCostPresets", "method": "POST", "summary": "Lists every cost preset configured by the caller carrier company, with the total rate computed from the preset's services.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Array of preset summaries with totalRate added." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "User not authorized", "when": "The caller is not a carrier." } ], "references": { "models": [ "CostPresets" ] } }, { "name": "getCSVHistory", "module": "drayage", "path": "/drayage/getCSVHistory", "method": "POST", "summary": "Returns the paginated CSV import history of the caller's company, joined with each CSV's parsed rows.", "params": [ { "name": "skip", "type": "number", "summary": "Pagination offset (default 0).", "required": true }, { "name": "limit", "type": "number", "summary": "Page size (default 25).", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Array of DrayageCSV documents with rows attached." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." } ], "references": { "models": [ "DrayageCSV", "DrayageCSVRow" ] } }, { "name": "getCustomerInfo", "module": "drayage", "path": "/drayage/getCustomerInfo", "method": "POST", "summary": "Returns the master-DB company info for the customer (consignee) of a drayage, looked up by the delivery's RFC. Returns null when no RFC is set.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Company info from the master DB, or null when no RFC is on the delivery location." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage matches drayageId." }, { "code": "User is not authorized.", "when": "The caller is neither shipper nor carrier on the drayage." } ], "references": { "models": [ "Drayage" ] } }, { "name": "getDocumentDrayageExtra", "module": "drayage", "path": "/drayage/getDocumentDrayageExtra", "method": "POST", "summary": "Returns the documentExtra array stored on the drayage's DocumentSetup.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Array of extra document descriptors." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage matches drayageId." }, { "code": "User is not authorized over this drayage. Operation: Obtener documentos.", "when": "The caller is not an owner of the drayage." } ], "references": { "models": [ "Drayage", "DocumentSetup" ] } }, { "name": "getDrayageRateByBrokerAndCarrierId", "module": "drayage", "path": "/drayage/getDrayageRateByBrokerAndCarrierId", "method": "GET", "summary": "Fetches the drayage rate sheet between a specific broker company and carrier company. The caller must belong to one of the two companies.", "params": [ { "name": "brokerCompanyId", "type": "string", "summary": "ObjectId of the broker company.", "required": true }, { "name": "carrierCompanyId", "type": "string", "summary": "ObjectId of the carrier company.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Aggregation containing the rate sheet, its documents, the carrier company identity and the admin user email." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "Unauthorized", "when": "The caller's company is neither the broker company nor the carrier company referenced in the rate." } ], "references": { "models": [ "DrayageRate", "Company", "User" ] } }, { "name": "getDrayageRates", "module": "drayage", "path": "/drayage/getDrayageRates", "method": "GET", "summary": "Returns every drayage rate sheet that the caller broker company has configured against carrier companies, joined with carrier company name and admin email.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Array of rate sheet aggregations containing drayage-rates info, the carrier company identity and the admin user email." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." } ], "references": { "models": [ "DrayageRate", "Company", "User" ] } }, { "name": "getDrayagesAvailableForChatbotBooking", "module": "drayage", "path": "/drayage/getDrayagesAvailableForChatbotBooking", "method": "POST", "summary": "Lists the awarded drayages of the caller carrier user that are available to be booked through the chatbot.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true }, { "name": "skip", "type": "number", "summary": "Pagination offset (default 0).", "required": false }, { "name": "limit", "type": "number", "summary": "Page size (default 10).", "required": false } ], "response": { "summary": "Array of drayage documents." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." } ], "references": { "models": [ "Drayage" ] } }, { "name": "getDrayagesAvailableForChatbotTracking", "module": "drayage", "path": "/drayage/getDrayagesAvailableForChatbotTracking", "method": "POST", "summary": "Lists the drayages assigned to the caller driver whose pickup is today and which are eligible for chatbot tracking.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true }, { "name": "skip", "type": "number", "summary": "Pagination offset (default 0).", "required": false }, { "name": "limit", "type": "number", "summary": "Page size (default 10).", "required": false } ], "response": { "summary": "Array of drayage documents." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." } ], "references": { "models": [ "Drayage" ] } }, { "name": "getDrayagesAvailableForTodayPickup", "module": "drayage", "path": "/drayage/getDrayagesAvailableForTodayPickup", "method": "POST", "summary": "Admin lookup that returns every drayage with an attached driver whose pickup falls in any common today-encoded representation.", "params": [ { "name": "token", "type": "string", "summary": "Admin session token", "required": true } ], "response": { "summary": "Array of drayage documents." }, "errors": [], "references": { "models": [ "Drayage" ] } }, { "name": "getOtherServicesByUser", "module": "drayage", "path": "/drayage/getOtherServicesByUser", "method": "POST", "summary": "Returns the list of custom 'other services' (accessorials) saved by the caller user.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The Services document associated with the caller.", "type": "Services" }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." } ], "references": { "models": [ "Services" ] } }, { "name": "getRegimenAduanero", "module": "drayage", "path": "/drayage/getRegimenAduanero", "method": "POST", "summary": "Returns the full Mexican Régimen Aduanero catalogue used in Carta Porte forms.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Array of RegimenAduanero documents." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." } ], "references": { "models": [ "RegimenAduanero" ] } }, { "name": "getServicesBidding", "module": "drayage", "path": "/drayage/getServicesBidding", "method": "POST", "summary": "Returns the chargeable and temporal services of a drayage for the bidding view, picking payment.close when present and falling back to payment.open.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Object with services and temporalServices arrays." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage matches drayageId." }, { "code": "User unauthorized over drayage.", "when": "The caller does not own the drayage." } ], "references": { "models": [ "Drayage" ] } }, { "name": "getServicesDrayageActive", "module": "drayage", "path": "/drayage/getServicesDrayageActive", "method": "POST", "summary": "Returns the configured services list (optionally filtered by US vs MX working rules) merged with company accessorials. When a drayageId is given, marks each entry as active if it already exists in payment.open or payment.close.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true }, { "name": "drayageId", "type": "string", "summary": "Optional drayage id to mark services as active when present.", "required": false } ], "response": { "summary": "Array of service descriptors with an extra 'active' boolean.", "type": "any[]" }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "DRAYAGE_NOT_FOUND", "when": "drayageId was provided but no drayage matches it." } ], "references": { "models": [ "Drayage", "Settings", "DataLookUp" ], "enums": [ "WorkingRules" ] } }, { "name": "getStatusTracking", "module": "drayage", "path": "/drayage/getStatusTracking", "method": "POST", "summary": "Returns the stages list, currentStage and delivered flag of a drayage's first container.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Container projection with stages, currentStage and delivered fields." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "User is not authorized.", "when": "The caller's role is not shipper, broker or carrier." }, { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage matches drayageId." }, { "code": "Your are not permissions in this load.", "when": "The caller's company is neither the shipper nor the carrier company on the drayage." } ], "references": { "models": [ "Drayage", "Container" ] } }, { "name": "getTodayDuplicateContainersFromCSV", "module": "drayage", "path": "/drayage/getTodayDuplicateContainersFromCSV", "method": "POST", "summary": "Inspects a CSV file and returns the list of container numbers already imported in the last day for the caller's company, helping the UI flag duplicates before re-import.", "params": [ { "name": "file", "type": "string", "summary": "Raw CSV content.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Array of duplicate container descriptors." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." } ], "references": { "models": [ "Drayage", "DrayageCSV", "DrayageCSVRow" ] } }, { "name": "importFileDrayage", "module": "drayage", "path": "/drayage/importFileDrayage", "method": "POST", "summary": "Parses a drayage CSV file (filtering out ignored container rows) and dispatches background import processing. Returns the created CSV record and rows.", "params": [ { "name": "file", "type": "string", "summary": "Raw CSV content, sanitised of unsupported characters.", "required": true }, { "name": "ignoredContainers", "type": "string[]", "summary": "Container numbers to drop from the CSV (column 4 of each row).", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Object with the created csv record and the parsed rows." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." } ], "references": { "models": [ "DrayageCSV", "DrayageCSVRow", "User" ] } }, { "name": "importMerchandiseFile", "module": "drayage", "path": "/drayage/importMerchandiseFile", "method": "POST", "summary": "Parses a comma-separated merchandise CSV (Mexican Carta Porte format) into an array of merchandise descriptors, marking rows with hazardous-material data when present.", "params": [ { "name": "file", "type": "Buffer", "summary": "Binary CSV content (sanitised of unsupported characters).", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Array of merchandise rows ready to attach to a container's informationMexico array." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." } ], "references": {} }, { "name": "invite", "module": "drayage", "path": "/drayage/invite", "method": "POST", "summary": "Sends an invitation email to a carrier address to cover an open drayage. Generates registry/login deep-links and routes through Mailgun in EN or ES.", "params": [ { "name": "invite", "type": "Invite", "summary": "Invitation payload with shipmentId, email, optional rate.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "No return value when all invitations were dispatched." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "User can not this action.", "when": "The caller is neither shipper nor broker." }, { "code": "Shipment not found: Drayage.invite", "when": "No new/open drayage matches the shipmentId for the caller's company." }, { "code": "User not authorized.", "when": "The drayage's company is not the caller's company." }, { "code": "Company not found.", "when": "The caller's company document does not exist." } ], "references": { "models": [ "Drayage", "Company", "User" ], "interfaces": [ "Invite" ] } }, { "name": "invoiceConfiguration", "module": "drayage", "path": "/drayage/invoiceConfiguration", "method": "POST", "summary": "Updates the invoice configuration of a drayage (forma de pago, método de pago, tipo de comprobante) and notifies both parties.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "payload", "type": "object", "summary": "Object with formaPago, metodoPago and comprobantePago fields.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The updated drayage document." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage matches drayageId." }, { "code": "User is not authorized.", "when": "The caller's company is neither the drayage owner nor the awarded carrier." } ], "references": { "models": [ "Drayage" ] } }, { "name": "negotiation", "module": "drayage", "path": "/drayage/negotiation", "method": "POST", "summary": "Adds a negotiation entry (counter-bid) to a drayage. Auto-registers any 'isOtherService' service as a company accessorial. For carriers, also mirrors the negotiation to OLPEP.", "params": [ { "name": "uniqueId", "type": "string", "summary": "Drayage uniqueId or _id.", "required": true }, { "name": "bid", "type": "BidInfo", "summary": "Negotiation payload including services and otherServices.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The negotiation entry produced by the underlying script." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "You can't trade without services", "when": "bid.services is empty or any service.rate is 0." } ], "references": { "models": [ "Drayage" ], "interfaces": [ "BidInfo" ] } }, { "name": "remove", "module": "drayage", "path": "/drayage/remove", "method": "POST", "summary": "Soft-deletes a drayage owned by the caller's company while in new/open/awarded state and removes its CSV row references.", "params": [ { "name": "uniqueId", "type": "string", "summary": "Drayage uniqueId or _id.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "No return value." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "User can not this action.", "when": "The caller is neither shipper nor broker." }, { "code": "Drayage not found.", "when": "No drayage matches uniqueId within the caller's company." } ], "references": { "models": [ "Drayage" ] } }, { "name": "removeServiceChargeable", "module": "drayage", "path": "/drayage/removeServiceChargeable", "method": "POST", "summary": "Removes a chargeable service from payment.open or payment.close (depending on the drayage state) by service.type.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "service", "type": "object", "summary": "Service descriptor; only service.type is used to match.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "No explicit return value." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage matches drayageId." }, { "code": "User is not authorized.", "when": "The caller's company is neither the drayage owner nor the awarded carrier." } ], "references": { "models": [ "Drayage" ] } }, { "name": "removeServiceTemporal", "module": "drayage", "path": "/drayage/removeServiceTemporal", "method": "POST", "summary": "Removes a temporal service from payment.open or payment.close (depending on the drayage state) by service.type.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "service", "type": "object", "summary": "Service descriptor; only service.type is used to match.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "No explicit return value." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage matches drayageId." }, { "code": "User is not authorized.", "when": "The caller's company is neither the drayage owner nor the awarded carrier." } ], "references": { "models": [ "Drayage" ] } }, { "name": "removeServiceTemporalNegotiation", "module": "drayage", "path": "/drayage/removeServiceTemporalNegotiation", "method": "POST", "summary": "Removes a temporal service from a specific carrier's negotiation entry on an open drayage by service.type.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "carrierCompanyId", "type": "string", "summary": "ObjectId of the carrier company whose bid is updated.", "required": true }, { "name": "service", "type": "object", "summary": "Service descriptor; only service.type is used to match.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Returns true on success.", "type": "boolean" }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage matches drayageId." }, { "code": "User is not authorized.", "when": "The caller's company is not the drayage owner." }, { "code": "Bid not found in drayage negotiation.", "when": "No carrier bid in drayage.negotiation matches carrierCompanyId." } ], "references": { "models": [ "Drayage" ] } }, { "name": "requestDestinationInfo", "module": "drayage", "path": "/drayage/requestDestinationInfo", "method": "POST", "summary": "Mexico-only helper that emails the shipment broker requesting more destination details so the carrier can quote (deep link includes broker login token).", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "A localized confirmation message." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user, or shipment.userId does not resolve to a broker." }, { "code": "Company not found.", "when": "The caller's company is missing." }, { "code": "Shipment not found: Drayage.requestDestinationInfo", "when": "No drayage matches drayageId." } ], "references": { "models": [ "Drayage", "Company", "User" ] } }, { "name": "retryCSVRow", "module": "drayage", "path": "/drayage/retryCSVRow", "method": "POST", "summary": "Re-queues a CSV row that previously failed import, marking it Pending and dispatching the import worker again.", "params": [ { "name": "rowId", "type": "string", "summary": "ObjectId of the CSV row.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "An httpOk message acknowledging the retry." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "CSV row not found", "when": "No CSV row matches rowId." }, { "code": "DRAYAGE_CSV_NOT_FOUND", "when": "The row's parent CSV does not exist or is not owned by the caller's company." }, { "code": "DRAYAGE_CSV_ROW_NOT_RETRYABLE", "when": "The row status is not Error." } ], "references": { "models": [ "DrayageCSV", "DrayageCSVRow" ], "enums": [ "DrayageCSVRowStatus" ] } }, { "name": "retrySendCdys", "module": "drayage", "path": "/drayage/retrySendCdys", "method": "POST", "summary": "Re-queues a delivery to the CDYS logistics integration: marks the drayage's CDYS status as Pending, notifies the company on each affected CSV row and enqueues the process_cdys job.", "params": [ { "name": "drayageId", "type": "string", "summary": "Drayage uniqueId or _id.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "No explicit return value." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "Drayage not found.", "when": "No drayage matches drayageId." }, { "code": "User is not authorized over this drayage.", "when": "The caller is not the shipper of the drayage." } ], "references": { "models": [ "Drayage", "DrayageCSVRow", "Settings" ], "enums": [ "DrayageCSVRowCdysStatus" ] } }, { "name": "reverseStageFromWebapp", "module": "drayage", "path": "/drayage/reverseStageFromWebapp", "method": "POST", "summary": "Web-app helper that rolls back a drayage's tracking stage to a specified previous stageId, recording the position and source.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true }, { "name": "load", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "locationStage", "type": "LocationInStage", "summary": "Optional { lat, lng } recorded with the rollback.", "required": false }, { "name": "targetStageId", "type": "string", "summary": "Stage id to roll back to.", "required": true } ], "response": { "summary": "No explicit return value." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage matches the provided id." }, { "code": "Unauthorized", "when": "The caller is not the drayage owner." } ], "references": { "models": [ "Drayage" ], "enums": [ "TrackingStage", "TrackingStageUpdateSource" ], "interfaces": [ "LocationInStage" ] } }, { "name": "searchCompanyToCreateDrayageRate", "module": "drayage", "path": "/drayage/searchCompanyToCreateDrayageRate", "method": "POST", "summary": "Searches carrier companies whose name or admin email matches the given fragment so a broker can create a drayage rate sheet against them.", "params": [ { "name": "data", "type": "string", "summary": "Search fragment matched case-insensitively against company name or admin email.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Array of matching carrier companies with admin user email, name and id." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." } ], "references": { "models": [ "Company", "User" ] } }, { "name": "searchCSVs", "module": "drayage", "path": "/drayage/searchCSVs", "method": "POST", "summary": "Searches CSV imports of the caller's company by container/drayage uniqueId fragment, with optional date range, returning paginated results joined with their rows.", "params": [ { "name": "search", "type": "string", "summary": "Free-text fragment matched against container or drayageUniqueId on the rows.", "required": true }, { "name": "startDate", "type": "string", "summary": "Optional range start date (parseable by Date).", "required": false }, { "name": "endDate", "type": "string", "summary": "Optional range end date (parseable by Date); upper bound is shifted by 1 day to be inclusive.", "required": false }, { "name": "skip", "type": "number", "summary": "Pagination offset (default 0).", "required": true }, { "name": "limit", "type": "number", "summary": "Page size (default 25).", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Array of DrayageCSV documents with rows attached." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." } ], "references": { "models": [ "DrayageCSV", "DrayageCSVRow" ] } }, { "name": "shareTrackingByEmail", "module": "drayage", "path": "/drayage/shareTrackingByEmail", "method": "POST", "summary": "Shares the customer-portal tracking link of a drayage with an external contact via email when no existing customer company is already linked to the drayage.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "contactName", "type": "string", "summary": "Recipient contact name.", "required": true }, { "name": "email", "type": "string", "summary": "Recipient email.", "required": true }, { "name": "razonSocial", "type": "string", "summary": "Recipient company legal name.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "An httpOk message acknowledging the invitation." }, "errors": [ { "code": "SCHEMA_VALIDATION_ERROR", "when": "drayageId, contactName, email, razonSocial or token failed StringSchema validation." }, { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage matches drayageId." }, { "code": "User is not authorized.", "when": "The caller is not an owner of the drayage." } ], "references": { "models": [ "Drayage" ] } }, { "name": "toBookBid", "module": "drayage", "path": "/drayage/toBookBid", "method": "POST", "summary": "Marks a carrier negotiation as accepted by the broker/shipper and emails the carrier user a capacity-confirmation invitation with a deep link to the drayage.", "params": [ { "name": "uniqueId", "type": "string", "summary": "Drayage uniqueId.", "required": true }, { "name": "bid", "type": "object", "summary": "Negotiation entry being accepted ({ id, userId, services, otherServices, ... }).", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Returns the accepted bid, with bid.accepted set to true." }, "errors": [ { "code": "USER NOT FOUND", "when": "The token does not resolve to a user." }, { "code": "UNAUTHORIZED", "when": "The caller's role is neither shipper nor broker, or the caller's company is not the drayage owner." }, { "code": "Drayage not found.", "when": "No drayage matches uniqueId." }, { "code": "UNAUTHORIZED DRAYAGE STATUS", "when": "The drayage is not in 'open' or 'new' state." }, { "code": "Company not found.", "when": "The caller's broker company is missing." } ], "references": { "models": [ "Drayage", "Company" ] } }, { "name": "universalSearch", "module": "drayage", "path": "/drayage/universalSearch", "method": "GET", "summary": "Universal search by uniqueId, container number, brokerReferenceID or carrierReferenceID, scoped to drayages the caller can see (carrier, shipper, broker, or public). Cached for 30 seconds.", "params": [ { "name": "search", "type": "string", "summary": "Free-text search term.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Array of search hits ({ type, _id, uniqueId, brokerReferenceID, carrierReferenceID, containerNumber })." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." } ], "references": { "models": [ "Drayage", "Container", "Settings" ] } }, { "name": "updateDrayageRate", "module": "drayage", "path": "/drayage/updateDrayageRate", "method": "POST", "summary": "Updates the rate entries of an existing drayage rate sheet by matching each entry's _id.", "params": [ { "name": "payload", "type": "DrayageRateUpdate", "summary": "Rate sheet payload with _id and the updated rates array.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Returns true on success." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "Rate not found.", "when": "No drayage rate sheet matches payload._id." }, { "code": "User is not authorized.", "when": "The caller's company is neither the broker nor the carrier on the rate sheet." } ], "references": { "models": [ "DrayageRate" ], "interfaces": [ "DrayageRateUpdate" ] } }, { "name": "updateDrayageVehicule", "module": "drayage", "path": "/drayage/updateDrayageVehicule", "method": "POST", "summary": "Updates the vehicle assigned to a drayage by the carrier and synchronises the tracking subsystem when the vehicle changes.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "vehiculeId", "type": "string", "summary": "ObjectId of the vehicle to assign.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The updated drayage document." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "User unauthorized over drayage.", "when": "The caller is not the assigned carrier of the drayage." } ], "references": { "models": [ "Drayage" ] } }, { "name": "updateServices", "module": "drayage", "path": "/drayage/updateServices", "method": "POST", "summary": "Broker-only update of the closed payment block on a drayage. Recomputes payment.rate when the drayage is delivered and regenerates the rate confirmation when it is no longer new/open.", "params": [ { "name": "shimentId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "payload", "type": "object", "summary": "Update payload that may include payment.close.services, otherServices, extraCharges and other drayage fields.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The Mongoose updateOne result." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "UNAUTHORIZED ROLE", "when": "The caller is not a broker." }, { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage matches shimentId." }, { "code": "UNAUTHORIZED", "when": "The caller's company is not the shipper company on the drayage." } ], "references": { "models": [ "Drayage", "DocumentSetup" ] } }, { "name": "updateStagewebApp", "module": "drayage", "path": "/drayage/updateStagewebApp", "method": "POST", "summary": "Web-app variant of stage advancement: moves the drayage tracking stage to the one immediately following the container's currentStage.", "params": [ { "name": "containerId", "type": "string", "summary": "ObjectId of the container.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true }, { "name": "locationStage", "type": "LocationInStage", "summary": "Optional { lat, lng } captured at the stage transition.", "required": false }, { "name": "source", "type": "TrackingStageUpdateSource", "summary": "Origin of the update used for audit (e.g. WebApp, Mobile).", "required": false } ], "response": { "summary": "No explicit return value." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "Container not found", "when": "No container matches containerId." }, { "code": "DRAYAGE_NOT_FOUND", "when": "The container's drayage does not exist." }, { "code": "Unauthorized", "when": "The caller is not a member of the drayage's shipper or carrier company." } ], "references": { "models": [ "Drayage", "Container" ], "enums": [ "TrackingStage", "TrackingStageUpdateSource" ], "interfaces": [ "LocationInStage" ] } }, { "name": "updateStateDrayageRate", "module": "drayage", "path": "/drayage/updateStateDrayageRate", "method": "POST", "summary": "Toggles the isActive flag of a single rate entry inside a drayage rate sheet.", "params": [ { "name": "_id", "type": "string", "summary": "ObjectId of the rate sheet.", "required": true }, { "name": "rateId", "type": "string", "summary": "ObjectId of the rate entry to toggle.", "required": true }, { "name": "isActive", "type": "boolean", "summary": "New active state for the entry.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Returns true on success." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "Drayage rate not found.", "when": "No drayage rate sheet matches _id." }, { "code": "User is not authorized.", "when": "The caller's company is neither the broker nor the carrier on the rate sheet." } ], "references": { "models": [ "DrayageRate" ] } }, { "name": "uploadDocumentDrayageExtra", "module": "drayage", "path": "/drayage/uploadDocumentDrayageExtra", "method": "POST", "summary": "Uploads extra documents linked to a drayage's DocumentSetup (kept under the supplied source folder on Google Cloud Storage) and notifies both parties.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "docs", "type": "DocumentsUpload[]", "summary": "Documents to upload.", "required": true }, { "name": "source", "type": "string", "summary": "Source folder used as the GCS prefix.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Returns true on success.", "type": "boolean" }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage matches drayageId." }, { "code": "User is not authorized.", "when": "The caller is not an owner of the drayage." } ], "references": { "models": [ "Drayage", "DocumentSetup" ], "interfaces": [ "DocumentsUpload" ] } }, { "name": "uploadDocumentDrayageRate", "module": "drayage", "path": "/drayage/uploadDocumentDrayageRate", "method": "POST", "summary": "Uploads agreement documents to an existing drayage rate sheet on Google Cloud Storage and stores their public URLs.", "params": [ { "name": "_id", "type": "string", "summary": "ObjectId of the rate sheet.", "required": true }, { "name": "docs", "type": "DocumentsUpload[]", "summary": "Documents to upload (each with file, name and extension).", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Returns the array of stored document descriptors (id, url, name, date) when persisted, otherwise an empty array." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "User is not authorized.", "when": "The caller is not a broker, or the caller's company is not the broker on the rate sheet." }, { "code": "Drayage rate not found.", "when": "No rate sheet matches _id." }, { "code": "Company not found.", "when": "The broker company referenced by the rate sheet does not exist." } ], "references": { "models": [ "DrayageRate", "Company" ], "interfaces": [ "DocumentsUpload" ] } }, { "name": "uploadImagesTracking", "module": "drayage", "path": "/drayage/uploadImagesTracking", "method": "POST", "summary": "Uploads a tracking proof file (POD, additional, additional_two or pod_delivery) to Google Cloud Storage and stores its URL on the drayage's fileSharing slot.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "file", "type": "Buffer | string", "summary": "Binary file content (or its base64 representation) to upload.", "required": true }, { "name": "name", "type": "'pod' | 'additional' | 'additional_two' | 'pod_delivery'", "summary": "fileSharing slot to populate.", "required": true }, { "name": "extension", "type": "'jpg' | 'png' | 'pdf'", "summary": "File extension stored in GCS.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Returns the public URL when persisted, otherwise an empty string.", "type": "string" }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "Unauthorized", "when": "The caller is not the drayage owner." } ], "references": { "models": [ "Drayage" ] } }, { "name": "uploadPdfValidatorLetter", "module": "drayage", "path": "/drayage/uploadPdfValidatorLetter", "method": "POST", "summary": "Uploads (or replaces) the Carta Porte PDF associated with a drayage's validator record on Google Cloud Storage.", "params": [ { "name": "doc", "type": "DocumentsUpload", "summary": "PDF upload (file, name, extension).", "required": true }, { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "No explicit return value." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage matches drayageId." } ], "references": { "models": [ "Drayage", "ValidatorCartaPorte" ], "interfaces": [ "DocumentsUpload" ] } }, { "name": "validatorLetter", "module": "drayage", "path": "/drayage/validatorLetter", "method": "POST", "summary": "Validates an XML Carta Porte 2.0 against the drayage, container and Mexican catalogues, attaching error codes when fields don't match. Persists the resulting validator record (URL, percentage and error list) and returns the error list.", "params": [ { "name": "docs", "type": "DocumentsUpload", "summary": "Carta Porte XML upload (file, name, extension).", "required": true }, { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Array of error objects { errorMessage } - empty when the XML is fully compliant." }, "errors": [ { "code": "User not found.", "when": "The token does not resolve to a user." }, { "code": "DRAYAGE_NOT_FOUND", "when": "No drayage matches drayageId." } ], "references": { "models": [ "Drayage", "Container", "ValidatorCartaPorte", "Company", "Settings", "CKeyProductService", "CCveTransport", "CColonia", "CState", "CMunicipality", "CLocation", "CCountry", "CConfigAutoTransport", "Caduana", "CpatentAduanal", "KeyProduct", "CPostalColonia" ], "interfaces": [ "DocumentsUpload" ] } }, { "name": "getDriverByCarrier", "module": "driver", "path": "/driver/getDriverByCarrier", "method": "POST", "summary": "Returns the number of users with the driver role that belong to the company of the supplied carrier user.", "params": [ { "name": "carrierId", "type": "string", "summary": "ObjectId of a carrier User; the count is performed against that user's companyId.", "required": true }, { "name": "token", "type": "string", "summary": "User session token of the caller; validated against the auth microservice.", "required": true } ], "response": { "summary": "Number of User documents with role 'driver' whose companyId matches the carrier's companyId." }, "errors": [ { "code": "CarrierNotFound", "when": "The User referenced by carrierId does not exist." } ], "references": { "models": [ "User" ] } }, { "name": "getNotifiers", "module": "emails", "path": "/emails/getNotifiers", "method": "POST", "summary": "Returns the configured email notifier recipients for the authenticated user's company, grouped by email type.", "params": [ { "name": "token", "type": "string", "summary": "Access token used to resolve the calling user and their company.", "required": true } ], "response": { "summary": "Array of email-notifier configurations for the company, one entry per configured EmailType.", "type": "Promise<{ type: EmailType; notifiers: string[] }[]>" }, "errors": [], "references": { "enums": [ "EmailType" ] } }, { "name": "setNotifiers", "module": "emails", "path": "/emails/setNotifiers", "method": "POST", "summary": "Replaces the email-notifier recipient list for the authenticated user's company, per email type.", "params": [ { "name": "token", "type": "string", "summary": "Access token used to resolve the calling user and their company.", "required": true }, { "name": "notifiers", "type": "{ type: EmailType; notifiers: string[] }[]", "summary": "List of notifier configurations to upsert; each entry sets the recipients for one EmailType.", "required": true } ], "response": { "summary": "Resolves once the notifier configurations have been upserted.", "type": "Promise" }, "errors": [ { "code": "InvalidNotifiers", "when": "`notifiers` is not an array." }, { "code": "InvalidNotifierEntry", "when": "An entry in `notifiers` is not an object." }, { "code": "InvalidNotifierType", "when": "An entry's `type` is not a valid `EmailType` member." }, { "code": "InvalidNotifierList", "when": "An entry's `notifiers` is not an array of strings." } ], "references": { "enums": [ "EmailType" ] } }, { "name": "getEnum", "module": "enums", "path": "/enums/getEnum", "method": "POST", "summary": "Return the array-typed enum identified by name. Only enum names that resolve to an array under common/enums are accepted.", "params": [ { "name": "enumName", "type": "Enums.ENUM", "summary": "Name of the enum to resolve. Must be one of the array-typed enums exported from common/enums.", "required": true } ], "response": { "summary": "The values of the requested enum.", "type": "Promise" }, "errors": [ { "code": "UnknownEnum", "when": "The provided enumName is not an array-typed export of common/enums." } ], "references": {} }, { "name": "getMap", "module": "enums", "path": "/enums/getMap", "method": "POST", "summary": "Return the map-typed enum identified by name. Only enum names that resolve to a non-array (object/map) under common/enums are accepted.", "params": [ { "name": "enumName", "type": "Enums.MAP", "summary": "Name of the map to resolve. Must be one of the non-array enums exported from common/enums.", "required": true } ], "response": { "summary": "The map/object value of the requested enum.", "type": "Promise>" }, "errors": [ { "code": "UnknownMap", "when": "The provided enumName is not a map-typed export of common/enums." } ], "references": {} }, { "name": "Google_getInfoSuggestionOfPlace", "module": "integrations", "path": "/Google.getInfoSuggestionOfPlace", "method": "POST", "summary": "Returns Google Places autocomplete suggestions enriched with geographic details for the supplied query, restricted to the given country. Each suggestion includes lat/lng, address components, place_id and the formatted address.", "params": [ { "name": "name", "type": "string", "summary": "Free-text query typed by the user; must be at least 3 characters long, otherwise an empty list is returned.", "required": true }, { "name": "country", "type": "string", "summary": "ISO country code used to restrict the autocomplete results.", "required": true } ], "response": { "summary": "Array of place suggestions, each containing the description, formatted address, location, place_id, zip code, city, state and country resolved from Google Places.", "type": "Array<{ description: string; fullAddress: string; location: { lat: number; lng: number }; place_id: string; zip_code?: string; city?: string; state?: string; country?: string }>" }, "errors": [] }, { "name": "Google_searchZipCode", "module": "integrations", "path": "/Google.searchZipCode", "method": "POST", "summary": "Geocodes the supplied address through the Google Maps API and returns the matching geodata records (city, state, country, zip code, latitude and longitude). New zip codes are persisted in the local Geodata collection so subsequent lookups are served from the database.", "params": [ { "name": "search", "type": "string", "summary": "Address or zip-code query to geocode; must be at least 4 characters long, otherwise no result is returned.", "required": true } ], "response": { "summary": "Array of geodata records matching the query (either freshly inserted or read from the Geodata collection).", "type": "Array<{ city: string; state: string; country: string; zip_code: string; latitude: number; longitude: number }>" }, "errors": [], "references": { "models": [ "Geodata" ] } }, { "name": "OLP_about", "module": "integrations", "path": "/Integrations.OLP.about", "method": "POST", "summary": "Calls the OLP `about` endpoint and returns the OLP node identity, advertising its version, registered channels and listening address.", "params": [ { "name": "token", "type": "string", "summary": "Admin user session token; the route is restricted to administrators.", "required": true } ], "response": { "summary": "Identity record returned by the OLP node.", "type": "{ id: string; version: string; channels: string[]; listeningAddress: string }" }, "errors": [] }, { "name": "OLP_acceptNegotiation", "module": "integrations", "path": "/Integrations.OLP.acceptNegotiation", "method": "POST", "summary": "Accepts a negotiation on the OLP marketplace by resolving the carrier's company DID, fetching an OLP token for the shipper and POSTing the acceptance to the OLP `negotiations/accept` endpoint.", "params": [ { "name": "shipmentDID", "type": "string", "summary": "DID of the OLP shipment whose negotiation is being accepted.", "required": true }, { "name": "carrierId", "type": "string", "summary": "Dexfreight user identifier of the carrier whose offer is being accepted.", "required": true }, { "name": "shipperId", "type": "string", "summary": "Dexfreight user identifier of the shipper accepting the offer.", "required": true }, { "name": "token", "type": "string", "summary": "Admin user session token used to authorise the call.", "required": true } ], "response": { "summary": "The OLP `negotiations/accept` response describing the updated negotiation." }, "errors": [] }, { "name": "OLP_confirmDelivery", "module": "integrations", "path": "/Integrations.OLP.confirmDelivery", "method": "POST", "summary": "Confirms a delivery stop on an OLP shipment on behalf of the assigned carrier by POSTing the action to the OLP `shipments/confirmStop` endpoint with the carrier's OLP token.", "params": [ { "name": "shipmentDID", "type": "string", "summary": "DID of the OLP shipment whose delivery stop is being confirmed.", "required": true }, { "name": "carrierId", "type": "string", "summary": "Dexfreight user identifier of the carrier confirming the delivery.", "required": true }, { "name": "token", "type": "string", "summary": "Admin user session token used to authorise the call.", "required": true } ], "response": { "summary": "The OLP `shipments/confirmStop` response." }, "errors": [] }, { "name": "OLP_confirmShipment", "module": "integrations", "path": "/Integrations.OLP.confirmShipment", "method": "POST", "summary": "Confirms an OLP shipment on behalf of the assigned carrier by POSTing the action to the OLP `shipments/confirmShipment` endpoint with the carrier's OLP token.", "params": [ { "name": "shipmentDID", "type": "string", "summary": "DID of the OLP shipment to confirm.", "required": true }, { "name": "carrierId", "type": "string", "summary": "Dexfreight user identifier of the carrier confirming the shipment.", "required": true }, { "name": "token", "type": "string", "summary": "Admin user session token used to authorise the call.", "required": true } ], "response": { "summary": "The OLP `shipments/confirmShipment` response." }, "errors": [] }, { "name": "OLP_counterofferNegotiationDrayage", "module": "integrations", "path": "/Integrations.OLP.counterofferNegotiationDrayage", "method": "POST", "summary": "Submits a counter-offer to an OLP drayage negotiation on behalf of a carrier, posting the new rate and payment services to the OLP `negotiations/counteroffer` endpoint.", "params": [ { "name": "shipmentDID", "type": "string", "summary": "DID of the OLP shipment whose negotiation is being countered.", "required": true }, { "name": "carrierId", "type": "string", "summary": "Dexfreight user identifier of the carrier issuing the counter-offer.", "required": true }, { "name": "value", "type": "BidOlpInfo", "summary": "Counter-offer payload with the new rate and payment services.", "required": true }, { "name": "token", "type": "string", "summary": "Admin user session token used to authorise the call.", "required": true } ], "response": { "summary": "The OLP `negotiations/counteroffer` response describing the updated negotiation." }, "errors": [], "references": { "interfaces": [ "BidOlpInfo" ] } }, { "name": "OLP_createNegotiationDrayage", "module": "integrations", "path": "/Integrations.OLP.createNegotiationDrayage", "method": "POST", "summary": "Creates a new negotiation on an OLP drayage shipment on behalf of a carrier, submitting the proposed rate and payment services to the OLP `negotiations/create` endpoint.", "params": [ { "name": "drayageDID", "type": "string", "summary": "DID of the OLP shipment for which the negotiation is being opened.", "required": true }, { "name": "carrierId", "type": "string", "summary": "Dexfreight user identifier of the carrier submitting the bid.", "required": true }, { "name": "value", "type": "BidOlpInfo", "summary": "Bid payload with the proposed rate and the requested payment services.", "required": true }, { "name": "token", "type": "string", "summary": "Admin user session token used to authorise the call.", "required": true } ], "response": { "summary": "The OLP `negotiations/create` response describing the new negotiation." }, "errors": [], "references": { "interfaces": [ "BidOlpInfo" ] } }, { "name": "OLP_ensureUser", "module": "integrations", "path": "/Integrations.OLP.ensureUser", "method": "POST", "summary": "Idempotently provisions a Dexfreight user on the OLP marketplace: locates the user and their Dexfreight company, creates the OLP company if it does not exist, persists the company DID locally and creates the OLP user with a deterministic password if it does not exist either.", "params": [ { "name": "userId", "type": "string", "summary": "Dexfreight user identifier to ensure on OLP.", "required": true }, { "name": "token", "type": "string", "summary": "Admin user session token used to authorise the call.", "required": true } ], "response": { "summary": "The OLP user record associated with the Dexfreight user (existing or newly created)." }, "errors": [ { "code": "AssertionFailed", "when": "The supplied `userId` does not match a Dexfreight user, or the user's company is missing from the local database." } ], "references": { "models": [ "User", "Company" ] } }, { "name": "OLP_getCompany", "module": "integrations", "path": "/Integrations.OLP.getCompany", "method": "POST", "summary": "Looks up an OLP company by its Dexfreight company identifier through the OLP companies microservice.", "params": [ { "name": "companyId", "type": "string", "summary": "Dexfreight company identifier whose OLP counterpart must be returned.", "required": true }, { "name": "token", "type": "string", "summary": "Admin user session token used to authorise the call.", "required": true } ], "response": { "summary": "The OLP company record associated with the Dexfreight company, or `undefined` if it has not been registered yet." }, "errors": [] }, { "name": "OLP_getCompanyDIDForDexUser", "module": "integrations", "path": "/Integrations.OLP.getCompanyDIDForDexUser", "method": "POST", "summary": "Returns the OLP company DID assigned to the Dexfreight user's company, provisioning the OLP user/company on demand via `userInfo` if needed.", "params": [ { "name": "userId", "type": "string", "summary": "Dexfreight user identifier whose company DID must be returned.", "required": true }, { "name": "token", "type": "string", "summary": "Admin user session token used to authorise the call.", "required": true } ], "response": { "summary": "The OLP company DID associated with the Dexfreight user's company.", "type": "string" }, "errors": [] }, { "name": "OLP_getCompanyIdByDID", "module": "integrations", "path": "/Integrations.OLP.getCompanyIdByDID", "method": "POST", "summary": "Resolves an OLP company DID back to the Dexfreight company identifier stored in the OLP `referenceId` field.", "params": [ { "name": "did", "type": "string", "summary": "OLP company DID whose Dexfreight company identifier must be returned.", "required": true }, { "name": "token", "type": "string", "summary": "Admin user session token used to authorise the call.", "required": true } ], "response": { "summary": "The Dexfreight company identifier referenced by the OLP company, or `undefined` if no company is registered for the DID." }, "errors": [] }, { "name": "OLP_getDexUserByDID", "module": "integrations", "path": "/Integrations.OLP.getDexUserByDID", "method": "POST", "summary": "Resolves an OLP DID to the matching Dexfreight user by extracting the Ethereum address from the OLP user record and looking it up in the Dexfreight users collection.", "params": [ { "name": "did", "type": "string", "summary": "OLP DID whose Dexfreight user counterpart must be returned.", "required": true }, { "name": "token", "type": "string", "summary": "Admin user session token used to authorise the call.", "required": true } ], "response": { "summary": "The Dexfreight user record whose `ethAddress` matches the OLP DID." }, "errors": [ { "code": "AssertionFailed", "when": "No Dexfreight user is registered with the Ethereum address derived from the OLP DID." } ], "references": { "models": [ "User" ] } }, { "name": "OLP_getDIDForDexUser", "module": "integrations", "path": "/Integrations.OLP.getDIDForDexUser", "method": "POST", "summary": "Returns the OLP DID assigned to a Dexfreight user, creating the OLP user/company on demand via `userInfo` if they do not yet exist.", "params": [ { "name": "userId", "type": "string", "summary": "Dexfreight user identifier whose OLP DID must be returned.", "required": true }, { "name": "token", "type": "string", "summary": "Admin user session token used to authorise the call.", "required": true } ], "response": { "summary": "The OLP DID associated with the Dexfreight user.", "type": "string" }, "errors": [] }, { "name": "OLP_getOLPShipmentByDID", "module": "integrations", "path": "/Integrations.OLP.getOLPShipmentByDID", "method": "POST", "summary": "Fetches an OLP shipment by its identifier by calling the OLP `shipments/get` endpoint with the configured admin token.", "params": [ { "name": "shipmentId", "type": "string", "summary": "OLP shipment identifier to retrieve.", "required": true }, { "name": "token", "type": "string", "summary": "Admin user session token used to authorise the call.", "required": true } ], "response": { "summary": "The OLP shipment record returned by the OLP node." }, "errors": [] }, { "name": "OLP_getOLPUserByDID", "module": "integrations", "path": "/Integrations.OLP.getOLPUserByDID", "method": "POST", "summary": "Looks up an OLP user by its decentralised identifier (DID) by calling the OLP `auth/get` endpoint.", "params": [ { "name": "did", "type": "string", "summary": "DID of the OLP user to retrieve.", "required": true }, { "name": "token", "type": "string", "summary": "Admin user session token used to authorise the call.", "required": true } ], "response": { "summary": "The OLP user record matching the supplied DID." }, "errors": [] }, { "name": "OLP_listen", "module": "integrations", "path": "/Integrations.OLP.listen", "method": "POST", "summary": "Webhook receiver for OLP-driven events. Routes the call to the matching handler in the local `OLPEvents` module; unknown event names are ignored after being logged.", "params": [ { "name": "method", "type": "string", "summary": "Name of the OLP event being delivered; used to resolve the local handler in `OLPEvents`.", "required": true }, { "name": "data", "type": "any", "summary": "Event payload forwarded to the matching `OLPEvents` handler.", "required": true } ], "response": { "summary": "Returns no value; resolves once the matching event handler completes (or immediately if the event is unknown)." }, "errors": [] }, { "name": "OLP_olpTokenFromDexToken", "module": "integrations", "path": "/Integrations.OLP.olpTokenFromDexToken", "method": "POST", "summary": "Exchanges a Dexfreight session token for an OLP authentication token by resolving the Dexfreight user behind the token and requesting an OLP login on their behalf.", "params": [ { "name": "token", "type": "string", "summary": "Dexfreight user session token to be exchanged.", "required": true } ], "response": { "summary": "The OLP `auth/login` response containing the JWT for the resolved user." }, "errors": [] }, { "name": "OLP_postDrayage", "module": "integrations", "path": "/Integrations.OLP.postDrayage", "method": "POST", "summary": "Publishes a Dexfreight drayage on the OLP marketplace by serialising its origin, destination, containers, payment terms and appointments and POSTing them to the OLP `shipments/create` endpoint with the drayage owner's OLP token.", "params": [ { "name": "drayageId", "type": "string", "summary": "Identifier of the drayage to be published on OLP.", "required": true }, { "name": "token", "type": "string", "summary": "Admin user session token used to authorise the call.", "required": true } ], "response": { "summary": "The OLP `shipments/create` response describing the newly created shipment." }, "errors": [], "references": { "models": [ "Drayage", "Container" ] } }, { "name": "OLP_sign", "module": "integrations", "path": "/Integrations.OLP.sign", "method": "POST", "summary": "Signs an arbitrary string with the caller's OLP keys. Resolves the Dexfreight user from the supplied token, fetches an OLP token for them and POSTs the data to the OLP `auth/sign` endpoint.", "params": [ { "name": "token", "type": "string", "summary": "User session token of the signer.", "required": true }, { "name": "data", "type": "string", "summary": "Payload to be signed with the caller's OLP identity.", "required": true } ], "response": { "summary": "The OLP `auth/sign` response containing the digital signature for the supplied data." }, "errors": [] }, { "name": "OLP_userInfo", "module": "integrations", "path": "/Integrations.OLP.userInfo", "method": "POST", "summary": "Returns the OLP user record associated with a Dexfreight user, ensuring that both the Dexfreight company and the OLP user/company exist and creating any missing OLP counterpart.", "params": [ { "name": "userId", "type": "string", "summary": "Dexfreight user identifier whose OLP record must be returned.", "required": true }, { "name": "token", "type": "string", "summary": "Admin user session token used to authorise the call.", "required": true } ], "response": { "summary": "The OLP user record (`did`, `companyDID`, role, etc.) associated with the Dexfreight user." }, "errors": [ { "code": "AssertionFailed", "when": "The Dexfreight user identifier does not match a stored user, or the user's company does not exist locally." } ], "references": { "models": [ "User", "Company" ] } }, { "name": "OLP_userRegisterStatus", "module": "integrations", "path": "/Integrations.OLP.userRegisterStatus", "method": "POST", "summary": "Reports whether a DID is registered on OLP and, if so, whether the corresponding Ethereum address is registered as a Dexfreight user.", "params": [ { "name": "did", "type": "string", "summary": "DID whose registration status must be checked on both OLP and Dexfreight.", "required": true }, { "name": "token", "type": "string", "summary": "Admin user session token used to authorise the call.", "required": true } ], "response": { "summary": "Two-flag record indicating whether the DID is registered on OLP and on Dexfreight respectively.", "type": "{ olp: boolean; dex: boolean }" }, "errors": [] }, { "name": "OLP_userToken", "module": "integrations", "path": "/Integrations.OLP.userToken", "method": "POST", "summary": "Returns an OLP authentication token for a given Dexfreight user, ensuring that the corresponding OLP user exists before requesting the token via the OLP `auth/login` endpoint.", "params": [ { "name": "userId", "type": "string", "summary": "Dexfreight user identifier whose OLP token is being requested.", "required": true }, { "name": "token", "type": "string", "summary": "Admin user session token used to authorise the call.", "required": true } ], "response": { "summary": "The OLP `auth/login` response containing the JWT used to authenticate further OLP calls on behalf of the user." }, "errors": [] }, { "name": "Pac_cancelCartaPorte", "module": "integrations", "path": "/Integrations.Pac.cancelCartaPorte", "method": "POST", "summary": "Schedules the cancellation of a previously stamped Carta Porte with the PAC, after validating that the document exists, is currently signed and that the caller is the carrier of the underlying drayage; on success the local Carta Porte status is moved to `Cancelled` and both companies are notified.", "params": [ { "name": "ccpId", "type": "string", "summary": "Identifier of the DataCartaPorte document to cancel.", "required": true }, { "name": "token", "type": "string", "summary": "User session token of the carrier cancelling the Carta Porte.", "required": true } ], "response": { "summary": "An `httpOk` envelope confirming that the Carta Porte cancellation was scheduled." }, "errors": [ { "code": "CCP_NOT_FOUND", "when": "No Carta Porte document was found for the supplied `ccpId`." }, { "code": "CCP_ALREADY_CANCELLED", "when": "The Carta Porte is not in `Signed` status, typically because it has already been cancelled." }, { "code": "DRAYAGE_NOT_FOUND", "when": "The Carta Porte points to a drayage that no longer exists." }, { "code": "USER_UNAUTHORIZED_OVER_DRAYAGE", "when": "The authenticated user is not the assigned carrier for the underlying drayage." } ], "references": { "models": [ "DataCartaPorte", "Drayage" ], "enums": [ "PACDocumentStatus", "NotificationType" ] } }, { "name": "Pac_cancelComplementoPago", "module": "integrations", "path": "/Integrations.Pac.cancelComplementoPago", "method": "POST", "summary": "Schedules the cancellation of a previously stamped Complemento de Pago with the PAC, optionally referencing a substitute UUID. Validates that the document exists, is currently OK and that the caller belongs to the carrier company; on success the local document status is moved to `Cancelled`.", "params": [ { "name": "cpagoId", "type": "string", "summary": "Identifier of the DocumentoPago to cancel.", "required": true }, { "name": "token", "type": "string", "summary": "User session token of the carrier user cancelling the Complemento de Pago.", "required": true }, { "name": "replacement", "type": "string", "summary": "Optional UUID of a substitute Complemento de Pago; when present the cancellation is sent with the `WithSubstitution` reason.", "required": false } ], "response": { "summary": "An `httpOk` envelope confirming that the Complemento de Pago cancellation was scheduled." }, "errors": [ { "code": "CPAGO_NOT_FOUND", "when": "No Complemento de Pago document was found for the supplied `cpagoId`." }, { "code": "CPAGO_ALREADY_CANCELLED", "when": "The Complemento de Pago is not in `OK` status, typically because it has already been cancelled." }, { "code": "UNAUTHORIZED", "when": "The authenticated user does not belong to the carrier company that issued the Complemento de Pago." } ], "references": { "models": [ "DocumentPago" ], "enums": [ "PACDocumentStatus", "PACCancelationReason" ] } }, { "name": "Pac_complementoPago", "module": "integrations", "path": "/Integrations.Pac.complementoPago", "method": "POST", "summary": "Builds and stamps a CFDI Complemento de Pago that covers a list of internal Carta Porte invoices and/or external invoices. Validates the SAT payment method, deduplicates external invoices, generates the PAC payload, dispatches the stamping job, persists the resulting DocumentoPago and resolves the asynchronous PAC promise.", "params": [ { "name": "options", "type": "{ listFact: string[]; externalInvoices?: ExternalFacturaCompliance[]; paymentMethod: string; paymentDate: string; cfdiPrevio?: string }", "summary": "Carta Porte unique-ids to include, optional external invoices, SAT payment method code, payment date and optional UUID of a previous CFDI being substituted.", "required": true }, { "name": "token", "type": "string", "summary": "User session token of the carrier issuing the Complemento de Pago.", "required": true } ], "response": { "summary": "Resolves with the asynchronous Complemento de Pago result registered in `ComplementoDePagoPromises` once the PAC stamping job finishes." }, "errors": [ { "code": "PAC_CDP_NO_INVOICES_PROVIDED", "when": "Neither internal Carta Porte invoices nor external invoices were supplied, so there is nothing to stamp." }, { "code": "PAC_DOCUMENT_STAMP_FAILED", "when": "The PAC rejected the Complemento de Pago stamping request and returned a non-OK status." } ], "references": { "models": [ "DocumentPago", "DataCartaPorte", "Company" ], "interfaces": [ "ComplementoPago", "ExternalFacturaCompliance" ] } }, { "name": "Pac_crearCartaPorte", "module": "integrations", "path": "/Integrations.Pac.crearCartaPorte", "method": "POST", "summary": "Builds the PAC Carta Porte payload for the given drayage, requests its digital stamp from the PAC, uploads the resulting XML/PDF to Google Cloud Storage, persists a DataCartaPorte record, links it to the drayage and notifies both the broker and the carrier company.", "params": [ { "name": "options", "type": "{ drayageID: string; displayAmount: boolean; CFDIPrevio?: string }", "summary": "Drayage identifier together with flags that control the PAC payload generation: whether the freight amount is shown and the previous CFDI UUID when the document is a substitute.", "required": true }, { "name": "token", "type": "string", "summary": "User session token of the carrier requesting the stamp.", "required": true } ], "response": { "summary": "The raw PAC stamping response. On success it includes the document UUID, the base64 encoded XML and PDF, the document unique identifier and a status flag; on failure it returns the PAC error payload." }, "errors": [ { "code": "AssertionFailed", "when": "The authenticated user is not the assigned carrier for the drayage, so they cannot stamp the Carta Porte." } ], "references": { "models": [ "DataCartaPorte", "Drayage", "Company" ], "enums": [ "PACDocumentStatus", "NotificationType" ] } }, { "name": "Pac_createBusinessEntity", "module": "integrations", "path": "/Integrations.Pac.createBusinessEntity", "method": "POST", "summary": "Registers the Mexican fiscal information of a company with the PAC provider. Looks up the company and its fiscal regime, posts the identity, address and regime code to the PAC `businessEntity/createBusinessEntity` service and, on success, marks the company as having a CSD entity in the companies microservice.", "params": [ { "name": "companyId", "type": "string", "summary": "Identifier of the company whose fiscal entity must be created in the PAC.", "required": true }, { "name": "token", "type": "string", "summary": "User session token used to authorise the call against the auth and companies microservices.", "required": true } ], "response": { "summary": "The PAC `businessEntity/createBusinessEntity` response payload, or the PAC error payload if the request failed." }, "errors": [], "references": { "models": [ "Company", "CFiscalRegime" ] } }, { "name": "Pac_deleteCompanyEntityCSD", "module": "integrations", "path": "/Integrations.Pac.deleteCompanyEntityCSD", "method": "POST", "summary": "Removes the SAT digital seal (CSD) registered for the caller's company in the companies microservice, effectively unlinking the company from the PAC fiscal entity.", "params": [ { "name": "token", "type": "string", "summary": "User session token of the company administrator deleting the CSD.", "required": true } ], "response": { "summary": "The companies microservice response confirming that the CSD record was deleted." }, "errors": [] }, { "name": "Pac_editBusinessEntity", "module": "integrations", "path": "/Integrations.Pac.editBusinessEntity", "method": "POST", "summary": "Updates the Mexican fiscal data of a previously registered company in the PAC by sending the latest identity, address and fiscal regime to the `businessEntity/updateBusinessEntity` service.", "params": [ { "name": "companyId", "type": "string", "summary": "Identifier of the company whose PAC fiscal entity must be updated.", "required": true }, { "name": "token", "type": "string", "summary": "User session token used to authorise the call.", "required": true } ], "response": { "summary": "The PAC `businessEntity/updateBusinessEntity` response payload, or the PAC error payload if the request failed." }, "errors": [], "references": { "models": [ "Company", "CFiscalRegime" ] } }, { "name": "Pac_getAllCartaPortes", "module": "integrations", "path": "/Integrations.Pac.getAllCartaPortes", "method": "POST", "summary": "Returns every DataCartaPorte document associated with a drayage, sorted by descending expedition date, after verifying that the caller is the broker, carrier or admin owner of the drayage.", "params": [ { "name": "drayageId", "type": "string", "summary": "Identifier of the drayage whose Carta Porte history must be returned.", "required": true }, { "name": "token", "type": "string", "summary": "User session token used to authorise access to the drayage.", "required": true } ], "response": { "summary": "Array of DataCartaPorte documents linked to the drayage, ordered from the most recent expedition date to the oldest." }, "errors": [ { "code": "USER_UNAUTHORIZED_OVER_DRAYAGE", "when": "The authenticated user is not the broker, carrier or admin owner of the drayage." } ], "references": { "models": [ "DataCartaPorte", "Drayage" ] } }, { "name": "Pac_getBusinessEntity", "module": "integrations", "path": "/Integrations.Pac.getBusinessEntity", "method": "POST", "summary": "Retrieves the fiscal entity registered in the PAC for the supplied RFC by calling the `businessEntity/getBusinessEntity` service.", "params": [ { "name": "rfc", "type": "string", "summary": "Mexican RFC (taxpayer identifier) whose PAC entity must be looked up.", "required": true }, { "name": "token", "type": "string", "summary": "User session token used to authorise the call.", "required": true } ], "response": { "summary": "The PAC `businessEntity/getBusinessEntity` response payload, or the PAC error payload if the request failed." }, "errors": [] }, { "name": "Pac_getDocumentoCartaPorte", "module": "integrations", "path": "/Integrations.Pac.getDocumentoCartaPorte", "method": "POST", "summary": "Retrieves the latest stamped Carta Porte from the PAC for a drayage in the requested representation (PDF or XML) and visibility mode (with or without freight amount). Authorises the caller against the broker or carrier company recorded on the document.", "params": [ { "name": "drayageId", "type": "string", "summary": "Identifier of the drayage whose stamped Carta Porte must be downloaded.", "required": true }, { "name": "option", "type": "'HIDE_FREIGHT' | 'HIDE_AMOUNT'", "summary": "Visibility flag forwarded to the PAC to mask either the freight section or the totals on the rendered document.", "required": true }, { "name": "documentType", "type": "'PDF' | 'XML'", "summary": "Representation of the Carta Porte to retrieve from the PAC.", "required": true }, { "name": "token", "type": "string", "summary": "User session token of the broker or carrier requesting the document.", "required": true } ], "response": { "summary": "The Carta Porte document fetched from the PAC in the requested representation." }, "errors": [ { "code": "USER_UNAUTHORIZED_OVER_DRAYAGE", "when": "The authenticated user's company is neither the carrier nor the broker recorded on the latest Carta Porte for the drayage." } ], "references": { "models": [ "DataCartaPorte" ] } }, { "name": "Pac_getLatestCartaPorte", "module": "integrations", "path": "/Integrations.Pac.getLatestCartaPorte", "method": "POST", "summary": "Returns the most recent DataCartaPorte document associated with a drayage, sorted by descending `_id`, after verifying that the caller is the broker, carrier or admin owner of the drayage.", "params": [ { "name": "drayageId", "type": "string", "summary": "Identifier of the drayage whose latest Carta Porte must be returned.", "required": true }, { "name": "token", "type": "string", "summary": "User session token used to authorise access to the drayage.", "required": true } ], "response": { "summary": "The latest DataCartaPorte document for the drayage, or null if no Carta Porte has been generated yet." }, "errors": [ { "code": "USER_UNAUTHORIZED_OVER_DRAYAGE", "when": "The authenticated user is not the broker, carrier or admin owner of the drayage." } ], "references": { "models": [ "DataCartaPorte", "Drayage" ] } }, { "name": "Pac_invoicesListCSV", "module": "integrations", "path": "/Integrations.Pac.invoicesListCSV", "method": "POST", "summary": "Parses a CSV listing of invoice UUIDs, validates that every UUID matches the SAT format, ensures every UUID corresponds to a Carta Porte issued by the caller's company and returns the matching internal `uniqueId`s.", "params": [ { "name": "csv", "type": "string", "summary": "Raw CSV content with the invoice UUIDs to be reconciled against the carrier's Carta Porte history.", "required": true }, { "name": "token", "type": "string", "summary": "User session token of the carrier reconciling the invoices.", "required": true } ], "response": { "summary": "Array of internal Carta Porte `uniqueId`s, one per UUID listed in the CSV.", "type": "string[]" }, "errors": [ { "code": "INVALID_UUID_FORMAT", "when": "One of the UUIDs read from the CSV does not match the canonical 8-4-4-4-12 hexadecimal format." }, { "code": "CCP_NOT_FOUND", "when": "At least one UUID listed in the CSV does not correspond to any DataCartaPorte stored in the database." }, { "code": "USER_UNAUTHORIZED_OVER_DRAYAGE", "when": "The authenticated user does not belong to the carrier company that issued one of the matching Carta Porte documents." } ], "references": { "models": [ "DataCartaPorte" ], "types": [ "InvoiceListCSVRow" ] } }, { "name": "Pac_previewFacturaCCP", "module": "integrations", "path": "/Integrations.Pac.previewFacturaCCP", "method": "POST", "summary": "Generates the PAC Carta Porte payload for a drayage without stamping it, so the carrier can preview the invoice before requesting the digital stamp.", "params": [ { "name": "drayageID", "type": "string", "summary": "Identifier of the drayage whose Carta Porte payload should be previewed.", "required": true }, { "name": "token", "type": "string", "summary": "User session token of the carrier requesting the preview.", "required": true } ], "response": { "summary": "The unsigned PaccCartaPorte payload that would be sent to the PAC if the carrier confirmed the issuance." }, "errors": [ { "code": "AssertionFailed", "when": "The authenticated user is not the assigned carrier for the drayage, so they cannot preview the Carta Porte." } ], "references": { "models": [ "Drayage" ], "interfaces": [ "PaccCartaPorte" ] } }, { "name": "Pac_setBusinessEntityCSD", "module": "integrations", "path": "/Integrations.Pac.setBusinessEntityCSD", "method": "POST", "summary": "Uploads the SAT digital seal certificate (CSD) for the caller's company to the PAC. Reads the `.cer` and `.key` files from the upload payload, base64-encodes them along with the alias and certificate password, sends them to the PAC `businessEntity/setBusinessEntityCSD` service and, on success, persists the CSD metadata in the companies microservice.", "params": [ { "name": "payload", "type": "{ rfc?: string; alias: string; certPassword: string }", "summary": "CSD metadata, including the RFC, the alias used to identify the seal in the PAC and the certificate password.", "required": true }, { "name": "cert", "type": "DocumentsUpload[]", "summary": "Uploaded `.cer` files; only the first usable buffer is forwarded to the PAC.", "required": true }, { "name": "key", "type": "DocumentsUpload[]", "summary": "Uploaded `.key` files; only the first usable buffer is forwarded to the PAC.", "required": true }, { "name": "token", "type": "string", "summary": "User session token of the company administrator registering the CSD.", "required": true } ], "response": { "summary": "The PAC `businessEntity/setBusinessEntityCSD` response payload, or the PAC error payload / error message if the request failed." }, "errors": [], "references": { "interfaces": [ "DocumentsUpload" ] } }, { "name": "Pac_validateDocuments", "module": "integrations", "path": "/Integrations.Pac.validateDocuments", "method": "POST", "summary": "Updates the list of external facturas matched by UUID, marking them as validated PDFs in the Carta Porte reconciliation pipeline.", "params": [ { "name": "uuids", "type": "string[]", "summary": "List of CFDI UUIDs to validate against the stored Carta Porte / external facturas records.", "required": true } ], "response": { "summary": "The result of the bulk update against the matched facturas." }, "errors": [], "references": { "models": [ "DataCartaPorte" ] } }, { "name": "notifyRelease", "module": "lazex", "path": "/lazex/notifyRelease", "method": "POST", "summary": "Lazex integration entrypoint that validates an import request (origin, destination, containers, client), and on success creates Draft CustomerPortalContainer rows enriched with SAT location data, shipping line and commodity metadata and emails the client a mid-mile feedback link. On prevalidation failure it emails the client a corrections report and returns the structured error list instead.", "params": [ { "name": "origen", "type": "LazexRequest['origen']", "summary": "Origin location (address, SAT location codes, RFC).", "required": true }, { "name": "destino", "type": "LazexRequest['destino']", "summary": "Destination location (address, SAT location codes, RFC).", "required": true }, { "name": "contenedores", "type": "LazexRequest['contenedores']", "summary": "Containers to draft, including type, weight, shipment (masterBL), patent and SAT-encoded merchandise list.", "required": true }, { "name": "cliente", "type": "LazexRequest['cliente']", "summary": "Client receiving the invitation (name, email, billing company).", "required": true }, { "name": "token", "type": "string", "summary": "User session token used to resolve the calling user via getTokenUser.", "required": true } ], "response": { "summary": "On prevalidation failure: { success: false, errors }. On success: { success: true, message: 'Registro guardado exitosamente', containers: ObjectId[] }.", "type": "Promise<{ success: false; errors: unknown[] } | { success: true; message: string; containers: ObjectId[] }>" }, "errors": [], "references": { "models": [ "CustomerPortalContainer" ], "enums": [ "CustomerPortalContainerStatus", "PortalContainerServiceType", "DrayageType" ], "types": [ "LazexRequest" ] } }, { "name": "postLastMileRequest", "module": "lazex", "path": "/lazex/postLastMileRequest", "method": "POST", "summary": "Lazex last-mile entrypoint that, given the client's already-drafted containers, validates the request, promotes each matching CustomerPortalContainer from Draft to Pending with the requested delivery time, and emails the client a release notification with a fresh invitation token. On prevalidation failure it emails the client a corrections report and returns the structured error list instead.", "params": [ { "name": "contenedores", "type": "LazexLastMileRequest['contenedores']", "summary": "Containers to release, keyed by container number and including the requested delivery time.", "required": true }, { "name": "cliente", "type": "LazexLastMileRequest['cliente']", "summary": "Client receiving the release email (name, email).", "required": true }, { "name": "token", "type": "string", "summary": "User session token used to resolve the calling user via getTokenUser.", "required": true } ], "response": { "summary": "On prevalidation failure: { success: false, errors }. On success: httpOk('Solicitud de última milla enviada exitosamente', { success: true, containers, token? }) — invitation `token` is only echoed back in local context.", "type": "Promise<{ success: false; errors: unknown[] } | ReturnType>" }, "errors": [ { "code": "CustomerPortalContainerNotFound", "when": "A container number in the request has no matching Draft CustomerPortalContainer for the client/company pair." } ], "references": { "models": [ "CustomerPortalContainer" ], "enums": [ "CustomerPortalContainerStatus" ], "types": [ "LazexLastMileRequest" ] } }, { "name": "create", "module": "load-location", "path": "/load-location/create", "method": "POST", "summary": "Creates a load location (a saved pickup or delivery point) for the caller's company. Names are unique within a company; payload is validated against CreateLoadLocationSchema and `isRegisteredInCDYS` defaults to false.", "params": [ { "name": "location", "type": "Omit, '_id' | 'companyId' | 'userId'>", "summary": "Load location payload (name, address, city, state, zipcode, country, colonia, locality, rfc, isRegisteredInCDYS).", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The newly created LoadLocation document.", "type": "LoadLocation" }, "errors": [ { "code": "LOAD_LOCATION_ALREADY_EXISTS", "when": "A load location with the same name already exists for the caller's company." } ], "references": { "models": [ "LoadLocationModel" ] } }, { "name": "deleteLoadId", "module": "load-location", "path": "/load-location/deleteLoadId", "method": "POST", "summary": "Deletes a load location by id. Caller's company must own the document.", "params": [ { "name": "locationId", "type": "ID", "summary": "Identifier of the LoadLocation to delete.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Mongoose deleteOne result.", "type": "{ n: number, deletedCount?: number, ok?: number }" }, "errors": [ { "code": "LOAD_LOCATION_CODE_NOT_FOUND", "when": "No load location with the supplied id exists or it does not belong to the caller's company." } ], "references": { "models": [ "LoadLocationModel" ] } }, { "name": "get", "module": "load-location", "path": "/load-location/get", "method": "POST", "summary": "Looks up a load location by name within the caller's company and returns it together with the SAT catalogue data (state, city, colony, etc.) computed from its address.", "params": [ { "name": "name", "type": "string", "summary": "Name of the load location to fetch.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The load location document together with its SAT catalogue lookup data.", "type": "{ location: LoadLocation } & CatalogueData" }, "errors": [ { "code": "LOAD_LOCATION_CODE_NOT_FOUND", "when": "No load location exists with the supplied name for the caller's company." } ], "references": { "models": [ "LoadLocationModel" ] } }, { "name": "getLocation", "module": "load-location", "path": "/load-location/getLocation", "method": "POST", "summary": "Returns every LoadLocation registered for the caller's company.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Array of LoadLocation documents owned by the caller's company.", "type": "LoadLocation[]" }, "errors": [ { "code": "AssertionError", "when": "The lookup returned a falsy value (defensive check; rare in practice)." } ], "references": { "models": [ "LoadLocationModel" ] } }, { "name": "getLocationId", "module": "load-location", "path": "/load-location/getLocationId", "method": "POST", "summary": "Returns a single LoadLocation by id.", "params": [ { "name": "locationId", "type": "ID", "summary": "Identifier of the LoadLocation to fetch.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The LoadLocation document.", "type": "LoadLocation" }, "errors": [ { "code": "AssertionError", "when": "No load location was found with the supplied id." } ], "references": { "models": [ "LoadLocationModel" ] } }, { "name": "locations", "module": "load-location", "path": "/load-location/locations", "method": "POST", "summary": "Paginated listing of LoadLocation documents owned by the caller's company.", "params": [ { "name": "skip", "type": "number", "summary": "Number of documents to skip (offset).", "required": true }, { "name": "limit", "type": "number", "summary": "Maximum number of documents to return.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Page of LoadLocation documents (lean).", "type": "LoadLocation[]" }, "errors": [], "references": { "models": [ "LoadLocationModel" ] } }, { "name": "update", "module": "load-location", "path": "/load-location/update", "method": "POST", "summary": "Updates the LoadLocation that matches the supplied `name` within the caller's company. Payload is validated against CreateLoadLocationSchema. The `isRegisteredInCDYS` flag is preserved from the existing document.", "params": [ { "name": "location", "type": "Omit, '_id' | 'companyId' | 'userId'>", "summary": "Replacement load location payload (name, address, city, state, zipcode, country, colonia, locality, rfc, wiecName).", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Standard httpOk envelope confirming the update.", "type": "{ ok: true, message: string }" }, "errors": [ { "code": "AssertionError", "when": "No load location with the supplied name exists for the caller's company." } ], "references": { "models": [ "LoadLocationModel" ] } }, { "name": "getZipcodeData", "module": "locations", "path": "/locations/getZipcodeData", "method": "POST", "summary": "Resolves a Mexican zipcode into its catalogue data: colonias, states (with municipalities), cities (geodata), and locations.", "params": [ { "name": "zipcode", "type": "string", "summary": "Mexican postal code; normalized and validated through the `Zipcode` value object before lookup.", "required": true } ], "response": { "summary": "Composite catalogue payload for the zipcode: settlement colonias, states (each with their municipalities for that zipcode), city names from geodata, and named locations.", "type": "Promise" }, "errors": [ { "code": "INVALID_ZIPCODE", "when": "The provided zipcode does not match the Mexican 5-digit format (`/^\\d{5}$/`)." } ], "references": { "valueObjects": [ "Zipcode" ] } }, { "name": "getZipcodeRanges", "module": "locations", "path": "/locations/getZipcodeRanges", "method": "POST", "summary": "Returns the static list of Mexican zipcode numeric ranges that are present in the catalogue.", "params": [], "response": { "summary": "Array of inclusive [start, end] numeric pairs describing each contiguous block of valid Mexican zipcodes; clients use this to validate a zipcode without round-tripping to the database.", "type": "readonly (readonly [number, number])[]" }, "errors": [], "references": {} }, { "name": "notifications", "module": "notifications", "path": "/notifications/notifications", "method": "POST", "summary": "Returns the authenticated user's notifications, paginated and hydrated with the title/message templates from the static notification type catalogue.", "params": [ { "name": "token", "type": "UserToken", "summary": "Access token of the user whose notifications are being listed.", "required": true }, { "name": "opts", "type": "{ skip?: number; limit?: number }", "summary": "Pagination options. `limit` defaults to 50 and may not exceed 50; `skip` defaults to 0.", "required": false } ], "response": { "summary": "List of hydrated notifications sorted by timestamp descending. Each item merges the notification document with its type metadata and renders the `title` and `message` templates against the notification `data`.", "type": "Promise" }, "errors": [ { "code": "MaxLimitExceeded", "when": "`opts.limit` is greater than 50." } ], "references": { "models": [ "Notification" ] } }, { "name": "notifyRead", "module": "notifications", "path": "/notifications/notifyRead", "method": "POST", "summary": "Marks a single notification owned by the authenticated user as read, stamping the current time on the `read` field.", "params": [ { "name": "notificationId", "type": "string", "summary": "Identifier of the notification to mark as read. Must belong to the authenticated user.", "required": true }, { "name": "token", "type": "UserToken", "summary": "Access token of the notification owner.", "required": true } ], "response": { "summary": "Mongoose `updateOne` result describing whether the notification was found and updated." }, "errors": [], "references": { "models": [ "Notification" ] } }, { "name": "notifySeen", "module": "notifications", "path": "/notifications/notifySeen", "method": "POST", "summary": "Marks every unseen notification belonging to the authenticated user as seen, stamping the current time on the `seen` field.", "params": [ { "name": "token", "type": "UserToken", "summary": "Access token of the user whose notifications should be marked as seen.", "required": true } ], "response": { "summary": "Mongoose `updateMany` result describing how many notifications were touched." }, "errors": [], "references": { "models": [ "Notification" ] } }, { "name": "subscribe", "module": "notifications", "path": "/notifications/subscribe", "method": "POST", "summary": "Registers a realtime session for the authenticated user so that new notifications are pushed through the provided callback.", "params": [ { "name": "sessionId", "type": "string", "summary": "Caller-supplied identifier that uniquely identifies the subscription so it can later be unsubscribed.", "required": true }, { "name": "token", "type": "UserToken", "summary": "Access token of the user that owns the subscription.", "required": true }, { "name": "cb", "type": "SessionCallback", "summary": "Callback invoked every time a notification is emitted to the user.", "required": true } ], "response": { "summary": "Resolves with an empty object once the session is registered.", "type": "Promise<{}>" }, "errors": [], "references": {} }, { "name": "unseenNotifications", "module": "notifications", "path": "/notifications/unseenNotifications", "method": "POST", "summary": "Returns the number of unseen notifications for the authenticated user, capped at 50.", "params": [ { "name": "token", "type": "UserToken", "summary": "Access token of the user whose unseen notifications are being counted.", "required": true } ], "response": { "summary": "Count of unseen notifications, between 0 and 50 inclusive.", "type": "Promise" }, "errors": [], "references": { "models": [ "Notification" ] } }, { "name": "unsubscribe", "module": "notifications", "path": "/notifications/unsubscribe", "method": "POST", "summary": "Removes a previously registered realtime notification session for the authenticated user.", "params": [ { "name": "sessionId", "type": "string", "summary": "Identifier of the session originally passed to `subscribe`.", "required": true }, { "name": "token", "type": "UserToken", "summary": "Access token of the user that owns the session.", "required": true } ], "response": { "summary": "Resolves with an empty object once the session has been removed.", "type": "Promise<{}>" }, "errors": [], "references": {} }, { "name": "unsyncNotifications", "module": "notifications", "path": "/notifications/unsyncNotifications", "method": "POST", "summary": "Drains buffered notifications that accumulated on the user's session while it was disconnected, returning up to 10 pending entries.", "params": [ { "name": "sessionId", "type": "string", "summary": "Identifier of the previously registered session whose buffer should be read.", "required": true }, { "name": "token", "type": "UserToken", "summary": "Access token of the session owner.", "required": true } ], "response": { "summary": "Up to 10 buffered notifications for the session, or an empty array when no session is registered." }, "errors": [], "references": {} }, { "name": "packagingTypeAll", "module": "packaging-type", "path": "/packaging-type/packagingTypeAll", "method": "POST", "summary": "Return the in-memory packaging-type catalogue served by the Catalogues helper.", "params": [], "response": { "summary": "All packaging types loaded by the Catalogues service.", "type": "PackagingType[]" }, "errors": [], "references": { "models": [ "PackagingType" ] } }, { "name": "packagingTypeGet", "module": "packaging-type", "path": "/packaging-type/packagingTypeGet", "method": "POST", "summary": "Look up a packaging type by its catalogue key.", "params": [ { "name": "keyData", "type": "string", "summary": "Catalogue key to look up (PackagingType.key).", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "Matching packaging type, or null when no entry has that key.", "type": "PackagingType | null" }, "errors": [ { "code": "MissingKey", "when": "The keyData argument is empty." }, { "code": "MissingToken", "when": "The token argument is empty." } ], "references": { "models": [ "PackagingType" ] } }, { "name": "packagingTypeGetId", "module": "packaging-type", "path": "/packaging-type/packagingTypeGetId", "method": "POST", "summary": "Look up a packaging type by its Mongo ObjectId.", "params": [ { "name": "key", "type": "string", "summary": "ObjectId of the PackagingType document to retrieve.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "Matching packaging type, or null when the id does not exist.", "type": "PackagingType | null" }, "errors": [ { "code": "MissingKey", "when": "The key argument is empty." }, { "code": "MissingToken", "when": "The token argument is empty." } ], "references": { "models": [ "PackagingType" ] } }, { "name": "truckParks", "module": "places", "path": "/places/truckParks", "method": "POST", "summary": "Find truck parks within a 200 km radius of the supplied geo position. Distance is computed with the Haversine formula against each place's stored latitude and longitude.", "params": [ { "name": "payload", "type": "{ lat: number; lng: number; timestamp?: number; src?: 'dexfreight' }", "summary": "Geo position used as the search center. Latitude and/or longitude must be provided.", "required": true } ], "response": { "summary": "Truck-park documents whose distance from the supplied position is at most 200000 metres.", "type": "Place[]" }, "errors": [ { "code": "MissingCoordinates", "when": "Both `lat` and `lng` are missing or zero on the payload." } ], "references": { "models": [ "Place" ], "interfaces": [ "Geoposition" ] } }, { "name": "getByState", "module": "points", "path": "/Point.getByState", "method": "POST", "summary": "Look up a Point catalogue entry whose `name` field matches the supplied state.", "params": [ { "name": "state", "type": "string", "summary": "State name used to match against Point.name.", "required": true } ], "response": { "summary": "Matching point document, or null when no point has that name.", "type": "Point | null" }, "errors": [], "references": { "models": [ "Point" ] } }, { "name": "getByState", "module": "points", "path": "/points/getByState", "method": "POST", "summary": "Returns the geographic point document matching the given state name.", "params": [ { "name": "state", "type": "string", "summary": "Name of the state used to look up the matching point.", "required": true } ], "response": { "summary": "The Point document matching the state name, or null if not found.", "type": "Promise" }, "errors": [ { "code": "MissingState", "when": "The `state` argument is missing or not a string." } ], "references": { "models": [ "Point" ] } }, { "name": "findAllCPaymentMethod", "module": "select-combo", "path": "/SelectCombo.findAllCPaymentMethod", "method": "POST", "summary": "Return the full payment-method catalogue used to populate combo boxes.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "All CPaymentMethod catalogue entries.", "type": "CPaymentMethod[]" }, "errors": [], "references": { "models": [ "CPaymentMethod" ] } }, { "name": "findAllCWayToPay", "module": "select-combo", "path": "/SelectCombo.findAllCWayToPay", "method": "POST", "summary": "Return the full way-to-pay catalogue used to populate combo boxes.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "All CWayToPay catalogue entries.", "type": "CWayToPay[]" }, "errors": [], "references": { "models": [ "CWayToPay" ] } }, { "name": "findAllDocumentAduanero", "module": "select-combo", "path": "/SelectCombo.findAllDocumentAduanero", "method": "POST", "summary": "Return the full customs-document (Documento Aduanero) catalogue used to populate combo boxes.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "All DocumentAduanero catalogue entries.", "type": "DocumentAduanero[]" }, "errors": [], "references": { "models": [ "DocumentAduanero" ] } }, { "name": "findAllTypeMatter", "module": "select-combo", "path": "/SelectCombo.findAllTypeMatter", "method": "POST", "summary": "Return the full type-of-matter catalogue used to populate combo boxes.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "All typeMatter catalogue entries.", "type": "typeMatter[]" }, "errors": [], "references": { "models": [ "typeMatter" ] } }, { "name": "findAllVoucherType", "module": "select-combo", "path": "/SelectCombo.findAllVoucherType", "method": "POST", "summary": "Return the full voucher-type catalogue used to populate combo boxes.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "All VoucherType catalogue entries.", "type": "VoucherType[]" }, "errors": [], "references": { "models": [ "VoucherType" ] } }, { "name": "notifyContainerDeparture", "module": "smart-port", "path": "/smart-port/notifyContainerDeparture", "method": "POST", "summary": "Stub endpoint that acknowledges a Smartport container-departure notification with a fixed httpOk envelope. No persistence or side-effects.", "params": [], "response": { "summary": "httpOk('Successfully notified container departure').", "type": "ReturnType" }, "errors": [], "references": {} }, { "name": "notifyRelease", "module": "smart-port", "path": "/smart-port/notifyRelease", "method": "POST", "summary": "Smartport integration entrypoint that records every container released for the authenticated company, maps its container type, persists CustomerPortalContainer rows in `Pending` status and emails each customs agent an invitation-token link to the customer portal.", "params": [ { "name": "releases", "type": "SmartPortRelease['releases']", "summary": "Smartport release batch — each release contains a transaction (customs agent, patent, document) and its associated containers.", "required": true }, { "name": "terminalCustomer", "type": "SmartPortRelease['terminalCustomer']", "summary": "Terminal-side customer metadata attached to the release batch.", "required": true }, { "name": "token", "type": "string", "summary": "User session token used to resolve the calling user via getTokenUser.", "required": true } ], "response": { "summary": "{ success: true, message: 'Registro guardado exitosamente', containers: ObjectId[] } — in local context, also returns the generated invitation `tokens` for each customs agent email.", "type": "Promise<{ success: boolean; message: string; containers: ObjectId[]; tokens?: string[] }>" }, "errors": [], "references": { "models": [ "CustomerPortalContainer" ], "enums": [ "CustomerPortalContainerStatus", "PortalContainerServiceType" ], "types": [ "SmartPortRelease" ] } }, { "name": "resendReleaseEmail", "module": "smart-port", "path": "/smart-port/resendReleaseEmail", "method": "POST", "summary": "Authorize a new customs agent on a list of existing Smartport CustomerPortalContainers (after verifying the caller is already an allowed customer on each) and resend the release-notification email with a fresh invitation token.", "params": [ { "name": "customsAgent", "type": "SmartPortRelease['releases'][0]['transaction']['customsAgent']", "summary": "Customs agent to authorize on the listed containers and to receive the resent release email.", "required": true }, { "name": "token", "type": "string", "summary": "User session token used to resolve the calling user via getTokenUser.", "required": true }, { "name": "ids", "type": "string[]", "summary": "CustomerPortalContainer ids whose allowed-customers list should be extended with `customsAgent.email`.", "required": true } ], "response": { "summary": "{ success: true, message: 'Successfully resent email to: ' } once the email send is dispatched.", "type": "Promise<{ success: boolean; message: string }>" }, "errors": [ { "code": "UnauthorizedUser", "when": "The authenticated user's email is not present in `allowedCustomers` for one of the requested containers." } ], "references": { "models": [ "CustomerPortalContainer" ], "types": [ "SmartPortRelease" ] } }, { "name": "getMaintenanceStatus", "module": "status-setting", "path": "/status-setting/getMaintenanceStatus", "method": "POST", "summary": "Return the current global maintenance flag stored on GlobalSettings.", "params": [], "response": { "summary": "Current value of GlobalSettings.maintenance.", "type": "boolean" }, "errors": [], "references": { "models": [ "GlobalSettings" ] } }, { "name": "updateGlobalSetting", "module": "status-setting", "path": "/status-setting/updateGlobalSetting", "method": "POST", "summary": "Update the global maintenance flag on GlobalSettings. Restricted to admins holding the `Function.updateGlobalSetting` access permission.", "params": [ { "name": "maintenanceData", "type": "boolean", "summary": "New value for GlobalSettings.maintenance.", "required": true }, { "name": "token", "type": "string", "summary": "Admin session token. The caller must hold the `Function.updateGlobalSetting` access permission.", "required": true } ], "response": { "summary": "Updated GlobalSettings document.", "type": "GlobalSettings" }, "errors": [], "references": { "models": [ "GlobalSettings" ] } }, { "name": "createTemplate", "module": "templates", "path": "/templates/createTemplate", "method": "POST", "summary": "Create a new role-scoped template entry for a company. The created record is set active by default.", "params": [ { "name": "payload", "type": "{ role: string; nameTemplate: string; companyId: string }", "summary": "Template definition. `role` is the role the template applies to, `nameTemplate` is the human-readable label, `companyId` is the owning company.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "The newly created template document.", "type": "Templates" }, "errors": [], "references": { "models": [ "Templates" ] } }, { "name": "deleteTemplate", "module": "templates", "path": "/templates/deleteTemplate", "method": "POST", "summary": "Delete a template identified by its name and owning company.", "params": [ { "name": "payload", "type": "{ nameTemplate: string; companyId: string }", "summary": "Locator describing which template to delete.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "Mongoose deleteOne result for the removed template.", "type": "{ acknowledged: boolean; deletedCount: number }" }, "errors": [ { "code": "Template not found.", "when": "No template exists for the supplied nameTemplate and companyId combination." } ], "references": { "models": [ "Templates" ] } }, { "name": "getCategory", "module": "templates", "path": "/templates/getCategory", "method": "POST", "summary": "List the template categories that apply to the calling user's role together with an `active` flag indicating whether the user's company has any active template within each category.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "Categories matching the caller's role with their description and current active state for the company.", "type": "Array<{ categoryId: string; category: string; description: string; active: boolean }>" }, "errors": [], "references": { "models": [ "Category", "Templates" ] } }, { "name": "getTemplate", "module": "templates", "path": "/templates/getTemplate", "method": "POST", "summary": "Get the first template registered for the given company.", "params": [ { "name": "companyId", "type": "string", "summary": "Company identifier whose template will be returned.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "Matching template document, or null if the company has none.", "type": "Templates | null" }, "errors": [], "references": { "models": [ "Templates" ] } }, { "name": "updateAndCreateTemplate", "module": "templates", "path": "/templates/updateAndCreateTemplate", "method": "POST", "summary": "Toggle the active flag of templates linked to a category for a company. If templates already exist for the company/category pair they are updated in bulk; otherwise new templates are created from the matching category-template definitions.", "params": [ { "name": "payload", "type": "{ role: string; active: boolean; category: string; companyId: string }", "summary": "Update payload. `category` is the CategoryTemplate identifier, `active` is the desired state, `companyId` is the owning company, `role` is applied when new templates are created.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "Mongoose update or insert result for the affected templates.", "type": "object" }, "errors": [], "references": { "models": [ "Templates", "CategoryTemplate", "Category" ] } }, { "name": "branixDevices", "module": "tracking", "path": "/tracking/branixDevices", "method": "POST", "summary": "Lists the GPS devices registered with Branix for the caller's carrier company under the given GPS provider.", "params": [ { "name": "gpsProvider", "type": "GPSProviderName", "summary": "GPS provider whose Branix-managed devices should be listed.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "List of GPS devices linked to the carrier company through Branix for the requested provider." }, "errors": [ { "code": "GPS_ONLY_ALLOWED_FOR_CARRIER", "when": "The caller's company role is not 'carrier'." } ], "references": { "enums": [ "GPSProviderName" ] } }, { "name": "generateDrayageTrackingLink", "module": "tracking", "path": "/tracking/generateDrayageTrackingLink", "method": "POST", "summary": "Builds a signed public tracking URL for a drayage shipment so the caller can share live location (or full shipment details) with third parties.", "params": [ { "name": "drayageId", "type": "string", "summary": "Mongo ObjectId of the drayage to be tracked.", "required": true }, { "name": "token", "type": "UserToken", "summary": "User session token returned by /auth/login", "required": true }, { "name": "sendShipmentDetails", "type": "boolean", "summary": "When true, the URL points to the full shipment-details view; otherwise it points to the public tracking-only view.", "required": false } ], "response": { "summary": "A fully qualified URL containing a signed JWT trackingToken that grants drayage-view access.", "type": "string" }, "errors": [ { "code": "AssertionError", "when": "The drayage referenced by drayageId does not exist." }, { "code": "AssertionError", "when": "The caller's company is neither the shipper nor the carrier on the drayage." } ], "references": { "models": [ "Drayage" ] } }, { "name": "getDrayageLocationHistory", "module": "tracking", "path": "/tracking/getDrayageLocationHistory", "method": "POST", "summary": "Returns the full position history for a drayage owned by the caller, optionally restricted to records created after a given position id.", "params": [ { "name": "drayageId", "type": "string", "summary": "Identifier of the drayage whose position history is requested.", "required": true }, { "name": "token", "type": "UserToken", "summary": "User session token returned by /auth/login", "required": true }, { "name": "lastPositionId", "type": "string", "summary": "When provided, only positions with an _id greater than this value are returned.", "required": false } ], "response": { "summary": "Position records for the drayage, sorted by _id descending." }, "errors": [ { "code": "ValidationError", "when": "Either `drayageId` or `token` is missing or not a string." }, { "code": "USER_UNAUTHORIZED_OVER_DRAYAGE", "when": "The caller is not an owner of the drayage (operation: 'Obtener historial de posiciones')." } ], "references": { "models": [ "Positions" ] } }, { "name": "gpsProviders", "module": "tracking", "path": "/tracking/gpsProviders", "method": "POST", "summary": "Lists the GPS providers configured for the caller's carrier company.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Collection of GPS provider configurations associated with the carrier company." }, "errors": [ { "code": "GPS_ONLY_ALLOWED_FOR_CARRIER", "when": "The caller's company role is not 'carrier'." } ] }, { "name": "lastDrayageLocation", "module": "tracking", "path": "/tracking/lastDrayageLocation", "method": "GET", "summary": "Returns the most recent persisted Position document for a drayage owned by the caller.", "params": [ { "name": "drayageId", "type": "ID", "summary": "Identifier of the drayage whose latest position is requested.", "required": true }, { "name": "token", "type": "UserToken", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "The newest Position record stored for the drayage, or null if none exists.", "type": "Position" }, "errors": [ { "code": "ValidationError", "when": "Either `drayageId` or `token` is missing or not a string." }, { "code": "USER_UNAUTHORIZED_OVER_DRAYAGE", "when": "The caller is not an owner of the drayage (operation: 'Obtener última posición')." } ], "references": { "models": [ "Positions" ], "interfaces": [ "Position" ] } }, { "name": "notifyLocation", "module": "tracking", "path": "/tracking/notifyLocation", "method": "POST", "summary": "Buffers a driver geoposition update under the caller's session token; queued positions are flushed every 20 seconds to the realtime tracking microservice.", "params": [ { "name": "position", "type": "Geoposition", "summary": "Latitude/longitude reading captured by the driver app, including any auxiliary fields defined by the Geoposition interface.", "required": true }, { "name": "token", "type": "UserToken", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "No return value; the position is appended to an in-memory queue keyed by the caller's token." }, "errors": [], "references": { "interfaces": [ "Geoposition" ] } }, { "name": "notifyLocationV2", "module": "tracking", "path": "/tracking/notifyLocationV2", "method": "POST", "summary": "Accepts a raw mobile geolocation payload (coords + timestamp), normalises it into a Geoposition shape tagged with the dexfreight source, and forwards it to notifyLocation.", "params": [ { "name": "location", "type": "any", "summary": "Raw geolocation object emitted by the device, expected to expose `coords.latitude`, `coords.longitude` and `timestamp`.", "required": true }, { "name": "token", "type": "UserToken", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Result returned by the underlying notifyLocation call (no value)." }, "errors": [] }, { "name": "registerInBranix", "module": "tracking", "path": "/tracking/registerInBranix", "method": "POST", "summary": "Registers the caller's carrier company with Branix using the supplied display name and validation key, enabling Branix-backed GPS tracking.", "params": [ { "name": "name", "type": "string", "summary": "Display name to register for the company in Branix.", "required": true }, { "name": "validationKey", "type": "string", "summary": "Validation key issued by Branix that authorises the registration.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Standard httpOk envelope confirming the company was registered in Branix." }, "errors": [ { "code": "ValidationError", "when": "Any of `name`, `validationKey` or `token` is missing or not a string." }, { "code": "GPS_ONLY_ALLOWED_FOR_CARRIER", "when": "The caller's company role is not 'carrier'." } ] }, { "name": "sendDrayageTrackingLinkEmail", "module": "tracking", "path": "/tracking/sendDrayageTrackingLinkEmail", "method": "POST", "summary": "Generates a signed public tracking link for a drayage and emails it (in English or Spanish, depending on the company's language setting) to the supplied recipients via a Mailgun template.", "params": [ { "name": "drayageId", "type": "string", "summary": "Mongo ObjectId of the drayage whose tracking link will be shared.", "required": true }, { "name": "emails", "type": "string[]", "summary": "List of email addresses that will receive the tracking-link email.", "required": true }, { "name": "token", "type": "UserToken", "summary": "User session token returned by /auth/login", "required": true }, { "name": "sendShipmentDetails", "type": "boolean", "summary": "When true, the URL points to the full shipment-details view; otherwise it points to the public tracking-only view.", "required": false } ], "response": { "summary": "The same tracking URL that was emailed to the recipients.", "type": "string" }, "errors": [ { "code": "AssertionError", "when": "The drayage referenced by drayageId does not exist." }, { "code": "AssertionError", "when": "The caller's company is neither the shipper nor the carrier on the drayage." } ], "references": { "models": [ "Drayage", "Company" ] } }, { "name": "simulateRoute", "module": "tracking", "path": "/tracking/simulateRoute", "method": "POST", "summary": "Development-only helper that starts a TrackingSimulator emitting synthetic positions along the drayage route so the carrier can test the live-tracking pipeline.", "params": [ { "name": "drayageId", "type": "string", "summary": "Identifier of the drayage whose route will be simulated.", "required": true }, { "name": "token", "type": "UserToken", "summary": "User session token returned by /auth/login", "required": true } ], "response": { "summary": "Standard httpOk envelope confirming the simulation has started for the drayage." }, "errors": [ { "code": "ValidationError", "when": "Either `drayageId` or `token` is missing or not a string." }, { "code": "UNAUTHORIZED", "when": "The server is not running in a development context." }, { "code": "USER_UNAUTHORIZED_OVER_DRAYAGE", "when": "The caller is not the carrier on the drayage (operation: 'Simular ruta')." } ] }, { "name": "truckParks", "module": "places", "path": "/TruckPark.Place.truckParks", "method": "POST", "summary": "Find truck parks within a 200 km radius of the supplied geo position. Distance is computed with the Haversine formula against each place's stored latitude and longitude.", "params": [ { "name": "payload", "type": "{ lat: number; lng: number }", "summary": "Geo position used as the search center. Latitude and/or longitude must be provided.", "required": true } ], "response": { "summary": "Truck-park documents whose distance from the supplied position is at most 200000 metres.", "type": "Place[]" }, "errors": [ { "code": "Latitude or length are required", "when": "Both `lat` and `lng` are missing or zero on the payload." }, { "code": "No information was found", "when": "The places collection returned no documents." } ], "references": { "models": [ "Place" ], "interfaces": [ "Geoposition" ] } }, { "name": "acceptCustomerInvitation", "module": "user", "path": "/user/acceptCustomerInvitation", "method": "POST", "summary": "Admin-only endpoint that accepts a pending Customer invitation: generates a random initial password, provisions a new admin User and Company for the invited shipper, marks the Customer record as confirmed and sends a localized welcome email containing the credentials. Notifies the broker company that the invitation was accepted via the realtime microservice.", "params": [ { "name": "customerData", "type": "AcceptCustomerInvitation", "summary": "Payload identifying the Customer invitation being accepted.", "required": true }, { "name": "token", "type": "AdminToken", "summary": "Admin session token; the call requires the caller to satisfy the isAdmin validation.", "required": true } ], "response": { "summary": "Returns true once the user, company, customer confirmation and welcome email have all been processed." }, "errors": [ { "code": "AssertionFailed", "when": "The Customer invitation referenced by customerId could not be found, or the email on the invitation is already registered to an existing User." } ], "references": { "models": [ "Customer", "Company", "User" ], "interfaces": [ "AcceptCustomerInvitation" ] } }, { "name": "createCustomer", "module": "user", "path": "/user/createCustomer", "method": "POST", "summary": "Creates a pending Customer invitation for a shipper from the caller's broker company, generates accept/decline JWT tokens and emails the invitation using a Mailgun template localized by the broker's company language setting.", "params": [ { "name": "data", "type": "CreateCustomer", "summary": "Invitation payload containing the customer company name, contact email, address and other details captured by the broker.", "required": true }, { "name": "token", "type": "string", "summary": "User session token of the broker creating the invitation; used to resolve the broker company.", "required": true } ], "response": { "summary": "The newly created Customer document representing the pending invitation linked to the broker company." }, "errors": [ { "code": "AssertionFailed", "when": "A Customer record already exists for the same broker company and email, meaning there is a pending or active invitation for that customer." } ], "references": { "models": [ "Customer", "Company", "User" ], "interfaces": [ "CreateCustomer" ] } }, { "name": "deleteCustomer", "module": "user", "path": "/user/deleteCustomer", "method": "POST", "summary": "Soft-deletes a Customer invitation by setting its disabled flag, after verifying that the caller's company is the broker that owns the Customer record.", "params": [ { "name": "customerId", "type": "string", "summary": "ObjectId of the Customer record to disable.", "required": true }, { "name": "token", "type": "string", "summary": "User session token of the broker performing the deletion; used to verify ownership.", "required": true } ], "response": { "summary": "The Customer document fetched before the disable flag was applied." }, "errors": [ { "code": "AssertionFailed", "when": "The Customer record does not exist or the authenticated user's company is not the broker that owns it." } ], "references": { "models": [ "Customer" ] } }, { "name": "editCustomer", "module": "user", "path": "/user/editCustomer", "method": "POST", "summary": "Updates a Customer invitation owned by the caller's broker company. When the customer has already accepted the invitation, propagates the new contact and address details to the linked User and Company documents (profile, identity, billing info).", "params": [ { "name": "customerId", "type": "string", "summary": "ObjectId of the Customer record to update.", "required": true }, { "name": "data", "type": "CreateCustomer", "summary": "Updated customer details (company name, email, address, phone) replacing the previous invitation data.", "required": true }, { "name": "token", "type": "string", "summary": "User session token of the broker performing the edit; used to verify ownership of the customer record.", "required": true } ], "response": { "summary": "The Customer document as it was before the update was applied (the in-memory copy fetched at the start of the call)." }, "errors": [ { "code": "AssertionFailed", "when": "The authenticated user's company is not the broker that owns the targeted Customer record." } ], "references": { "models": [ "Customer", "Company", "User" ], "interfaces": [ "CreateCustomer" ] } }, { "name": "create", "module": "vehicle", "path": "/vehicle/create", "method": "POST", "summary": "Register a new vehicle for the caller's company. When a GPS provider is supplied the device is also registered with the external tracking provider; if registration fails the vehicle row is rolled back.", "params": [ { "name": "vehicle", "type": "{ type: string; year: string; plate: string; weight?: string; remolques?: Array<{ subType: string; plate: string }>; gpsProvider?: string; gpsReference?: string }", "summary": "Vehicle definition. `plate` is normalized through the Plate value object. `weight` defaults to '40' when omitted. When `gpsProvider` is set the matching `gpsReference` must be one of the provider's available references.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "The newly created vehicle document.", "type": "Vehicle" }, "errors": [ { "code": "INVALID_GPS_REFERENCE", "when": "A gpsProvider was supplied without a gpsReference, or the supplied gpsReference is not in the provider's available references list." }, { "code": "INVALID_GPS_PROVIDER", "when": "The supplied gpsProvider is not configured for the caller's company." } ], "references": { "models": [ "Vehicle" ], "valueObjects": [ "Plate" ], "enums": [ "GPSProviderName" ] } }, { "name": "get", "module": "vehicle", "path": "/vehicle/get", "method": "POST", "summary": "Get a single vehicle owned by the caller's company by id.", "params": [ { "name": "vehicleId", "type": "string", "summary": "ObjectId of the vehicle to retrieve.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "The matching vehicle document.", "type": "Vehicle" }, "errors": [ { "code": "VEHICLE_NOT_FOUND", "when": "No vehicle exists with the supplied id under the caller's company." } ], "references": { "models": [ "Vehicle" ] } }, { "name": "getAll", "module": "vehicle", "path": "/vehicle/getAll", "method": "POST", "summary": "List every vehicle registered under the caller's company.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "Array of vehicle documents belonging to the caller's company.", "type": "Vehicle[]" }, "errors": [], "references": { "models": [ "Vehicle" ] } }, { "name": "getAllSubTipoRem", "module": "vehicle", "path": "/vehicle/getAllSubTipoRem", "method": "POST", "summary": "Return the trailer subtype catalogue used when registering vehicles with trailers.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "All SubTipoRem catalogue entries.", "type": "SubTipoRem[]" }, "errors": [], "references": { "models": [ "SubTipoRem" ] } }, { "name": "getDrayageVehicle", "module": "vehicle", "path": "/vehicle/getDrayageVehicle", "method": "POST", "summary": "Get the vehicle currently assigned to a drayage. Only callers who own the drayage may use this endpoint.", "params": [ { "name": "drayageId", "type": "string", "summary": "ObjectId of the drayage whose vehicle is being requested.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "Vehicle document assigned to the drayage, or null when the drayage has no vehicle.", "type": "Vehicle | null" }, "errors": [ { "code": "USER_UNAUTHORIZED_OVER_DRAYAGE", "when": "The caller is not the owner of the drayage referenced by drayageId." } ], "references": { "models": [ "Drayage", "Vehicle" ] } }, { "name": "getPermissionType", "module": "vehicle", "path": "/vehicle/getPermissionType", "method": "POST", "summary": "Return the catalogue of vehicle permission types.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "All PermissionType catalogue entries.", "type": "PermissionType[]" }, "errors": [], "references": { "models": [ "PermissionType" ] } }, { "name": "getTotalVehiclesByCarrier", "module": "vehicle", "path": "/vehicle/getTotalVehiclesByCarrier", "method": "POST", "summary": "Count the number of vehicles registered under the caller's company.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "Total vehicles registered for the caller's company.", "type": "number" }, "errors": [], "references": { "models": [ "Vehicle" ] } }, { "name": "remove", "module": "vehicle", "path": "/vehicle/remove", "method": "POST", "summary": "Delete a vehicle owned by the caller's company. If the vehicle has an associated GPS provider/reference, the device is unregistered from the external tracking provider before deletion.", "params": [ { "name": "vehicleId", "type": "string", "summary": "ObjectId of the vehicle to remove.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "Standard ok envelope with the message 'Successfully delete vehicle'.", "type": "{ ok: true; message: string }" }, "errors": [ { "code": "VEHICLE_NOT_FOUND", "when": "No vehicle exists with the supplied id, or the vehicle does not belong to the caller's company." } ], "references": { "models": [ "Vehicle" ] } }, { "name": "selectVehicle", "module": "vehicle", "path": "/vehicle/selectVehicle", "method": "POST", "summary": "Return the auto-transport configuration catalogue used to populate vehicle selection drop-downs.", "params": [ { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "All CConfigAutoTransport catalogue entries.", "type": "CConfigAutoTransport[]" }, "errors": [], "references": { "models": [ "CConfigAutoTransport" ] } }, { "name": "update", "module": "vehicle", "path": "/vehicle/update", "method": "POST", "summary": "Update a vehicle owned by the caller's company. When the GPS provider or reference changes, unregisters the previous device and registers the new one with the external tracking provider before persisting the change.", "params": [ { "name": "vehicleId", "type": "string", "summary": "ObjectId of the vehicle to update.", "required": true }, { "name": "vehicle", "type": "Partial<{ type: string; year: string; plate: string; weight: string; remolques: Array<{ subType: string; plate: string }>; gpsProvider: string; gpsReference: string }>", "summary": "Partial update payload. `plate` and trailer plates are normalized through the Plate value object. When `gpsProvider` changes the new `gpsReference` must be valid for the provider.", "required": true }, { "name": "token", "type": "string", "summary": "User session token returned by /auth/login.", "required": true } ], "response": { "summary": "Standard ok envelope with the message 'Successfully updated vehicle'.", "type": "{ ok: true; message: string }" }, "errors": [ { "code": "VEHICLE_NOT_FOUND", "when": "No vehicle exists with the supplied id, or the vehicle does not belong to the caller's company." }, { "code": "INVALID_GPS_REFERENCE", "when": "A new gpsProvider was supplied without a gpsReference, or the supplied gpsReference is not in the provider's available references list." }, { "code": "INVALID_GPS_PROVIDER", "when": "The supplied gpsProvider is not configured for the caller's company." } ], "references": { "models": [ "Vehicle", "Drayage" ], "valueObjects": [ "Plate" ], "enums": [ "GPSProviderName" ] } } ], "models": [ { "name": "BrokerEmail", "module": "_common", "summary": "Mexico broker email subscription flag controlling whether the broker receives Mexico Carta Porte / CFDI document emails.", "collection": "brokeremails", "fields": [ { "name": "brokerId", "type": "ObjectId", "summary": "Identifier of the broker user this email subscription belongs to.", "required": true }, { "name": "active", "type": "boolean", "summary": "Whether the broker is currently opted-in to receive Mexico-related email notifications." } ], "relations": [ { "field": "brokerId", "target": "Broker", "kind": "one-to-one" } ], "restrictions": [] }, { "name": "CachedTripDistance", "module": "_common", "summary": "Cached origin-destination distance and travel-time response from the routing/maps provider, used to avoid recomputing the same trip metrics.", "collection": "cachedtripdistances", "fields": [ { "name": "origin", "type": "string", "summary": "Encoded origin location (typically a place id, lat/lng pair, or address string)." }, { "name": "destination", "type": "string", "summary": "Encoded destination location." }, { "name": "distance", "type": "number", "summary": "Distance between origin and destination in the provider's native unit (meters/miles).", "required": true }, { "name": "trafficTime", "type": "number", "summary": "Travel time including current/typical traffic conditions, in seconds.", "required": true }, { "name": "baseTime", "type": "number", "summary": "Travel time assuming no traffic, in seconds.", "required": true }, { "name": "text", "type": "string", "summary": "Human-readable distance string returned by the provider (e.g. '125 mi').", "required": true }, { "name": "travelTime", "type": "number", "summary": "Provider-reported expected travel time used as the canonical estimate, in seconds.", "required": true } ], "restrictions": [] }, { "name": "CarrierEmail", "module": "_common", "summary": "Mexico carrier email subscription flag controlling whether the carrier receives Mexico Carta Porte / CFDI document emails.", "collection": "carrieremails", "fields": [ { "name": "carrierId", "type": "ObjectId", "summary": "Identifier of the carrier user this email subscription belongs to.", "required": true }, { "name": "active", "type": "boolean", "summary": "Whether the carrier is currently opted-in to receive Mexico-related email notifications." } ], "relations": [ { "field": "carrierId", "target": "Carrier", "kind": "one-to-one" } ], "restrictions": [] }, { "name": "CarrierRelationMx", "module": "_common", "summary": "Mapping between a Dexcarga carrier user and its counterpart inside the Mexican PAC (CFDI/Carta Porte stamping provider). The same source file also exports RelationPdfXmlCartaPorteMx, which links a drayage to the generated PDF/XML Carta Porte documents.", "collection": "carrierrelationmxes", "fields": [ { "name": "idCarrierPac", "type": "string", "summary": "Carrier identifier assigned by the PAC (Mexican stamping provider)." }, { "name": "idCarrierDex", "type": "ObjectId", "summary": "Identifier of the Dexcarga Carrier user this mapping refers to." }, { "name": "email", "type": "string", "summary": "Email address registered with the PAC for this carrier." }, { "name": "rfc", "type": "string", "summary": "RFC (Mexican taxpayer ID) of the carrier." } ], "relations": [ { "field": "idCarrierDex", "target": "Carrier", "kind": "one-to-one" } ], "restrictions": [] }, { "name": "Category", "module": "catalogue", "summary": "Generic named category with a description and a role tag, used to group templates and other catalogue entries.", "fields": [ { "name": "name", "type": "string", "summary": "Display name of the category.", "required": true }, { "name": "description", "type": "string", "summary": "Free-text description of the category.", "required": true }, { "name": "role", "type": "string", "summary": "Role tag classifying the category (e.g. for permissions or template scoping).", "required": true } ], "restrictions": [] }, { "name": "CategoryTemplate", "module": "catalogue", "summary": "Template content (e.g. document or message body) associated with a category.", "fields": [ { "name": "categoryId", "type": "ObjectId", "summary": "Reference to the owning Category document.", "required": true }, { "name": "template", "type": "string", "summary": "Template body associated with the category.", "required": true } ], "relations": [ { "field": "categoryId", "target": "Category", "kind": "one-to-one", "summary": "Links the template to its Category." } ], "restrictions": [] }, { "name": "CKeyProductService", "module": "catalogue", "summary": "Aggregated catalogue file containing many SAT/CFDI reference catalogues used across CFDI 4.0 and Carta Porte; the most prominent is CKeyProductService, the SAT product/service key catalogue, while sibling classes hold units, materials, locations, postal codes, fiscal regimes, customs and transport reference data.", "fields": [ { "name": "keyProdServ", "type": "number", "summary": "SAT product or service key (ClaveProdServ).", "required": false }, { "name": "description", "type": "string", "summary": "Long description for the product or service key.", "required": false }, { "name": "name", "type": "string", "summary": "Short name of the product or service key.", "constraints": [ "indexed" ], "required": false }, { "name": "nameTradu", "type": "string", "summary": "Translated name of the product or service key.", "required": false } ], "indexes": [ { "keys": "name", "summary": "Lookup by short name." } ], "relations": [ { "field": "_companion_KeyUnits", "target": "KeyUnits", "kind": "embedded", "summary": "Sibling catalogue of measurement units (keyUnit unique-indexed)." }, { "field": "_companion_KeyProduct", "target": "KeyProduct", "kind": "embedded", "summary": "Sibling catalogue of product keys with dangerous-material flag." }, { "field": "_companion_KeyMaterial", "target": "KeyMaterial", "kind": "embedded", "summary": "Sibling catalogue of hazardous material keys." }, { "field": "_companion_Ccolonia", "target": "Ccolonia", "kind": "embedded", "summary": "Settlement (colonia) catalogue: cColonia, zipCode, settlementName." }, { "field": "_companion_Clocation", "target": "Clocation", "kind": "embedded", "summary": "Locality catalogue: location, estate, description." }, { "field": "_companion_Cmunicipality", "target": "Cmunicipality", "kind": "embedded", "summary": "Municipality catalogue with indexed description." }, { "field": "_companion_CState", "target": "CState", "kind": "embedded", "summary": "State catalogue: estate, country, nameEstate." }, { "field": "_companion_CPostalColonia", "target": "CPostalColonia", "kind": "embedded", "summary": "Postal-code → state/municipality/locality catalogue, indexed by zipCode." }, { "field": "_companion_CFiscalRegime", "target": "CFiscalRegime", "kind": "embedded", "summary": "SAT fiscal regime catalogue." }, { "field": "_companion_CSeasons", "target": "CSeasons", "kind": "embedded", "summary": "Seasonal/transport keys catalogue." }, { "field": "_companion_CCveTransport", "target": "CCveTransport", "kind": "embedded", "summary": "Transport key (ClaveTransporte) catalogue." }, { "field": "_companion_CConfigAutoTransport", "target": "CConfigAutoTransport", "kind": "embedded", "summary": "Auto-transport configuration catalogue with axes/tires/trailer info." }, { "field": "_companion_CFigureTransport", "target": "CFigureTransport", "kind": "embedded", "summary": "Transport figure (figura del transporte) catalogue." }, { "field": "_companion_CCountry", "target": "CCountry", "kind": "embedded", "summary": "SAT country catalogue." }, { "field": "_companion_CUsoCfdi", "target": "CUsoCfdi", "kind": "embedded", "summary": "CFDI use catalogue (UsoCFDI)." }, { "field": "_companion_Caduana", "target": "Caduana", "kind": "embedded", "summary": "Customs (aduana) catalogue." }, { "field": "_companion_CpatentAduanal", "target": "CpatentAduanal", "kind": "embedded", "summary": "Customs patent catalogue." }, { "field": "_companion_CpetitionAduana", "target": "CpetitionAduana", "kind": "embedded", "summary": "Customs petition catalogue (aduana, patent, exercise, quantity)." }, { "field": "_companion_ValidatorCartaPorte", "target": "ValidatorCartaPorte", "kind": "embedded", "summary": "Carta Porte validation tracking record (drayageId, userId, url, pdf, sendM, percentage)." }, { "field": "_companion_Cpais", "target": "Cpais", "kind": "embedded", "summary": "Country key catalogue." } ], "restrictions": [] }, { "name": "ClassMx", "module": "geography", "summary": "Mexican classification entry pairing a class type with a display name (used for Mexican reference data).", "fields": [ { "name": "type", "type": "string", "summary": "Classification type code.", "required": false }, { "name": "name", "type": "string", "summary": "Human-readable name of the classification.", "required": false } ], "restrictions": [] }, { "name": "CodeCountry", "module": "geography", "summary": "International phone calling-code catalogue with country name and flag image variants.", "fields": [ { "name": "callingCode", "type": "string", "summary": "International telephone calling code (e.g. \"+52\").", "required": true }, { "name": "name", "type": "string", "summary": "Country name.", "required": true }, { "name": "flag", "type": "{ small: string, medium: string, large: string }", "summary": "URLs for the country flag in three sizes.", "required": false } ], "restrictions": [] }, { "name": "Colonia", "module": "geography", "summary": "Mexican settlement (colonia) entry mapping a colonia code and zip code to the settlement name.", "fields": [ { "name": "cColonia", "type": "string", "summary": "SAT colonia code.", "required": false }, { "name": "zipCode", "type": "string", "summary": "Mexican postal (CP) code that contains the colonia.", "required": false }, { "name": "settlementName", "type": "string", "summary": "Display name of the settlement / colonia.", "required": false } ], "restrictions": [] }, { "name": "CommunicationEvent", "module": "events", "summary": "Outbound communication event sent to a user. Captures the channel (sms, email or in-app notification), the payload, the lifecycle status and a per-status history. Used to track delivery state of transactional messages.", "fields": [ { "name": "id", "type": "string", "summary": "External provider identifier for the event (e.g. Mailgun message id).", "required": false }, { "name": "type", "type": "CommunicationEventType", "summary": "Channel of the event: 'sms', 'email' or 'notification'.", "required": true }, { "name": "eventName", "type": "string", "summary": "Logical name of the event (e.g. 'shipment-delivered', 'invoice-ready').", "required": true }, { "name": "eventHistory", "type": "CommunicationEventHistory[]", "summary": "Append-only log of (status, time) entries as the event progresses through provider states.", "constraints": [ "default: []" ], "required": false }, { "name": "status", "type": "EmailStatus | SMSStatus", "summary": "Current status reported by the delivery provider.", "required": true }, { "name": "data", "type": "SMSData | EmailData | NotificationData", "summary": "Channel-specific payload: SMSData (target phone, body), EmailData (template, target, subject, data, url) or NotificationData (notificationId).", "required": true }, { "name": "shipmentId", "type": "ObjectId", "summary": "Optional reference to the shipment/drayage that triggered the event.", "required": false }, { "name": "createdAt", "type": "Date", "summary": "Timestamp when the event was created.", "required": true } ], "relations": [ { "field": "shipmentId", "target": "Drayage", "kind": "one-to-one", "summary": "Shipment/drayage that originated the communication, when applicable." } ], "restrictions": [] }, { "name": "Company", "module": "companies", "summary": "A tenant company on the platform, holding identity, fiscal billing details, operational details (DOT/MC numbers, addresses, Mexican fiscal info), governance terms, payment configuration, role and integration metadata. The companies.ts file also exports sibling models Settings (per-company operational settings), EntityCSD (Mexican CSD certificates), and PendingCompany (signup placeholder mirroring Company).", "fields": [ { "name": "lastActivity", "type": "Date", "summary": "Timestamp of the company's most recent activity on the platform.", "required": false }, { "name": "paymentInfo", "type": "{ methods: any[]; responsibles: any[]; controller: { dateOfBirth: Date }; default: string; status: string }", "summary": "Payment configuration including registered methods, responsible parties, controlling officer details, the default method and the overall payment status.", "required": false }, { "name": "governanceTerms", "type": "{ acceptTOS: boolean; checkCertify: boolean }", "summary": "Governance acceptance flags for terms of service and certification confirmation.", "required": false }, { "name": "billToInfo", "type": "{ name: string; address: string; zipCode: number; country: string; city: string; state: string; email: string; phone: string; ext: number; taxRegime?: string; cfdi?: string }", "summary": "Bill-to address and contact details used on invoices, including optional Mexican tax regime and CFDI use codes.", "required": false }, { "name": "identity", "type": "{ name: string; ein?: string; workspace: string; businessType?: string }", "summary": "Public identity of the company: legal name, EIN, workspace slug and business type.", "required": false }, { "name": "details", "type": "{ address?: string; zipCode?: number; country?: string; city?: string; state?: string; mcNumber: string; dotNumber: string; externalNumber: string; internalNumber: string; colony: string; rfc: string; permissionSICT?: string; permitNumber?: string; ensuresEnvironment?: string; policyNumber?: string; dischargedInBorderRegion?: string; timeZone?: string; cargoInsurer?: string; cargoInsurancePolicy?: string }", "summary": "Operational details including physical address, US carrier numbers (MC/DOT), Mexican RFC, SICT permit data, insurance policies and timezone.", "required": false }, { "name": "admin", "type": "ObjectId", "summary": "Identifier of the user who administers the company.", "required": false }, { "name": "SendEmail", "type": "boolean", "summary": "Whether the company should receive email notifications.", "required": false }, { "name": "favoriteCarriers", "type": "any[]", "summary": "List of carriers this company has marked as favorites.", "required": false }, { "name": "role", "type": "string", "summary": "Company role on the platform (e.g. broker, carrier, shipper).", "required": true }, { "name": "integration", "type": "string", "summary": "Identifier of the external integration the company is connected to, if any.", "required": false }, { "name": "mexicoInformation", "type": "{ regime: { fiscalRegime: string; description: string }; cfdi: { usoCfdi: string; description: string } }", "summary": "Mexican tax-compliance metadata including fiscal regime and CFDI use codes with their descriptions.", "required": false }, { "name": "did", "type": "string", "summary": "Decentralized identifier of the company. Indexed.", "constraints": [ "indexed" ], "required": true }, { "name": "delegated", "type": "boolean", "summary": "Whether this company is delegated from another node.", "required": false }, { "name": "delegatedNode", "type": "string", "summary": "Source node identifier when the company is delegated.", "required": false }, { "name": "EntityCSD", "type": "string", "summary": "Reference to the Mexican CSD entity used to sign documents.", "required": false }, { "name": "logoProfile", "type": "string", "summary": "URL or storage path of the company logo image.", "required": false }, { "name": "cdysCarrierId", "type": "string", "summary": "Identifier of the company in the CDYS logistics integration.", "required": false }, { "name": "dexPaymentsId", "type": "ObjectId", "summary": "Identifier of the company in the DexFreight Payments service.", "required": false } ], "indexes": [ { "keys": "identity.ein", "summary": "Lookup by company EIN." }, { "keys": "did", "summary": "Lookup by company decentralized identifier." } ], "relations": [ { "field": "admin", "target": "User", "kind": "one-to-one", "summary": "Administrator user of the company." }, { "field": "dexPaymentsId", "target": "DexPaymentsAccount", "kind": "one-to-one", "summary": "Linked DexFreight Payments account." } ], "restrictions": [] }, { "name": "CostPresets", "module": "payments", "summary": "A reusable preset of services and their rates, scoped to a company and user, used to populate cost lines on shipments based on origin and optional destination zones.", "fields": [ { "name": "companyId", "type": "ObjectId", "summary": "Identifier of the company that owns this preset.", "required": true }, { "name": "userId", "type": "ObjectId", "summary": "Identifier of the user who created the preset.", "required": true }, { "name": "name", "type": "string", "summary": "Human-readable name of the preset.", "required": true }, { "name": "timesUsed", "type": "number", "summary": "Counter of how many times the preset has been applied.", "required": true }, { "name": "services", "type": "ServicesInfo[]", "summary": "Primary services included in the preset, each with name, units and rate.", "required": true }, { "name": "otherServices", "type": "ServicesInfo[]", "summary": "Optional additional services rendered alongside the primary ones.", "required": false }, { "name": "temporalServices", "type": "ServicesInfo[]", "summary": "Optional one-off services included only temporarily.", "required": false }, { "name": "isActive", "type": "boolean", "summary": "Whether the preset is currently active and selectable.", "required": false }, { "name": "origin", "type": "{ zipCode: string; city: string; state: string }[]", "summary": "List of origin locations the preset applies to.", "required": true }, { "name": "destination", "type": "{ zipCode: string; city: string; state: string }[]", "summary": "Optional list of destination locations the preset applies to.", "required": false } ], "restrictions": [] }, { "name": "CPaymentMethod", "module": "payments", "summary": "A catalogue entry describing an SAT payment method code (clave de forma de pago) used in Mexican CFDI documents, with its description and effective date.", "fields": [ { "name": "paymentMethod", "type": "string", "summary": "SAT payment method code (e.g. '01', '03', '99').", "required": true }, { "name": "description", "type": "string", "summary": "Human-readable description of the payment method.", "required": true }, { "name": "effectiveDate", "type": "string", "summary": "Date from which the catalogue entry is effective.", "required": true } ], "restrictions": [] }, { "name": "CustomerPortalContainer", "module": "customer-portal", "summary": "A container request raised through the customer portal, holding the container, transaction, customs and logistics data needed to coordinate pickup, delivery and return between customers, customs agents and the platform.", "fields": [ { "name": "_id", "type": "ObjectId", "summary": "Primary identifier of the container record.", "required": false }, { "name": "companyId", "type": "ObjectId", "summary": "Identifier of the company that owns the container record. Indexed.", "constraints": [ "indexed" ], "required": false }, { "name": "userId", "type": "ObjectId", "summary": "Identifier of the user that created the container record. Indexed.", "constraints": [ "indexed" ], "required": false }, { "name": "allowedCustomers", "type": "string[]", "summary": "Customer identifiers allowed to view or operate on this container. Indexed.", "constraints": [ "indexed" ], "required": false }, { "name": "containerNumber", "type": "string", "summary": "External container number. Indexed.", "constraints": [ "indexed" ], "required": false }, { "name": "transactionId", "type": "string", "summary": "External transaction identifier from the smart-port system. Indexed.", "constraints": [ "indexed" ], "required": false }, { "name": "patent", "type": "string", "summary": "Customs broker patent number associated with the container.", "required": false }, { "name": "document", "type": "string", "summary": "Document identifier (pedimento or equivalent) associated with the container.", "required": false }, { "name": "customsAgent", "type": "{ email: string; name: string; companyName: string }", "summary": "Customs agent contact information.", "required": false }, { "name": "type", "type": "string", "summary": "Movement type for the container.", "required": false }, { "name": "pickup", "type": "SmartPortReleaseLocationInfo", "summary": "Pickup location and release information.", "required": false }, { "name": "delivery", "type": "SmartPortReleaseLocationInfo", "summary": "Delivery location and release information.", "required": false }, { "name": "return", "type": "SmartPortReleaseLocationInfo", "summary": "Return location and release information.", "required": false }, { "name": "temperature", "type": "string", "summary": "Temperature requirement for refrigerated containers.", "required": false }, { "name": "containerId", "type": "string", "summary": "Internal identifier of the container.", "required": false }, { "name": "size", "type": "string", "summary": "Size of the container (e.g. '20', '40').", "required": false }, { "name": "containerType", "type": "string", "summary": "Container equipment type (e.g. dry, reefer, flat-rack).", "required": false }, { "name": "totalWeight", "type": "string", "summary": "Total declared weight of the cargo.", "required": false }, { "name": "shippingLine", "type": "string", "summary": "Ocean shipping line carrying the container.", "required": false }, { "name": "lastDay", "type": "string", "summary": "Last free day before demurrage applies.", "required": false }, { "name": "vessel", "type": "string", "summary": "Vessel name for the maritime leg.", "required": false }, { "name": "voyageNumber", "type": "string", "summary": "Voyage number for the maritime leg.", "required": false }, { "name": "masterBL", "type": "string", "summary": "Master Bill of Lading number.", "required": false }, { "name": "UNNumber", "type": "string", "summary": "UN dangerous-goods identification number, when applicable.", "required": false }, { "name": "class", "type": "string", "summary": "Hazardous-material class, when applicable.", "required": false }, { "name": "booking", "type": "string", "summary": "Ocean booking reference.", "required": false }, { "name": "status", "type": "string", "summary": "Current status of the container request.", "required": false }, { "name": "drayageId", "type": "ObjectId", "summary": "Identifier of the drayage shipment created for this container, when assigned.", "required": false }, { "name": "serviceType", "type": "string", "summary": "Service type requested.", "required": false }, { "name": "commodities", "type": "InformationMexico[]", "summary": "Commodities transported, in the InformationMexico structure.", "required": false } ], "indexes": [ { "keys": "status:-1, allowedCustomers:1", "summary": "Listing by status and allowed customers." }, { "keys": "status:-1, containerNumber:1", "summary": "Listing by status and container number." }, { "keys": "status:-1, allowedCustomers:1, containerNumber:1", "summary": "Listing by status, allowed customers and container number." }, { "keys": "companyId", "summary": "Lookup by company." }, { "keys": "userId", "summary": "Lookup by user." }, { "keys": "allowedCustomers", "summary": "Lookup by allowed customer." }, { "keys": "containerNumber", "summary": "Lookup by container number." }, { "keys": "transactionId", "summary": "Lookup by external transaction id." } ], "relations": [ { "field": "companyId", "target": "Company", "kind": "one-to-one", "summary": "Owner company of the container record." }, { "field": "userId", "target": "User", "kind": "one-to-one", "summary": "User who created the container record." }, { "field": "drayageId", "target": "Drayage", "kind": "one-to-one", "summary": "Drayage shipment associated with this container." } ], "restrictions": [] }, { "name": "CWayToPay", "module": "payments", "summary": "A catalogue/configuration entry for a SAT payment-method (forma de pago) used by Mexican CFDI complemento de pago, capturing the bank coordinates of payer and beneficiary required to issue compliant payment receipts.", "fields": [ { "name": "cPaymentMethod", "type": "string", "summary": "SAT payment-method code this entry configures.", "required": true }, { "name": "year", "type": "Date", "summary": "Reference year/date for the configuration.", "required": true }, { "name": "description", "type": "string", "summary": "Human-readable description of the payment-method configuration.", "required": true }, { "name": "banked", "type": "string", "summary": "Banking institution involved in the payment.", "required": true }, { "name": "operatioNumber", "type": "string", "summary": "Operation number of the payment transaction.", "required": true }, { "name": "RFCOrderingIssuer", "type": "string", "summary": "RFC of the ordering issuer (payer).", "required": true }, { "name": "orderingAccount", "type": "string", "summary": "Bank account number of the payer.", "required": true }, { "name": "payerAccountPattern", "type": "string", "summary": "Pattern/mask describing the payer's account.", "required": true }, { "name": "RFCIssuerAccountBeneficiary", "type": "string", "summary": "RFC of the issuer of the beneficiary's account.", "required": true }, { "name": "beneficiaryAccount", "type": "string", "summary": "Bank account number of the beneficiary.", "required": true }, { "name": "beneficiaryAccountPattern", "type": "string", "summary": "Pattern/mask describing the beneficiary's account.", "required": true }, { "name": "typePaymentChain", "type": "string", "summary": "Type of payment chain referenced in the CFDI complement.", "required": true }, { "name": "issuingBankForeignPayerAccount", "type": "string", "summary": "Issuing bank when the payer's account is foreign.", "required": true } ], "restrictions": [] }, { "name": "DataCartaPorte", "module": "carta-porte", "summary": "A persisted Carta Porte CFDI document for a Mexican drayage shipment, holding the PAC payload, fiscal references (UUID, folio, taxes), document URLs (XML/PDF), payment status and links to broker/carrier companies. The data-carta-porte.ts file also exports DocumentPago (CFDI complemento de pago records), DocumentAduanero (customs document catalogue) and TypeMatter (matter type catalogue) as sibling collections.", "fields": [ { "name": "payload", "type": "PaccCartaPorte", "summary": "Full PAC-bound Carta Porte payload submitted for stamping.", "required": false }, { "name": "companyBroker", "type": "ObjectId", "summary": "Identifier of the broker company on the document.", "required": true }, { "name": "companyCarrier", "type": "ObjectId", "summary": "Identifier of the carrier company on the document.", "required": true }, { "name": "containerNumber", "type": "string", "summary": "Container number associated with the document.", "required": true }, { "name": "delivery", "type": "string", "summary": "Delivery reference for the shipment.", "required": true }, { "name": "taxConcepts", "type": "string[]", "summary": "List of tax concept codes applied on the document.", "required": true }, { "name": "taxes", "type": "string[]", "summary": "List of tax identifiers applied on the document.", "required": true }, { "name": "uuId", "type": "string", "summary": "SAT UUID issued by the PAC after stamping.", "required": true }, { "name": "uniqueId", "type": "string", "summary": "Internal unique identifier of the document.", "required": true }, { "name": "moneyDr", "type": "string", "summary": "Amount expressed in the document's currency.", "required": true }, { "name": "urlXml", "type": "string", "summary": "Storage URL of the stamped CFDI XML.", "required": false }, { "name": "urlPdf", "type": "string", "summary": "Storage URL of the rendered CFDI PDF.", "required": false }, { "name": "dateE", "type": "Date", "summary": "Issuance date of the CFDI.", "required": false }, { "name": "balanceTotal", "type": "string", "summary": "Total balance of the document.", "required": false }, { "name": "datePay", "type": "Date", "summary": "Payment date when the document is settled.", "required": false }, { "name": "paymentForm", "type": "string", "summary": "SAT payment form code applied on the document.", "required": false }, { "name": "amount", "type": "string", "summary": "Document amount.", "required": false }, { "name": "balanceAmountAnte", "type": "string", "summary": "Outstanding balance prior to the latest payment.", "required": false }, { "name": "amountPaid", "type": "string", "summary": "Amount paid so far.", "required": false }, { "name": "NoParcialidad", "type": "string", "summary": "Parcialidad number assigned by SAT for partial-payment tracking.", "required": false }, { "name": "statusData", "type": "boolean", "summary": "Active flag for the data row. Defaults to true.", "required": false }, { "name": "documentUniqueIdentifier", "type": "string", "summary": "External unique identifier of the document.", "required": false }, { "name": "drayageId", "type": "string", "summary": "Identifier of the drayage shipment the document belongs to.", "required": false }, { "name": "status", "type": "string", "summary": "Current status of the CFDI document (e.g. issued, cancelled).", "required": false }, { "name": "cancellationPackageIdentifier", "type": "string", "summary": "Identifier of the cancellation package when the document has been cancelled.", "required": false }, { "name": "complementoPago", "type": "ObjectId", "summary": "Identifier of the linked complemento de pago (DocumentPago) settling this CFDI.", "required": false } ], "indexes": [ { "keys": "drayageId:1, _id:-1", "unique": true, "summary": "Ensures a unique CFDI per drayage and orders by most recent document." } ], "relations": [ { "field": "companyBroker", "target": "Company", "kind": "one-to-one", "summary": "Broker company on the CFDI." }, { "field": "companyCarrier", "target": "Company", "kind": "one-to-one", "summary": "Carrier company on the CFDI." }, { "field": "drayageId", "target": "Drayage", "kind": "one-to-one", "summary": "Drayage shipment the CFDI belongs to." }, { "field": "complementoPago", "target": "DocumentPago", "kind": "one-to-one", "summary": "Complemento de pago that settles this CFDI." } ], "restrictions": [ "Only one Carta Porte document is allowed per drayageId (unique compound index on drayageId, _id)." ] }, { "name": "DataLookUp", "module": "data-lookups", "summary": "Generic key/list lookup table used to persist arbitrary catalogue-like collections under a named slot identified by a COLLECTIONS enum member.", "fields": [ { "name": "name", "type": "COLLECTIONS", "summary": "Identifier of the lookup slot. Each value of the COLLECTIONS enum corresponds to one logical lookup list.", "required": false }, { "name": "list", "type": "any[]", "summary": "Heterogeneous array holding the items of the lookup. Item shape depends on the slot identified by name.", "required": false } ], "restrictions": [] }, { "name": "Devices", "module": "_common", "summary": "Mobile/desktop device registered for a user. Tracks hardware/OS identification, app status and OS-level permissions granted to the dexcarga client.", "fields": [ { "name": "userId", "type": "string", "summary": "Identifier of the user that owns the device.", "required": false }, { "name": "manufacturer", "type": "string", "summary": "Device manufacturer (e.g. Apple, Samsung).", "required": false }, { "name": "model", "type": "string", "summary": "Device model name.", "required": false }, { "name": "systemName", "type": "string", "summary": "Operating system name reported by the client (iOS, Android, etc.).", "required": false }, { "name": "systemVersion", "type": "string", "summary": "Operating system version string.", "required": false }, { "name": "appStatus", "type": "string", "summary": "Free-form status reported by the dexcarga app on the device.", "required": false }, { "name": "permissions", "type": "{ location?: string; camera: boolean; storage: boolean; notifications: boolean; motion: Boolean }", "summary": "OS-level permissions granted to the app on this device. location is a textual permission state; camera/storage/notifications/motion are booleans.", "required": true }, { "name": "createdAt", "type": "Date", "summary": "Timestamp when the device record was first registered.", "required": false }, { "name": "updatedAt", "type": "Date", "summary": "Timestamp of the last update to the device record.", "required": false } ], "restrictions": [] }, { "name": "DocumentMexico", "module": "mexico", "summary": "Reference to a PDF document that belongs to a company under Mexico-specific compliance flows (CFDI, Carta Porte, fiscal documents).", "fields": [ { "name": "name", "type": "string", "summary": "Display name of the document.", "required": false }, { "name": "urlpdf", "type": "string", "summary": "URL where the PDF asset is stored.", "required": false }, { "name": "companyId", "type": "ObjectId", "summary": "Owning company. Documents are scoped per company.", "required": true }, { "name": "typeDocument", "type": "string", "summary": "Free-form classifier for the document (e.g. fiscal certificate, CFDI template, carta porte).", "required": false } ], "relations": [ { "field": "companyId", "target": "Company", "kind": "one-to-one", "summary": "Owning company." } ], "restrictions": [] }, { "name": "DocumentSetup", "module": "documents", "summary": "Per-shipment document workspace tying together the carrier and shipper companies, their uploaded documents, signed/generated rate confirmations, acceptance flags and any extra attachments. Sibling classes in the same file model the document hub/group/instance hierarchy and signed-document references used by other flows.", "fields": [ { "name": "carrierCompany", "type": "string", "summary": "Identifier of the carrier company participating in the shipment.", "required": false }, { "name": "shipperCompany", "type": "string", "summary": "Identifier of the shipper company participating in the shipment.", "required": false }, { "name": "accepted", "type": "boolean", "summary": "Aggregate flag indicating that the document setup has been accepted.", "required": false }, { "name": "shipment", "type": "string", "summary": "Shipment identifier this document setup belongs to.", "required": true }, { "name": "carrier_docs", "type": "DocumentInfo[]", "summary": "Documents uploaded or generated on the carrier side. Each DocumentInfo tracks type, version, accepted/declined flags, comment, urls, addendum flag, agreed-rate copies and timestamps.", "required": false }, { "name": "shipper_docs", "type": "DocumentInfo[]", "summary": "Documents uploaded or generated on the shipper side, mirroring carrier_docs.", "required": false }, { "name": "rateConfirmations", "type": "RateConfirmation[]", "summary": "Signed rate-confirmation records for the shipment (version, url, createdAt, signedBy).", "required": false }, { "name": "generatedRateConfirmations", "type": "GeneratedConfirmation[]", "summary": "Generated rate-confirmation artifacts before signing (url, createdAt, generatedBy).", "required": false }, { "name": "document_preview_url", "type": "string", "summary": "URL of the latest document preview rendered for the shipment. Defaults to empty string.", "required": false }, { "name": "shipper_accepted", "type": "boolean", "summary": "Whether the shipper side has accepted the document setup. Defaults to false.", "required": false }, { "name": "carrier_accepted", "type": "boolean", "summary": "Whether the carrier side has accepted the document setup. Defaults to false.", "required": false }, { "name": "name", "type": "string", "summary": "Optional display name for the document setup.", "required": false }, { "name": "nameDocument", "type": "string", "summary": "Optional name of the primary document associated with the setup.", "required": false }, { "name": "documentExtra", "type": "DocumentExtra[]", "summary": "Additional document attachments outside of the carrier/shipper buckets (e.g. extra files uploaded by either party).", "required": false } ], "relations": [ { "field": "shipment", "target": "Shipment", "kind": "one-to-one", "summary": "Shipment whose document workflow this setup represents." }, { "field": "carrier_docs", "target": "DocumentInfo", "kind": "embedded", "summary": "Embedded list of carrier-side documents." }, { "field": "shipper_docs", "target": "DocumentInfo", "kind": "embedded", "summary": "Embedded list of shipper-side documents." }, { "field": "rateConfirmations", "target": "RateConfirmation", "kind": "embedded", "summary": "Embedded list of signed rate confirmations." }, { "field": "generatedRateConfirmations", "target": "GeneratedConfirmation", "kind": "embedded", "summary": "Embedded list of generated (pre-signature) rate confirmations." }, { "field": "documentExtra", "target": "DocumentExtra", "kind": "embedded", "summary": "Embedded list of extra attachments." }, { "field": "_companion_DocumentHub", "target": "DocumentHub", "kind": "embedded", "summary": "Sibling class: top-level document hub keyed by path with an access list." }, { "field": "_companion_DocumentGroup", "target": "DocumentGroup", "kind": "embedded", "summary": "Sibling class: a group within a hub identified by hub/type/path with an active flag." }, { "field": "_companion_DocumentInstance", "target": "DocumentInstance", "kind": "embedded", "summary": "Sibling class: a versioned document instance inside a group, with hash, url, issue/expiration timestamps, active flag and document metadata." }, { "field": "_companion_SignedDocuments", "target": "SignedDocuments", "kind": "embedded", "summary": "Sibling class: cross-reference linking shipper/carrier/shipment to a signed document URL and shipment type." } ], "restrictions": [] }, { "name": "Drayage", "module": "drayage", "summary": "Central freight/drayage shipment document. Tracks state, lifecycle stage, the broker (owner) and carrier sides, location triplet (pickup/delivery/return), payment and rate negotiation history, booking checklists, attached containers, drivers, vehicles, uploaded documents, and Mexican CFDI / Carta Porte detail. A Drayage is the operational unit a company moves; it can be grouped under a DrayageGroup (drayageGroupId) and contains one or more Container subdocuments.", "fields": [ { "name": "_id", "type": "ObjectId", "summary": "Mongo identifier of the drayage shipment.", "required": true }, { "name": "uniqueId", "type": "string", "summary": "Public unique identifier of the drayage.", "required": true }, { "name": "state", "type": "string", "summary": "Current lifecycle state of the drayage (e.g. quote, booked, in_transit, delivered).", "constraints": [ "indexed" ], "required": true }, { "name": "trackingStage", "type": "string", "summary": "Current operational tracking stage label.", "required": true }, { "name": "companyId", "type": "ObjectId", "summary": "Owner company (broker/shipper).", "constraints": [ "indexed" ], "required": true }, { "name": "userId", "type": "ObjectId", "summary": "Creating user on the owner company side.", "constraints": [ "indexed" ], "required": true }, { "name": "carrierCompanyId", "type": "ObjectId", "summary": "Assigned carrier company.", "constraints": [ "indexed" ], "required": true }, { "name": "userCarrierId", "type": "ObjectId", "summary": "Assigned user on the carrier side.", "constraints": [ "indexed" ], "required": true }, { "name": "type", "type": "string", "summary": "Drayage type (e.g. import, export, dropoff).", "required": true }, { "name": "location", "type": "locationInfo", "summary": "Triplet of pickup, delivery and return locations (each with date/time, address, accessorials and Mexican fiscal location keys).", "required": true }, { "name": "serie", "type": "string", "summary": "Serie identifier used in invoicing/documents.", "required": true }, { "name": "additionalServices", "type": "additionalServicesInfo", "summary": "Optional add-on services: drop/pickup dates, warehouse, days in storage, transload, loose boxes, comments.", "required": false }, { "name": "payment", "type": "paymentInfo", "summary": "Rate, currency and open/close negotiation containers (each with method, terms, services, otherServices, temporalServices, extraCharges).", "required": true }, { "name": "comments", "type": "string", "summary": "Free-form comments about the drayage.", "required": true }, { "name": "negotiation", "type": "negotiationInfo[]", "summary": "Bid/negotiation entries placed on this drayage.", "required": true }, { "name": "carriers", "type": "ObjectId[]", "summary": "Carrier companies invited / participating in negotiation.", "required": true }, { "name": "accepted", "type": "boolean", "summary": "Whether a bid has been accepted and the drayage booked.", "required": true }, { "name": "history", "type": "historyInfo", "summary": "Historical bid records grouped by bidder.", "required": true }, { "name": "_booking", "type": "bookingInfo", "summary": "Shipper and carrier booking checklists (docs signed, attached driver/equipment, appointment).", "required": true }, { "name": "isAgreedRate", "type": "boolean", "summary": "True when the rate is taken from a previously agreed DrayageRate rather than negotiated.", "required": true }, { "name": "isActive", "type": "boolean", "summary": "Soft-delete / visibility flag.", "constraints": [ "indexed" ], "required": true }, { "name": "drayageRateId", "type": "ObjectId", "summary": "Reference to the DrayageRate that produced this shipment, if any.", "required": false }, { "name": "customer", "type": "ObjectId", "summary": "Optional customer/account this drayage belongs to.", "required": false }, { "name": "brokerReferenceID", "type": "string", "summary": "Broker-side external reference id.", "required": false }, { "name": "carrierReferenceID", "type": "string", "summary": "Carrier-side external reference id.", "required": false }, { "name": "containers", "type": "Container[]", "summary": "Embedded containers belonging to this drayage.", "required": false }, { "name": "drivers", "type": "ObjectId[]", "summary": "Drivers historically attached to the drayage.", "required": false }, { "name": "hubspotDeals", "type": "any[]", "summary": "Linked HubSpot deal payloads.", "required": false }, { "name": "currentDrivers", "type": "ObjectId[]", "summary": "Drivers currently active on the drayage.", "required": false }, { "name": "invoice_number", "type": "string", "summary": "Invoice number tied to this drayage.", "required": true }, { "name": "fileSharing", "type": "documentsInfo", "summary": "Shared document URLs (POD, additional, delivery POD).", "required": false }, { "name": "accessorial", "type": "string[]", "summary": "Top-level accessorials applied to the drayage.", "required": false }, { "name": "finalCharges", "type": "boolean", "summary": "Whether final charges have been agreed/closed.", "required": false }, { "name": "companyFinalCharges", "type": "ObjectId", "summary": "Company that owns/issues the final charges.", "required": false }, { "name": "uploadedDocuments", "type": "UploadedDocs[]", "summary": "Documents uploaded against the drayage.", "required": false }, { "name": "deliveredPOD", "type": "string", "summary": "URL or marker of the delivered POD.", "required": false }, { "name": "turn", "type": "string", "summary": "Turn / shift identifier.", "required": false }, { "name": "typeofTruck", "type": "string", "summary": "Truck type label.", "required": false }, { "name": "importExcel", "type": "boolean", "summary": "True when the drayage was created via Excel/CSV import.", "required": false }, { "name": "folioid", "type": "string", "summary": "Internal folio identifier.", "required": false }, { "name": "folio", "type": "string", "summary": "Public folio.", "required": false }, { "name": "detailMexico", "type": "detailMexico", "summary": "Mexican CFDI/Carta Porte detail (national/international, customer name, distance, RFC sender, insurer, customs regime, SICT permits, notes, etc.).", "required": false }, { "name": "truckPlate", "type": "string", "summary": "Plate number of the assigned truck.", "required": false }, { "name": "drayageMerge", "type": "string[]", "summary": "Identifiers of other drayages merged into this one.", "required": false }, { "name": "olpDID", "type": "string", "summary": "OLP (One Load Plan) drayage identifier.", "required": false }, { "name": "isCarrierAutoAssigned", "type": "boolean", "summary": "True if the carrier was auto-assigned by the platform.", "required": false }, { "name": "vehiculeId", "type": "ObjectId", "summary": "Vehicle assigned to the drayage.", "required": false }, { "name": "invoiceConfiguration", "type": "invoiceConfiguration", "summary": "Invoicing preferences (cWaytoPay, cPaymentMethod, voucherType).", "required": false }, { "name": "ccId", "type": "ObjectId", "summary": "Linked credit card / customer-portal context id.", "required": false }, { "name": "customerPortalContainerId", "type": "ObjectId", "summary": "Customer-portal container reference.", "constraints": [ "indexed" ], "required": false }, { "name": "version", "type": "number", "summary": "Version counter for optimistic concurrency / migrations.", "constraints": [ "default: 0" ], "required": false }, { "name": "drayageGroupId", "type": "string", "summary": "Reference to the parent DrayageGroup uniqueId.", "constraints": [ "indexed" ], "required": false }, { "name": "createdAt", "type": "Date", "summary": "Creation timestamp.", "required": false }, { "name": "updatedAt", "type": "Date", "summary": "Last update timestamp.", "required": false }, { "name": "cdysStatus", "type": "string", "summary": "Status reported by the CDYS logistics integration.", "required": false }, { "name": "cdysResponse", "type": "string", "summary": "Raw response payload returned by the CDYS integration.", "required": false }, { "name": "agreedRate", "type": "AgreedRate", "summary": "Agreed rate snapshot (brokerCompanyId, carrierCompanyId, rateId, userCarrierId).", "required": false } ], "indexes": [ { "keys": "drayageGroupId", "summary": "Lookup by parent drayage group." }, { "keys": "companyId:-1", "summary": "Lookup by owner company." }, { "keys": "carrierCompanyId:-1", "summary": "Lookup by carrier company." }, { "keys": "userId:-1", "summary": "Lookup by owning user." }, { "keys": "userCarrierId:-1", "summary": "Lookup by carrier user." }, { "keys": "state:-1", "summary": "Filter by lifecycle state." }, { "keys": "isActive:-1", "summary": "Filter active vs inactive." }, { "keys": "customerPortalContainerId", "summary": "Lookup by customer-portal container reference." } ], "relations": [ { "field": "drayageGroupId", "target": "DrayageGroup", "kind": "one-to-one", "summary": "Parent drayage group." }, { "field": "companyId", "target": "Companies", "kind": "one-to-one", "summary": "Owner (broker/shipper) company." }, { "field": "carrierCompanyId", "target": "Companies", "kind": "one-to-one", "summary": "Assigned carrier company." }, { "field": "userId", "target": "Users", "kind": "one-to-one", "summary": "Creating user on the owner side." }, { "field": "userCarrierId", "target": "Users", "kind": "one-to-one", "summary": "Assigned user on the carrier side." }, { "field": "drayageRateId", "target": "DrayageRate", "kind": "one-to-one", "summary": "Rate quote that produced this drayage." }, { "field": "customer", "target": "Companies", "kind": "one-to-one", "summary": "Customer/account the drayage is sold to." }, { "field": "containers", "target": "Container", "kind": "embedded", "summary": "Embedded container subdocuments." }, { "field": "drivers", "target": "Users", "kind": "one-to-many", "summary": "Drivers historically attached to the drayage." }, { "field": "currentDrivers", "target": "Users", "kind": "one-to-many", "summary": "Drivers currently active on the drayage." }, { "field": "vehiculeId", "target": "Vehicle", "kind": "one-to-one", "summary": "Vehicle assigned to the drayage." }, { "field": "carriers", "target": "Companies", "kind": "one-to-many", "summary": "Carriers invited to bid." }, { "field": "uploadedDocuments", "target": "UploadedDocs", "kind": "embedded", "summary": "Embedded documents uploaded against the drayage." } ], "restrictions": [ "Once accepted is true, payment.close should be populated and isAgreedRate determines whether closing came from a saved DrayageRate.", "drayageGroupId, when set, must match an existing DrayageGroup.uniqueId." ] }, { "name": "DrayageCSV", "module": "drayage", "summary": "Header record for a drayage bulk-import CSV upload. Tracks the company, the user that uploaded it, and the overall processing status. Each row of the imported file is stored separately in DrayageCSVRow and references the parent CSV via csvId.", "fields": [ { "name": "_id", "type": "ObjectId", "summary": "Mongo identifier of the CSV upload.", "required": false }, { "name": "createdAt", "type": "Date", "summary": "Timestamp when the CSV was uploaded.", "required": false }, { "name": "updatedAt", "type": "Date", "summary": "Timestamp of the last status change.", "required": false }, { "name": "companyId", "type": "ObjectId", "summary": "Company that owns the upload.", "required": false }, { "name": "userId", "type": "ObjectId", "summary": "User that performed the upload.", "required": false }, { "name": "status", "type": "string", "summary": "Processing status of the CSV as a whole.", "required": false } ], "indexes": [ { "keys": "companyId, hash", "unique": true, "summary": "Prevents the same company from uploading the exact same CSV (by content hash) twice." }, { "keys": "companyId, createdAt:-1", "summary": "Lists a company's uploads in reverse chronological order." } ], "relations": [ { "field": "_id", "target": "DrayageCSVRow", "kind": "one-to-many", "summary": "Each DrayageCSVRow references its parent CSV via csvId." } ], "restrictions": [ "(companyId, hash) is unique to avoid duplicate uploads of the same CSV file." ] }, { "name": "DrayageGroup", "module": "drayage", "summary": "A group of related drayage shipments that share an overview, pickup, destination and (optional) return location. Acts as the parent grouping that individual Drayage documents reference via drayageGroupId, used to coordinate full vs. single rates and shared logistics for a freight order.", "fields": [ { "name": "createdAt", "type": "Date", "summary": "Creation timestamp.", "constraints": [ "default: now" ], "required": true }, { "name": "updatedAt", "type": "Date", "summary": "Last update timestamp.", "constraints": [ "default: now" ], "required": true }, { "name": "uniqueId", "type": "DrayageGroupId", "summary": "Public, human-readable unique identifier of the drayage group.", "constraints": [ "unique", "indexed" ], "required": true }, { "name": "referenceId", "type": "string", "summary": "External reference identifier for the group (per-company reference).", "required": true }, { "name": "companyId", "type": "ObjectId", "summary": "Owner company (broker/shipper) of the group.", "constraints": [ "indexed" ], "required": false }, { "name": "carrierCompanyId", "type": "ObjectId", "summary": "Carrier company assigned to the group, if any.", "constraints": [ "indexed" ], "required": false }, { "name": "userId", "type": "ObjectId", "summary": "User from the owner company that created the group.", "required": true }, { "name": "carrierUserId", "type": "ObjectId", "summary": "User from the carrier company assigned to the group.", "required": false }, { "name": "overview", "type": "object", "summary": "Aggregate descriptors for the group: groupType (DrayageGroupType), drayageType, traffic (DrayageType), customer, folio, inOut, inOutWay, customsRegime, optional fullRate / singleRate.", "required": true }, { "name": "pickup", "type": "DrayageGroupLocation", "summary": "Pickup location for the group (origin terminal/yard/customer).", "required": true }, { "name": "destination", "type": "DrayageGroupLocation", "summary": "Destination location for the group.", "required": true }, { "name": "return", "type": "DrayageGroupLocation", "summary": "Return location for the group, if applicable (e.g. empty container return).", "required": false }, { "name": "isActive", "type": "boolean", "summary": "Whether the group is active. Defaults to true.", "constraints": [ "default: true" ], "required": false } ], "indexes": [ { "keys": "uniqueId", "unique": true, "summary": "Public group identifier." }, { "keys": "companyId, referenceId", "unique": true, "summary": "A given company cannot reuse the same referenceId twice." }, { "keys": "carrierCompanyId, referenceId", "unique": true, "summary": "A given carrier cannot reuse the same referenceId twice." }, { "keys": "companyId", "summary": "Lookup by owner company." }, { "keys": "carrierCompanyId", "summary": "Lookup by assigned carrier company." } ], "relations": [ { "field": "uniqueId", "target": "Drayage", "kind": "one-to-many", "summary": "Drayage documents reference their parent group via drayageGroupId." }, { "field": "companyId", "target": "Companies", "kind": "one-to-one", "summary": "Owner (broker/shipper) company." }, { "field": "carrierCompanyId", "target": "Companies", "kind": "one-to-one", "summary": "Assigned carrier company." }, { "field": "userId", "target": "Users", "kind": "one-to-one", "summary": "Creating user on the owner side." }, { "field": "carrierUserId", "target": "Users", "kind": "one-to-one", "summary": "Assigned user on the carrier side." }, { "field": "pickup", "target": "DrayageGroupLocation", "kind": "embedded", "summary": "Embedded pickup location." }, { "field": "destination", "target": "DrayageGroupLocation", "kind": "embedded", "summary": "Embedded destination location." }, { "field": "return", "target": "DrayageGroupLocation", "kind": "embedded", "summary": "Embedded return location." } ], "restrictions": [ "uniqueId is required and globally unique across drayage groups.", "(companyId, referenceId) is unique: a company cannot reuse the same referenceId.", "(carrierCompanyId, referenceId) is unique: a carrier cannot reuse the same referenceId.", "createdAt, updatedAt, uniqueId, referenceId, userId, overview, pickup and destination are required." ] }, { "name": "Eld", "module": "integrations", "summary": "Credentials and vendor metadata required to connect a company to an Electronic Logging Device (ELD) provider. Embedded inside company-level integration configuration to authenticate outbound calls to the ELD vendor's API.", "fields": [ { "name": "username", "type": "string", "summary": "Username used to authenticate against the ELD vendor." }, { "name": "password", "type": "string", "summary": "Password used to authenticate against the ELD vendor." }, { "name": "eldvendor", "type": "string", "summary": "Human readable name of the ELD vendor." }, { "name": "eldvendorId", "type": "number", "summary": "Numeric identifier of the ELD vendor inside the platform." }, { "name": "apiKey", "type": "string", "summary": "API key issued by the ELD vendor for programmatic access." } ], "restrictions": [] }, { "name": "EmailNotifiers", "module": "notifications", "summary": "Per-company configuration of which email recipients should be notified for a given event type. One document represents the notifier list for a single (companyId, type) pair.", "fields": [ { "name": "companyId", "type": "ObjectId", "summary": "Company this notifier configuration belongs to.", "constraints": [ "indexed", "unique" ], "required": true }, { "name": "type", "type": "string", "summary": "Notification event type (e.g. shipment update, invoice issued).", "required": false }, { "name": "notifiers", "type": "string[]", "summary": "Email addresses to notify for the given event type.", "required": false } ], "indexes": [ { "keys": "companyId, type", "unique": true, "summary": "Each company has at most one notifier list per event type." }, { "keys": "companyId", "unique": true, "summary": "Field-level unique index on companyId." } ], "relations": [ { "field": "companyId", "target": "Companies", "kind": "one-to-one", "summary": "Owner company." } ], "restrictions": [ "(companyId, type) is unique.", "companyId itself is also declared unique at the prop level." ] }, { "name": "EquipmentMx", "module": "vehicles", "summary": "Mexican catalogue entry describing a kind of equipment (e.g. trailer/chassis type) used for SAT / Carta Porte classification.", "fields": [ { "name": "type", "type": "string", "summary": "Catalogue type/category code for the equipment.", "required": false }, { "name": "name", "type": "string", "summary": "Human-readable name of the equipment in the catalogue.", "required": false } ], "restrictions": [] }, { "name": "Geodata", "module": "geography", "summary": "Cached geographic record mapping a (country, state, city, zip_code) tuple to a latitude/longitude pair. Used to resolve addresses to coordinates without re-querying external geocoding providers.", "fields": [ { "name": "state", "type": "string", "summary": "State or province name.", "required": false }, { "name": "city", "type": "string", "summary": "City or locality name.", "required": false }, { "name": "zip_code", "type": "string", "summary": "Postal/ZIP code.", "required": false }, { "name": "latitude", "type": "number", "summary": "Latitude coordinate of the location.", "required": false }, { "name": "longitude", "type": "number", "summary": "Longitude coordinate of the location.", "required": false }, { "name": "country", "type": "string", "summary": "Country name or ISO code.", "required": false } ], "restrictions": [] }, { "name": "GlobalSettings", "module": "_common", "summary": "Singleton document storing platform-wide operational flags toggled by administrators. Currently exposes a single maintenance switch that gates user access while ops work is in progress.", "collection": "globalsettings", "fields": [ { "name": "maintenance", "type": "boolean", "summary": "When true the platform is in maintenance mode and most user-facing operations are blocked.", "required": true } ], "restrictions": [] }, { "name": "GooglePlace", "module": "places", "summary": "Cached Google Places API result describing a single address autocomplete entry. Stores the descriptive label together with the canonical place identifier and the parsed address components used to prefill load and shipment forms.", "collection": "googleplaces", "fields": [ { "name": "description", "type": "string", "summary": "Display label returned by the autocomplete suggestion.", "required": true }, { "name": "fullAddress", "type": "string", "summary": "Full formatted address resolved for the place.", "required": true }, { "name": "location", "type": "string", "summary": "Geographic coordinates serialised as a string (lat,lng).", "required": true }, { "name": "place_id", "type": "string", "summary": "Stable Google place identifier used to refetch details on demand.", "required": true }, { "name": "zip_code", "type": "string", "summary": "Postal code component of the address.", "required": true }, { "name": "city", "type": "string", "summary": "City or locality component of the address.", "required": true }, { "name": "state", "type": "string", "summary": "State or administrative area of the address.", "required": true }, { "name": "country", "type": "string", "summary": "Country component of the address.", "required": true } ], "restrictions": [] }, { "name": "HazardousMaterial", "module": "catalogue", "summary": "Catalogue entry for a hazardous material (UN-style classification) used when describing dangerous goods on Mexican Carta Porte and shipment documents.", "collection": "hazardousmaterials", "fields": [ { "name": "key", "type": "string", "summary": "Catalogue key identifying the hazardous material (e.g. UN number).", "required": true }, { "name": "description", "type": "string", "summary": "Human-readable description of the material.", "required": true }, { "name": "class", "type": "string", "summary": "Hazard class assigned to the material.", "required": true } ], "restrictions": [] }, { "name": "History", "module": "_common", "summary": "Audit trail entry recording an action performed by a user against a document of any collection. Used as a generic activity log that ties user, document and company together with Mongoose timestamps.", "collection": "histories", "fields": [ { "name": "userId", "type": "ObjectId", "summary": "Identifier of the user that performed the action.", "required": true }, { "name": "documentId", "type": "ObjectId", "summary": "Identifier of the document the action was performed on.", "required": true }, { "name": "collection_name", "type": "string", "summary": "Name of the Mongo collection the document belongs to." }, { "name": "action", "type": "string", "summary": "Free-form action label describing what happened (create, update, delete, etc.)." }, { "name": "document_companyId", "type": "ObjectId", "summary": "Identifier of the company that owns the affected document, used for tenant scoping.", "required": true }, { "name": "createdAt", "type": "Date", "summary": "Auto-managed timestamp set when the entry is created." }, { "name": "updatedAt", "type": "Date", "summary": "Auto-managed timestamp updated whenever the entry changes." } ], "restrictions": [ "userId, documentId and document_companyId are required to persist a history entry.", "createdAt and updatedAt are managed automatically by Mongoose timestamps." ] }, { "name": "LoadLocation", "module": "load-location", "summary": "Reusable origin or destination address registered by a company for use on loads, shipments and Carta Porte documents. Tracks the postal address, optional GeoJSON coordinates, Mexican fiscal data (RFC, WIEC name) and whether the location has been registered with CDYS.", "collection": "loadlocations", "fields": [ { "name": "_id", "type": "ObjectId", "summary": "Mongo identifier of the load location." }, { "name": "name", "type": "string", "summary": "Friendly name used to identify the location in pickers." }, { "name": "address", "type": "string", "summary": "Street address of the location." }, { "name": "city", "type": "string", "summary": "City component of the address." }, { "name": "state", "type": "string", "summary": "State or administrative area component of the address." }, { "name": "zipcode", "type": "string", "summary": "Postal code of the address." }, { "name": "country", "type": "string", "summary": "Country component of the address." }, { "name": "locality", "type": "string", "summary": "Locality or municipality used by Mexican fiscal catalogues." }, { "name": "colonia", "type": "string", "summary": "Colonia (neighbourhood) used by Mexican fiscal catalogues." }, { "name": "userId", "type": "ObjectId", "summary": "Identifier of the user that created the location." }, { "name": "companyId", "type": "ObjectId", "summary": "Identifier of the company that owns the location." }, { "name": "wiecName", "type": "string", "summary": "WIEC (warehouse) name associated with the location for cross-border operations." }, { "name": "rfc", "type": "string", "summary": "Mexican RFC tax identifier of the entity at the location." }, { "name": "isRegisteredInCDYS", "type": "boolean", "summary": "Whether the location has been registered with the CDYS logistics integration." }, { "name": "location", "type": "{ type: 'Point', coordinates: [number, number] }", "summary": "GeoJSON point with the [longitude, latitude] coordinates of the location." } ], "indexes": [ { "keys": "{ companyId: 1, name: 1 }", "unique": true, "summary": "Each company can only have one load location per name." } ], "restrictions": [ "Location names must be unique within a company (enforced by the companyId+name unique index)." ] }, { "name": "LogMx", "module": "carta-porte", "summary": "Audit trail entry for Mexico-specific (CFDI / Carta Porte) operations: records the method invoked, the raw payload sent, and the originating user token / email.", "fields": [ { "name": "method", "type": "string", "summary": "Identifier of the operation or RPC method that produced the log entry.", "required": false }, { "name": "data", "type": "string", "summary": "Serialized payload associated with the operation (request body, response, or arbitrary debug data).", "required": false }, { "name": "token", "type": "string", "summary": "Authentication token that was active when the operation was executed.", "required": false }, { "name": "email", "type": "string", "summary": "Email of the user who triggered the operation, when known.", "required": false } ], "restrictions": [] }, { "name": "Loop", "module": "_common", "summary": "Generic key/data record used by the platform to persist arbitrary recurring loop or background-job state by name.", "fields": [ { "name": "name", "type": "string", "summary": "Logical name identifying the loop or job whose state is being persisted.", "required": false }, { "name": "data", "type": "any", "summary": "Free-form payload holding the loop's last known state or context.", "required": false } ], "restrictions": [] }, { "name": "NavieraMx", "module": "carta-porte", "summary": "Mexican shipping line (naviera) catalogue entry used to populate Carta Porte maritime references.", "fields": [ { "name": "type", "type": "string", "summary": "Classification or category of the shipping line entry.", "required": false }, { "name": "name", "type": "string", "summary": "Display name of the shipping line.", "required": false } ], "restrictions": [] }, { "name": "Negotiation", "module": "negotiations", "summary": "Active rate negotiation between a shipper and a carrier over a shipment, tracking offer history, acceptance flags, pickup/delivery proposals and the resulting agreed value.", "fields": [ { "name": "shipment", "type": "string", "summary": "Identifier of the shipment being negotiated.", "required": false }, { "name": "company", "type": "string", "summary": "Identifier of the company participating in the negotiation.", "required": false }, { "name": "user", "type": "string[]", "summary": "Users from the company involved in the negotiation.", "required": false }, { "name": "accepted", "type": "boolean", "summary": "Whether the negotiation has been finally accepted by both parties.", "constraints": [ "defaults to false" ], "required": false }, { "name": "declined", "type": "boolean", "summary": "Whether the negotiation has been declined.", "constraints": [ "defaults to false" ], "required": false }, { "name": "pending_verification", "type": "boolean", "summary": "Whether the negotiation is awaiting a verification step before proceeding.", "constraints": [ "defaults to false" ], "required": false }, { "name": "by_edition", "type": "boolean", "summary": "Whether the negotiation was triggered by an edit to a previously agreed shipment.", "constraints": [ "defaults to false" ], "required": false }, { "name": "acceptCarrier", "type": "boolean", "summary": "Whether the carrier side has accepted the current offer.", "constraints": [ "defaults to false" ], "required": false }, { "name": "acceptShipper", "type": "boolean", "summary": "Whether the shipper side has accepted the current offer.", "constraints": [ "defaults to false" ], "required": false }, { "name": "negotiationCarrier", "type": "boolean", "summary": "Flag indicating the negotiation was initiated by the carrier.", "constraints": [ "defaults to false" ], "required": false }, { "name": "value", "type": "number", "summary": "Current negotiated rate value.", "required": false }, { "name": "shipper", "type": "string", "summary": "Identifier of the shipper company involved in the negotiation.", "required": false }, { "name": "history", "type": "History[]", "summary": "Chronological log of each counter-offer, including the value, the user and the company that made it.", "required": false }, { "name": "reason", "type": "string", "summary": "Free-form reason or note attached to the negotiation (e.g. why a counter or decline was issued).", "required": false }, { "name": "bidder", "type": "string", "summary": "Identifier of the user or company that placed the most recent bid.", "required": false }, { "name": "limit", "type": "number", "summary": "Optional maximum value boundary for the negotiation.", "required": false }, { "name": "extraChargeTurn", "type": "string", "summary": "Identifier indicating which side currently owes a response on extra charges.", "required": false }, { "name": "addtonu", "type": "boolean", "summary": "Whether the value should be added to the next-up balance flow.", "constraints": [ "defaults to false" ], "required": false }, { "name": "pickup", "type": "PickupDate", "summary": "Proposed pickup date and time embedded with the offer.", "required": true }, { "name": "delivered", "type": "DeliveryDate", "summary": "Proposed delivery date and time embedded with the offer.", "required": true }, { "name": "comment", "type": "string", "summary": "Optional free-form comment attached to the negotiation.", "required": false }, { "name": "companyDecline", "type": "string", "summary": "Identifier of the company that declined the negotiation, when applicable.", "required": false }, { "name": "createdAt", "type": "Date", "summary": "Timestamp at which the negotiation was created.", "required": false } ], "restrictions": [] }, { "name": "Notification", "module": "notifications", "summary": "Per-user notification record produced by the platform, carrying a typed payload and a creation timestamp for in-app or push delivery.", "fields": [ { "name": "type", "type": "string", "summary": "Notification type discriminator used by the client to render the message.", "required": false }, { "name": "createdAt", "type": "Date", "summary": "Timestamp at which the notification was generated.", "required": false }, { "name": "data", "type": "any", "summary": "Type-specific payload describing the event that triggered the notification.", "required": false }, { "name": "userId", "type": "string", "summary": "Identifier of the user the notification is targeted to.", "required": false } ], "restrictions": [] }, { "name": "PackagingType", "module": "catalogue", "summary": "SAT packaging type catalogue entry used to classify how goods are packaged for Carta Porte and customs purposes.", "fields": [ { "name": "key", "type": "string", "summary": "SAT-defined code identifying the packaging type.", "required": true }, { "name": "startDate", "type": "Date", "summary": "Date from which this packaging type entry is valid.", "required": true }, { "name": "description", "type": "string", "summary": "Human-readable description of the packaging type.", "required": true } ], "restrictions": [] }, { "name": "PermissionType", "module": "auth", "summary": "Catalogue entry defining a permission flag that can be granted to roles or users in the access-control system.", "fields": [ { "name": "key", "type": "string", "summary": "Stable code identifying the permission (used in role and access-control rules).", "required": true }, { "name": "description", "type": "string", "summary": "Human-readable description of what the permission grants.", "required": true } ], "restrictions": [] }, { "name": "Places", "module": "places", "summary": "Truck-stop / parking facility catalogue used to recommend stopping points along a shipment route. Captures the location, contact data and an extensive list of amenity flags (fuel, food, security, surface type, vehicle compatibility, etc.).", "collection": "places", "fields": [ { "name": "id", "type": "string", "summary": "External provider identifier for the place." }, { "name": "truckparkid", "type": "string", "summary": "Identifier supplied by the upstream truck-park data feed." }, { "name": "name", "type": "string", "summary": "Display name of the facility." }, { "name": "address1", "type": "string", "summary": "Street address line." }, { "name": "city", "type": "string", "summary": "City where the facility is located." }, { "name": "state", "type": "string", "summary": "State or province where the facility is located." }, { "name": "zip", "type": "string", "summary": "Postal / ZIP code." }, { "name": "timezone", "type": "string", "summary": "IANA-style timezone of the facility." }, { "name": "latitude", "type": "number", "summary": "Geographic latitude in decimal degrees." }, { "name": "longitude", "type": "number", "summary": "Geographic longitude in decimal degrees." }, { "name": "spots", "type": "string", "summary": "Number of parking spots available, stored as a string." }, { "name": "price", "type": "string", "summary": "Free-form description of pricing for the facility." }, { "name": "description", "type": "string", "summary": "Free-form description of the facility." }, { "name": "diesel", "type": "boolean", "summary": "Whether diesel fuel is available on site." }, { "name": "food", "type": "boolean", "summary": "Whether food service is available on site." }, { "name": "lodging", "type": "boolean", "summary": "Whether lodging is available on site." }, { "name": "partsrepair", "type": "boolean", "summary": "Whether parts and repair services are available." }, { "name": "showers", "type": "boolean", "summary": "Whether shower facilities are available." }, { "name": "truckwash", "type": "boolean", "summary": "Whether a truck-wash service is available." }, { "name": "tireshop", "type": "boolean", "summary": "Whether tyre service is available." }, { "name": "weighscale", "type": "boolean", "summary": "Whether a weigh scale is available." }, { "name": "camera", "type": "boolean", "summary": "Whether the facility has surveillance cameras." }, { "name": "mannedsecurity", "type": "boolean", "summary": "Whether manned security is on site." }, { "name": "fenced", "type": "boolean", "summary": "Whether the perimeter is fenced." }, { "name": "welllit", "type": "boolean", "summary": "Whether the area is well-lit." }, { "name": "gravel", "type": "boolean", "summary": "Whether the surface is gravel." }, { "name": "asphalt", "type": "boolean", "summary": "Whether the surface is asphalt." }, { "name": "longterm", "type": "boolean", "summary": "Whether long-term parking is offered." }, { "name": "overnight", "type": "boolean", "summary": "Whether overnight parking is offered." }, { "name": "bobtail", "type": "boolean", "summary": "Whether bobtail trucks are accepted." }, { "name": "truck1226", "type": "boolean", "summary": "Whether trucks in the 12-26 ft length range are accepted." }, { "name": "truck4853", "type": "boolean", "summary": "Whether trucks in the 48-53 ft length range are accepted." }, { "name": "refrigerated", "type": "boolean", "summary": "Whether refrigerated units are supported." }, { "name": "hazardous", "type": "boolean", "summary": "Whether hazardous-material loads are accepted." }, { "name": "other", "type": "boolean", "summary": "Catch-all flag for amenities outside the predefined list." } ], "restrictions": [] }, { "name": "Point", "module": "points", "summary": "Named polygon or polyline of geographic coordinates used to draw user-defined points / regions on the map. Persisted as a Mongoose schema with timestamps so that creation and last-edit times are tracked automatically.", "collection": "points", "fields": [ { "name": "_id", "type": "ObjectId", "summary": "Mongo identifier of the point.", "required": true }, { "name": "name", "type": "string", "summary": "Display name of the point or region." }, { "name": "color", "type": "string", "summary": "Color used to render the point on the map (CSS / hex string)." }, { "name": "point", "type": "Array<{ lat: number; lng: number }>", "summary": "Ordered list of latitude / longitude pairs that make up the geometry." }, { "name": "createdAt", "type": "Date", "summary": "Automatically populated by the Mongoose timestamps option." }, { "name": "updatedAt", "type": "Date", "summary": "Automatically populated by the Mongoose timestamps option." } ], "restrictions": [ "Mongoose schema is configured with `{ timestamps: true }`, so `createdAt` and `updatedAt` are managed by the ODM." ] }, { "name": "Positions", "module": "tracking", "summary": "Time-stamped GPS sample emitted by a tracked vehicle / driver. Each document represents a single ping along a shipment, including the recorded position, the inferred activity and the GPS provider that reported it.", "collection": "positions", "fields": [ { "name": "_id", "type": "ObjectId", "summary": "Mongo identifier of the position sample.", "required": true }, { "name": "shipmentId", "type": "ObjectId", "summary": "Shipment the position is associated with." }, { "name": "driverId", "type": "string", "summary": "Identifier of the driver that produced the sample." }, { "name": "vehicleId", "type": "string", "summary": "Identifier of the vehicle that produced the sample." }, { "name": "timestamp", "type": "number", "summary": "Epoch time at which the GPS fix was taken on the device." }, { "name": "receive_timestamp", "type": "number", "summary": "Epoch time at which the backend received the sample." }, { "name": "lat", "type": "number", "summary": "Latitude of the GPS fix in decimal degrees." }, { "name": "lng", "type": "number", "summary": "Longitude of the GPS fix in decimal degrees." }, { "name": "activity", "type": "string", "summary": "Activity reported alongside the sample (e.g. driving, idle)." }, { "name": "distanceDriven", "type": "number", "summary": "Distance covered since the previous sample, in the unit used by the GPS provider." }, { "name": "gpsProvider", "type": "string", "summary": "Identifier of the upstream GPS provider that emitted the sample." } ], "indexes": [ { "keys": "{ shipmentId: 1 }", "summary": "Look up all position samples for a shipment." }, { "keys": "{ vehicleId: 1 }", "summary": "Look up the position history for a specific vehicle." } ], "relations": [ { "field": "shipmentId", "target": "Shipment", "kind": "one-to-one", "summary": "Shipment the GPS sample belongs to." } ], "restrictions": [] }, { "name": "RegimenAduanero", "module": "carta-porte", "summary": "Catalogue of Mexican customs regimes (regimenes aduaneros) used when issuing Carta Porte / CFDI documents. Each entry captures the SAT key, its description and whether it applies to imports or exports.", "collection": "regimenaduaneros", "fields": [ { "name": "_id", "type": "ObjectId", "summary": "Mongo identifier of the catalogue entry.", "required": true }, { "name": "key", "type": "string", "summary": "SAT-issued key identifying the customs regime." }, { "name": "description", "type": "string", "summary": "Human-readable description of the regime." }, { "name": "impoExpo", "type": "string", "summary": "Whether the regime applies to imports or exports (e.g. impo, expo)." } ], "restrictions": [] }, { "name": "Ruleset", "module": "auth", "summary": "Named bundle of access-control rule identifiers that can be assigned to users or roles to grant a coherent set of permissions. The source file also exports a sibling Rule class that maps an owner identifier to an ordered list of rule strings.", "collection": "rulesets", "fields": [ { "name": "_id", "type": "ObjectId", "summary": "Mongo identifier of the ruleset.", "required": true }, { "name": "name", "type": "string", "summary": "Human readable label used to reference the ruleset in admin UIs." }, { "name": "rules", "type": "string[]", "summary": "List of rule identifiers granted by this ruleset.", "constraints": [ "default: []" ] } ], "relations": [ { "field": "rules", "target": "Rule", "kind": "one-to-many", "summary": "Each entry in rules matches a Rule.owner value defined in the same source file." } ], "restrictions": [] }, { "name": "Services", "module": "services", "summary": "Per-user, per-company list of enabled service identifiers. One document binds a (companyId, userId) pair to the set of services the user is allowed to operate within that company.", "collection": "services", "fields": [ { "name": "_id", "type": "ObjectId", "summary": "Mongo identifier of the services document.", "required": true }, { "name": "companyId", "type": "ObjectId", "summary": "Company the service grants apply to." }, { "name": "userId", "type": "ObjectId", "summary": "User whose services are listed." }, { "name": "services", "type": "string[]", "summary": "List of service identifiers enabled for the (company, user) pair." } ], "relations": [ { "field": "companyId", "target": "Company", "kind": "one-to-one", "summary": "Owning company." }, { "field": "userId", "target": "User", "kind": "one-to-one", "summary": "Owning user." } ], "restrictions": [] }, { "name": "ShippingHistory", "module": "drayage", "summary": "Audit / import-trace document recorded each time containers are pushed into a shipment via bulk-import flows. Tracks which shipment the import targeted, the user and company who issued it, the container numbers and any error details produced during the import.", "collection": "shippinghistories", "fields": [ { "name": "_id", "type": "ObjectId", "summary": "Mongo identifier of the history entry.", "required": true }, { "name": "no_container", "type": "string[]", "summary": "Container numbers included in the import batch." }, { "name": "uniqueId", "type": "string", "summary": "Stable identifier used to deduplicate or reference the import batch externally." }, { "name": "error_detail", "type": "string[]", "summary": "Per-row error messages emitted while processing the import." }, { "name": "date", "type": "Date", "summary": "Moment the import was executed." }, { "name": "userId", "type": "ObjectId", "summary": "User that triggered the import." }, { "name": "companyId", "type": "ObjectId", "summary": "Company that owns the import." }, { "name": "active", "type": "boolean", "summary": "Soft-delete flag; false hides the entry from history listings." }, { "name": "groupId", "type": "string", "summary": "Optional group identifier used to bundle related imports together." }, { "name": "shipmentId", "type": "ObjectId", "summary": "Shipment the imported containers were attached to." }, { "name": "importType", "type": "string", "summary": "Discriminator describing the type of import (CSV, manual, third-party feed, etc.)." } ], "relations": [ { "field": "shipmentId", "target": "Shipment", "kind": "one-to-one", "summary": "Shipment the imported rows were attached to." }, { "field": "userId", "target": "User", "kind": "one-to-one", "summary": "User who triggered the import." }, { "field": "companyId", "target": "Company", "kind": "one-to-one", "summary": "Owning company." } ], "restrictions": [] }, { "name": "SmartPortLocation", "module": "smart-port", "summary": "Per-customer SmartPort location record. Stores the delivery / return locations registered for a SmartPort account so they can be matched to shipments and replayed to the SmartPort integration. The source file also exports an empty SmartPortActionHistoryItem placeholder used for upcoming action-history support.", "collection": "smartportlocations", "fields": [ { "name": "_id", "type": "ObjectId", "summary": "Mongo identifier of the location record.", "required": true }, { "name": "email", "type": "string", "summary": "Email of the SmartPort account that owns the location.", "required": true }, { "name": "code", "type": "string", "summary": "External SmartPort code identifying the location.", "required": true }, { "name": "type", "type": "string", "summary": "High-level type of the record as reported by SmartPort.", "required": true }, { "name": "locationType", "type": "string", "summary": "Domain location type, mirrors SmartPortLocationType (delivery | return).", "required": true }, { "name": "locationName", "type": "string", "summary": "Display name of the location.", "required": true }, { "name": "address", "type": "string", "summary": "Street address of the location.", "required": true }, { "name": "city", "type": "string", "summary": "City of the location.", "required": true }, { "name": "state", "type": "string", "summary": "State / province of the location.", "required": true }, { "name": "postalCode", "type": "string", "summary": "Postal / ZIP code of the location.", "required": true } ], "indexes": [ { "keys": "{ type: 1, email: 1, code: 1 }", "summary": "Look up a SmartPort location by account email, type and external code." } ], "relations": [ { "field": "locationType", "target": "SmartPortLocationType", "kind": "one-to-one", "summary": "String value drawn from the SmartPortLocationType enum." } ], "restrictions": [ "email, code, type, locationType, locationName, address, city, state and postalCode are all marked `required: true` in the Typegoose schema." ] }, { "name": "States", "module": "geography", "summary": "Catalogue of states (administrative regions) with abbreviation and a GeoJSON-style point location.", "fields": [ { "name": "state", "type": "string", "summary": "Full state name.", "required": false }, { "name": "abbreviation", "type": "string", "summary": "Short code or abbreviation for the state.", "required": false }, { "name": "location", "type": "{ type: string, coordinates: number[] }", "summary": "GeoJSON-style geographic location of the state (typically a representative centroid).", "required": false } ], "restrictions": [] }, { "name": "SubTipoRem", "module": "carta-porte", "summary": "SAT catalogue of trailer (remolque) sub-types used in Carta Porte vehicle declarations.", "fields": [ { "name": "claveRemolque", "type": "string", "summary": "SAT key identifying the trailer sub-type.", "required": true }, { "name": "remolque", "type": "string", "summary": "Human-readable description of the trailer sub-type.", "required": true } ], "restrictions": [] }, { "name": "Task", "module": "tasks", "summary": "Asynchronous background task record tracking type, status, payload, result, errors and notification targets.", "fields": [ { "name": "_id", "type": "ObjectId", "summary": "Mongo identifier of the task.", "required": true }, { "name": "type", "type": "string", "summary": "Task type discriminator that selects the worker / handler.", "required": false }, { "name": "createdAt", "type": "Date", "summary": "Timestamp when the task was queued.", "required": false }, { "name": "completedAt", "type": "Date", "summary": "Timestamp when the task finished (success or failure).", "required": false }, { "name": "notifiers", "type": "Notifier[]", "summary": "Targets to notify about progress or completion of the task.", "required": false }, { "name": "relatedEntities", "type": "TaskEntity[]", "summary": "Domain entities the task is linked to (used for lookups via EntityTasks).", "required": false }, { "name": "status", "type": "string", "summary": "Lifecycle status of the task (e.g. pending, running, completed, failed).", "required": false }, { "name": "taskErrors", "type": "CustomError[]", "summary": "Errors captured during task execution.", "required": false }, { "name": "data", "type": "any", "summary": "Arbitrary input payload consumed by the task handler.", "required": false }, { "name": "result", "type": "any", "summary": "Arbitrary output produced by the task handler.", "required": false } ], "indexes": [ { "keys": "{ type: 1 }", "summary": "Index for filtering tasks by their type." }, { "keys": "{ status: 1 }", "summary": "Index for filtering tasks by lifecycle status." } ], "restrictions": [] }, { "name": "Templates", "module": "templates", "summary": "Configurable template definition scoped by role and (optionally) company and category, with an active flag for soft enable/disable.", "fields": [ { "name": "role", "type": "string", "summary": "Role the template applies to.", "required": true }, { "name": "nameTemplate", "type": "string", "summary": "Display name / identifier of the template.", "required": true }, { "name": "active", "type": "boolean", "summary": "Whether the template is currently enabled.", "required": true }, { "name": "companyId", "type": "ObjectId", "summary": "Optional company that owns the template; absent for global templates.", "required": false }, { "name": "categoryId", "type": "ObjectId", "summary": "Optional category the template belongs to.", "required": false } ], "relations": [ { "field": "companyId", "target": "Company", "kind": "one-to-one", "summary": "Company that owns the template." }, { "field": "categoryId", "target": "Category", "kind": "one-to-one", "summary": "Category the template is grouped under." } ], "restrictions": [] }, { "name": "Transaction", "module": "payments", "summary": "Money movement record between two parties on the platform, capturing the source and target identities, the linked shipment, the lifecycle status and the amount, used to drive the payments ledger.", "fields": [ { "name": "txId", "type": "string", "summary": "External transaction identifier returned by the upstream payments provider.", "required": true }, { "name": "sourceId", "type": "string", "summary": "Identifier of the party originating the funds.", "required": true }, { "name": "targetId", "type": "string", "summary": "Identifier of the party receiving the funds.", "required": true }, { "name": "class", "type": "string", "summary": "Classification tag grouping the transaction (e.g. settlement, refund, fee).", "required": true }, { "name": "shipmentId", "type": "ObjectId", "summary": "Identifier of the shipment this transaction belongs to.", "required": true }, { "name": "resourceId", "type": "string", "summary": "Identifier of the related domain resource the transaction settles (invoice, charge, etc.).", "required": true }, { "name": "correlationId", "type": "string", "summary": "Correlation identifier used to tie related transactions (e.g. payment + counter-payment) together.", "required": true }, { "name": "status", "type": "TRANSACTION_STATUS", "summary": "Current lifecycle status of the transaction.", "required": true }, { "name": "type", "type": "TRANSACTION_TYPES", "summary": "Business type of the transaction.", "required": true }, { "name": "mailed_notifications", "type": "any", "summary": "Bookkeeping object tracking which notification emails have already been sent for this transaction.", "required": true }, { "name": "amount", "type": "number", "summary": "Monetary amount moved by the transaction.", "required": true }, { "name": "timestamp", "type": "Date", "summary": "Time at which the transaction was created.", "required": true }, { "name": "reason", "type": "string", "summary": "Free-form reason describing why the transaction was issued.", "required": true }, { "name": "completedAt", "type": "Date", "summary": "Time at which the transaction reached its terminal status, when applicable.", "required": false }, { "name": "details", "type": "{ source: { companyId: ObjectId, institution: string, identity: { name: string } }, target: { companyId: ObjectId, institution: string, identity: { name: string } } }", "summary": "Embedded snapshot of the source and target parties (company id, financial institution and display name) at the time the transaction was created.", "required": true } ], "relations": [ { "field": "shipmentId", "target": "Drayage", "kind": "one-to-one", "summary": "Shipment the transaction settles." }, { "field": "details.source.companyId", "target": "Company", "kind": "one-to-one", "summary": "Company originating the funds." }, { "field": "details.target.companyId", "target": "Company", "kind": "one-to-one", "summary": "Company receiving the funds." } ], "restrictions": [] }, { "name": "User", "module": "auth", "summary": "Core account entity for every human or programmatic actor in the system: shippers, brokers, carriers, drivers, customers and pending users are all stored as User documents (with sibling subclasses Shipper, Carrier, Driver, Broker and PendingUser specializing the shape, plus Session, SessionActivity and Customer auxiliary models in the same file).", "collection": "users", "fields": [ { "name": "_id", "type": "ObjectId", "summary": "Mongo identifier of the user.", "required": true }, { "name": "username", "type": "string", "summary": "Legacy username; new accounts authenticate by email so this field is kept for backward compatibility only.", "constraints": [ "index: true" ] }, { "name": "email", "type": "string", "summary": "Primary email address used for login and notifications.", "constraints": [ "index: true", "unique: true" ] }, { "name": "companyId", "type": "ObjectId", "summary": "Company the user belongs to. Only role:customer accounts may be missing this reference.", "constraints": [ "ref: Company" ], "required": true }, { "name": "role", "type": "string", "summary": "Application role identifier (shipper, carrier, broker, driver, customer, etc.).", "required": true }, { "name": "password", "type": "string", "summary": "Hashed password. Only present when the user enabled the password authentication method." }, { "name": "emailAuthentication", "type": "{ code: string; sentAt: Date; retries: number }", "summary": "Active email-code challenge used for passwordless email authentication." }, { "name": "_resetPassword", "type": "{ expiration: Date; token: string }", "summary": "Pending password-reset challenge, including the token and its expiration." }, { "name": "_accountBlocker", "type": "{ count: number; time: Date }", "summary": "Login-failure counter and last-failure timestamp used to throttle brute-force attempts." }, { "name": "profile", "type": "{ name?: string; lastname?: string; phone?: string; mobile?: string; countryCode?: string; picture?: string }", "summary": "Personal profile data displayed across the UI.", "constraints": [ "default: {}" ] }, { "name": "smsTracking", "type": "boolean", "summary": "Whether the user opted into SMS-based shipment tracking notifications.", "constraints": [ "default: false" ] }, { "name": "_accessLevel", "type": "string", "summary": "Access-level tier (e.g. User, Admin) controlling administrative privileges.", "constraints": [ "default: UserAccessLevel.User" ] }, { "name": "disabled", "type": "boolean", "summary": "When true the user is blocked from logging in.", "constraints": [ "default: false" ] }, { "name": "acceptCarrier", "type": "boolean", "summary": "Indicates whether the user has accepted carrier terms (used for brokers/shippers carrying freight).", "constraints": [ "default: false" ] }, { "name": "license", "type": "{ id?: string; expiration?: Date; location?: string }", "summary": "Driver license metadata. Always present on Driver subclass; optional on the base User.", "constraints": [ "default: { id: '', expiration: null, location: '' }" ] }, { "name": "isOwnerOperator", "type": "boolean", "summary": "Indicates whether the carrier/driver also owns the equipment they operate." }, { "name": "ethAddress", "type": "string", "summary": "Ethereum address linked to the user for blockchain-based authentication or payments." }, { "name": "nonce", "type": "number", "summary": "Incrementing nonce for Ethereum signed-message auth." }, { "name": "tlx", "type": "{ driverId?: number; eldvendorId?: number; eldVendorName?: string; carrierId?: number; carrierName?: string; currentVehicleId?: string }", "summary": "TLX/ELD integration metadata linking the user to their telematics vendor account.", "required": true }, { "name": "customerOf", "type": "ObjectId", "summary": "When the user is a customer, points to the broker/shipper that owns them." }, { "name": "customerId", "type": "ObjectId", "summary": "Reference to the Customer mapping document, used to resolve customer-specific settings." }, { "name": "lastActivity", "type": "Date", "summary": "Timestamp of the user's last authenticated activity." }, { "name": "driverId", "type": "ObjectId", "summary": "When the user is a Driver, the Driver document identifier." }, { "name": "settings", "type": "any", "summary": "Free-form per-user settings document." }, { "name": "dexPaymentsId", "type": "string", "summary": "External identifier in the DexFreight Payments system." }, { "name": "mexicoInformation", "type": "{ figureType?: { keyFigureType?: string; description?: string }; rfc?: string }", "summary": "Mexico-specific tax data: SAT figure type and RFC (taxpayer ID)." } ], "indexes": [ { "keys": "{\"profile.phone\":1}", "summary": "Look up users by their profile phone number." }, { "keys": "{\"username\":1}", "summary": "Index on legacy username field." }, { "keys": "{\"email\":1}", "unique": true, "summary": "Email uniqueness across the user collection." } ], "relations": [ { "field": "companyId", "target": "Company", "kind": "one-to-one" }, { "field": "customerOf", "target": "User", "kind": "one-to-one", "summary": "Self-reference: customer accounts point to the broker/shipper they belong to." }, { "field": "customerId", "target": "Customer", "kind": "one-to-one" }, { "field": "driverId", "target": "Driver", "kind": "one-to-one" } ], "restrictions": [ "email must be unique across the users collection.", "Accounts whose role is not 'customer' must have companyId populated." ] }, { "name": "Vehicle", "module": "vehicles", "summary": "Motor vehicle (tractor) registry with type, identification, optional GPS provider linkage, owning company and attached trailers (remolques).", "fields": [ { "name": "_id", "type": "ObjectId", "summary": "Mongo identifier of the vehicle.", "required": true }, { "name": "type", "type": "string", "summary": "Vehicle configuration / type code.", "required": true }, { "name": "year", "type": "string", "summary": "Model year of the vehicle.", "required": true }, { "name": "weight", "type": "string", "summary": "Declared weight of the vehicle.", "required": true }, { "name": "plate", "type": "string", "summary": "License plate number of the tractor unit.", "required": true }, { "name": "companyId", "type": "ObjectId", "summary": "Owning company of the vehicle.", "required": false }, { "name": "remolques", "type": "Array<{ subType: string, plate: string }>", "summary": "Trailers attached to this vehicle, each with its sub-type code and plate.", "required": false }, { "name": "gpsProvider", "type": "string", "summary": "Identifier of the GPS provider integration used to track the vehicle.", "required": false }, { "name": "gpsReference", "type": "string", "summary": "External reference / unit id used by the GPS provider.", "required": false } ], "relations": [ { "field": "companyId", "target": "Company", "kind": "one-to-one", "summary": "Company that owns the vehicle." }, { "field": "remolques", "target": "SubTipoRem", "kind": "embedded", "summary": "Embedded trailer references; subType points to a SAT trailer sub-type catalogue key." } ], "restrictions": [] }, { "name": "VoucherType", "module": "catalogue", "summary": "Catalogue of voucher / receipt types with their human-readable description.", "fields": [ { "name": "voucherType", "type": "string", "summary": "Code identifying the voucher type.", "required": true }, { "name": "description", "type": "string", "summary": "Human-readable description of the voucher type.", "required": true } ], "restrictions": [] } ], "valueObjects": [ { "name": "ContainerNumber", "module": "drayage", "summary": "Validates that a drayage container number is a non-empty string.", "primitiveType": "string", "validations": [ { "rule": "Container number must not be empty.", "errorCode": "CONTAINER_NUMBER_REQUIRED" } ], "methods": [ { "signature": "ContainerNumber(containerNumber: string): string", "summary": "Returns the container number unchanged after asserting it is non-empty.", "throws": [ "CONTAINER_NUMBER_REQUIRED" ] } ] }, { "name": "DrayageContainerSize", "module": "drayage", "summary": "Validates that a drayage container size is non-empty and belongs to the canonical DRAYAGE_CONTAINER_SIZE catalog.", "primitiveType": "string", "validations": [ { "rule": "Container size must not be empty.", "errorCode": "DRAYAGE_CONTAINER_SIZE_REQUIRED" }, { "rule": "Container size must be one of the values listed in the DRAYAGE_CONTAINER_SIZE enum.", "errorCode": "DRAYAGE_CONTAINER_SIZE_INVALID" } ], "methods": [ { "signature": "DrayageContainerSize(size: string): string", "summary": "Returns the container size unchanged after asserting it is non-empty and present in the DRAYAGE_CONTAINER_SIZE catalog.", "throws": [ "DRAYAGE_CONTAINER_SIZE_REQUIRED", "DRAYAGE_CONTAINER_SIZE_INVALID" ] } ] }, { "name": "DrayageContainerType", "module": "drayage", "summary": "Validates that a drayage container type is non-empty and belongs to the EQUIPMENT_MX catalog.", "primitiveType": "string", "validations": [ { "rule": "Container type must not be empty.", "errorCode": "DRAYAGE_CONTAINER_TYPE_REQUIRED" }, { "rule": "Container type must be one of the values listed in the EQUIPMENT_MX enum.", "errorCode": "DRAYAGE_CONTAINER_TYPE_INVALID" } ], "methods": [ { "signature": "DrayageContainerType(type: string): string", "summary": "Returns the container type unchanged after asserting it is non-empty and present in the EQUIPMENT_MX catalog.", "throws": [ "DRAYAGE_CONTAINER_TYPE_REQUIRED", "DRAYAGE_CONTAINER_TYPE_INVALID" ] } ] }, { "name": "Email", "module": "identity", "summary": "Trims, lowercases, and validates that a string is a structurally valid email address.", "primitiveType": "string", "validations": [ { "rule": "Value must match /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/ — a local part, '@', a domain, '.', and a TLD with no whitespace or extra '@'.", "errorCode": "INVALID_EMAIL" } ], "methods": [ { "signature": "constructor(email: string | Email)", "summary": "Builds an Email; clones if an Email instance is supplied, otherwise trims, lowercases, and validates the input.", "throws": [ "INVALID_EMAIL" ] }, { "signature": "toString(): string", "summary": "Returns the canonical email string." }, { "signature": "valueOf(): string", "summary": "Returns the canonical email string for primitive coercion." }, { "signature": "toJSON(): string", "summary": "Serializes the value object as the canonical email string." } ] }, { "name": "Password", "module": "identity", "summary": "Wraps a user password and enforces the platform's strength rules; can be constructed in 'secure' mode (full strength checks) or 'credential' mode (presence-only, used when verifying existing credentials).", "primitiveType": "string", "validations": [ { "rule": "Password must not be null or undefined.", "errorCode": "INVALID_PASSWORD" }, { "rule": "Password must be a non-empty string.", "errorCode": "INVALID_PASSWORD" }, { "rule": "When validateSecurity is enabled (default), password must be at least 8 characters long.", "errorCode": "INVALID_PASSWORD" }, { "rule": "When validateSecurity is enabled, password must not exceed 72 characters (bcrypt limit).", "errorCode": "INVALID_PASSWORD" }, { "rule": "When validateSecurity is enabled, password must include at least one uppercase letter.", "errorCode": "INVALID_PASSWORD" }, { "rule": "When validateSecurity is enabled, password must include at least one digit.", "errorCode": "INVALID_PASSWORD" }, { "rule": "When validateSecurity is enabled, password must include at least one symbol from the set !#$%&()*+,-./:;<=>?@[\\]^_`{|}~.", "errorCode": "INVALID_PASSWORD" } ], "methods": [ { "signature": "constructor(password: string | Password, options?: { validateSecurity?: boolean })", "summary": "Builds a Password; clones if a Password instance is supplied, otherwise validates the input. Strength checks run by default and can be disabled via options.validateSecurity = false.", "throws": [ "INVALID_PASSWORD" ] }, { "signature": "static credential(password: string | Password): Password", "summary": "Builds a Password without strength checks (presence only) — used when handling already-stored credentials during sign-in.", "throws": [ "INVALID_PASSWORD" ] }, { "signature": "static secure(password: string | Password): Password", "summary": "Builds a Password with full strength validation — used when accepting new passwords during sign-up or password change.", "throws": [ "INVALID_PASSWORD" ] }, { "signature": "toString(): string", "summary": "Returns the raw password string." }, { "signature": "valueOf(): string", "summary": "Returns the raw password string for primitive coercion." }, { "signature": "toJSON(): string", "summary": "Serializes the value object as the raw password string." } ] }, { "name": "Phone", "module": "identity", "summary": "Trims and normalizes a phone number (stripping spaces and dashes) and validates it against the international 7-15 digit format with an optional leading '+'.", "primitiveType": "string", "validations": [ { "rule": "After stripping whitespace and dashes, value must match /^\\+?\\d{7,15}$/ — an optional leading '+' followed by 7 to 15 digits.", "errorCode": "INVALID_PHONE_FORMAT" } ], "methods": [ { "signature": "constructor(phone: string | Phone)", "summary": "Builds a Phone; clones if a Phone instance is supplied, otherwise trims, removes spaces/dashes, and validates the digit pattern.", "throws": [ "INVALID_PHONE_FORMAT" ] }, { "signature": "toString(): string", "summary": "Returns the normalized phone number string." }, { "signature": "valueOf(): string", "summary": "Returns the normalized phone number string for primitive coercion." }, { "signature": "toJSON(): string", "summary": "Serializes the value object as the normalized phone number string." } ] }, { "name": "Plate", "module": "vehicles", "summary": "Validates a vehicle license plate as 5-7 alphanumeric characters and returns it uppercased.", "primitiveType": "string", "validations": [ { "rule": "Plate must match /^[A-Z0-9]{5,7}$/i — between 5 and 7 alphanumeric characters, case-insensitive.", "errorCode": "INVALID_PLATE" } ], "methods": [ { "signature": "Plate(plate: string): string", "summary": "Returns the plate uppercased after asserting it matches the 5-7 alphanumeric pattern.", "throws": [ "INVALID_PLATE" ] } ] }, { "name": "RFC", "module": "sat", "summary": "Validates a Mexican SAT taxpayer identifier (Registro Federal de Contribuyentes) for both individuals (13 chars) and companies (12 chars), uppercasing and trimming the input.", "primitiveType": "string", "validations": [ { "rule": "Value must match the canonical RFC pattern: 3-4 uppercase letters (including 'Ñ' or '&'), followed by 6 digits (date), 2 alphanumerics (homoclave), and a final letter or digit (check character).", "errorCode": "INVALID_FORMAT" }, { "rule": "RFC body (everything except the final check character) must be 11 or 12 characters long, yielding a total RFC length of 12 (company) or 13 (individual).", "errorCode": "INVALID_FORMAT" } ], "methods": [ { "signature": "constructor(rfc: string | RFC)", "summary": "Builds an RFC; clones if an RFC instance is supplied, otherwise uppercases, trims, and validates the input.", "throws": [ "INVALID_FORMAT" ] }, { "signature": "toString(): string", "summary": "Returns the canonical uppercase RFC string." }, { "signature": "valueOf(): string", "summary": "Returns the canonical uppercase RFC string for primitive coercion." }, { "signature": "toJSON(): string", "summary": "Serializes the value object as the canonical uppercase RFC string." } ] }, { "name": "Time", "module": "datetime", "summary": "Validates a time-of-day string in HH:MM format and returns it in canonical hour:minute form.", "primitiveType": "string", "validations": [ { "rule": "Input must contain both an hour and a minute component separated by ':' (HH:MM format).", "errorCode": "INVALID_FORMAT" }, { "rule": "Hour component must be a number between 0 and 23 inclusive.", "errorCode": "INVALID_FORMAT" }, { "rule": "Minute component must be a number between 0 and 59 inclusive.", "errorCode": "INVALID_FORMAT" } ], "methods": [ { "signature": "Time(time: string): string", "summary": "Validates the HH:MM input and returns the canonical 'hour:minute' string.", "throws": [ "INVALID_FORMAT" ] } ] }, { "name": "TimeRange", "module": "datetime", "summary": "Validates a 'HH:MM - HH:MM' time-range string and returns it in canonical 'start - end' form (collapsing to 'start - start' when no end is provided).", "primitiveType": "string", "validations": [ { "rule": "Input must contain a non-empty start time when split by '-' (HH:MM - HH:MM format).", "errorCode": "INVALID_FORMAT" } ], "methods": [ { "signature": "TimeRange(times: string): string", "summary": "Parses a '-' separated time range, trims each side, and returns the canonical 'start - end' string. When no end is given, returns 'start - start'.", "throws": [ "INVALID_FORMAT" ] } ] }, { "name": "Username", "module": "identity", "summary": "Trims and validates a username, enforcing length bounds and rejecting any whitespace.", "primitiveType": "string", "validations": [ { "rule": "Username must be between 3 and 64 characters long after trimming.", "errorCode": "INVALID_FORMAT" }, { "rule": "Username must not contain any whitespace characters.", "errorCode": "INVALID_FORMAT" } ], "methods": [ { "signature": "constructor(username: string | Username)", "summary": "Builds a Username; clones if a Username instance is supplied, otherwise trims and validates the input.", "throws": [ "INVALID_FORMAT" ] }, { "signature": "toString(): string", "summary": "Returns the canonical username string." }, { "signature": "valueOf(): string", "summary": "Returns the canonical username string for primitive coercion." }, { "signature": "toJSON(): string", "summary": "Serializes the value object as the canonical username string." } ] }, { "name": "Zipcode", "module": "identity", "summary": "Validates that a string is a Mexican 5-digit postal code (CP).", "primitiveType": "string", "validations": [ { "rule": "Value must match /^\\d{5}$/ — exactly five decimal digits, no whitespace or other characters.", "errorCode": "INVALID_ZIPCODE" } ], "methods": [ { "signature": "constructor(zipcode: string | Zipcode)", "summary": "Builds a Zipcode; clones if a Zipcode instance is supplied, otherwise trims and validates the input as a 5-digit numeric string.", "throws": [ "INVALID_ZIPCODE" ] }, { "signature": "toString(): string", "summary": "Returns the canonical zipcode string." }, { "signature": "valueOf(): string", "summary": "Returns the canonical zipcode string for primitive coercion." }, { "signature": "toJSON(): string", "summary": "Serializes the value object as the canonical zipcode string." } ] } ], "enums": [ { "name": "ApiScopes", "module": "auth", "summary": "Permission scopes assigned to API tokens to delimit which surfaces of the platform a caller may access.", "values": [ { "key": "Admin", "value": "admin", "summary": "Full administrative access to the platform's internal API surface." }, { "key": "GPSProvider", "value": "gps-provider", "summary": "External scope reserved for GPS provider integrations to push tracking data." } ] }, { "name": "ClavePedimento", "module": "carta-porte", "summary": "Mexican customs (SAT) pedimento keys identifying the customs regime under which goods enter or leave the country.", "values": [ { "key": "A1", "value": "A1", "summary": "Definitive import or export." }, { "key": "A3", "value": "A3", "summary": "Regularization of merchandise as a definitive import." }, { "key": "C1", "value": "C1", "summary": "Definitive import to the northern border strip." }, { "key": "D1", "value": "D1", "summary": "Return by substitution." }, { "key": "GC", "value": "GC", "summary": "Complementary global pedimento." }, { "key": "K1", "value": "K1", "summary": "Withdrawal of regime and return of merchandise." }, { "key": "L1", "value": "L1", "summary": "Small definitive import." }, { "key": "P1", "value": "P1", "summary": "Reshipment of merchandise from border strip or region." }, { "key": "S2", "value": "S2", "summary": "Import and export of merchandise for specific purposes." }, { "key": "T1", "value": "T1", "summary": "Import and export by qualified companies." }, { "key": "VF", "value": "VF", "summary": "Definitive import of used vehicles to the border strip." }, { "key": "VU", "value": "VU", "summary": "Definitive import of used vehicles." }, { "key": "G9", "value": "G9", "summary": "Transfer of merchandise between bonded warehouses." }, { "key": "V1", "value": "V1", "summary": "Transfer of merchandise (virtual)." }, { "key": "V2", "value": "V2", "summary": "Transfer of imported merchandise under temporary regime." }, { "key": "V5", "value": "V5", "summary": "Transfer of merchandise of qualified companies." }, { "key": "V6", "value": "V6", "summary": "Transfer of merchandise subject to quota." }, { "key": "V7", "value": "V7", "summary": "Transfers in the sugar sector (export)." }, { "key": "V9", "value": "V9", "summary": "Transfer of merchandise by donation." }, { "key": "VD", "value": "VD", "summary": "Miscellaneous virtual operations." }, { "key": "AD", "value": "AD", "summary": "Temporary import of merchandise destined for a specific use." }, { "key": "AJ", "value": "AJ", "summary": "Temporary import and export of containers and packaging." }, { "key": "BA", "value": "BA", "summary": "Temporary import and export of goods." }, { "key": "BB", "value": "BB", "summary": "Virtual export, import and returns." }, { "key": "BC", "value": "BC", "summary": "Temporary import and export of merchandise (general)." }, { "key": "BD", "value": "BD", "summary": "Temporary import and export of equipment." }, { "key": "BE", "value": "BE", "summary": "Temporary import and export of vehicles." }, { "key": "BF", "value": "BF", "summary": "Temporary export of merchandise destined for a specific use." }, { "key": "BH", "value": "BH", "summary": "Temporary import of containers, aircraft and similar assets." }, { "key": "BI", "value": "BI", "summary": "Temporary import under article 106, fraction III." }, { "key": "BM", "value": "BM", "summary": "Temporary export of merchandise for a specific purpose." }, { "key": "BO", "value": "BO", "summary": "Temporary export for repair or maintenance." }, { "key": "BP", "value": "BP", "summary": "Temporary import and export of samples or muestrarios." }, { "key": "BR", "value": "BR", "summary": "Temporary export and return of merchandise." }, { "key": "H1", "value": "H1", "summary": "Return of merchandise in the same state." }, { "key": "H8", "value": "H8", "summary": "Return of containers and packaging." }, { "key": "I1", "value": "I1", "summary": "Import, export and return of merchandise." }, { "key": "F4", "value": "F4", "summary": "Change of regime of inputs or merchandise." }, { "key": "F5", "value": "F5", "summary": "Change of regime from temporary to definitive import." }, { "key": "IN", "value": "IN", "summary": "Temporary import of goods to be subject to a process." }, { "key": "AF", "value": "AF", "summary": "Temporary import of fixed-asset goods." }, { "key": "RT", "value": "RT", "summary": "Return of merchandise under the IMMEX program." }, { "key": "A4", "value": "A4", "summary": "Introduction into bonded warehouse (AGD)." }, { "key": "E1", "value": "E1", "summary": "Extraction from bonded warehouse of goods to be processed." }, { "key": "E2", "value": "E2", "summary": "Extraction from bonded warehouse of fixed-asset goods." }, { "key": "G1", "value": "G1", "summary": "Extraction from bonded warehouse (AGD)." }, { "key": "C3", "value": "C3", "summary": "Extraction from bonded warehouse to border strip or region." }, { "key": "K2", "value": "K2", "summary": "Extraction from bonded warehouse by withdrawal." }, { "key": "A5", "value": "A5", "summary": "Introduction into bonded warehouse in authorized local site." }, { "key": "E3", "value": "E3", "summary": "Extraction from authorized-site bonded warehouse." }, { "key": "E4", "value": "E4", "summary": "Extraction from authorized-site bonded warehouse (variant)." }, { "key": "G2", "value": "G2", "summary": "Extraction from authorized-site bonded warehouse." }, { "key": "K3", "value": "K3", "summary": "Extraction from authorized-site bonded warehouse." }, { "key": "F2", "value": "F2", "summary": "Introduction into bonded warehouse (IA)." }, { "key": "F3", "value": "F3", "summary": "Extraction from bonded warehouse (IA)." }, { "key": "V3", "value": "V3", "summary": "Extraction from bonded warehouse of goods for processing." }, { "key": "V4", "value": "V4", "summary": "Virtual return derived from constancia." }, { "key": "F8", "value": "F8", "summary": "Introduction and extraction of bonded-warehouse merchandise." }, { "key": "F9", "value": "F9", "summary": "Introduction and extraction of bonded-warehouse merchandise (variant)." }, { "key": "G6", "value": "G6", "summary": "Report of bonded-warehouse extraction." }, { "key": "G7", "value": "G7", "summary": "Report of bonded-warehouse extraction (variant)." }, { "key": "V8", "value": "V8", "summary": "Transfer of merchandise in bonded warehouse." }, { "key": "M1", "value": "M1", "summary": "Introduction and export of inputs." }, { "key": "M2", "value": "M2", "summary": "Introduction and export of machinery and equipment." }, { "key": "J3", "value": "J3", "summary": "Return and export of inputs that have been processed." }, { "key": "M3", "value": "M3", "summary": "Introduction of merchandise (RFE)." }, { "key": "M4", "value": "M4", "summary": "Introduction of fixed assets (RFE)." }, { "key": "J4", "value": "J4", "summary": "Return of foreign merchandise (RFE)." }, { "key": "T3", "value": "T3", "summary": "Internal transit." }, { "key": "T6", "value": "T6", "summary": "International transit through foreign territory." }, { "key": "T7", "value": "T7", "summary": "International transit through national territory." }, { "key": "T9", "value": "T9", "summary": "International transit of transmigrants." }, { "key": "R1", "value": "R1", "summary": "Rectification of pedimentos." }, { "key": "CT", "value": "CT", "summary": "Complementary pedimento." } ] }, { "name": "CompanyRole", "module": "auth", "summary": "Role a company plays in the platform, determining whether it brokers freight or physically moves it.", "values": [ { "key": "Broker", "value": "broker", "summary": "Company that arranges drayage on behalf of shippers without operating its own trucks." }, { "key": "Carrier", "value": "carrier", "summary": "Company that physically transports the freight with its own equipment and drivers." } ] }, { "name": "CustomerPortalContainerStatus", "module": "customer-portal", "summary": "Lifecycle status of a container record created by a customer through the customer portal before it is dispatched as a drayage.", "values": [ { "key": "Draft", "value": "draft", "summary": "Container is being edited by the customer and has not been submitted yet." }, { "key": "Pending", "value": "pending", "summary": "Container has been submitted and is awaiting review or posting by operations." }, { "key": "Posted", "value": "posted", "summary": "Container has been accepted and posted as an actionable drayage." } ] }, { "name": "DrayageCSVRowCdysStatus", "module": "drayage", "summary": "Status of the CDYS (Mexican logistics integration) submission for an individual row in a bulk-uploaded drayage CSV.", "values": [ { "key": "Pending", "value": "pending", "summary": "Row is queued and has not yet been submitted to CDYS." }, { "key": "Success", "value": "success", "summary": "Row was successfully synchronized with CDYS." }, { "key": "Error", "value": "error", "summary": "CDYS rejected the row or the submission failed." }, { "key": "NA", "value": "no_apply", "summary": "Row does not require CDYS synchronization." } ] }, { "name": "DrayageCSVRowError", "module": "drayage", "summary": "Categorized validation error attached to a drayage CSV row that could not be processed.", "values": [ { "key": "InvalidPickupLocation", "value": "InvalidPickupLocation", "summary": "Pickup location supplied in the row could not be resolved or is not allowed." }, { "key": "InvalidDeliveryLocation", "value": "InvalidDeliveryLocation", "summary": "Delivery location supplied in the row could not be resolved or is not allowed." }, { "key": "InvalidReturnLocation", "value": "InvalidReturnLocation", "summary": "Empty-return location supplied in the row could not be resolved or is not allowed." }, { "key": "Unknown", "value": "Unknown", "summary": "Row failed for an unclassified reason." } ] }, { "name": "DrayageCSVRowStatus", "module": "drayage", "summary": "Processing status of an individual row in a bulk-uploaded drayage CSV.", "values": [ { "key": "Pending", "value": "pending", "summary": "Row has been parsed and is waiting to be processed." }, { "key": "Success", "value": "success", "summary": "Row was processed successfully and the corresponding drayage was created." }, { "key": "Error", "value": "error", "summary": "Row failed validation or processing and was not converted into a drayage." } ] }, { "name": "DrayageCSVStatus", "module": "drayage", "summary": "Overall status of a bulk drayage CSV upload as it moves through the ingestion pipeline.", "values": [ { "key": "Processing", "value": "processing", "summary": "CSV is currently being parsed and its rows are being processed." }, { "key": "Processed", "value": "processed", "summary": "All rows in the CSV have been processed and final per-row outcomes are available." } ] }, { "name": "DrayageGroupType", "module": "drayage", "summary": "Shape of a multi-stop drayage group, indicating whether the legs run end-to-end or close back on themselves.", "values": [ { "key": "Direct", "value": "direct", "summary": "Linear group whose legs run from origin to destination without returning to the starting point." }, { "key": "Cyclic", "value": "cyclic", "summary": "Round-trip group whose legs return to the starting point, typically for repeated equipment moves." } ] }, { "name": "DrayagePaymentMethod", "module": "payments", "summary": "Payment channel used to settle drayage-related charges with terminal or port operators.", "values": [ { "key": "HutchisonPorts", "value": "Pago-Hutchison-Ports", "summary": "Payment processed through the Hutchison Ports terminal billing channel." } ] }, { "name": "DrayageServices", "module": "drayage", "summary": "Catalogue of billable Mexican drayage service charge types that can be itemized on a drayage invoice or quote.", "values": [ { "key": "SERVICE_COST", "value": "Costo del Servicio", "summary": "Base cost of the drayage service itself." }, { "key": "GASOLINE", "value": "Gasolina", "summary": "Fuel surcharge applied to the trip." }, { "key": "CONTAINER_STORAGE", "value": "Almacenaje del contenedor o mercancia", "summary": "Charge for storing the container or its merchandise." }, { "key": "LOADING_UNLOADING", "value": "Carga o descargar carga suelta no palletizada", "summary": "Charge for loading or unloading loose, non-palletized cargo." }, { "key": "ADDITIONAL_ADDRESS_CHARGE", "value": "Cargo por entregar en una nueva direccion adicional", "summary": "Charge for delivering at an additional address beyond the agreed stop." }, { "key": "TRUCK_WEIGHTING_CHARGE", "value": "Cargo por ir a una estacion de pesaje de camiones y pesar mercancia adentro", "summary": "Charge for taking the truck to a weighing station to weigh the cargo inside." }, { "key": "OVERWEIGHT_CHARGE", "value": "Cargo por pieza que exceda el peso legal permitido", "summary": "Per-piece surcharge for cargo exceeding legal weight limits." }, { "key": "CONTAINER_HANDLING", "value": "Descargar y cargar la mercancia desde un contenedor o hacia un contenedor", "summary": "Charge for stuffing or unstuffing merchandise into or out of a container." }, { "key": "TEMPERATURE_GENERATOR", "value": "Generador de temperatura", "summary": "Charge for using a temperature-control generator (reefer)." }, { "key": "TARPAULINS", "value": "Lonas", "summary": "Charge for the use of tarpaulins to cover the load." }, { "key": "HAZARDOUS_MATERIAL", "value": "Material peligroso", "summary": "Surcharge for transporting hazardous materials." }, { "key": "TOLL", "value": "Peaje", "summary": "Toll fees incurred during the route." }, { "key": "CONTAINER_SEAL", "value": "Sello para asegurar el contenedor", "summary": "Charge for the seal used to secure the container." } ] }, { "name": "DrayageState", "module": "drayage", "summary": "Lifecycle state of a drayage shipment from creation through completion or cancellation.", "values": [ { "key": "Unpublished", "value": "unpublished", "summary": "Drayage has been drafted but is not yet visible to carriers." }, { "key": "New", "value": "new", "summary": "Drayage has just been created and not yet opened for bidding." }, { "key": "Open", "value": "open", "summary": "Drayage is published and available for carriers to bid on or accept." }, { "key": "Awarded", "value": "awarded", "summary": "A carrier has been selected and assigned to the drayage." }, { "key": "ReadyForPickup", "value": "readyForPickup", "summary": "Cargo is ready and the carrier may proceed with pickup." }, { "key": "InTransit", "value": "inTransit", "summary": "Cargo has been picked up and is currently being transported." }, { "key": "Delivered", "value": "delivered", "summary": "Cargo has reached the destination and been delivered." }, { "key": "Cancelled", "value": "cancelled", "summary": "Drayage was cancelled before completion." }, { "key": "Completed", "value": "completed", "summary": "Drayage has been fully completed including post-delivery settlement." } ] }, { "name": "DrayageTruckType", "module": "drayage", "summary": "Truck configuration used to operate a drayage shipment.", "values": [ { "key": "Single", "value": "single", "summary": "Single-unit truck capable of carrying one container." }, { "key": "Full", "value": "full", "summary": "Full configuration capable of carrying two containers (double-stack)." } ] }, { "name": "DrayageType", "module": "drayage", "summary": "Direction of a drayage shipment relative to the country of operation.", "values": [ { "key": "Import", "value": "import", "summary": "Inbound drayage moving cargo from a port or border crossing to a domestic destination." }, { "key": "Export", "value": "export", "summary": "Outbound drayage moving cargo from a domestic origin to a port or border crossing." } ] }, { "name": "EmailType", "module": "emails", "summary": "Categorization of outbound transactional emails sent by the platform.", "values": [ { "key": "ComplementoDePago", "value": "Complemento de pago", "summary": "Email delivering a Mexican CFDI 'Complemento de Pago' (payment complement) document to the recipient." } ] }, { "name": "EventTopics", "module": "events", "summary": "Pub/sub topic names used by the platform's internal event bus to route domain events between modules.", "values": [ { "key": "GPSPositions", "value": "gps-positions", "summary": "Topic carrying GPS position updates ingested from telematics providers." }, { "key": "Tracking", "value": "tracking", "summary": "Topic carrying shipment tracking stage updates." }, { "key": "DrayageCreated", "value": "drayage-created", "summary": "Topic emitted when a new drayage shipment is created." } ] }, { "name": "GPSProviderName", "module": "tracking", "summary": "Identifier of the third-party GPS / telematics provider that supplies a vehicle's position data.", "values": [ { "key": "Branix", "value": "Branix", "summary": "Branix telematics provider integration." }, { "key": "PosiTrace", "value": "PosiTrace", "summary": "PosiTrace telematics provider integration." }, { "key": "Bajatrack", "value": "Bajatrack", "summary": "Bajatrack telematics provider integration." }, { "key": "Simulator", "value": "Simulator", "summary": "Internal simulator that produces synthetic GPS positions for testing and demos." }, { "key": "Wialon", "value": "Wialon", "summary": "Wialon telematics provider integration." }, { "key": "Epcon", "value": "Epcon", "summary": "Epcon telematics provider integration." } ] }, { "name": "HazmatType", "module": "catalogue", "summary": "Classifies cargo or a shipment by its hazardous-material handling requirement.", "values": [ { "key": "Hazmat", "value": "hazmat", "summary": "Cargo is classified as hazardous and requires hazmat handling." }, { "key": "NonHazmat", "value": "non-hazmat", "summary": "Cargo is non-hazardous and can be transported with standard handling." }, { "key": "Optional", "value": "optional", "summary": "Hazmat handling is optional or shipper has not yet declared a classification." } ] }, { "name": "IANATimezones", "module": "_common", "summary": "Subset of IANA tz-database time zone identifiers used by the platform for Mexican operations; only the Mexico-relevant zones explicitly exported by this enum are listed here.", "values": [ { "key": "America_Mexico_City", "value": "America/Mexico_City", "summary": "Central Mexico time zone covering Mexico City and most of central Mexico." }, { "key": "America_Baja_California", "value": "America/Tijuana", "summary": "Baja California (Tijuana) time zone for the northwestern Pacific corridor of Mexico." }, { "key": "America_Cancun", "value": "America/Cancun", "summary": "Quintana Roo (Cancun) time zone for the southeastern Caribbean coast of Mexico." } ] }, { "name": "InvoiceDetailType", "module": "payments", "summary": "Categorises a single line on a payments invoice.", "values": [ { "key": "TransactionFee", "value": "TransactionFee", "summary": "Platform transaction fee charged on the invoice." }, { "key": "FinancingFee", "value": "FinancingFee", "summary": "Fee charged for financing the invoiced amount." }, { "key": "Shipment", "value": "Shipment", "summary": "Charge for an underlying shipment." } ] }, { "name": "MexicoTax", "module": "mexico", "summary": "Standard Mexican tax rates expressed as decimal fractions, used to compute taxes on invoices and freight charges.", "values": [ { "key": "VAT", "value": 0.16, "summary": "Standard Mexican Value Added Tax (IVA) rate of 16%." }, { "key": "ExceptionalVAT", "value": 0.08, "summary": "Reduced 8% VAT rate applied in northern and southern border tax zones." }, { "key": "Transport", "value": 0.04, "summary": "4% income tax withholding (retención de ISR) applied to freight transport services." } ] }, { "name": "MexicoTaxType", "module": "mexico", "summary": "SAT-defined tax type codes used when emitting Mexican CFDI tax entries.", "values": [ { "key": "Transport", "value": "002", "summary": "Tax applied to transportation services (SAT code 002)." } ] }, { "name": "MongoDBOperation", "module": "_common", "summary": "Identifiers for MongoDB CRUD operations used by the data-access layer to label and route queries.", "values": [ { "key": "FindOne", "value": "findOne", "summary": "Retrieve a single document matching the filter." }, { "key": "Find", "value": "find", "summary": "Retrieve multiple documents matching the filter." }, { "key": "Count", "value": "count", "summary": "Count documents matching the filter without returning them." }, { "key": "UpdateOne", "value": "updateOne", "summary": "Update the first document that matches the filter." }, { "key": "UpdateMany", "value": "updateMany", "summary": "Update every document that matches the filter." }, { "key": "InsertOne", "value": "insertOne", "summary": "Insert a single new document into the collection." }, { "key": "InsertMany", "value": "insertMany", "summary": "Insert multiple new documents into the collection." }, { "key": "DeleteOne", "value": "deleteOne", "summary": "Delete the first document that matches the filter." }, { "key": "DeleteMany", "value": "deleteMany", "summary": "Delete every document that matches the filter." }, { "key": "Aggregate", "value": "aggregate", "summary": "Run an aggregation pipeline against the collection." } ] }, { "name": "NotificationType", "module": "notifications", "summary": "Discriminator values for the real-time notifications dispatched to clients over the websocket channel.", "values": [ { "key": "DrayageCreated", "value": "createDrayage", "summary": "A new drayage shipment has been created." }, { "key": "DrayageBidAccepted", "value": "bidAcceptedDrayage", "summary": "A bid on a drayage has been accepted by the shipper." }, { "key": "DrayageBidAcceptedLog", "value": "bidAcceptedDrayageLog", "summary": "Audit-log entry recording that a drayage bid was accepted." }, { "key": "DrayageBidAcceptedChat", "value": "bidAcceptedDrayageChat", "summary": "Chat-channel notification that a drayage bid was accepted." }, { "key": "DrayagePublished", "value": "drayagePublished", "summary": "A drayage has transitioned to the published state and is now visible to carriers." }, { "key": "DrayageUpdated", "value": "drayageUpdated", "summary": "An existing drayage has been modified." }, { "key": "DrayageCSVUpdated", "value": "drayageCSVUpdated", "summary": "A drayage CSV import has been updated." }, { "key": "DrayageCSVRowUpdated", "value": "drayageCSVRowUpdated", "summary": "A single row of a drayage CSV import has changed." }, { "key": "LoadLocationCreated", "value": "loadLocationCreated", "summary": "A new load location has been registered." }, { "key": "LoadLocationUpdated", "value": "loadLocationUpdated", "summary": "An existing load location has been modified." }, { "key": "LoadLocationDeleted", "value": "loadLocationDeleted", "summary": "A load location has been removed." }, { "key": "DrayageGroupUpdated", "value": "drayageGroupUpdated", "summary": "A drayage group has been modified." }, { "key": "DrayageGroupCreated", "value": "drayageGroupCreated", "summary": "A new drayage group has been created." }, { "key": "TaskUpdated", "value": "taskUpdated", "summary": "A task has changed state or content." }, { "key": "DrayageGroupDocumentsUpdated", "value": "drayageGroupDocumentsUpdated", "summary": "Documents attached to a drayage group have been updated." }, { "key": "AuctionStartDrayage", "value": "auctionStartDrayage", "summary": "An auction for a drayage has started (shipper-side notification)." }, { "key": "AuctionStartDrayageCarrier", "value": "auctionStartDrayageCarrier", "summary": "An auction for a drayage has started (carrier-side notification)." }, { "key": "DrayagePositionUpdated", "value": "drayagePositionUpdated", "summary": "Live GPS position of a drayage has been updated." }, { "key": "TrackingDrayageLog", "value": "trackingDrayageLog", "summary": "A new tracking log entry has been recorded for a drayage." }, { "key": "DriverAssigned", "value": "driverAssigned", "summary": "A driver has been assigned to a drayage." }, { "key": "DriverReassigne", "value": "driverReassigne", "summary": "A drayage's driver has been reassigned to a different driver." } ] }, { "name": "PACCancelationReason", "module": "pac", "summary": "SAT-defined reason codes accepted by the PAC when canceling a CFDI document.", "values": [ { "key": "WithSubstitution", "value": "01", "summary": "Cancellation because the document is being replaced by another CFDI (substitution)." }, { "key": "WithoutSubstitution", "value": "02", "summary": "Cancellation without issuing a replacement CFDI." }, { "key": "OperationNotCompleted", "value": "03", "summary": "Cancellation because the underlying operation was never carried out." }, { "key": "NominativeOperation", "value": "04", "summary": "Cancellation because the operation is now covered by a global/nominative invoice." } ] }, { "name": "PACDocumentStatus", "module": "pac", "summary": "Lifecycle status of a CFDI document tracked through the PAC integration.", "values": [ { "key": "Signed", "value": "signed", "summary": "Document has been stamped and signed by the PAC and is currently valid." }, { "key": "Cancelled", "value": "cancelled", "summary": "Document has been canceled with the SAT and is no longer valid." } ] }, { "name": "PACDocumentType", "module": "pac", "summary": "PAC-specific identifiers for the kinds of CFDI documents emitted through the integration.", "values": [ { "key": "CartaPorte", "value": "CCPICV", "summary": "Carta Porte (transportation waybill) CFDI complement." }, { "key": "ComplementoPago", "value": "CMPICV", "summary": "Payment-receipt complement (Complemento de Pago) CFDI." } ] }, { "name": "PACWeightUnit", "module": "pac", "summary": "Weight-unit codes (UN/ECE Recommendation 20) accepted by the PAC for Carta Porte cargo declarations.", "values": [ { "key": "Micrograms", "value": "MC", "summary": "Micrograms." }, { "key": "Decagram", "value": "DJ", "summary": "Decagrams." }, { "key": "Kilograms", "value": "KGM", "summary": "Kilograms." }, { "key": "Ton", "value": "TNE", "summary": "Metric tons." } ] }, { "name": "PortalContainerServiceType", "module": "customer-portal", "summary": "Customer-portal scraping providers that expose container status from Mexican maritime terminals.", "values": [ { "key": "Verex", "value": "VEREX", "summary": "Veracruz terminal portal (VEREX)." }, { "key": "Lazex", "value": "LAZEX", "summary": "Lazaro Cardenas terminal portal (LAZEX)." } ] }, { "name": "ServiceNames", "module": "_common", "summary": "Stable identifiers for the external services the backend connects to, used for configuration lookup and health reporting.", "values": [ { "key": "Kafka", "value": "kafka", "summary": "Kafka message broker." }, { "key": "Branix", "value": "branix-gps-provider", "summary": "Branix GPS provider integration." }, { "key": "MasterDB", "value": "dexcarga-master-db", "summary": "Primary MongoDB cluster (Dexcarga master database)." } ] }, { "name": "SmartPortLocationType", "module": "smart-port", "summary": "Role of a stop within a SmartPort container movement.", "values": [ { "key": "Delivery", "value": "delivery", "summary": "Location where the loaded container is delivered to the consignee." }, { "key": "Return", "value": "return", "summary": "Location where the empty container is returned after delivery." } ] }, { "name": "SmartportShippingClass", "module": "smart-port", "summary": "Hazardous-material (IMDG/UN) shipping class codes accepted by the Smartport integration.", "values": [ { "key": "CLASS_3.1", "value": "3.1", "summary": "Flammable liquids subdivision 3.1." }, { "key": "CLASS_3.2", "value": "3.2", "summary": "Flammable liquids subdivision 3.2." }, { "key": "CLASS_3.3", "value": "3.3", "summary": "Flammable liquids subdivision 3.3." }, { "key": "CLASS_1.1", "value": "1.1", "summary": "Explosives division 1.1 (mass explosion hazard)." }, { "key": "CLASS_1.2", "value": "1.2", "summary": "Explosives division 1.2 (projection hazard)." }, { "key": "CLASS_1.3", "value": "1.3", "summary": "Explosives division 1.3 (fire hazard)." }, { "key": "CLASS_1.4", "value": "1.4", "summary": "Explosives division 1.4 (minor explosion hazard)." }, { "key": "CLASS_1.5", "value": "1.5", "summary": "Explosives division 1.5 (very insensitive substances)." }, { "key": "CLASS_1.6", "value": "1.6", "summary": "Explosives division 1.6 (extremely insensitive articles)." }, { "key": "CLASS_2.1", "value": "2.1", "summary": "Flammable gases (class 2.1)." }, { "key": "CLASS_2.2", "value": "2.2", "summary": "Non-flammable, non-toxic gases (class 2.2)." }, { "key": "CLASS_2.3", "value": "2.3", "summary": "Toxic gases (class 2.3)." }, { "key": "CLASS_3", "value": "3", "summary": "Flammable liquids (class 3)." }, { "key": "CLASS_4.1", "value": "4.1", "summary": "Flammable solids (class 4.1)." }, { "key": "CLASS_4.2", "value": "4.2", "summary": "Substances liable to spontaneous combustion (class 4.2)." }, { "key": "CLASS_4.3", "value": "4.3", "summary": "Substances which emit flammable gases on contact with water (class 4.3)." }, { "key": "CLASS_5.1", "value": "5.1", "summary": "Oxidizing substances (class 5.1)." }, { "key": "CLASS_5.2", "value": "5.2", "summary": "Organic peroxides (class 5.2)." }, { "key": "CLASS_6.1", "value": "6.1", "summary": "Toxic substances (class 6.1)." }, { "key": "CLASS_6.2", "value": "6.2", "summary": "Infectious substances (class 6.2)." }, { "key": "CLASS_7", "value": "7", "summary": "Radioactive material (class 7)." }, { "key": "CLASS_4", "value": "4", "summary": "Flammable solids and related materials (class 4)." }, { "key": "CLASS_2", "value": "2", "summary": "Gases (class 2)." }, { "key": "CLASS_5", "value": "5", "summary": "Oxidizing substances and organic peroxides (class 5)." }, { "key": "CLASS_1", "value": "1", "summary": "Explosives (class 1)." }, { "key": "CLASS_6", "value": "6", "summary": "Toxic and infectious substances (class 6)." }, { "key": "CLASS_61", "value": "61", "summary": "Toxic-substances supplemental code 61 (Smartport-specific)." }, { "key": "CLASS_8.1", "value": "8.1", "summary": "Corrosive substances subdivision 8.1." }, { "key": "CLASS_8", "value": "8", "summary": "Corrosive substances (class 8)." }, { "key": "CLASS_32", "value": "32", "summary": "Smartport-specific class code 32." }, { "key": "CLASS_42", "value": "42", "summary": "Smartport-specific class code 42." }, { "key": "CLASS_22", "value": "22", "summary": "Smartport-specific class code 22." }, { "key": "CLASS_11", "value": "11", "summary": "Smartport-specific class code 11." }, { "key": "CLASS_0", "value": "0", "summary": "No hazardous classification recorded (class 0)." }, { "key": "CLASS_NON", "value": "NON", "summary": "Non-hazardous cargo marker." }, { "key": "CLASS_1.3C", "value": "1.3C", "summary": "Explosives compatibility group 1.3C." }, { "key": "CLASS_1.1D", "value": "1.1D", "summary": "Explosives compatibility group 1.1D." }, { "key": "CLASS_1.4S", "value": "1.4S", "summary": "Explosives compatibility group 1.4S." }, { "key": "CLASS_COMB", "value": "COMB", "summary": "Combustible-liquid Smartport designation." }, { "key": "CLASS_1.4C", "value": "1.4C", "summary": "Explosives compatibility group 1.4C." }, { "key": "CLASS_1.2E", "value": "1.2E", "summary": "Explosives compatibility group 1.2E." }, { "key": "CLASS_9", "value": "9", "summary": "Miscellaneous dangerous substances and articles (class 9)." }, { "key": "CLASS_1.4G", "value": "1.4G", "summary": "Explosives compatibility group 1.4G." }, { "key": "CLASS_1.3G", "value": "1.3G", "summary": "Explosives compatibility group 1.3G." }, { "key": "CLASS_1.4B", "value": "1.4B", "summary": "Explosives compatibility group 1.4B." }, { "key": "CLASS_.+", "value": ".+", "summary": "Wildcard pattern preserved from upstream feed." }, { "key": "CLASS_..?", "value": "..?", "summary": "Wildcard pattern preserved from upstream feed." }, { "key": "CLASS_10", "value": "10", "summary": "Smartport-specific class code 10." }, { "key": "CLASS_12", "value": "12", "summary": "Smartport-specific class code 12." }, { "key": "CLASS_13", "value": "13", "summary": "Smartport-specific class code 13." }, { "key": "CLASS_15", "value": "15", "summary": "Smartport-specific class code 15." }, { "key": "CLASS_16", "value": "16", "summary": "Smartport-specific class code 16." }, { "key": "CLASS_3.8", "value": "3.8", "summary": "Smartport-specific flammable-liquids variant 3.8." }, { "key": "CLASS_9,0", "value": "9,0", "summary": "Smartport-specific class code 9,0 (literal upstream value)." }, { "key": "CLASS_9.2", "value": "9.2", "summary": "Smartport-specific miscellaneous-dangerous variant 9.2." }, { "key": "CLASS_98", "value": "98", "summary": "Smartport-specific class code 98." } ] }, { "name": "SmartportShippingLine", "module": "smart-port", "summary": "Three-letter SCAC-style shipping-line codes recognised by the Smartport integration.", "values": [ { "key": "ACL", "value": "ACL", "summary": "Atlantic Container Line." }, { "key": "ALI", "value": "ALI", "summary": "Smartport carrier code ALI." }, { "key": "AMS", "value": "AMS", "summary": "Smartport carrier code AMS." }, { "key": "APL", "value": "APL", "summary": "American President Lines." }, { "key": "CAG", "value": "CAG", "summary": "Smartport carrier code CAG." }, { "key": "CAS", "value": "CAS", "summary": "Smartport carrier code CAS." }, { "key": "CAT", "value": "CAT", "summary": "Smartport carrier code CAT." }, { "key": "CCI", "value": "CCI", "summary": "Smartport carrier code CCI." }, { "key": "CCL", "value": "CCL", "summary": "Smartport carrier code CCL." }, { "key": "CCN", "value": "CCN", "summary": "Smartport carrier code CCN." }, { "key": "CGM", "value": "CGM", "summary": "Smartport carrier code CGM (CMA CGM variant)." }, { "key": "CLN", "value": "CLN", "summary": "Smartport carrier code CLN." }, { "key": "CLS", "value": "CLS", "summary": "Smartport carrier code CLS." }, { "key": "CMA", "value": "CMA", "summary": "CMA shipping line." }, { "key": "CMA-CGM", "value": "CMA-CGM", "summary": "CMA CGM Group." }, { "key": "CME", "value": "CME", "summary": "Smartport carrier code CME." }, { "key": "CMM", "value": "CMM", "summary": "Smartport carrier code CMM." }, { "key": "CMN", "value": "CMN", "summary": "Smartport carrier code CMN." }, { "key": "COL", "value": "COL", "summary": "Smartport carrier code COL." }, { "key": "COR", "value": "COR", "summary": "Smartport carrier code COR." }, { "key": "COS", "value": "COS", "summary": "COSCO Shipping." }, { "key": "CPP", "value": "CPP", "summary": "Smartport carrier code CPP." }, { "key": "CPS", "value": "CPS", "summary": "Smartport carrier code CPS." }, { "key": "CSA", "value": "CSA", "summary": "Smartport carrier code CSA." }, { "key": "CSV", "value": "CSV", "summary": "Smartport carrier code CSV." }, { "key": "CTE", "value": "CTE", "summary": "Smartport carrier code CTE." }, { "key": "DCO", "value": "DCO", "summary": "Smartport carrier code DCO." }, { "key": "DEP", "value": "DEP", "summary": "Smartport carrier code DEP." }, { "key": "ECL", "value": "ECL", "summary": "Smartport carrier code ECL." }, { "key": "EMC", "value": "EMC", "summary": "Evergreen Marine Corp." }, { "key": "GLL", "value": "GLL", "summary": "Smartport carrier code GLL." }, { "key": "HAMBURG", "value": "HAMBURG", "summary": "Hamburg Süd shipping line." }, { "key": "HLC", "value": "HLC", "summary": "Hapag-Lloyd Container line code." }, { "key": "HMM", "value": "HMM", "summary": "HMM (Hyundai Merchant Marine)." }, { "key": "HSD", "value": "HSD", "summary": "Smartport carrier code HSD." }, { "key": "HSL", "value": "HSL", "summary": "Smartport carrier code HSL." }, { "key": "INT", "value": "INT", "summary": "Smartport carrier code INT." }, { "key": "ITA", "value": "ITA", "summary": "Smartport carrier code ITA." }, { "key": "IVA", "value": "IVA", "summary": "Smartport carrier code IVA." }, { "key": "LBI", "value": "LBI", "summary": "Smartport carrier code LBI." }, { "key": "LIB", "value": "LIB", "summary": "Smartport carrier code LIB." }, { "key": "LPI", "value": "LPI", "summary": "Smartport carrier code LPI." }, { "key": "LYK", "value": "LYK", "summary": "Smartport carrier code LYK." }, { "key": "MEL", "value": "MEL", "summary": "Smartport carrier code MEL." }, { "key": "MELBRIDGE", "value": "MELBRIDGE", "summary": "Melbridge shipping line." }, { "key": "MMC", "value": "MMC", "summary": "Smartport carrier code MMC." }, { "key": "MOL", "value": "MOL", "summary": "Mitsui O.S.K. Lines." }, { "key": "MOM", "value": "MOM", "summary": "Smartport carrier code MOM." }, { "key": "MPE", "value": "MPE", "summary": "Smartport carrier code MPE." }, { "key": "MSC", "value": "MSC", "summary": "Mediterranean Shipping Company." }, { "key": "MSK", "value": "MSK", "summary": "Maersk Line." }, { "key": "NAV", "value": "NAV", "summary": "Smartport carrier code NAV." }, { "key": "NAVEMAR", "value": "NAVEMAR", "summary": "Navemar shipping line." }, { "key": "NDL", "value": "NDL", "summary": "Smartport carrier code NDL." }, { "key": "NLL", "value": "NLL", "summary": "Smartport carrier code NLL." }, { "key": "NOR", "value": "NOR", "summary": "Smartport carrier code NOR." }, { "key": "NYK", "value": "NYK", "summary": "NYK Line (Nippon Yusen Kaisha)." }, { "key": "OBK", "value": "OBK", "summary": "Smartport carrier code OBK." }, { "key": "ONE", "value": "ONE", "summary": "Ocean Network Express." }, { "key": "OOCL", "value": "OOCL", "summary": "Orient Overseas Container Line." }, { "key": "OOL", "value": "OOL", "summary": "Smartport carrier code OOL." }, { "key": "PCC", "value": "PCC", "summary": "Smartport carrier code PCC." }, { "key": "PON", "value": "PON", "summary": "Smartport carrier code PON." }, { "key": "SAF", "value": "SAF", "summary": "Smartport carrier code SAF." }, { "key": "SEA", "value": "SEA", "summary": "Smartport carrier code SEA." }, { "key": "SFV", "value": "SFV", "summary": "Smartport carrier code SFV." }, { "key": "TCA", "value": "TCA", "summary": "Smartport carrier code TCA." }, { "key": "TEC", "value": "TEC", "summary": "Smartport carrier code TEC." }, { "key": "TMG", "value": "TMG", "summary": "Smartport carrier code TMG." }, { "key": "TMM", "value": "TMM", "summary": "Transportación Marítima Mexicana." }, { "key": "XXX", "value": "XXX", "summary": "Placeholder for unknown carrier." }, { "key": "YML", "value": "YML", "summary": "Yang Ming Line." }, { "key": "ZIM", "value": "ZIM", "summary": "ZIM Integrated Shipping Services." }, { "key": "ZZZ", "value": "ZZZ", "summary": "Sentinel value used at end of upstream lists." } ] }, { "name": "TaskEntityType", "module": "tasks", "summary": "Identifies the kind of domain entity an asynchronous task targets.", "values": [ { "key": "Drayage", "value": "drayage", "summary": "Task operates on a single drayage shipment." }, { "key": "DrayageGroup", "value": "drayage-group", "summary": "Task operates on a group of drayage shipments." } ] }, { "name": "TaskStatus", "module": "tasks", "summary": "Lifecycle state of an asynchronous task.", "values": [ { "key": "Pending", "value": "pending", "summary": "Task is queued and has not started yet." }, { "key": "Processing", "value": "processing", "summary": "Task is currently being executed." }, { "key": "Success", "value": "success", "summary": "Task finished successfully." }, { "key": "Failed", "value": "failed", "summary": "Task finished with an error." } ] }, { "name": "TaskType", "module": "tasks", "summary": "Discriminator for the kind of work an asynchronous task performs.", "values": [ { "key": "DrayageGroupSetCarrier", "value": "drayage-group-set-carrier", "summary": "Assigns a carrier to every drayage in a drayage group." } ] }, { "name": "TokenType", "module": "auth", "summary": "Discriminator for short-lived signed tokens issued by the auth module.", "values": [ { "key": "CustomerPortalInvitation", "value": "customer-portal:invitation", "summary": "Single-user invitation to the customer portal." }, { "key": "CustomerPortalCompanyInvitation", "value": "customer-portal:company-invitation", "summary": "Company-scoped invitation to the customer portal." } ] }, { "name": "TrackingStage", "module": "tracking", "summary": "Stage of a shipment along its pickup-to-delivery tracking lifecycle.", "values": [ { "key": "None", "value": "none", "summary": "No tracking activity has occurred yet." }, { "key": "PickingUp", "value": "pickup", "summary": "Driver is at the pickup location." }, { "key": "InRoadToDelivery", "value": "pickup:leave", "summary": "Driver has left pickup and is en route to the delivery location." }, { "key": "Delivering", "value": "delivery", "summary": "Driver is at the delivery location." }, { "key": "Delivered", "value": "delivery:leave", "summary": "Driver has left the delivery location after dropping the load." }, { "key": "Returning", "value": "return", "summary": "Driver is returning the empty container or equipment." }, { "key": "Completed", "value": "delivered", "summary": "Tracking is closed and the shipment is fully completed." } ] }, { "name": "TrackingStageUpdateSource", "module": "tracking", "summary": "Channel that produced a tracking-stage update.", "values": [ { "key": "WebApp", "value": "WebApp", "summary": "Update originated from the dexcarga web application." }, { "key": "ChatBot", "value": "ChatBot", "summary": "Update originated from the chat-bot integration." } ] }, { "name": "UserAccessLevel", "module": "auth", "summary": "Permission tier of a user inside their company.", "values": [ { "key": "Admin", "value": "admin", "summary": "Full administrative privileges within the company." }, { "key": "User", "value": "user", "summary": "Standard, non-administrative access." } ] }, { "name": "UserRole", "module": "auth", "summary": "Business role a user plays inside the dexcarga platform.", "values": [ { "key": "Carrier", "value": "carrier", "summary": "Trucking company that moves freight." }, { "key": "Shipper", "value": "shipper", "summary": "Owner of the freight that needs to be moved." }, { "key": "Broker", "value": "broker", "summary": "Intermediary that arranges freight between shippers and carriers." }, { "key": "Driver", "value": "driver", "summary": "Operator who physically drives a load." }, { "key": "Customer", "value": "customer", "summary": "Customer-portal end user (typically the shipper's client)." } ] }, { "name": "WeightUnits", "module": "_common", "summary": "Unit of measure used for weight values across the platform.", "values": [ { "key": "Kilograms", "value": "KG", "summary": "Kilograms." }, { "key": "Pounds", "value": "LB", "summary": "Pounds." }, { "key": "Tons", "value": "TON", "summary": "Metric tons." } ] } ], "interfaces": [ { "name": "AcceptCustomerInvitation", "module": "companies", "summary": "Payload used by a customer to accept the invitation to be linked to another company.", "shape": "interface AcceptCustomerInvitation {\n\tcustomerId: string;\n}", "fields": [ { "name": "customerId", "type": "string", "summary": "Identifier of the pending customer record being accepted." } ], "usage": [] }, { "name": "Accessorials", "module": "drayage", "summary": "Per-company accessorial preset listing the accessorial codes a user/company has configured.", "shape": "interface Accessorials{\n companyId: any //is ObjectId\n userId: any //is ObjectId\n accessorials: Array;\n}", "fields": [ { "name": "companyId", "type": "ObjectId", "summary": "Company that owns the accessorial preset." }, { "name": "userId", "type": "ObjectId", "summary": "User that authored the preset." }, { "name": "accessorials", "type": "Array", "summary": "List of accessorial codes." } ], "usage": [] }, { "name": "AndroidPushNotification", "module": "notifications", "summary": "FCM push payload sent to Android devices, with title, body and free-form data.", "shape": "interface AndroidPushNotification {\n title: string;\n body: string;\n data: any;\n}", "fields": [ { "name": "title", "type": "string", "summary": "Title shown in the Android notification." }, { "name": "body", "type": "string", "summary": "Body text of the notification." }, { "name": "data", "type": "any", "summary": "Custom data payload delivered to the app." } ], "usage": [] }, { "name": "ApplePushNotification", "module": "notifications", "summary": "APNs push payload sent to iOS devices, with optional shipment and chat metadata.", "shape": "interface ApplePushNotification {\n title: string;\n body?: string;\n payload?: {\n messageFrom?: string;\n shipmentId?: string;\n };\n topic: string;\n}", "fields": [ { "name": "title", "type": "string", "summary": "Title shown in the iOS notification." }, { "name": "body", "type": "string", "summary": "Body text of the notification.", "optional": true }, { "name": "payload", "type": "{ messageFrom?: string; shipmentId?: string; }", "summary": "Custom payload attached to the notification (chat sender, shipment).", "optional": true }, { "name": "topic", "type": "string", "summary": "APNs topic (typically the iOS app bundle identifier)." } ], "usage": [] }, { "name": "BankAccount", "module": "payments", "summary": "ACH bank account information used for sending or receiving payments.", "shape": "interface BankAccount {\n routingNumber: string;\n accountNumber: string;\n bankAccountType: string;\n name: string;\n}", "fields": [ { "name": "routingNumber", "type": "string", "summary": "ABA routing number identifying the bank." }, { "name": "accountNumber", "type": "string", "summary": "Bank account number." }, { "name": "bankAccountType", "type": "string", "summary": "Account type, e.g. checking or savings." }, { "name": "name", "type": "string", "summary": "Account holder name as registered at the bank." } ], "usage": [] }, { "name": "BidInfo", "module": "negotiations", "summary": "Bid submitted by a counterparty during a drayage negotiation, with services, accessorials, payment terms and references to the originating cost preset.", "shape": "interface BidInfo {\n id?: string;\n services: {\n type: string;\n units: string;\n rate: number;\n qty: number;\n accepted: boolean;\n freeHours?: number;\n isOtherService?: boolean;\n }[];\n otherServices: {\n type: string;\n units: string;\n rate: number;\n qty: number;\n accepted: boolean;\n }[];\n costPresetID?: ID;\n method?: string;\n terms?: string;\n invoice_number?: string;\n companyId?: ID;\n userId?: ID;\n}", "fields": [ { "name": "id", "type": "string", "summary": "Optional bid identifier.", "optional": true }, { "name": "services", "type": "Array<{ type: string; units: string; rate: number; qty: number; accepted: boolean; freeHours?: number; isOtherService?: boolean; }>", "summary": "Primary service lines with rate, quantity and acceptance flag." }, { "name": "otherServices", "type": "Array<{ type: string; units: string; rate: number; qty: number; accepted: boolean; }>", "summary": "Additional accessorial service lines included in the bid." }, { "name": "costPresetID", "type": "ID", "summary": "Cost preset the bid was generated from.", "optional": true }, { "name": "method", "type": "string", "summary": "Proposed payment method.", "optional": true }, { "name": "terms", "type": "string", "summary": "Proposed payment terms.", "optional": true }, { "name": "invoice_number", "type": "string", "summary": "Invoice number assigned to the bid.", "optional": true }, { "name": "companyId", "type": "ID", "summary": "Company submitting the bid.", "optional": true }, { "name": "userId", "type": "ID", "summary": "User submitting the bid.", "optional": true } ], "usage": [] }, { "name": "Carrier", "module": "users", "summary": "User specialization for carrier accounts, adding USDOT identifiers and owner-operator flag.", "shape": "interface Carrier extends User {\n mcNumber: string;\n dotNumber: string;\n isOwnerOperator: boolean;\n}", "fields": [ { "name": "mcNumber", "type": "string", "summary": "Motor Carrier (MC) number issued by FMCSA." }, { "name": "dotNumber", "type": "string", "summary": "USDOT number issued by FMCSA." }, { "name": "isOwnerOperator", "type": "boolean", "summary": "Whether the carrier operates as an owner-operator (single-truck) entity." } ], "usage": [] }, { "name": "CarrierBidDate", "module": "negotiations", "summary": "Carrier-supplied pickup and delivery dates submitted alongside a bid on a shipment.", "shape": "interface CarrierBidDate {\n carrierId: any //is ObjectId\n shipmentId: any //is ObjectId\n pickup: Date;\n delivered: Date;\n}", "fields": [ { "name": "carrierId", "type": "ObjectId", "summary": "Carrier company submitting the bid." }, { "name": "shipmentId", "type": "ObjectId", "summary": "Shipment being bid on." }, { "name": "pickup", "type": "Date", "summary": "Proposed pickup date." }, { "name": "delivered", "type": "Date", "summary": "Proposed delivery date." } ], "usage": [] }, { "name": "CategoryCreate", "module": "drayage", "summary": "Category bucket inside a cost preset, holding either flat costs or typed cost groups.", "shape": "interface CategoryCreate {\n category: COST_CATEGORY,\n costs?: CostCreate[] | null | undefined;\n types?: TypesCreate[] | null | undefined;\n}", "fields": [ { "name": "category", "type": "COST_CATEGORY", "summary": "Cost category from the COST_CATEGORY enum." }, { "name": "costs", "type": "CostCreate[] | null | undefined", "summary": "Flat list of cost lines in this category.", "optional": true }, { "name": "types", "type": "TypesCreate[] | null | undefined", "summary": "Typed cost subgroups for categories that need a sub-classification.", "optional": true } ], "usage": [] }, { "name": "CentrifugeWebhook", "module": "integrations", "summary": "Webhook payload received from the Centrifuge protocol describing a document event between two on-chain accounts.", "shape": "interface CentrifugeWebhook {\n account_id: string;\n document_id: string;\n document_type: string;\n event_type: number;\n from_id: string;\n message: string;\n recorded: string;\n status: string;\n to_id: string;\n}", "fields": [ { "name": "account_id", "type": "string", "summary": "Centrifuge account identifier receiving the webhook." }, { "name": "document_id", "type": "string", "summary": "Identifier of the document the event refers to." }, { "name": "document_type", "type": "string", "summary": "Type of document (e.g. invoice, BOL)." }, { "name": "event_type", "type": "number", "summary": "Numeric event type code." }, { "name": "from_id", "type": "string", "summary": "Account identifier originating the event." }, { "name": "message", "type": "string", "summary": "Human-readable message attached to the event." }, { "name": "recorded", "type": "string", "summary": "Timestamp at which Centrifuge recorded the event." }, { "name": "status", "type": "string", "summary": "Status of the event." }, { "name": "to_id", "type": "string", "summary": "Account identifier destination of the event." } ], "usage": [] }, { "name": "ComplementoPago", "module": "carta-porte", "summary": "CFDI 4.0 Complemento de Pagos payload sent to the PAC, accounting for a partial or full payment against a previously issued CFDI.", "shape": "interface ComplementoPago {\n Version: string;\n Folio: string;\n Fecha: string;\n TipoDeComprobante: string;\n LugarExpedicion: string;\n Moneda: string;\n SubTotal: number;\n Total: number;\n Exportacion: string;\n CfdiRelacionados?: [{ TipoRelacion: \"04\", CfdiRelacionado: [{ UUID: string }] }];\n Emisor: { ... };\n Receptor: { ... };\n Conceptos: { ... }[];\n Impuestos?: { ... };\n Complemento: { Pagos: { Version: string; Totales: { ... }; Pago: { ... }[] } }\n}", "fields": [ { "name": "Version", "type": "string", "summary": "CFDI version (4.0)." }, { "name": "Folio", "type": "string", "summary": "Internal folio identifier." }, { "name": "Fecha", "type": "string", "summary": "ISO date of the payment CFDI." }, { "name": "TipoDeComprobante", "type": "string", "summary": "CFDI document type ('P' for pago)." }, { "name": "LugarExpedicion", "type": "string", "summary": "Postal code of the issuance location." }, { "name": "Moneda", "type": "string", "summary": "Currency code." }, { "name": "SubTotal", "type": "number", "summary": "Pre-tax subtotal (typically 0 for pago)." }, { "name": "Total", "type": "number", "summary": "Total amount (typically 0 for pago)." }, { "name": "Exportacion", "type": "string", "summary": "SAT export classifier code." }, { "name": "CfdiRelacionados", "type": "[{ TipoRelacion: \"04\", CfdiRelacionado: [{ UUID: string }] }]", "summary": "CFDI substitution links.", "optional": true }, { "name": "Emisor", "type": "{ RegimenFiscal: string; Rfc: string; Nombre: string; Domicilio: { ... }; }", "summary": "Issuer fiscal data." }, { "name": "Receptor", "type": "{ Rfc: string; UsoCFDI: string; Nombre: string; RegimenFiscalReceptor: string; DomicilioFiscalReceptor: string; Domicilio: { ... }; Email: string; }", "summary": "Receiver fiscal data." }, { "name": "Conceptos", "type": "{ ClaveProdServ: string; Cantidad: string; Descripcion: string; ValorUnitario: number; Importe: number; ClaveUnidad?: string; ObjetoImp?: string; }[]", "summary": "Concept line items (typically a single 'pago' line)." }, { "name": "Impuestos", "type": "{ TotalImpuestosRetenidos?: string; TotalImpuestosTrasladados?: string; Retenciones?: { Impuesto?: string; Importe?: string; }[]; Traslados?: { Base?: string; Impuesto?: string; TipoFactor?: string; TasaOCuota?: string; Importe?: string; }[]; }", "summary": "Document-level tax totals.", "optional": true }, { "name": "Complemento", "type": "{ Pagos: { Version: string; Totales: { TotalRetencionesIVA: string; TotalTrasladosBaseIVA16: string; TotalTrasladosImpuestoIVA16: string; TotalTrasladosBaseIVA8?: string; TotalTrasladosImpuestoIVA8?: string; MontoTotalPagos: string; }; Pago: { FechaPago: string; FormaDePagoP: string; MonedaP: string; Monto: string; TipoCambioP: string; DoctoRelacionado: { ... }[]; ImpuestosP?: ...; }[]; } }", "summary": "Pagos 2.0 complement with totals and payment-by-payment breakdown." } ], "usage": [] }, { "name": "Container", "module": "drayage", "summary": "Single container moved on a drayage, holding equipment specs, hazmat data, stages, driver assignment and Mexico-specific information.", "shape": "interface Container {\n _id?: any //is ObjectId\n drayageId?: any //is ObjectId\n size: string;\n equipment: string;\n totalWeight?: number;\n hazmat?: boolean;\n hazardousMaterial?: HazardInfo;\n loadDescription?: string;\n temperature?: TemperatureInfo;\n oggCheck?: boolean;\n oog?: OogInfo;\n sealNumbers?: string | string[];\n containerNumber?: string;\n shippingLineInformation?: ShippingInfo;\n\n position?: number;\n driverId?: any //is ObjectId\n stages?: Stage[];\n currentStage?: string;\n delivered?: boolean;\n active?: boolean;\n sendSms?: boolean;\n stop?: boolean;\n currentDriver?: any; //is ObjectId\n quantity?: number;\n descPackaging?: string;\n\n units?: number;\n weight?: number;\n grossWeight?: number;\n informationMexico?: InformationMexico[];\n}", "fields": [ { "name": "_id", "type": "ObjectId", "summary": "Container identifier.", "optional": true }, { "name": "drayageId", "type": "ObjectId", "summary": "Parent drayage identifier.", "optional": true }, { "name": "size", "type": "string", "summary": "Container size, e.g. 20, 40, 45." }, { "name": "equipment", "type": "string", "summary": "Container equipment type, e.g. Standard, High Cube, Reefer." }, { "name": "totalWeight", "type": "number", "summary": "Total weight of the container payload.", "optional": true }, { "name": "hazmat", "type": "boolean", "summary": "Whether the container carries hazardous materials.", "optional": true }, { "name": "hazardousMaterial", "type": "HazardInfo", "summary": "Detailed hazardous material classification when hazmat is true.", "optional": true }, { "name": "loadDescription", "type": "string", "summary": "Free-form description of the load.", "optional": true }, { "name": "temperature", "type": "TemperatureInfo", "summary": "Temperature requirements for reefer containers.", "optional": true }, { "name": "oggCheck", "type": "boolean", "summary": "Whether the load is out-of-gauge and needs OOG dimensions.", "optional": true }, { "name": "oog", "type": "OogInfo", "summary": "Out-of-gauge dimensions of the load.", "optional": true }, { "name": "sealNumbers", "type": "string | string[]", "summary": "Container seal number(s).", "optional": true }, { "name": "containerNumber", "type": "string", "summary": "Container number assigned by the steamship line.", "optional": true }, { "name": "shippingLineInformation", "type": "ShippingInfo", "summary": "Per-container shipping line booking and vessel info.", "optional": true }, { "name": "position", "type": "number", "summary": "Ordering position of the container inside the drayage.", "optional": true }, { "name": "driverId", "type": "ObjectId", "summary": "Driver assigned to move this container.", "optional": true }, { "name": "stages", "type": "Stage[]", "summary": "Operational stages tracking pickup, delivery and return.", "optional": true }, { "name": "currentStage", "type": "string", "summary": "Identifier of the stage currently active.", "optional": true }, { "name": "delivered", "type": "boolean", "summary": "Whether the container has been delivered.", "optional": true }, { "name": "active", "type": "boolean", "summary": "Whether the container is active inside the drayage.", "optional": true }, { "name": "sendSms", "type": "boolean", "summary": "Whether to send SMS notifications for this container.", "optional": true }, { "name": "stop", "type": "boolean", "summary": "Whether to halt operations on this container.", "optional": true }, { "name": "currentDriver", "type": "ObjectId", "summary": "Driver currently moving the container.", "optional": true }, { "name": "quantity", "type": "number", "summary": "Quantity of items inside the container.", "optional": true }, { "name": "descPackaging", "type": "string", "summary": "Packaging description.", "optional": true }, { "name": "units", "type": "number", "summary": "Units of merchandise.", "optional": true }, { "name": "weight", "type": "number", "summary": "Net weight of merchandise.", "optional": true }, { "name": "grossWeight", "type": "number", "summary": "Gross weight including packaging.", "optional": true }, { "name": "informationMexico", "type": "InformationMexico[]", "summary": "Mexico CFDI/Carta-Porte specific fields per merchandise.", "optional": true } ], "usage": [] }, { "name": "CostCreate", "module": "drayage", "summary": "Single cost line inside a preset category, with cost name, unit, value and active flag.", "shape": "interface CostCreate {\n cost: COST_NAME;\n unit: COST_UNIT;\n value: number;\n isActive: boolean;\n}", "fields": [ { "name": "cost", "type": "COST_NAME", "summary": "Cost line name from the COST_NAME enum." }, { "name": "unit", "type": "COST_UNIT", "summary": "Unit of measure from the COST_UNIT enum." }, { "name": "value", "type": "number", "summary": "Monetary value charged per unit." }, { "name": "isActive", "type": "boolean", "summary": "Whether the cost line is currently active in the preset." } ], "usage": [] }, { "name": "CreateCustomer", "module": "companies", "summary": "Payload describing a customer company being created from another company's portal, with billing-address fields.", "shape": "interface CreateCustomer {\n\tcompanyName: string;\n\n\tfullName: string;\n\temail: string;\n\n\tphone?: string;\n\taddress?: string;\n\tzipCode?: string;\n\tcity?: string;\n\tstate?: string;\n}", "fields": [ { "name": "companyName", "type": "string", "summary": "Legal or commercial name of the customer company." }, { "name": "fullName", "type": "string", "summary": "Full name of the primary customer contact." }, { "name": "email", "type": "string", "summary": "Primary email of the customer contact." }, { "name": "phone", "type": "string", "summary": "Customer contact phone number.", "optional": true }, { "name": "address", "type": "string", "summary": "Street address of the customer.", "optional": true }, { "name": "zipCode", "type": "string", "summary": "Postal/ZIP code of the customer.", "optional": true }, { "name": "city", "type": "string", "summary": "City of the customer.", "optional": true }, { "name": "state", "type": "string", "summary": "State or province of the customer.", "optional": true } ], "usage": [] }, { "name": "DataComplementoPago", "module": "carta-porte", "summary": "Internal payment-tracking record used to build a Complemento de Pago CFDI from an installment.", "shape": "interface DataComplementoPago {\n uniqueId: string;\n fechaPago: Date;\n formaPago: string;\n monto: string;\n importeSaldoAnte: string;\n importePagado: string;\n NoParcialidad: string;\n}", "fields": [ { "name": "uniqueId", "type": "string", "summary": "Internal identifier of the payment installment." }, { "name": "fechaPago", "type": "Date", "summary": "Date the payment was received." }, { "name": "formaPago", "type": "string", "summary": "SAT payment form code." }, { "name": "monto", "type": "string", "summary": "Total amount of the payment." }, { "name": "importeSaldoAnte", "type": "string", "summary": "Outstanding balance before this payment." }, { "name": "importePagado", "type": "string", "summary": "Amount applied with this installment." }, { "name": "NoParcialidad", "type": "string", "summary": "Sequential installment number." } ], "usage": [] }, { "name": "Discount", "module": "payments", "summary": "Single discount line applied to an invoice or quote, with description and value amount.", "shape": "interface Discount {\n _id?: string;\n description: string;\n value: number;\n}", "fields": [ { "name": "_id", "type": "string", "summary": "Optional identifier of the discount entry.", "optional": true }, { "name": "description", "type": "string", "summary": "Human-readable description of the discount." }, { "name": "value", "type": "number", "summary": "Monetary amount of the discount." } ], "usage": [] }, { "name": "DocumentInfo", "module": "documents", "summary": "Single document entry inside a DocumentSetup, holding type, version, signature URLs and review state.", "shape": "interface DocumentInfo {\n type: string,\n version: number,\n accepted: boolean,\n declined: boolean,\n repliedAt: Date,\n comment: string,\n accepted_url: URL,\n url: URL,\n data: any;\n}", "fields": [ { "name": "type", "type": "string", "summary": "Document type code (e.g. BOL, POD, contract)." }, { "name": "version", "type": "number", "summary": "Monotonically increasing version of the document." }, { "name": "accepted", "type": "boolean", "summary": "Whether the counterparty has accepted this document." }, { "name": "declined", "type": "boolean", "summary": "Whether the counterparty has declined this document." }, { "name": "repliedAt", "type": "Date", "summary": "Timestamp at which the counterparty replied to the document." }, { "name": "comment", "type": "string", "summary": "Free-form comment entered when accepting or declining the document." }, { "name": "accepted_url", "type": "URL", "summary": "URL of the signed/accepted version of the document." }, { "name": "url", "type": "URL", "summary": "URL of the document being reviewed." }, { "name": "data", "type": "any", "summary": "Free-form payload associated with the document." } ], "usage": [] }, { "name": "DocumentSetup", "module": "documents", "summary": "Two-sided document workspace tracking the carrier and shipper acceptance state plus the documents each side has uploaded for a shipment.", "shape": "interface DocumentSetup {\n carrierCompany: any //is ObjectId\n shipperCompany: any //is ObjectId\n\n carrier_accepted: boolean;\n shipper_accepted: boolean;\n \n shipment: ID; \n carrier_docs: DocumentInfo[];\n shipper_docs: DocumentInfo[];\n}", "fields": [ { "name": "carrierCompany", "type": "ObjectId", "summary": "Company acting as carrier in this document setup." }, { "name": "shipperCompany", "type": "ObjectId", "summary": "Company acting as shipper in this document setup." }, { "name": "carrier_accepted", "type": "boolean", "summary": "Whether the carrier has accepted the document setup." }, { "name": "shipper_accepted", "type": "boolean", "summary": "Whether the shipper has accepted the document setup." }, { "name": "shipment", "type": "ID", "summary": "Shipment to which this document setup belongs." }, { "name": "carrier_docs", "type": "DocumentInfo[]", "summary": "Documents required from or supplied by the carrier side." }, { "name": "shipper_docs", "type": "DocumentInfo[]", "summary": "Documents required from or supplied by the shipper side." } ], "usage": [] }, { "name": "Domicilio", "module": "carta-porte", "summary": "Mexican fiscal address used in CFDI emisor/receptor blocks, with street, numbers, locality and postal code.", "shape": "interface Domicilio {\n calle: string;\n noExterior: string;\n noInterior: string;\n colonia: string;\n municipio: string;\n estado: string;\n pais: string;\n codigoPostal: string;\n}", "fields": [ { "name": "calle", "type": "string", "summary": "Street name." }, { "name": "noExterior", "type": "string", "summary": "Exterior street number." }, { "name": "noInterior", "type": "string", "summary": "Interior street number." }, { "name": "colonia", "type": "string", "summary": "Neighborhood (colonia)." }, { "name": "municipio", "type": "string", "summary": "Municipality." }, { "name": "estado", "type": "string", "summary": "State or federal entity." }, { "name": "pais", "type": "string", "summary": "Country." }, { "name": "codigoPostal", "type": "string", "summary": "Postal code." } ], "usage": [] }, { "name": "DomicilioUbicacion", "module": "carta-porte", "summary": "Address sub-block used inside Carta Porte Ubicaciones, capitalized to match the SAT XSD field naming.", "shape": "interface DomicilioUbicacion {\n Estado: string;\n Pais: string;\n CodigoPostal: string;\n Calle: string;\n NumeroExterior: string;\n NumeroInterior: string;\n Colonia: string;\n Localidad: string;\n Municipio: string;\n Ubicacion: string;\n}", "fields": [ { "name": "Estado", "type": "string", "summary": "State or federal entity." }, { "name": "Pais", "type": "string", "summary": "Country." }, { "name": "CodigoPostal", "type": "string", "summary": "Postal code." }, { "name": "Calle", "type": "string", "summary": "Street name." }, { "name": "NumeroExterior", "type": "string", "summary": "Exterior street number." }, { "name": "NumeroInterior", "type": "string", "summary": "Interior street number." }, { "name": "Colonia", "type": "string", "summary": "Neighborhood (colonia)." }, { "name": "Localidad", "type": "string", "summary": "Locality." }, { "name": "Municipio", "type": "string", "summary": "Municipality." }, { "name": "Ubicacion", "type": "string", "summary": "Free-form location reference." } ], "usage": [] }, { "name": "DrayageCreate", "module": "drayage", "summary": "Payload accepted when posting a new drayage shipment, bundling locations, containers, payment, additional services and integration metadata.", "shape": "interface DrayageCreate {\n type: string;\n location: LocationInfo;\n state?: string;\n additionalServices?: AdditionalServicesInfo;\n payment: PaymentInfo;\n comments?: string;\n containerDetails: Container[];\n brokerReferenceID?: string;\n carrierReferenceID?: string;\n hubspotDeals?: DealDrayage[];\n customer?: string;\n typeofTruck?: string;\n agreedRate?: DrayageCreateAgreedRate;\n importExcel?: boolean;\n folioid?: string;\n importedWithCarrier?: boolean;\n detailMexico?: detailMexico;\n customerPortalContainerId?: string;\n drayageGroupId?: string;\n}", "fields": [ { "name": "type", "type": "string", "summary": "Drayage type code (e.g. import, export)." }, { "name": "location", "type": "LocationInfo", "summary": "Pickup, delivery and optional return locations." }, { "name": "state", "type": "string", "summary": "Initial business state of the drayage.", "optional": true }, { "name": "additionalServices", "type": "AdditionalServicesInfo", "summary": "Optional warehouse, transload and storage services.", "optional": true }, { "name": "payment", "type": "PaymentInfo", "summary": "Open payment terms, services and accessorials." }, { "name": "comments", "type": "string", "summary": "Free-form comments attached to the drayage.", "optional": true }, { "name": "containerDetails", "type": "Container[]", "summary": "List of containers being moved on this drayage." }, { "name": "brokerReferenceID", "type": "string", "summary": "Broker-side external reference identifier.", "optional": true }, { "name": "carrierReferenceID", "type": "string", "summary": "Carrier-side external reference identifier.", "optional": true }, { "name": "hubspotDeals", "type": "DealDrayage[]", "summary": "Linked HubSpot deals for CRM tracking.", "optional": true }, { "name": "customer", "type": "string", "summary": "Customer company identifier the drayage is billed to.", "optional": true }, { "name": "typeofTruck", "type": "string", "summary": "Truck type required for this drayage.", "optional": true }, { "name": "agreedRate", "type": "DrayageCreateAgreedRate", "summary": "Pre-negotiated rate sheet to lock at creation time.", "optional": true }, { "name": "importExcel", "type": "boolean", "summary": "Flag set when the drayage is imported via the Excel uploader.", "optional": true }, { "name": "folioid", "type": "string", "summary": "External folio identifier from a third-party system.", "optional": true }, { "name": "importedWithCarrier", "type": "boolean", "summary": "Whether the import already binds a carrier to the drayage.", "optional": true }, { "name": "detailMexico", "type": "detailMexico", "summary": "Mexico-specific compliance and operational details.", "optional": true }, { "name": "customerPortalContainerId", "type": "string", "summary": "Identifier of the originating customer-portal container.", "optional": true }, { "name": "drayageGroupId", "type": "string", "summary": "Identifier of the drayage group this shipment belongs to.", "optional": true } ], "usage": [] }, { "name": "DrayageRateCreate", "module": "drayage", "summary": "Payload used to create a recurring drayage rate sheet between a broker and a carrier, including supporting documents and per-lane rate definitions.", "shape": "interface DrayageRateCreate {\n brokerCompanyId: string;\n carrierCompanyId: string;\n brokerId: string;\n documents?: DrayageRateDocuments[];\n rates: DrayageRateInfo[];\n}", "fields": [ { "name": "brokerCompanyId", "type": "string", "summary": "Broker company that owns the rate sheet." }, { "name": "carrierCompanyId", "type": "string", "summary": "Carrier company the rate sheet applies to." }, { "name": "brokerId", "type": "string", "summary": "Broker user authoring the rate sheet." }, { "name": "documents", "type": "DrayageRateDocuments[]", "summary": "Supporting documents (contracts, addenda) attached to the rate sheet.", "optional": true }, { "name": "rates", "type": "DrayageRateInfo[]", "summary": "Per-lane rate entries with pickup/delivery/return information and charges." } ], "usage": [] }, { "name": "DrayageRateInfo", "module": "drayage", "summary": "Single rate-sheet lane definition with origin/destination/return locations, booking type, total price, expiration date and per-line charges.", "shape": "interface DrayageRateInfo {\n _id?: any;\n isActive?: boolean;\n pickUpInfo?: DrayageLocationInfo;\n deliveryInfo?: DrayageLocationInfo;\n returnInfo?: DrayageLocationInfo;\n bookingType?: string;\n totalRatePrice?: number;\n expirationDate?: Date;\n charges?: DrayageRateCharges[];\n temporalCharges?: DrayageRateCharges[];\n name?: string;\n}", "fields": [ { "name": "_id", "type": "any", "summary": "Optional identifier of the rate entry.", "optional": true }, { "name": "isActive", "type": "boolean", "summary": "Whether the rate entry is currently active.", "optional": true }, { "name": "pickUpInfo", "type": "DrayageLocationInfo", "summary": "Pickup location for the lane.", "optional": true }, { "name": "deliveryInfo", "type": "DrayageLocationInfo", "summary": "Delivery location for the lane.", "optional": true }, { "name": "returnInfo", "type": "DrayageLocationInfo", "summary": "Return-yard location for the lane.", "optional": true }, { "name": "bookingType", "type": "string", "summary": "Booking type associated with the lane.", "optional": true }, { "name": "totalRatePrice", "type": "number", "summary": "Total agreed rate for the lane.", "optional": true }, { "name": "expirationDate", "type": "Date", "summary": "Date after which the rate is no longer valid.", "optional": true }, { "name": "charges", "type": "DrayageRateCharges[]", "summary": "Permanent charges applied to the lane.", "optional": true }, { "name": "temporalCharges", "type": "DrayageRateCharges[]", "summary": "Temporary surcharges (fuel, congestion) applied to the lane.", "optional": true }, { "name": "name", "type": "string", "summary": "Optional display name for the lane.", "optional": true } ], "usage": [] }, { "name": "Driver", "module": "users", "summary": "User specialization for driver accounts, holding license, physical attributes and Mexico-specific tax data.", "shape": "interface Driver extends User {\n license?: {\n id: string;\n expiration: string;\n location: string;\n }\n borndate?: Date;\n address?: string;\n height?: { ft: number; in: number };\n mexicoInformation?: {\n figureType?: {\n keyFigureType?: string;\n description?: string;\n };\n rfc?: string;\n }\n}", "fields": [ { "name": "license", "type": "{ id: string; expiration: string; location: string; }", "summary": "Driver license identifier, expiration date and issuing location.", "optional": true }, { "name": "borndate", "type": "Date", "summary": "Date of birth of the driver.", "optional": true }, { "name": "address", "type": "string", "summary": "Residential address of the driver.", "optional": true }, { "name": "height", "type": "{ ft: number; in: number }", "summary": "Driver height in feet and inches.", "optional": true }, { "name": "mexicoInformation", "type": "{ figureType?: { keyFigureType?: string; description?: string; }; rfc?: string; }", "summary": "Mexico SAT tax figure type and RFC for the driver.", "optional": true } ], "usage": [] }, { "name": "DriverPosition", "module": "tracking", "summary": "Position ping reported by a driver for a shipment, tagged with capture and server timestamps.", "shape": "interface DriverPosition {\n shipmentId: string;\n timestamp: Date;\n serverTimestamp: Date;\n position: Geoposition;\n}", "fields": [ { "name": "shipmentId", "type": "string", "summary": "Shipment the position applies to." }, { "name": "timestamp", "type": "Date", "summary": "Time the position was captured by the device." }, { "name": "serverTimestamp", "type": "Date", "summary": "Time the server received the position." }, { "name": "position", "type": "Geoposition", "summary": "Geographic coordinates of the ping." } ], "usage": [] }, { "name": "Geopoint", "module": "tracking", "summary": "Plain latitude/longitude pair without metadata, used as a generic location primitive.", "shape": "interface Geopoint {\n lat: number;\n lng: number;\n}", "fields": [ { "name": "lat", "type": "number", "summary": "Latitude in decimal degrees." }, { "name": "lng", "type": "number", "summary": "Longitude in decimal degrees." } ], "usage": [] }, { "name": "Geoposition", "module": "tracking", "summary": "Latitude/longitude pair with an optional timestamp and source identifier, used for tracking pings.", "shape": "interface Geoposition {\n lat: number;\n lng: number;\n timestamp?: number;\n src?: \"dexfreight\";\n}", "fields": [ { "name": "lat", "type": "number", "summary": "Latitude in decimal degrees." }, { "name": "lng", "type": "number", "summary": "Longitude in decimal degrees." }, { "name": "timestamp", "type": "number", "summary": "Epoch milliseconds at which the position was captured.", "optional": true }, { "name": "src", "type": "\"dexfreight\"", "summary": "Source system that produced the ping.", "optional": true } ], "usage": [] }, { "name": "Georadius", "module": "tracking", "summary": "Circular geographic region defined by a center point and radius in meters, used for proximity searches.", "shape": "interface Georadius {\n lat: number;\n lng: number;\n radius: number;\n}", "fields": [ { "name": "lat", "type": "number", "summary": "Latitude of the center point." }, { "name": "lng", "type": "number", "summary": "Longitude of the center point." }, { "name": "radius", "type": "number", "summary": "Radius of the area, in meters." } ], "usage": [] }, { "name": "GooglePlace", "module": "geography", "summary": "Resolved Google Places result with address components useful for shipment locations.", "shape": "interface GooglePlace{\n description: string;\n fullAddress: string;\n location: string;\n place_id: string;\n zip_code: string;\n city: string;\n state: string; \n country: string;\n}", "fields": [ { "name": "description", "type": "string", "summary": "Display description returned by Google Places." }, { "name": "fullAddress", "type": "string", "summary": "Formatted full address." }, { "name": "location", "type": "string", "summary": "Encoded latitude/longitude pair." }, { "name": "place_id", "type": "string", "summary": "Google Places identifier." }, { "name": "zip_code", "type": "string", "summary": "Postal/ZIP code component." }, { "name": "city", "type": "string", "summary": "City component." }, { "name": "state", "type": "string", "summary": "State or region component." }, { "name": "country", "type": "string", "summary": "Country component." } ], "usage": [] }, { "name": "ICDYSRequestLastMileServicePayload", "module": "integration-mexico", "summary": "Payload sent to the CDYS Mexican logistics partner to request a last-mile service for one or more containers, including merchandise, route and timing data.", "shape": "interface ICDYSRequestLastMileServicePayload {\n lastMile: {\n container: string;\n booking: string;\n type: \"IMPO\" | \"EXPO\";\n truckType: string;\n carrierId: string;\n winerySource: string;\n wineryDestination: string;\n returnYard: string;\n billableCustomer: string;\n programDate: string;\n deliveryTime: string;\n deliveryTimeMax: string;\n maneuver: string;\n observations?: string;\n tripNumber: string;\n commodities: {\n commoditySat: string;\n commoditySatDesc: string;\n quantity: number;\n packagingSat: string;\n packagingSatDesc: string;\n weightKg: string;\n }[];\n }[];\n}", "fields": [ { "name": "lastMile", "type": "Array<{ container: string; booking: string; type: \"IMPO\" | \"EXPO\"; truckType: string; carrierId: string; winerySource: string; wineryDestination: string; returnYard: string; billableCustomer: string; programDate: string; deliveryTime: string; deliveryTimeMax: string; maneuver: string; observations?: string; tripNumber: string; commodities: { commoditySat: string; commoditySatDesc: string; quantity: number; packagingSat: string; packagingSatDesc: string; weightKg: string; }[]; }>", "summary": "List of last-mile movements being requested. Each entry is a single container move with origin/destination yards, dates, customer, type and SAT-coded commodities." } ], "usage": [] }, { "name": "InformationMexico", "module": "carta-porte", "summary": "Per-merchandise Mexico CFDI/Carta-Porte data attached to a container, including SAT keys, hazmat classification and dimensions.", "shape": "interface InformationMexico {\n unitKey?: string;\n valueGoods?: number;\n tariffFraction?: string;\n uuid?: string;\n petition?: string;\n weight?: number;\n\n UNNumber?: number;\n class?: string;\n packingGroup?: string;\n properShippingName?: string;\n quantityTypeOfPackaging?: string;\n emergencyNumber?: string;\n packagingType?: string;\n merchandiseDescription?: string;\n productKey?: string;\n\n unit?: number;\n length?: number;\n width?: number;\n height?: number;\n measurementUnit?: string;\n\n hazardousMaterialKey?: string;\n hazardousMaterialKeyId?: string;\n cbm?: string;\n units?: number;\n measurementQuantity?: string;\n\n hazardActive?: boolean;\n overDimensions?: boolean;\n\n typeMatter?: string;\n documentAduanera?:DocumentAduanera[];\n\n}", "fields": [ { "name": "unitKey", "type": "string", "summary": "SAT unit key (ClaveUnidad).", "optional": true }, { "name": "valueGoods", "type": "number", "summary": "Declared value of the goods.", "optional": true }, { "name": "tariffFraction", "type": "string", "summary": "Customs tariff fraction (FraccionArancelaria).", "optional": true }, { "name": "uuid", "type": "string", "summary": "Foreign-trade UUID associated with the merchandise.", "optional": true }, { "name": "petition", "type": "string", "summary": "Customs petition reference (NumPedimento).", "optional": true }, { "name": "weight", "type": "number", "summary": "Weight in kilograms.", "optional": true }, { "name": "UNNumber", "type": "number", "summary": "United Nations hazardous material number.", "optional": true }, { "name": "class", "type": "string", "summary": "Hazmat class.", "optional": true }, { "name": "packingGroup", "type": "string", "summary": "Hazmat packing group.", "optional": true }, { "name": "properShippingName", "type": "string", "summary": "Hazmat proper shipping name.", "optional": true }, { "name": "quantityTypeOfPackaging", "type": "string", "summary": "Quantity and type of packaging description.", "optional": true }, { "name": "emergencyNumber", "type": "string", "summary": "Emergency phone number for hazmat incidents.", "optional": true }, { "name": "packagingType", "type": "string", "summary": "Packaging type code (Embalaje).", "optional": true }, { "name": "merchandiseDescription", "type": "string", "summary": "Description of the merchandise.", "optional": true }, { "name": "productKey", "type": "string", "summary": "SAT product/service key (ClaveProdServ).", "optional": true }, { "name": "unit", "type": "number", "summary": "Unit count of the load.", "optional": true }, { "name": "length", "type": "number", "summary": "Length dimension.", "optional": true }, { "name": "width", "type": "number", "summary": "Width dimension.", "optional": true }, { "name": "height", "type": "number", "summary": "Height dimension.", "optional": true }, { "name": "measurementUnit", "type": "string", "summary": "Unit of measure for dimensions.", "optional": true }, { "name": "hazardousMaterialKey", "type": "string", "summary": "SAT key for the hazardous material.", "optional": true }, { "name": "hazardousMaterialKeyId", "type": "string", "summary": "Internal id for the hazardous material key.", "optional": true }, { "name": "cbm", "type": "string", "summary": "Cubic-meter volume of the merchandise.", "optional": true }, { "name": "units", "type": "number", "summary": "Number of units.", "optional": true }, { "name": "measurementQuantity", "type": "string", "summary": "Quantity expressed in measurement unit.", "optional": true }, { "name": "hazardActive", "type": "boolean", "summary": "Whether hazmat fields are active for this entry.", "optional": true }, { "name": "overDimensions", "type": "boolean", "summary": "Whether the merchandise is over-dimensioned.", "optional": true }, { "name": "typeMatter", "type": "string", "summary": "SAT TipoMateria code for foreign-trade matter type.", "optional": true }, { "name": "documentAduanera", "type": "DocumentAduanera[]", "summary": "List of customs documents associated with the merchandise.", "optional": true } ], "usage": [] }, { "name": "InviteCarrier", "module": "negotiations", "summary": "Payload used to invite an external carrier to bid on a shipment by email and DOT/MC numbers.", "shape": "interface InviteCarrier {\n shipmentId: string;\n email: string;\n rate: number;\n dot_number: string;\n mt_number: string;\n }", "fields": [ { "name": "shipmentId", "type": "string", "summary": "Shipment to invite the carrier on." }, { "name": "email", "type": "string", "summary": "Email of the carrier contact being invited." }, { "name": "rate", "type": "number", "summary": "Initial offered rate to the carrier." }, { "name": "dot_number", "type": "string", "summary": "Carrier USDOT number." }, { "name": "mt_number", "type": "string", "summary": "Carrier MC number." } ], "usage": [] }, { "name": "JiraIssue", "module": "integrations", "summary": "Atlassian Jira issue payload posted from the platform support flow, with project, type and Atlassian Document Format description.", "shape": "interface JiraIssue {\n summary: string;\n project: { key: string };\n issuetype: { id: string };\n description: {\n type: string;\n version: number;\n content: {\n type: string;\n content: { text: string; type: string }[]\n }[]\n }\n \n customfield_10010: string;\n}", "fields": [ { "name": "summary", "type": "string", "summary": "Issue summary/title." }, { "name": "project", "type": "{ key: string }", "summary": "Jira project the issue is created under." }, { "name": "issuetype", "type": "{ id: string }", "summary": "Issue type identifier (bug, task, etc.)." }, { "name": "description", "type": "{ type: string; version: number; content: { type: string; content: { text: string; type: string }[] }[] }", "summary": "Issue description encoded as Atlassian Document Format." }, { "name": "customfield_10010", "type": "string", "summary": "Service-desk request type custom field." } ], "usage": [] }, { "name": "LocationInfo", "module": "drayage", "summary": "Triple of pickup, delivery and optional return locations for a drayage shipment.", "shape": "interface LocationInfo {\n pickup: PickUpInfo;\n delivery: DeliveryInfo;\n return?: ReturnInfo;\n}", "fields": [ { "name": "pickup", "type": "PickUpInfo", "summary": "Pickup location details including accessorials and contact." }, { "name": "delivery", "type": "DeliveryInfo", "summary": "Delivery location details including stops and contact." }, { "name": "return", "type": "ReturnInfo", "summary": "Optional empty-container return location.", "optional": true } ], "usage": [] }, { "name": "MailgunWebhook", "module": "notifications", "summary": "Payload received from Mailgun's webhook callbacks, containing signature, message headers and event type.", "shape": "interface MailgunWebhook {\n signature: {\n timestamp: string;\n token: string;\n signature: string;\n };\n\n message: {\n headers: {\n \"message-id\": string;\n }\n };\n\n event: string;\n}", "fields": [ { "name": "signature", "type": "{ timestamp: string; token: string; signature: string; }", "summary": "Mailgun HMAC signature triplet used to authenticate the webhook." }, { "name": "message", "type": "{ headers: { \"message-id\": string; } }", "summary": "Message metadata, including the original Mailgun message id." }, { "name": "event", "type": "string", "summary": "Type of Mailgun event (delivered, opened, failed, etc.)." } ], "usage": [] }, { "name": "Negotiation", "module": "negotiations", "summary": "State of an ongoing rate negotiation between shipper and carrier on a specific shipment, with bid history, acceptance flags and dates.", "shape": "interface Negotiation {\n _id?: string;\n shipment: string;\n company: string;\n user: [string];\n accepted: boolean;\n declined: boolean;\n pending_verification: boolean;\n by_edition: boolean;\n acceptCarrier:boolean;\n acceptShipper:boolean;\n negotiationCarrier: boolean;\n value: number;\n shipper: string;\n history: History[];\n reason: string;\n bidder?: string;\n limit?: number;\n extraChargeTurn?: string;\n pickup?: PickupDate;\n delivered?: DeliveryDate;\n comment?:string;\n companyDecline?:string;\n \n}", "fields": [ { "name": "_id", "type": "string", "summary": "Identifier of the negotiation.", "optional": true }, { "name": "shipment", "type": "string", "summary": "Shipment under negotiation." }, { "name": "company", "type": "string", "summary": "Company that owns the negotiation entry." }, { "name": "user", "type": "[string]", "summary": "Users involved in the negotiation." }, { "name": "accepted", "type": "boolean", "summary": "Whether the negotiation was accepted." }, { "name": "declined", "type": "boolean", "summary": "Whether the negotiation was declined." }, { "name": "pending_verification", "type": "boolean", "summary": "Whether the negotiation is waiting for verification." }, { "name": "by_edition", "type": "boolean", "summary": "Whether the negotiation was triggered by editing." }, { "name": "acceptCarrier", "type": "boolean", "summary": "Whether the carrier accepted." }, { "name": "acceptShipper", "type": "boolean", "summary": "Whether the shipper accepted." }, { "name": "negotiationCarrier", "type": "boolean", "summary": "Whether the carrier opened the negotiation." }, { "name": "value", "type": "number", "summary": "Latest bid value of the negotiation." }, { "name": "shipper", "type": "string", "summary": "Shipper company on the negotiation." }, { "name": "history", "type": "History[]", "summary": "Chronological list of bid history entries." }, { "name": "reason", "type": "string", "summary": "Reason explaining the latest action." }, { "name": "bidder", "type": "string", "summary": "User or company placing the bid.", "optional": true }, { "name": "limit", "type": "number", "summary": "Maximum value the bidder is willing to accept.", "optional": true }, { "name": "extraChargeTurn", "type": "string", "summary": "Side responsible for extra charges in the current turn.", "optional": true }, { "name": "pickup", "type": "PickupDate", "summary": "Proposed pickup date and time.", "optional": true }, { "name": "delivered", "type": "DeliveryDate", "summary": "Proposed delivery date and time.", "optional": true }, { "name": "comment", "type": "string", "summary": "Optional comment attached to the bid.", "optional": true }, { "name": "companyDecline", "type": "string", "summary": "Identifier of the company that declined the negotiation.", "optional": true } ], "usage": [] }, { "name": "NegotiationInfo", "module": "negotiations", "summary": "Single negotiation/bid entry stored on a drayage, listing the proposed services and other services, bidder identity and acceptance flags.", "shape": "interface NegotiationInfo {\n accepted: boolean;\n bidder?: string;\n id: string;\n services?: {\n units: string;\n rate: number;\n type: string;\n accepted: boolean;\n }[];\n otherServices?: {\n units: string;\n rate: number;\n type: string;\n accepted: boolean;\n }[];\n companyId: any //is ObjectId\n userId: any //is ObjectId\n automatic?: boolean;\n date: Date;\n}", "fields": [ { "name": "accepted", "type": "boolean", "summary": "Whether the bid was accepted." }, { "name": "bidder", "type": "string", "summary": "Identifier of the side that placed the bid.", "optional": true }, { "name": "id", "type": "string", "summary": "Bid identifier inside the negotiation history." }, { "name": "services", "type": "Array<{ units: string; rate: number; type: string; accepted: boolean; }>", "summary": "Primary service lines of the bid.", "optional": true }, { "name": "otherServices", "type": "Array<{ units: string; rate: number; type: string; accepted: boolean; }>", "summary": "Other accessorial service lines of the bid.", "optional": true }, { "name": "companyId", "type": "ObjectId", "summary": "Company that submitted the bid." }, { "name": "userId", "type": "ObjectId", "summary": "User that submitted the bid." }, { "name": "automatic", "type": "boolean", "summary": "Whether the bid was generated by an automatic-bid rule.", "optional": true }, { "name": "date", "type": "Date", "summary": "Time the bid was submitted." } ], "usage": [] }, { "name": "OLPShipment", "module": "drayage", "summary": "Shipment representation exchanged through the Open Logistics Protocol (OLP), including DID identities, origin/destination, payment, appointments and equipments.", "shape": "interface OLPShipment {\n did: string;\n node: { did: string; name: string; };\n shipper: { did: string; name: string; dot: string; mc: string; };\n shipment: {\n _id: string;\n shipper: string;\n origin: { city: string; state: string; zipCode: string; country: string; };\n destination: { city: string; state: string; zipCode: string; country: string; };\n active: boolean;\n state: string;\n createdAt: string;\n updatedAt: string;\n payment: { negotiable: boolean; rate: number; rules: string; rulesAddress: string; processor: string; processorAddress: string; extraCharges: any[]; extraData: string; dueDate: number; };\n appointment: { pickup: { from: string; until: string; }; arrive: { from: string; until: string; }; };\n partial: boolean;\n equipments: string[];\n shipmentId: string;\n shipperCompany: string;\n };\n}", "fields": [ { "name": "did", "type": "string", "summary": "Decentralized identifier of the OLP shipment." }, { "name": "node", "type": "{ did: string; name: string; }", "summary": "OLP node hosting the shipment." }, { "name": "shipper", "type": "{ did: string; name: string; dot: string; mc: string; }", "summary": "Shipper company DID and FMCSA identifiers." }, { "name": "shipment", "type": "{ _id: string; shipper: string; origin: {...}; destination: {...}; active: boolean; state: string; createdAt: string; updatedAt: string; payment: {...}; appointment: {...}; partial: boolean; equipments: string[]; shipmentId: string; shipperCompany: string; }", "summary": "Inner shipment payload with origin, destination, payment terms, appointments and equipments." } ], "usage": [] }, { "name": "OLPShipmentDocumentSetup", "module": "drayage", "summary": "OLP-protocol document setup describing per-side document templates, signing requirements and DID references.", "shape": "interface OLPShipmentDocumentSetup {\n shipperDocuments: { type: string, did: string, signed: boolean }[];\n carrierDocuments: { type: string, did: string, signed: boolean }[];\n shipmentDocuments: { type: string, signer: string, side: string }[];\n}", "fields": [ { "name": "shipperDocuments", "type": "{ type: string; did: string; signed: boolean; }[]", "summary": "Documents owned and signed by the shipper side." }, { "name": "carrierDocuments", "type": "{ type: string; did: string; signed: boolean; }[]", "summary": "Documents owned and signed by the carrier side." }, { "name": "shipmentDocuments", "type": "{ type: string; signer: string; side: string; }[]", "summary": "Document templates required at the shipment level, with required signer and side." } ], "usage": [] }, { "name": "OLPShipmentLookup", "module": "drayage", "summary": "Filter object accepted by the OLP shipment search endpoint, supporting array/range filters on origin, destination, dates, rate and equipment.", "shape": "interface OLPShipmentLookup {\n originCity?: ArrayOrValueFilter;\n originState?: ArrayOrValueFilter;\n originZipCode?: ArrayOrValueFilter;\n originCountry?: ArrayOrValueFilter;\n\n destinationCity?: ArrayOrValueFilter;\n destinationState?: ArrayOrValueFilter;\n destinationZipCode?: ArrayOrValueFilter;\n destinationCountry?: ArrayOrValueFilter;\n\n pickupDate?: BetweenFilter;\n deliveryDate?: BetweenFilter;\n\n paymentRate?: BetweenFilter;\n equipment?: ArrayOrValueFilter;\n postedAt?: BetweenFilter;\n\n nodes?: string[];\n}", "fields": [ { "name": "originCity", "type": "ArrayOrValueFilter", "summary": "Filter by origin city.", "optional": true }, { "name": "originState", "type": "ArrayOrValueFilter", "summary": "Filter by origin state.", "optional": true }, { "name": "originZipCode", "type": "ArrayOrValueFilter", "summary": "Filter by origin postal code.", "optional": true }, { "name": "originCountry", "type": "ArrayOrValueFilter", "summary": "Filter by origin country.", "optional": true }, { "name": "destinationCity", "type": "ArrayOrValueFilter", "summary": "Filter by destination city.", "optional": true }, { "name": "destinationState", "type": "ArrayOrValueFilter", "summary": "Filter by destination state.", "optional": true }, { "name": "destinationZipCode", "type": "ArrayOrValueFilter", "summary": "Filter by destination postal code.", "optional": true }, { "name": "destinationCountry", "type": "ArrayOrValueFilter", "summary": "Filter by destination country.", "optional": true }, { "name": "pickupDate", "type": "BetweenFilter", "summary": "Filter shipments by pickup date range.", "optional": true }, { "name": "deliveryDate", "type": "BetweenFilter", "summary": "Filter shipments by delivery date range.", "optional": true }, { "name": "paymentRate", "type": "BetweenFilter", "summary": "Filter shipments by payment rate range.", "optional": true }, { "name": "equipment", "type": "ArrayOrValueFilter", "summary": "Filter by equipment type required.", "optional": true }, { "name": "postedAt", "type": "BetweenFilter", "summary": "Filter shipments by posting date range.", "optional": true }, { "name": "nodes", "type": "string[]", "summary": "Restrict the search to a specific list of OLP nodes.", "optional": true } ], "usage": [] }, { "name": "OnChainShipment", "module": "drayage", "summary": "Smart-contract representation of a shipment used to mirror on-chain state into the platform, including payment rules, status, stops and associated payments.", "shape": "interface OnChainShipment {\n id: string;\n\n carrier: string;\n shipper: string;\n\n shipperDocs: string[];\n carrierDocs: string[];\n\n paymentRules: string;\n paymentProcessor: string;\n paymentData: string;\n\n status: number;\n\n associatedPayments: {\n paymentId: number,\n status: string,\n updates: { status: string, timestamp: number }[],\n timestamps: string[]\n }[];\n\n stops: number[];\n totalStops: number;\n currentStop: number;\n createdAt: number;\n}", "fields": [ { "name": "id", "type": "string", "summary": "On-chain shipment identifier." }, { "name": "carrier", "type": "string", "summary": "Carrier wallet/account address." }, { "name": "shipper", "type": "string", "summary": "Shipper wallet/account address." }, { "name": "shipperDocs", "type": "string[]", "summary": "Document hashes/refs uploaded by the shipper." }, { "name": "carrierDocs", "type": "string[]", "summary": "Document hashes/refs uploaded by the carrier." }, { "name": "paymentRules", "type": "string", "summary": "Address or hash of the deployed payment rules contract." }, { "name": "paymentProcessor", "type": "string", "summary": "Address of the payment processor contract." }, { "name": "paymentData", "type": "string", "summary": "Encoded payment configuration data." }, { "name": "status", "type": "number", "summary": "Numeric on-chain status of the shipment." }, { "name": "associatedPayments", "type": "{ paymentId: number; status: string; updates: { status: string; timestamp: number }[]; timestamps: string[]; }[]", "summary": "Payments attached to the shipment with their status updates and timestamps." }, { "name": "stops", "type": "number[]", "summary": "Stop identifiers in the order traversed." }, { "name": "totalStops", "type": "number", "summary": "Total number of stops on the shipment." }, { "name": "currentStop", "type": "number", "summary": "Index of the stop currently being executed." }, { "name": "createdAt", "type": "number", "summary": "Unix epoch creation timestamp." } ], "usage": [] }, { "name": "PaccCartaPorte", "module": "carta-porte", "summary": "Full Carta-Porte CFDI 4.0 payload sent to the Mexican PAC stamping provider, covering issuer/receiver fiscal data, conceptos, taxes and the Carta Porte transport complement.", "shape": "interface PaccCartaPorte {\n Fecha: string;\n Folio: string;\n TipoDeComprobante: string;\n LugarExpedicion: string;\n Moneda: string;\n SubTotal: string;\n Total: string;\n Version: string;\n Exportacion: string;\n FormaPago: string;\n MetodoPago: string; \n Emisor: { ... };\n CfdiRelacionados?: { ... }[];\n Receptor: { ... };\n Conceptos?: { ... }[];\n Impuestos?: { ... };\n Complemento: { CartaPorte: { ... } };\n MostrarImportes: \"Si\" | \"No\";\n Notas: string;\n}", "fields": [ { "name": "Fecha", "type": "string", "summary": "ISO date of the CFDI emission." }, { "name": "Folio", "type": "string", "summary": "Internal folio identifier for the invoice." }, { "name": "TipoDeComprobante", "type": "string", "summary": "CFDI document type (typically 'T' for traslado)." }, { "name": "LugarExpedicion", "type": "string", "summary": "Postal code of the issuance location." }, { "name": "Moneda", "type": "string", "summary": "Currency code." }, { "name": "SubTotal", "type": "string", "summary": "Pre-tax subtotal." }, { "name": "Total", "type": "string", "summary": "Total amount including taxes." }, { "name": "Version", "type": "string", "summary": "CFDI version (4.0)." }, { "name": "Exportacion", "type": "string", "summary": "SAT export classifier code." }, { "name": "FormaPago", "type": "string", "summary": "SAT payment form code." }, { "name": "MetodoPago", "type": "string", "summary": "SAT payment method code." }, { "name": "Emisor", "type": "{ RegimenFiscal: string; Rfc: string; Nombre: string; DomicilioFiscal: Domicilio; }", "summary": "Issuer fiscal data." }, { "name": "CfdiRelacionados", "type": "{ TipoRelacion?: string; CfdiRelacionado?: { UUID?: string; }[]; }[]", "summary": "Related CFDIs (substitutions, cancellations).", "optional": true }, { "name": "Receptor", "type": "{ Rfc: string; UsoCFDI: string; Nombre: string; RegimenFiscalReceptor: string; DomicilioFiscalReceptor: string; Domicilio: Domicilio; Email: string; }", "summary": "Receiver fiscal data." }, { "name": "Conceptos", "type": "{ NoIdentificacion?: null; ClaveProdServ?: number; Cantidad?: number; Descripcion?: string; ValorUnitario?: number; Importe?: string; ClaveUnidad?: string; InformacionAduanera?: null; ObjetoImp?: string; Impuestos?: { Traslados?: ImpuestoTrasladoRetenciones[]; Retenciones?: ImpuestoTrasladoRetenciones[]; } }[]", "summary": "Line items (conceptos) of the CFDI.", "optional": true }, { "name": "Impuestos", "type": "{ TotalImpuestosRetenidos?: string; TotalImpuestosTrasladados?: string; Retenciones?: [{ Impuesto?: string; Importe?: string; }]; Traslados?: ImpuestoTrasladoRetenciones[]; }", "summary": "CFDI-level tax totals.", "optional": true }, { "name": "Complemento", "type": "{ CartaPorte: { Version: string; IdCCP: string; TranspInternac: string; EntradaSalidaMerc: string; PaisOrigenDestino: string; ViaEntradaSalida: string; TotalDistRec: string; RegimenesAduaneros?: ...; Ubicaciones: [...]; Mercancias: { ... }; FiguraTransporte: { ... } } }", "summary": "Carta Porte transport complement with locations, merchandise, vehicle and figure information." }, { "name": "MostrarImportes", "type": "\"Si\" | \"No\"", "summary": "Whether to show monetary amounts on the printed Carta Porte." }, { "name": "Notas", "type": "string", "summary": "Free-form notes printed on the document." } ], "usage": [] }, { "name": "PaymentInfo", "module": "drayage", "summary": "Open-payment terms, currency and per-service rates configured on a drayage shipment.", "shape": "interface PaymentInfo {\n currency?: string;\n open: {\n negotiable: boolean;\n method: string,\n terms: string,\n customDays?: number;\n services?: ServicesInfo[];\n otherServices?: OtherServicesInfo[];\n temporalServices?: TemporalServicesInfo[];\n }\n}", "fields": [ { "name": "currency", "type": "string", "summary": "ISO currency code used to settle the payment.", "optional": true }, { "name": "open", "type": "{ negotiable: boolean; method: string; terms: string; customDays?: number; services?: ServicesInfo[]; otherServices?: OtherServicesInfo[]; temporalServices?: TemporalServicesInfo[]; }", "summary": "Open-rate payment block describing whether the rate is negotiable and the services and accessorials being charged." } ], "usage": [] }, { "name": "SendMailgunTemplateOptions", "module": "notifications", "summary": "Options accepted by the Mailgun template sender, defining destination, subject, payload data, attachments and storage hints.", "shape": "interface SendMailgunTemplateOptions {\n templateName: string;\n destination: Email;\n html?: string;\n cc?: Email;\n subject: string;\n data: any;\n senderName?: string;\n replyTo?: string;\n tags?: string[];\n store?: {\n name?: string;\n shipmentId?: ID;\n subject?: string;\n },\n attachments?: {\n doc: any;\n filename: string;\n }[];\n}", "fields": [ { "name": "templateName", "type": "string", "summary": "Name of the Mailgun template to render." }, { "name": "destination", "type": "Email", "summary": "Recipient email address." }, { "name": "html", "type": "string", "summary": "Optional pre-rendered HTML body to override the template.", "optional": true }, { "name": "cc", "type": "Email", "summary": "Optional CC recipient.", "optional": true }, { "name": "subject", "type": "string", "summary": "Email subject line." }, { "name": "data", "type": "any", "summary": "Variables passed into the template." }, { "name": "senderName", "type": "string", "summary": "Display name shown to recipients.", "optional": true }, { "name": "replyTo", "type": "string", "summary": "Reply-to address.", "optional": true }, { "name": "tags", "type": "string[]", "summary": "Mailgun tags applied to the message.", "optional": true }, { "name": "store", "type": "{ name?: string; shipmentId?: ID; subject?: string; }", "summary": "Hint for storing the email reference inside Dexcarga.", "optional": true }, { "name": "attachments", "type": "{ doc: any; filename: string; }[]", "summary": "Files attached to the email.", "optional": true } ], "usage": [] }, { "name": "ServicesInfo", "module": "drayage", "summary": "Single charged service line on a drayage payment, with rate, units, quantity and acceptance state.", "shape": "interface ServicesInfo {\n type: string;\n rate?: number;\n units?: string;\n qty: number;\n accepted?: any;\n freeHours?: any;\n active?: boolean;\n isOtherService?: boolean;\n}", "fields": [ { "name": "type", "type": "string", "summary": "Service code or label." }, { "name": "rate", "type": "number", "summary": "Unit rate charged for the service.", "optional": true }, { "name": "units", "type": "string", "summary": "Unit of measure (e.g. hour, mile, flat).", "optional": true }, { "name": "qty", "type": "number", "summary": "Quantity of units." }, { "name": "accepted", "type": "any", "summary": "Whether the service line was accepted by the counterparty.", "optional": true }, { "name": "freeHours", "type": "any", "summary": "Free hours included before charging applies.", "optional": true }, { "name": "active", "type": "boolean", "summary": "Whether the service line is currently active.", "optional": true }, { "name": "isOtherService", "type": "boolean", "summary": "Marks the line as belonging to the other-services bucket.", "optional": true } ], "usage": [] }, { "name": "Shipper", "module": "users", "summary": "User specialization for shipper accounts, adding bill-to billing information used on invoices and BOLs.", "shape": "interface Shipper extends User {\n billToInfo: {\n contactName: string;\n address: string;\n zipCode: string;\n city: string;\n state: string;\n country: string;\n };\n}", "fields": [ { "name": "billToInfo", "type": "{ contactName: string; address: string; zipCode: string; city: string; state: string; country: string; }", "summary": "Billing contact and address used to issue invoices to this shipper." } ], "usage": [] }, { "name": "signedDocuments", "module": "documents", "summary": "Reference to a fully-signed document tied to a specific shipper, carrier and shipment.", "shape": "interface signedDocuments{\n shipperId: any //is ObjectId\n carrierId: any //is ObjectId\n shipmentId: any //is ObjectId\n documentType: string;\n signedDocumentUrl: string;\n shipmentType: string;\n}", "fields": [ { "name": "shipperId", "type": "ObjectId", "summary": "Shipper company identifier." }, { "name": "carrierId", "type": "ObjectId", "summary": "Carrier company identifier." }, { "name": "shipmentId", "type": "ObjectId", "summary": "Shipment to which the signed document belongs." }, { "name": "documentType", "type": "string", "summary": "Document type code (BOL, POD, contract, etc.)." }, { "name": "signedDocumentUrl", "type": "string", "summary": "URL of the fully-signed document." }, { "name": "shipmentType", "type": "string", "summary": "Type of shipment this signed document corresponds to." } ], "usage": [] }, { "name": "SkipLimit", "module": "_common", "summary": "Pagination cursor passed to list endpoints, expressed as integer offset and page size.", "shape": "interface SkipLimit {\n skip: number;\n limit: number;\n}", "fields": [ { "name": "skip", "type": "number", "summary": "Number of items to skip from the beginning of the result set." }, { "name": "limit", "type": "number", "summary": "Maximum number of items to return." } ], "usage": [] }, { "name": "Stage", "module": "drayage", "summary": "Operational checkpoint inside a container's lifecycle (pickup, delivery, return) with completion state, requirements and on-chain reference.", "shape": "interface Stage {\n type: StageType;\n name: string;\n id: string; // origin\n description?: string; // Description set by user\n requirements: Requirement[];\n required: boolean;\n timestamp?: Date;\n driverId?: any //is ObjectId\n blockchainTransaction?: string;\n position: { lat: number, lng: number };\n location?: { lat: number, lng: number };\n parentStage?: string; // ID\n completed: boolean;\n relatedPhotos: string[];\n}", "fields": [ { "name": "type", "type": "\"stop\" | \"action\"", "summary": "Stage classification: physical stop or operational action." }, { "name": "name", "type": "string", "summary": "Human-readable name of the stage." }, { "name": "id", "type": "string", "summary": "Unique identifier of the stage inside the container." }, { "name": "description", "type": "string", "summary": "Optional user-supplied description.", "optional": true }, { "name": "requirements", "type": "Requirement[]", "summary": "Requirements to mark the stage complete (position or photos)." }, { "name": "required", "type": "boolean", "summary": "Whether this stage must be completed before the next." }, { "name": "timestamp", "type": "Date", "summary": "Time at which the stage was completed.", "optional": true }, { "name": "driverId", "type": "ObjectId", "summary": "Driver who completed the stage.", "optional": true }, { "name": "blockchainTransaction", "type": "string", "summary": "On-chain transaction hash recording the completion.", "optional": true }, { "name": "position", "type": "{ lat: number, lng: number }", "summary": "Expected geo position of the stage." }, { "name": "location", "type": "{ lat: number, lng: number }", "summary": "Actual geo position recorded on completion.", "optional": true }, { "name": "parentStage", "type": "string", "summary": "Identifier of the parent stage when nested.", "optional": true }, { "name": "completed", "type": "boolean", "summary": "Whether the stage has been completed." }, { "name": "relatedPhotos", "type": "string[]", "summary": "URLs of photos attached to the stage." } ], "usage": [] }, { "name": "updateDriver", "module": "users", "summary": "Payload used to update an existing driver's profile, license and Mexico tax information.", "shape": "interface updateDriver {\n\t_id: string;\n\tprofile: {\n\t\tname: string;\n\t\tlastname: string;\n\t\tmobile: string;\n\t};\n\tlicense: {\n\t\tid: string;\n\t\texpiration: Date;\n\t\tlocation: string;\n\t};\n\tmexicoInformation?: {\n figureType?: {\n keyFigureType?: string;\n description?: string;\n };\n rfc?: string;\n }\n}", "fields": [ { "name": "_id", "type": "string", "summary": "Identifier of the driver being updated." }, { "name": "profile", "type": "{ name: string; lastname: string; mobile: string; }", "summary": "Driver profile fields to update." }, { "name": "license", "type": "{ id: string; expiration: Date; location: string; }", "summary": "Driver license fields to update." }, { "name": "mexicoInformation", "type": "{ figureType?: { keyFigureType?: string; description?: string; }; rfc?: string; }", "summary": "Mexico SAT figure type and RFC for the driver.", "optional": true } ], "usage": [] }, { "name": "User", "module": "users", "summary": "Base user record covering credentials, profile data, company affiliation and role used across all user-typed accounts.", "shape": "interface User {\n _id: any //is ObjectId\n\n username?: string;\n email?: string;\n password: string;\n\n\n companyId: any //is ObjectId\n role: String\n profile: {\n name?: string;\n lastname?: string;\n phone?: string;\n mobile?: string;\n countryCode?: string;\n picture?: string;\n }\n\n _accessLevel: string;\n license?: {\n id: string;\n expiration: string;\n location: string;\n }\n\n borndate?: Date;\n address?: string;\n height?: { ft: number; in: number };\n isOwnerOperator?: boolean;\n}", "fields": [ { "name": "_id", "type": "ObjectId", "summary": "Mongo identifier for the user document." }, { "name": "username", "type": "string", "summary": "Optional username login alias.", "optional": true }, { "name": "email", "type": "string", "summary": "Email address for login and notifications.", "optional": true }, { "name": "password", "type": "string", "summary": "Hashed password used for authentication." }, { "name": "companyId", "type": "ObjectId", "summary": "Company the user belongs to." }, { "name": "role", "type": "String", "summary": "Internal role label inside the owning company." }, { "name": "profile", "type": "{ name?: string; lastname?: string; phone?: string; mobile?: string; countryCode?: string; picture?: string; }", "summary": "Personal profile fields displayed to other users." }, { "name": "_accessLevel", "type": "string", "summary": "Computed access level granted to this user inside the company." }, { "name": "license", "type": "{ id: string; expiration: string; location: string; }", "summary": "Driver license details when applicable.", "optional": true }, { "name": "borndate", "type": "Date", "summary": "Birth date of the user.", "optional": true }, { "name": "address", "type": "string", "summary": "Residential address of the user.", "optional": true }, { "name": "height", "type": "{ ft: number; in: number }", "summary": "Driver height in feet and inches.", "optional": true }, { "name": "isOwnerOperator", "type": "boolean", "summary": "Whether the user operates as an owner-operator carrier.", "optional": true } ], "usage": [] }, { "name": "UserGet", "module": "users", "summary": "Read projection of a User returned to clients, omitting credentials and exposing computed flags.", "shape": "interface UserGet {\n profile: {\n name?: string;\n lastname?: string;\n phone?: string;\n mobile?: string;\n countryCode?: string;\n picture?: string;\n };\n username: string;\n email: string;\n companyId: string;\n role: string;\n _accessLevel: string;\n _id: string;\n license: {\n id?: string;\n expiration?: string;\n location?: string;\n };\n isOwnerOperator: boolean;\n disabled: boolean;\n tlx?: {\n driverId: Number;\n eldvendorId: Number;\n eldVendorName: String;\n carrierId: String;\n carrierName: String;\n currentVehicleId: Number;\n };\n smsTracking: boolean;\n acceptCarrier: boolean;\n ethAddress?: string;\n mexicoInformation?: {\n figureType?: {\n keyFigureType?: string;\n description?: string;\n };\n rfc?: string;\n }\n}", "fields": [ { "name": "profile", "type": "{ name?: string; lastname?: string; phone?: string; mobile?: string; countryCode?: string; picture?: string; }", "summary": "Public profile fields of the user." }, { "name": "username", "type": "string", "summary": "Login username alias." }, { "name": "email", "type": "string", "summary": "Email address used for login and notifications." }, { "name": "companyId", "type": "string", "summary": "Company the user belongs to." }, { "name": "role", "type": "string", "summary": "Role label inside the owning company." }, { "name": "_accessLevel", "type": "string", "summary": "Computed access level granted in the company." }, { "name": "_id", "type": "string", "summary": "User identifier." }, { "name": "license", "type": "{ id?: string; expiration?: string; location?: string; }", "summary": "Driver license details when applicable." }, { "name": "isOwnerOperator", "type": "boolean", "summary": "Whether the user is an owner-operator." }, { "name": "disabled", "type": "boolean", "summary": "Whether the user account is disabled." }, { "name": "tlx", "type": "{ driverId: Number; eldvendorId: Number; eldVendorName: String; carrierId: String; carrierName: String; currentVehicleId: Number; }", "summary": "Trimble TLX integration linkage data for ELD/HOS.", "optional": true }, { "name": "smsTracking", "type": "boolean", "summary": "Whether the user opted in to SMS tracking notifications." }, { "name": "acceptCarrier", "type": "boolean", "summary": "Whether the user has accepted the carrier terms." }, { "name": "ethAddress", "type": "string", "summary": "Optional Ethereum wallet address linked to the user.", "optional": true }, { "name": "mexicoInformation", "type": "{ figureType?: { keyFigureType?: string; description?: string; }; rfc?: string; }", "summary": "Mexico SAT tax figure type and RFC information.", "optional": true } ], "usage": [] }, { "name": "UserMexico", "module": "integration-mexico", "summary": "Mexico-specific user/onboarding payload with RFC, CAAT, postal code and CFDI tax fields.", "shape": "interface UserMexico {\n email: string;\n username: string;\n firstName: string;\n lastName: string; \n phone: string;\n companyName: string;\n caatNumber: string;\n rfc: string;\n postalCode: string;\n taxRegime: string;\n usoCfdi: string;\n}", "fields": [ { "name": "email", "type": "string", "summary": "Email address." }, { "name": "username", "type": "string", "summary": "Username login alias." }, { "name": "firstName", "type": "string", "summary": "First name." }, { "name": "lastName", "type": "string", "summary": "Last name." }, { "name": "phone", "type": "string", "summary": "Phone number." }, { "name": "companyName", "type": "string", "summary": "Company name." }, { "name": "caatNumber", "type": "string", "summary": "CAAT customs broker number." }, { "name": "rfc", "type": "string", "summary": "Mexican RFC tax identifier." }, { "name": "postalCode", "type": "string", "summary": "Postal code of the fiscal address." }, { "name": "taxRegime", "type": "string", "summary": "SAT tax regime code." }, { "name": "usoCfdi", "type": "string", "summary": "Default SAT UsoCFDI code applied to invoices." } ], "usage": [] }, { "name": "UserUsa", "module": "integration-usa", "summary": "USA-specific user/onboarding payload with FMCSA identifiers and US fiscal address.", "shape": "interface UserUsa {\n email: string;\n username: string;\n firstName: string;\n lastName: string; \n phone: string;\n companyName: string;\n role: string;\n mcNumber?: string;\n dotNumber?: string;\n zipCode?: string;\n address?: string;\n city?: string;\n state?: string;\n country?: string;\n postalCode?: string; \n taxRegime?: string;\n}", "fields": [ { "name": "email", "type": "string", "summary": "Email address." }, { "name": "username", "type": "string", "summary": "Username login alias." }, { "name": "firstName", "type": "string", "summary": "First name." }, { "name": "lastName", "type": "string", "summary": "Last name." }, { "name": "phone", "type": "string", "summary": "Phone number." }, { "name": "companyName", "type": "string", "summary": "Company name." }, { "name": "role", "type": "string", "summary": "Company role label." }, { "name": "mcNumber", "type": "string", "summary": "FMCSA Motor Carrier number.", "optional": true }, { "name": "dotNumber", "type": "string", "summary": "FMCSA USDOT number.", "optional": true }, { "name": "zipCode", "type": "string", "summary": "ZIP code of the fiscal address.", "optional": true }, { "name": "address", "type": "string", "summary": "Street address.", "optional": true }, { "name": "city", "type": "string", "summary": "City.", "optional": true }, { "name": "state", "type": "string", "summary": "State.", "optional": true }, { "name": "country", "type": "string", "summary": "Country.", "optional": true }, { "name": "postalCode", "type": "string", "summary": "Postal code.", "optional": true }, { "name": "taxRegime", "type": "string", "summary": "Tax regime code.", "optional": true } ], "usage": [] } ], "types": [ { "name": "ActionToken", "module": "auth", "summary": "Short-lived JWT issued for a single sensitive action (e.g. confirm email, reset password) instead of a long-lived session.", "shape": "export type ActionToken = string;", "usage": [] }, { "name": "AdminToken", "module": "auth", "summary": "Privileged JWT bearer token for administrative users with elevated permissions across the platform.", "shape": "export type AdminToken = string;", "usage": [] }, { "name": "AppToken", "module": "auth", "summary": "JWT bearer token that authenticates a third-party application calling the API on its own behalf (no user context).", "shape": "export type AppToken = string;", "usage": [] }, { "name": "ArrayOrValueFilter", "module": "_common", "summary": "Generic filter helper accepting either a single value or an array of values, used by list endpoints to allow comma/array filters.", "shape": "export declare type ArrayOrValueFilter = T | T[];", "usage": [] }, { "name": "BetweenFilter", "module": "_common", "summary": "Generic range/equality filter accepting an exact value, an array of values, or a { gt, lt } bounds object for list-endpoint queries.", "shape": "export declare type BetweenFilter = { gt?: T; lt?: T } | T | ArrayOrValueFilter;", "usage": [] }, { "name": "CustomerPortalInvitationTokenPayload", "module": "auth", "summary": "Decoded JWT payload of an invitation token sent to a customer to onboard onto the customer portal.", "shape": "export type CustomerPortalInvitationTokenPayload = {\n type: TokenType.CustomerPortalInvitation;\n email: string;\n exp: number;\n};", "usage": [] }, { "name": "CustomError", "module": "_common", "summary": "Standard error shape used in API responses when a domain error is reported as { code, message }.", "shape": "export type CustomError = {\n code: string;\n message: string;\n};", "usage": [] }, { "name": "Doc", "module": "_common", "summary": "Generic helper that strips the Typegoose base members from a model class, leaving only the plain document fields.", "shape": "export type Doc = Omit;", "usage": [] }, { "name": "DrayageGroupId", "module": "drayage", "summary": "String alias for the public identifier of a DrayageGroup, used in URLs and inter-module references.", "shape": "export type DrayageGroupId = string;", "usage": [] }, { "name": "Email", "module": "identity", "summary": "String alias for an RFC-5322 email address; the validated wrapper lives as the Email value-object.", "shape": "export type Email = string;", "usage": [] }, { "name": "EmailConfirmationTokenPayload", "module": "auth", "summary": "Decoded JWT payload of the email-confirmation token emitted on signup and verified when a user clicks the confirmation link.", "shape": "export type EmailConfirmationTokenPayload = {\n type: \"email-confirmation\";\n userId: string;\n};", "usage": [] }, { "name": "FieldError", "module": "_common", "summary": "Per-field validation error shape attaching a code/message to a specific input field, returned in form-style endpoint responses.", "shape": "export type FieldError = {\n field: string;\n code: string;\n message: string;\n};", "usage": [] }, { "name": "FieldStatus", "module": "_common", "summary": "Per-field readiness descriptor reporting the field name, current value and whether it satisfies its completion rule.", "shape": "export type FieldStatus = {\n field: string;\n value: any;\n ready: boolean;\n};", "usage": [] }, { "name": "FilePath", "module": "_common", "summary": "String alias representing a path to a file in local storage or a remote bucket (e.g. Google Cloud Storage object key).", "shape": "export type FilePath = string;", "usage": [] }, { "name": "HexString", "module": "_common", "summary": "String alias for a hexadecimal-encoded value (transaction hashes, signatures, raw byte payloads from blockchain integrations).", "shape": "export type HexString = string;", "usage": [] }, { "name": "ID", "module": "_common", "summary": "Generic string identifier alias used for opaque domain IDs that are not necessarily Mongo ObjectIds.", "shape": "export type ID = string;", "usage": [] }, { "name": "MongoID", "module": "_common", "summary": "Union type accepted everywhere a MongoDB document identifier is expected, allowing either a string or a Mongoose ObjectId instance.", "shape": "export declare type MongoID = string | Types.ObjectId;", "usage": [] }, { "name": "MongoRef", "module": "_common", "summary": "Generic reference type representing either a populated document of type T or its raw MongoID, used for fields that may or may not be hydrated.", "shape": "export type MongoRef = X | T;", "usage": [] }, { "name": "MongoSession", "module": "_common", "summary": "Branded alias for a MongoDB client session handle threaded through transactional operations.", "shape": "export type MongoSession = any & { readonly __brand: unique symbol };", "usage": [] }, { "name": "NetworkAddress", "module": "_common", "summary": "String alias for a blockchain wallet address or other on-chain network address used by integrations.", "shape": "export type NetworkAddress = string;", "usage": [] }, { "name": "Notifier", "module": "notifications", "summary": "Polymorphic identifier for the entity that originates a notification, tagged by its kind (Company, User, or DrayageGroup) and id.", "shape": "export type Notifier = { type: \"Company\" | \"User\" | \"DrayageGroup\"; id: string };", "usage": [] }, { "name": "ObjectId", "module": "_common", "summary": "Loose alias for a MongoDB ObjectId; typed as any so it accepts both the bson type and its string serialization across the API surface.", "shape": "export type ObjectId = any;", "usage": [] }, { "name": "Phone", "module": "identity", "summary": "String alias for a phone number in E.164 or local format; the validated wrapper lives as the Phone value-object.", "shape": "export type Phone = string;", "usage": [] }, { "name": "SanitizedUser", "module": "users", "summary": "Public-facing User shape with credential-bearing fields (password, reset tokens, email-auth state) stripped before serialization.", "shape": "export type SanitizedUser = Omit;", "usage": [] }, { "name": "SignupPayload", "module": "auth", "summary": "Request body for the signup endpoint capturing the new user's credentials, full name and the company they are registering with.", "shape": "export type SignupPayload = {\n email: string;\n password: string;\n fullName: string;\n company: {\n razonSocial: string;\n rfc: string;\n entidadLegal?: string;\n usoCFDI?: string;\n website?: string;\n noExterior?: string;\n noInterior?: string;\n address?: string;\n zipcode?: string;\n city?: string;\n state?: string;\n caat?: string;\n colonia?: string;\n country?: string;\n role: string;\n };\n};", "usage": [] }, { "name": "TaskEntity", "module": "_common", "summary": "Polymorphic reference to the domain entity a task is attached to, tagged by TaskEntityType and the entity's MongoID.", "shape": "export type TaskEntity = {\n type: TaskEntityType;\n id: MongoID;\n};", "usage": [] }, { "name": "Ticket", "module": "auth", "summary": "Single-use string ticket exchanged out-of-band (email link, deep-link) and redeemed for a session token.", "shape": "export type Ticket = string;", "usage": [] }, { "name": "URL", "module": "_common", "summary": "String alias for an absolute HTTP(S) URL returned to clients (signed download URLs, redirect targets, etc.).", "shape": "export type URL = string;", "usage": [] }, { "name": "UserAppToken", "module": "auth", "summary": "JWT bearer token that authenticates a user acting through a specific third-party application integration.", "shape": "export type UserAppToken = string;", "usage": [] }, { "name": "UserName", "module": "auth", "summary": "String alias for a user's login handle or display name.", "shape": "export type UserName = string;", "usage": [] }, { "name": "UserToken", "module": "auth", "summary": "JWT bearer token returned by /auth/login that authenticates a web user for subsequent API calls.", "shape": "export type UserToken = string;", "usage": [] } ], "flows": [] }