Resumen
API de Ukrposhta (Укрпошта) para clientes empresariales en Ucrania: seguimiento de envíos, envíos y etiquetas PDF, estimaciones de precios nacionales, comprobaciones de rutas, clientes y direcciones, y el clasificador de direcciones con oficinas de correos y horarios de apertura. Creación y eliminación de envíos instalados desactivados. Portadores de contrato y token de contraparte.
Configuración guiada
Conecta Ukrposhta a Gemini en 2 minutos
Empieza la prueba gratuita en AnythingMCP Cloud, conecta Ukrposhta con la configuración guiada y añade tu URL MCP a Gemini. Sin código y sin servidores que mantener.
Sin tarjeta de crédito · 7 días de prueba · Alternativa self-host disponible
Prueba a pedir
Prompts de ejemplo para Ukrposhta
Haz clic en un prompt para copiarlo. Pégalo en Claude, ChatGPT, Cursor, Gemini, Copilot u OpenClaw para ejecutarlo contra este conector.
Claude es IA y puede equivocarse. Verifica siempre las respuestas.
💡 ¿No tienes instalación? Usa cloud.anythingmcp.com directamente. Inicia sesión, haz clic en Conectores → Ukrposhta, pega tus credenciales, genera una clave API de MCP y listo. Sin Docker, sin
git clone, sin servidor local.
Ukrposhta + Gemini
API de Ukrposhta (Укрпошта) para clientes empresariales en Ucrania: seguimiento de envíos, envíos y etiquetas PDF, estimaciones de precios nacionales, comprobaciones de rutas, clientes y direcciones, y el clasificador de direcciones con oficinas de correos y horarios de apertura. Creación y eliminación de envíos instalados desactivados. Portadores de contrato y token de contraparte.
Requisitos previos
Consulta las instrucciones completas de configuración integradas en el conector (visibles en la tienda de la aplicación cuando seleccionas el conector). Las variables de entorno requeridas para este conector son:
UKRPOSHTA_ECOM_BEARER, UKRPOSHTA_TRACKING_BEARER, UKRPOSHTA_COUNTERPARTY_TOKEN
Paso 1 — Obtener credenciales
- Firma un contrato para la API con Ukrposhta (servicio al cliente empresarial, [email protected]). Con el contrato recibirás un anexo con tus claves de producción.
- Copia PRODUCTION BEARER eCom en
UKRPOSHTA_ECOM_BEARER, PRODUCTION BEARER StatusTracking enUKRPOSHTA_TRACKING_BEARERy PROD_COUNTERPARTY TOKEN enUKRPOSHTA_COUNTERPARTY_TOKEN.
Las claves de sandbox (SANDBOX ...) no funcionan aquí: este conector llama al host de producción. El portador de eCom también abre el clasificador de direcciones y el servicio de etiquetas; el seguimiento tiene su propio portador; el token de contraparte identifica tu cuenta en las llamadas sobre tus clientes y envíos.
Dónde empezar: ukrposhta_track_shipment o ukrposhta_get_last_status con un código de barras. Para los envíos de tu cuenta, ukrposhta_get_shipment_by_barcode o ukrposhta_list_sender_shipments con el uuid del cliente remitente.
Seguimiento: ukrposhta_track_shipment (todos los eventos), ukrposhta_get_last_status, ukrposhta_get_last_statuses (hasta 50 códigos de barras) y ukrposhta_get_shipment_route. Pasa lang en para nombres de eventos en inglés.
Envíos: ukrposhta_get_shipment, ukrposhta_get_shipment_by_barcode, ukrposhta_list_sender_shipments, ukrposhta_get_shipment_lifecycle, ukrposhta_list_shipment_groups, ukrposhta_list_group_shipments, y ukrposhta_get_label (PDF). Antes de enviar, ukrposhta_check_route y ukrposhta_calculate_domestic_price (UAH, sin los descuentos de tu contrato).
Crear un envío sigue el orden de Ukrposhta: ukrposhta_create_address para el remitente y el destinatario, ukrposhta_create_client para cada uno (o reutilízalos: ukrposhta_get_client, ukrposhta_find_clients_by_phone, ukrposhta_get_address), luego ukrposhta_create_shipment, y luego la etiqueta. ukrposhta_create_shipment y ukrposhta_delete_shipment están instalados desactivados: un envío creado se cobra una vez entregado, y uno eliminado no puede ser restaurado. Las direcciones y los clientes no tienen costo.
Clasificador de direcciones: ukrposhta_search_regions, ukrposhta_search_districts, ukrposhta_search_cities, ukrposhta_search_streets, ukrposhta_get_house_postcode, ukrposhta_get_city_by_postcode, y para oficinas de correos ukrposhta_find_post_offices_by_postcode, ukrposhta_find_post_offices_near y ukrposhta_get_post_office_hours. Las respuestas vienen como listas de Entries.Entry con nombres de campo en mayúsculas; los ids son cadenas.
Unidades y trampas: peso en gramos, tamaños en cm, dinero en UAH. Tipos de entrega: W2W de oficina de correos a oficina de correos, W2D a la puerta, D2W y D2D desde la puerta. Un código postal marcado como RESTRICTED_ACCESS solo puede ser una dirección de remitente o de retorno. Estados: CREATED (no entregado aún), REGISTERED, DELIVERING, IN_DEPARTMENT (esperando en la oficina), DELIVERED, RETURNING, RETURNED, CANCELLED, DELETED. Los tiempos son hora local de Kyiv.
Paso 2 — Instalar el adaptador
curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d
Paso 3 — Agregar el conector en Gemini
La URL de tu servidor: en AnythingMCP abre MCP Servers → el servidor donde está este conector y copia su URL (
https://cloud.anythingmcp.com/mcp/…). Úsala donde esta guía muestraYOUR_SERVER_ID.
Gemini CLI lee los servidores MCP de ~/.gemini/settings.json (en Windows, %USERPROFILE%\.gemini\settings.json). Añade:
{
"mcpServers": {
"anythingmcp": {
"httpUrl": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
"headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
}
}
}
- Crea una clave de API MCP en AnythingMCP en MCP Servers → tu servidor → API keys y pégala en lugar de
YOUR_MCP_API_KEY. - Guarda el archivo y reinicia
gemini. - Ejecuta
/mcpdentro de Gemini CLI (ogemini mcp listen tu terminal):anythingmcpdebería aparecer como conectado. - Empieza a escribir prompts: Gemini CLI ya puede llamar a las herramientas de
Ukrposhta.
Herramientas disponibles
| Herramienta | Qué hace |
|---|---|
ukrposhta_track_shipment | Historial completo de estado de un envío por código de barras: por paso de evento, fecha, índice y nombre de la oficina de correos, código de evento y eventName (por ejemplo… |
ukrposhta_get_last_status | El estado más reciente de un envío por código de barras: fecha, índice y nombre de la oficina de correos, código de evento, eventName y eventReason. Solo lectura |
ukrposhta_get_last_statuses | El estado más reciente de hasta 50 envíos a la vez, más los códigos de barras que Ukrposhta no conoce: por código de barras fecha, oficina de correos, código de evento y… |
ukrposhta_get_shipment_route | Desde dónde y hacia dónde viaja un envío (país y localidad) por código de barras. Solo lectura |
ukrposhta_get_shipment | Lee un envío de tu cuenta por uuid: código de barras, tipo, clientes remitente y destinatario con direcciones, deliveryType, paquetes (peso… |
ukrposhta_get_shipment_by_barcode | Lee un envío de tu cuenta por su código de barras (mismos campos que ukrposhta_get_shipment). Solo lectura |
ukrposhta_list_sender_shipments | Lista los envíos creados para un cliente remitente: uuid, código de barras, destinatario, deliveryType, paquetes, precios y estado del ciclo de vida. Solo lectura |
ukrposhta_get_shipment_lifecycle | Estado actual de un envío desde el lado de eCom: shipmentUuid, shipmentBarcode, estado (CREATED, REGISTERED, DELIVERING, IN_DEPARTMENT… |
ukrposhta_list_shipment_groups | Lista los grupos de envíos (registros para el formulario 103a) de un cliente: uuid, nombre, tipo, fecha de creación, bandera de cerrado y número de envíos.… |
ukrposhta_list_group_shipments | Lista los envíos en un grupo de envíos: uuid, código de barras, destinatario, paquetes, precios y estado del ciclo de vida. Solo lectura |
ukrposhta_get_label | Descarga la etiqueta de dirección (sticker) de un envío que creaste, como un archivo PDF: 100 x 100 mm por defecto, o en una hoja A4 o A5. Imprimir un… |
ukrposhta_calculate_domestic_price | Estima el precio de un envío dentro de Ucrania antes de crearlo: deliveryPrice en UAH, rawDeliveryPrice, postPayDeliveryPrice… |
ukrposhta_check_route | Verifica que Ukrposhta entregue entre dos códigos postales: código (SUCCESS cuando está disponible), descripción y mrtps (donde la oficina de correos móvil de… |
ukrposhta_get_client | Lee un cliente (remitente o destinatario) de tu cuenta: uuid, tipo (INDIVIDUAL, PRIVATE_ENTREPRENEUR, COMPANY), nombre, firstName, lastName… |
ukrposhta_find_clients_by_phone | Encuentra los clientes de tu cuenta con un número de teléfono: uuid, nombre, tipo, direcciones. Solo lectura |
ukrposhta_get_address | Lee una dirección creada con ukrposhta_create_address: id, código postal, región, distrito, ciudad, calle, número de casa, número de apartamento, país… |
ukrposhta_create_address | Crea una dirección para usar para un cliente o un envío. Solo se requiere el código postal; agrega calle y casa para entrega a domicilio. Gratis; las respuestas… |
ukrposhta_create_client | Crea un cliente (remitente o destinatario) en una dirección de ukrposhta_create_address. Los individuos y empresarios privados necesitan first_name… |
ukrposhta_create_shipment | Crea un envío nacional de un cliente remitente a un cliente destinatario. Obtiene un código de barras y un precio, y se cobra una vez entregado en la… |
ukrposhta_delete_shipment | Elimina un envío que aún está en estado CREATED (no entregado aún). No se puede deshacer. Instalado desactivado |
ukrposhta_find_post_offices_by_postcode | Oficinas de correos que sirven a un código postal: ID, PO_SHORT y PO_LONG (nombre), DIRECCIÓN, TELÉFONO, TYPE_LONG, LATITUD, LONGITUD, POSTTERMINAL… |
ukrposhta_find_post_offices_near | Oficinas de correos cerca de un punto, las más cercanas primero: ID, nombre, dirección, código postal, distancia, coordenadas y tipo. Solo lectura |
ukrposhta_get_post_office_hours | Horarios de apertura de una oficina de correos por código postal: por día de la semana el horario de apertura y cierre y descansos. Solo lectura |
ukrposhta_get_city_by_postcode | La localidad, distrito y región de un código postal, con sus ids. Solo lectura |
ukrposhta_search_regions | Encuentra regiones (oblasts) por parte del nombre, en ucraniano o inglés: REGION_ID, REGION_UA, REGION_EN, códigos KOATUU y KATOTTG. Deja ambos… |
ukrposhta_search_districts | Encuentra distritos de una región por nombre: DISTRICT_ID, nombres en UA y EN, región. Solo lectura |
ukrposhta_search_cities | Encuentra localidades por nombre, opcionalmente dentro de una región y distrito: CITY_ID, nombres en UA y EN, tipo (ciudad, pueblo), distrito, región y… |
ukrposhta_search_streets | Encuentra calles de una localidad por nombre: STREET_ID, nombres en UA y EN, tipo de calle. Solo lectura |
ukrposhta_get_house_postcode | El código postal de una casa en una calle: número de casa y POSTCODE. Solo lectura |
Ejemplos de indicaciones
- "¿Dónde está el paquete de Ukrposhta 0503112345678?"
- "Muestra el último estado de estos 10 códigos de barras del despacho de ayer."
- "¿Cuánto cuesta un paquete de 2 kg de Kyiv 01001 a Lviv 79000?"
- "¿Qué oficinas de correos están cerca del código postal 65000, y cuándo están abiertas el sábado?"
- "Descarga la etiqueta del envío 0503112345678."
Preguntas frecuentes
¿De dónde vienen las claves? Solo de un contrato empresarial: Ukrposhta envía el portador de producción eCom, el portador de StatusTracking y el token de contraparte en un anexo a tu contrato de API. Las claves de sandbox no funcionan aquí.
¿Qué cubre? Seguimiento, tus envíos y grupos, etiquetas PDF, estimaciones de precios nacionales, comprobaciones de rutas, clientes y direcciones, y el clasificador de direcciones con regiones, localidades, calles, códigos postales y oficinas de correos con horarios de apertura.
¿Qué herramientas están instaladas desactivadas? ukrposhta_create_shipment y ukrposhta_delete_shipment. Actívalas en la página del conector solo si la IA debe crear o eliminar envíos.
¿Dónde busca Gemini CLI los servidores MCP? En ~/.gemini/settings.json para tu usuario, o en .gemini/settings.json dentro de un proyecto. gemini mcp list muestra cada servidor y si se conecta.
Próximos pasos
¿Te ha sido útil esta guía?