Associate child guides with a master guide

Descripción

Allows associating one or more guide batches with an existing master guide.

⚠️ Precondition: Before associating a batch, verify via GET /hawb/{batchId} that processingGuides = 0.

Up to 5 batches per request. For more than 5 batches, make multiple calls.

Rate limiting: 15 associations per minute per client.

Step 5 of 6 in the nationalization flow:

Authentication
POST /hawb
GET /hawb/{batchId} → verify processingGuides = 0
POST /mawb
POST /mawb/hawb ← HERE
POST /mawb/nationalization

🔐 Authentication required


Header	`Authorization: Bearer <access_token>`
Token (TEST)	`POST https://api-test.coordinadora.tech/oauth/token`
Token (PROD)	`POST https://api.coordinadora.tech/oauth/token`
Method	Basic Auth — Client ID as username, Client Secret as password
Body	`Content-Type: application/x-www-form-urlencoded` · `grant_type=client_credentials`
Validity	3600 seconds
HTTP 401	Token not sent, invalid or expired

Credentials (Client ID and Client Secret) are provided by Coordinadora's Technology Department.

Quick Start

Obtén tus credenciales de acceso (Bearer Token).
Selecciona el ambiente y completa los parámetros requeridos.
Envía la solicitud y procesa la respuesta.

Ejemplo rápido

Generando ejemplo…

Generando ejemplo…

Generando ejemplo…

Endpoint

POST /mawb/hawb

Base URL https://api-dev.coordinadora.tech/nacionalizacion

Parámetros

Sin parámetros declarados.

Body *

{
    "$ref": "#/components/schemas/AssociateChildGuidesRequest"
}

Ejemplo de request

[]

Respuesta

200

Guides associated successfully.

{
    "isError": false,
    "data": {
        "mawb": "MAWB-12345678",
        "total_associated_guides": 150,
        "total_weight_kg": 345.67,
        "batches": [
            {
                "batch": "b7e6a3c6-3392-4d23-8f0a-1725841e7e4e",
                "guides": 100
            },
            {
                "batch": "264081134-1776785291254-9d6c97",
                "guides": 50
            }
        ],
        "message": "Guides associated successfully",
        "processingTime": "123ms"
    }
}

Ejemplo de respuesta

200 Guides associated successfully.

{
    "isError": false,
    "data": {
        "mawb": "MAWB-12345678",
        "total_associated_guides": 150,
        "total_weight_kg": 345.67,
        "batches": [
            {
                "batch": "b7e6a3c6-3392-4d23-8f0a-1725841e7e4e",
                "guides": 100
            },
            {
                "batch": "264081134-1776785291254-9d6c97",
                "guides": 50
            }
        ],
        "message": "Guides associated successfully",
        "processingTime": "123ms"
    }
}

Errores

400

One or more of the provided batch IDs do not exist or are invalid.

{
    "isError": true,
    "data": {
        "ok": "The following batches do not exist or have no child guides: INVALID-BATCH-1",
        "message": "The following batches do not exist or have no child guides: INVALID-BATCH-1",
        "detail": "Error ID: 61ac231149f2431"
    }
}

401

Unauthorized. The authentication token is invalid, has expired, or was not provided.

JWT has expired

404

The specified master guide was not found.

{
    "isError": true,
    "data": {
        "ok": "Master guide does not exist",
        "message": "Master guide does not exist",
        "detail": "Error ID: c139033957a17358"
    }
}

409

Conflict. The operation cannot be completed due to a business rule.

{
    "isError": true,
    "data": {
        "ok": "Business conflict",
        "message": "Cannot associate {totalNuevas} child guides. Already have {totalActual}. Limit {limite}",
        "detail": "The maximum number of guides that can be associated with a master has been exceeded."
    }
}

500

Internal server error.

{
    "isError": true,
    "data": {
        "ok": "Internal server error",
        "message": "Internal server error",
        "detail": "An unexpected error occurred while processing the request."
    }
}