Geografía y paqueterías

Los ids que devuelven estos endpoints son exactamente los que POST /orders espera. No los deduzcas ni los mapees por nombre.

Países

Cada país trae su id (es el countryId que piden los demás endpoints de geografía y paqueterías), su moneda como par nombre/símbolo y un campo que conviene mirar antes de crear órdenes:

currencyName viene tal como lo guardamos: a veces es el código (USD), a veces el nombre (Dólar).

Referencia: GET /geo/countries.

Departamentos y municipios

curl -X GET '{BASE_URL}/integrations/v1/geo/states?countryId=6696fac87d6004185f53320a' \
  -H 'X-Drop-Key: …' -H 'X-Drop-Timestamp: …' \
  -H 'X-Drop-Nonce: …' -H 'X-Drop-Signature: …'

Cada departamento trae sus municipios anidados en cities:

• El id del departamento va en shipping.stateId al crear la orden.
• El id del municipio (cities[].id) va en shipping.cityId.
• latitude y longitude del municipio son su centro aproximado, para prellenar un mapa. Pueden venir null.

Estos ids no son los mismos que los de países: vienen del sistema logístico y son opacos. No los deduzcas ni los busques por nombre.

No hay una lista de nombres alternativos. Si tus clientes escriben un nombre distinto al del catálogo (por ejemplo, "Distrito Central" en Honduras, que en el catálogo es "Tegucigalpa"), resolvé esa equivalencia de tu lado y mandá el id que corresponde.

Esta lista cambia poco: cacheala del lado tuyo y refrescala cada tanto, en lugar de pedirla en cada orden.

Referencia: GET /geo/states.

Configuración de dirección del país

Qué niveles de dirección existen en el país y cuáles son obligatorios. La respuesta trae config.levels[], con un nivel por entrada:

Departamento y municipio son universales; algunos países definen un nivel adicional (el poblado en Guatemala, el distrito en Costa Rica), que se manda en shipping.extraLevels con el id de uno de los valores de levelValues. La respuesta puede traer campos de configuración interna además de los documentados: ignorá los que no reconozcas.

Referencia: GET /geo/countries/{countryId}/address-config.

Paqueterías del país

Todas las paqueterías del país, con su tarifa base de envío (dropPrice), su tasa histórica de entregas exitosas (efectivityPercentage) y la comisión sobre el monto cobrado contra entrega (codCommissionPercentage), que ya lleva aplicada tu comisión preferencial si tenés una negociada. El id es el que va en courierId al crear la orden.

dropPrice es la tarifa base del país, no el costo de una orden tuya. Para cotizar una ruta usá el price de Paqueterías que cubren una ruta; el costo real de cada orden viene en su shippingCost desde que se despacha (ver Costos de la orden).

Esta lista no verifica cobertura. Son todas las del país. Para saber cuáles pueden llevar una orden concreta, usá Paqueterías que cubren una ruta.

Cargo Expreso pide los niveles de dirección adicionales del país (el poblado en Guatemala). Si la elegís, o si dejás que Drop resuelva la paquetería y cae en ella, tenés que mandar shipping.extraLevels. El resto no los necesita.

Referencia: GET /couriers.

Paqueterías que cubren una ruta

Las que de verdad pueden llevar esa orden. Es lo que conviene ofrecerle a tu usuario: la lista del país incluye paqueterías que no llegan al destino, y si elegís una de esas la orden se despacha con otra.

curl -X GET '{BASE_URL}/integrations/v1/couriers/available?catalogId=65b0…c1&cityId=65b0…b01' \
  -H 'X-Drop-Key: …' -H 'X-Drop-Timestamp: …' \
  -H 'X-Drop-Nonce: …' -H 'X-Drop-Signature: …'

La respuesta es { couriers, unverifiedCount }. Cada paquetería trae su price para esa ruta (ya incluye tus condiciones preferenciales), su codCommissionPercentage, los días en que entrega y recolecta, y requiresAddressExtraLevels, que te dice si con esa paquetería tenés que mandar shipping.extraLevels.

Si igual preferís no elegir, omití courierId al crear la orden y la resolvemos nosotros. Y si elegís una que no cubra, te lo decimos en requestedCourier (Crear una orden).

Referencia: GET /couriers/available.