La integración vía API con Inter Rapidísimo se distingue de otras transportadoras debido a que antes de poder cotizar o crear un envío, debes solicitar la verificación de una dirección de origen que está representada por un template_id.
Realiza los siguientes pasos para realizar tus envíos por API con Inter Rapidísimo.
¿Por qué Inter Rapidísimo requiere una dirección verificada?
Interrapidísimo valida las direcciones de origen antes de procesar guías. Por eso, en lugar de enviar los datos completos de la dirección en cada request de cotización o envío, se utiliza un template_id que es el identificador de una dirección que ya fue registrada y verificada en la plataforma. Esto garantiza que la dirección de origen sea válida y reduce errores al momento de generar guías.
Paso 1 — Obtén el ID de tu dirección
Tienes dos caminos:
Opción A
Si aún no tienes direcciones guardadas, usa el endpoint POST /api/v1/address_templatespara guardar una dirección.
Request:
POST /api/v1/address_templates
Authorization: Bearer {{TOKEN}}
Content-Type: application/json
{
"address": {
"name": "Almacén Principal",
"street1": "Carrera 7 # 32-16",
"area_level1": "Cundinamarca",
"area_level2": "Bogotá",
"area_level3": "La Candelaria",
"country_code": "CO",
"postal_code": "110111",
"phone": "573001234567",
"email": "almacen@ejemplo.com",
"company": "Mi Empresa S.A.S.",
"tax_id_number": "900123456-1"
}
}
Response (201):
{
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"type": "address_template",
"attributes": {
"name": "Almacén Principal",
"street1": "Carrera 7 # 32-16",
"area_level1": "Cundinamarca",
"area_level2": "Bogotá",
"country_code": "CO",
"postal_code": "110111",
"phone": "573001234567",
"email": "almacen@ejemplo.com"
}
}
}
Al crear la dirección exitosamente, el response te devuelve un id — ese es tu template_id.
Opción B
Si ya tienes direcciones guardadas, consúltalas con GET /api/v1/address_templates para recuperar el template_id de la que quieres usar como origen.
Request
GET /api/v1/address_templates
Authorization: Bearer {{TOKEN}}
Response (200):
{
"data": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"type": "address_template",
"attributes": {
"name": "Almacén Principal",
"area_level2": "Bogotá",
"country_code": "CO"
}
}
]
}
También puedes consultar una dirección específica con GET /api/v1/address_templates/{id}.
Una vez que tengas tu dirección guardada, solicita tu ID siguiendo el proceso dentro de la plataforma. La transportadora debe validar la cobertura de tu dirección y el proceso puede tardar 2 días hábiles.
Ejemplo de dirección en proceso de validación:
{
"id": "dd39a8a4-a4aa-4ee2-91d9-52ae6fddde8f",
"alias_name": "Bodega Cali Nueva",
"address_type": "from",
"default": false,
"address": {
"name": "Carlos Garcia",
"company": "Envios Rapidos SAS",
"street1": "Carrera 7 71-21",
"street_number": "71-21",
"apartment_number": "301",
"postal_code": "76001",
"area_level1": "Valle del Cauca",
"area_level2": "Cali",
"area_level3": null,
"country_code": "CO",
"phone": "3001234567",
"email": "carlos@example.com",
"reference": "Edificio Torre Central",
"rfc": "900123456-8",
"tax_id_number": "900123456-8",
"tax_id_type": "nit"
},
"verified_carriers": [
{
"carrier_name": "interrapidisimo",
"status": "process",
"verification_id": null
}
]
}
Ejemplo de dirección validada:
{
"id": "da96358b-689a-46ce-9800-9067d9269e54",
"alias_name": "Origen",
"address_type": "from",
"default": true,
"address": {
"name": "cotizacion ejemplo",
"company": "cotizacion ejemplo",
"street1": "Cra 67 # 100 - 21",
"street_number": "100-20",
"apartment_number": null,
"postal_code": "11001000",
"area_level1": "Bogota D.C.",
"area_level2": "Bogota",
"area_level3": "test",
"country_code": "CO",
"phone": "3005024367",
"email": "fernando.diaz@skydropx.com",
"reference": "Ref Origen",
"rfc": null,
"tax_id_number": "",
"tax_id_type": null
},
"verified_carriers": [
{
"carrier_name": "interrapidisimo",
"status": "verified",
"verification_id": "30622"
}
]
}
Paso 2 — Cotiza usando el ID de tu dirección
Al incluir el template_id en el campo address_from de tu solicitud de cotización, no necesitas repetir los datos completos de la dirección de origen.
Request:
POST /api/v1/quotations
Authorization: Bearer {{TOKEN}}
Content-Type: application/json
{
"quotation": {
"address_from": {
"template_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"address_to": {
"country_code": "CO",
"postal_code": "050001",
"area_level1": "Antioquia",
"area_level2": "Medellín"
},
"parcels": [
{
"length": 20,
"width": 15,
"height": 10,
"weight": 1.5,
"declared_amount": 50000
}
]
}
}
Recuerda incluir el campo declared_amount (valor declarado) en pesos colombianos dentro de cada paquete.
Response (201):
{
"id": "9f9b21c4-1802-4427-8cd3-ffb41c3a9b5f",
"quotation_scope": {
"found_carriers": [
"interrapidisimo"
],
"carriers_scoped_to": "PARTIALLY_SELECTED_CARRIERS",
"not_found_carriers": []
},
"is_completed": true,
"cash_on_delivery": false,
"recipient_pays_shipping": false,
"on_delivery_amount": null,
"address_template_from_id": "da96358b-689a-46ce-9800-9067d9269e54",
"address_template_to_id": null,
"requires_origin_verification": false,
"rates": [
{
"success": true,
"id": "19b22a5c-c0ba-4dee-a21c-b2e2f1dfe4de",
"rate_type": null,
"provider_name": "interrapidisimo",
"provider_display_name": "Inter Rapidísimo",
"provider_service_name": "Mensajeria Express",
"provider_service_code": "mensajeria",
"status": "price_found_internal",
"currency_code": "COP",
"amount": "20668.20",
"total": "21543.20",
"days": 1,
"insurable": null,
"has_own_agreement": false,
"own_agreement_amount": null,
"zone": "NACIONAL_A",
"service_zone": "NACIONAL_A",
"vat_fee": "0.0",
"country_code": null,
"plan_type": null,
"packaging_type": "package",
"error_messages": null,
"extra_fees": [
{
"code": "insurance_3",
"value": 875.0000000000001,
"groupable": false,
"group_code": null
}
],
"external_price": "21543.2",
"weight": "3.0",
"protection_value_total": 0,
"total_value_with_protection": "21543.20",
"pickup": true,
"pickup_automatic": false,
"pickup_package_min": 0,
"pickup_ocurre": true,
"pickup_via_support": false,
"shipment_creation_type": "single",
"requires_origin_verification": false
}
Dado que la cotización se completa de forma progresiva, verifica el campo is_completed antes de leer los rates (tarifas).
Identifica el rate de Interrapidísimo por su provider_name y guarda el rate_id.
Los rates tienen validez de 24 horas.
Paso 3 — Crea el envío
Con el rate_id crea el envío usando POST /api/v1/shipments/. Debes volver a referenciar el template_id en el campo address_from — no hace falta repetir los datos de origen.
Request:
POST /api/v1/shipments/
Authorization: Bearer {{TOKEN}}
Content-Type: application/json
{
"shipment": {
"rate_id": "rate-xyz789",
"address_from": {
"template_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"address_to": {
"street1": "Calle 50 # 40-20",
"name": "María García",
"company": "Empresa Destino S.A.S.",
"phone": "573109876543",
"email": "maria@destino.com",
"reference": "Oficina 301"
},
"packages": [
{
"package_content": "Ropa",
"package_number": "1"
}
]
}
}
Para la dirección de destino sí deberás enviar los datos completos del destinatario.
El campo package_content es requerido al crear el envío. Describe ahí el contenido del paquete en texto libre, por ejemplo: "Ropa" o "Electrónica".
Si la solicitud es exitosa, el response incluye el número de rastreo y la URL de la guía lista para descargar.
Response 202:
{
"data": {
"id": "envio-def456",
"type": "shipment",
"attributes": {
"carrier_name": "interrapidisimo",
"workflow_status": "pending",
"payment_status": "paid",
"master_tracking_number": "IR123456789CO",
"total": "12500.0"
}
},
"included": [
{
"type": "package",
"attributes": {
"tracking_number": "IR123456789CO",
"label_url": "https://pro.skydropx.com/labels/IR123456789CO.pdf"
}
}
]
}
El envío queda creado con su número de rastreo (master_tracking_number) y la guía lista para descargar en label_url.
¿Necesitas ayuda?
Si tienes dudas sobre tu integración, escríbenos a api@skydropx.com.
