API SIRE y TRA para tu PMS

Conecta tu PMS con Digitra Rentals y reporta cada huésped a la TRA del MinCIT y al SIRE de Migración Colombia: crea reservas con tu propio identificador, envía el enlace de registro al huésped y recibe cada avance por webhook.

Esta guía explica cómo conectar tu PMS (Guesty u otro) con la API de Digitra Rentals para reportar automáticamente a la TRA del MinCIT (Tarjeta de Registro de Alojamiento) y al SIRE de Migración Colombia, sin integrar tú mismo cada sistema del Estado. Con ella:

1. cada reserva nueva de tu PMS se cree en Digitra con tu propio identificador;
2. Digitra te devuelva el enlace de registro para enviárselo al huésped;
3. Digitra te avise por webhook de cada avance (registro, firma, reportes a TRA y SIRE);
4. puedas consultar el estado de cualquier reserva y modificarla o cancelarla.

Digitra no se conecta a tu PMS: tu sistema llama a Digitra, y Digitra le avisa a tu sistema.

• Especificación completa (OpenAPI 3): la referencia de la API (openapi.yaml)
• Webhooks en detalle: Webhooks
• Ejemplos de verificación de firma: verificar-firma.js y verificar_firma.py
• Colección de Postman: digitra-api.postman_collection.json

1. Autenticación

Cada petición lleva tu llave en el header Authorization:

Authorization: Bearer dgt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Hay dos tipos de llave, y la llave decide el ambiente:

• La URL base es la misma para los dos ambientes: https://digitra.rentals.
• Cada llave solo ve las propiedades, reservas y webhooks de tu cuenta.
• Una llave de pruebas no puede tocar propiedades reales, y una de producción no puede tocar las de prueba.
• Cada llave se muestra una sola vez, al crearla. Guárdala como un secreto (en variables de entorno o en un gestor de secretos, nunca en el código ni en el navegador). Si se pierde o se filtra, revócala y crea otra.

Cómo obtener tus llaves

Las creas tú mismo en el panel de Digitra, en Configuración → API. Si no ves esa pestaña, escríbenos para habilitar la API en tu cuenta.

• Pruebas: el botón Crear ambiente de pruebas te arma dos propiedades de prueba y te entrega tu primera llave dgt_test_. Ahí mismo ves los property_id de esas propiedades.
• Producción: al crear una llave dgt_live_ te enviamos un código a tu correo para confirmar que eres tú, y cuando la creas te avisamos por correo. Si recibes ese aviso y no fuiste tú, revoca la llave de inmediato.
• Puedes tener hasta 3 llaves activas de cada tipo, por ejemplo una por sistema. Revocar una llave no afecta a las demás.

2. Flujo completo

Reserva nueva en tu PMS
        │
        ▼
POST /api/partners/reservations        ← con tu reservation_id como external_id
        │  201: { reservation_id, checkin_url, ... }
        ▼
Tu PMS le envía checkin_url al huésped (correo, WhatsApp, mensaje de la OTA)
        │
        ▼
El huésped se registra en Digitra (datos, documento, firma si aplica)
        │
        ▼
Webhooks a tu URL:
  registration.completed → contract.signed → sire.reported → tra.reported
        │
        ▼
GET /api/partners/registrations?external_id=...   ← cuando quieras el detalle

Paso 0 — Conocer tus propiedades

curl https://digitra.rentals/api/partners/properties \
  -H "Authorization: Bearer $DIGITRA_KEY"

{
  "properties": [
    {
      "property_id": "3f1c2b9a-0d4e-4a51-9a7e-2b6f0c8d1e23",
      "external_id": null,
      "rnt_id": "123456",
      "name": "Apartamento 501",
      "internal_name": "501",
      "checkin_enabled": true,
      "compliance": { "tra": true, "sire": true },
      "requires_contract_signature": false,
      "requires_document_photos": true
    }
  ]
}

compliance te dice si esa propiedad reporta TRA y SIRE. Si alguna aparece en false y debería reportar, escríbenos antes de empezar.

Paso 1 — Asociar tus listings (una sola vez)

Para crear reservas con el id de la propiedad en tu PMS (en Guesty, el listing_id), asocia cada propiedad de Digitra con ese id:

curl -X PATCH https://digitra.rentals/api/partners/properties \
  -H "Authorization: Bearer $DIGITRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mappings": [
      { "property_id": "3f1c2b9a-0d4e-4a51-9a7e-2b6f0c8d1e23", "external_id": "64f1a2b3c4d5e6f7a8b9c0d1" }
    ]
  }'

• Se aplica todo o nada: si un mapeo falla, no se cambia ninguno.
• external_id: null quita la asociación.
• Un mismo external_id no puede estar en dos propiedades.

También puedes identificar la propiedad por property_id (el de Digitra) o por rnt_id. Solo se envía uno de los tres.

Paso 2 — Crear la reserva

curl -X POST https://digitra.rentals/api/partners/reservations \
  -H "Authorization: Bearer $DIGITRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "65a1b2c3d4e5f6a7b8c9d0e1",
    "source": "guesty",
    "property_external_id": "64f1a2b3c4d5e6f7a8b9c0d1",
    "check_in": "2026-10-10",
    "check_out": "2026-10-12",
    "guest_name": "María Pérez",
    "guests_count": 2,
    "guest_email": "huesped@ejemplo.com",
    "guest_phone": "+573001234567",
    "total_amount": 850000,
    "currency": "COP",
    "metadata": { "guesty_listing": "64f1a2b3c4d5e6f7a8b9c0d1", "canal": "airbnb" }
  }'

Respuesta 201:

{
  "ok": true,
  "reservation_id": "manual-1727650000000",
  "external_id": "65a1b2c3d4e5f6a7b8c9d0e1",
  "status": "pending_checkin",
  "reservation_status": "confirmed",
  "checkin_token": "8b0c4f7e-2a1d-4c3b-9e5f-6a7b8c9d0e1f",
  "checkin_status": "pending",
  "guests_registered": 0,
  "tra": { "status": "not_applicable", "sends_on": "2026-10-12", "reported_at": null, "mincit_code": null,
           "warning": "Aún no hay huéspedes registrados. El TRA se programa cuando el huésped complete el check-in." },
  "sire": { "status": "not_applicable", "foreign_guests": 0, "reported_at": null },
  "source": "guesty",
  "metadata": { "guesty_listing": "64f1a2b3c4d5e6f7a8b9c0d1", "canal": "airbnb" },
  "checkin_url": "https://digitra.rentals/checkin/8b0c4f7e-2a1d-4c3b-9e5f-6a7b8c9d0e1f",
  "created_at": "2026-09-30T15:04:05.000Z"
}

checkin_url es el enlace que le envías al huésped. Digitra no se lo envía por su cuenta en este flujo: lo decides tú, desde tu PMS.

Paso 3 — Recibir los avisos

Registra tu URL una vez (ver Webhooks) y Digitra te avisará de cada avance.

Paso 4 — Consultar cuando lo necesites

curl "https://digitra.rentals/api/partners/registrations?external_id=65a1b2c3d4e5f6a7b8c9d0e1" \
  -H "Authorization: Bearer $DIGITRA_KEY"

Agrega &include=guests para recibir los datos de cada huésped registrado (documento, nacionalidad, residencia, contacto y fecha de registro). Sin ese parámetro la respuesta trae solo estados, sin datos personales.

Cada huésped trae document_uploaded: true si subió la foto del documento y false si no. La imagen nunca viaja por la API. Treinta días después de la salida las fotos se borran por política de retención de datos y el campo pasa a null.

También existe GET /api/partners/registrations/{external_id}. Si tu identificador puede llevar /, usa la forma con ?external_id=.

El campo status

Es el único campo que necesitas mirar para saber en qué va la reserva:

tra.status y sire.status traen el detalle de cada reporte. Cuando un reporte no va a salir por un motivo de configuración, warning lo explica.

3. Idempotencia: reintentar sin miedo

La combinación (tu llave, external_id) es única y está garantizada en la base de datos.

Ejemplo: tu servidor envía el POST, se corta la conexión y no sabes si llegó. Reenvía exactamente el mismo cuerpo: si ya se había creado, recibes 200 con la misma reserva y el mismo checkin_url.

4. Cambios y cancelaciones

Modificar

curl -X PATCH https://digitra.rentals/api/partners/reservations \
  -H "Authorization: Bearer $DIGITRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "65a1b2c3d4e5f6a7b8c9d0e1", "check_out": "2026-10-13", "guests_count": 3 }'

Campos modificables: check_in, check_out, guests_count, guest_name, guest_email, guest_phone, notes, metadata. La respuesta trae el estado actualizado y changed con lo que cambió.

Reglas:

• Una reserva cancelada no admite cambios (409 reservation_cancelled).
• El TRA se reporta a MinCIT el día de llegada del huésped. Después de eso, lo único que se puede cambiar por API es ampliar la salida: Digitra registra las noches nuevas ante MinCIT automáticamente. Mover la llegada, acortar la estadía o cambiar fechas cuya entrada ya se reportó a Migración Colombia no se puede por API (409 already_reported). Escríbenos: hay que corregirlo también ante la autoridad.
• guests_count no puede ser menor que los huéspedes ya registrados (409 guests_already_registered).

Cancelar

curl -X POST https://digitra.rentals/api/partners/reservations/cancel \
  -H "Authorization: Bearer $DIGITRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "65a1b2c3d4e5f6a7b8c9d0e1", "reason": "Cancelada en Guesty" }'

• Una reserva cancelada no se reporta a TRA ni a SIRE. Si ya estaba incluida en un reporte SIRE pendiente, sale de él.
• Es idempotente: cancelar dos veces devuelve 200 las dos (already_cancelled: true la segunda).
• Si algo ya se había reportado antes de cancelar, already_reported lo indica y warning lo explica. Ese reporte no se anula automáticamente; escríbenos para corregirlo ante la autoridad.

Cancela siempre en Digitra cuando cancelen en tu PMS. Si no, la reserva se reportará como si el huésped hubiera llegado.

5. Ambiente de pruebas

Con tu llave dgt_test_ trabajas sobre propiedades de prueba. El contrato es idéntico al de producción, con estas diferencias:

• TRA y SIRE se simulan. Las respuestas y los webhooks traen "sandbox": true y cada reporte trae "simulated": true. Cuando el registro se completa, los dos reportes pasan a success al instante (en producción, el TRA sale el día de llegada del huésped).
• Nada sale del sistema hacia MinCIT, Migración Colombia ni la aseguradora.
• Para probar el manejo de errores, crea una reserva con "sandbox_simulate": "tra_failed" o "sandbox_simulate": "sire_failed". El reporte correspondiente queda en error y recibes el webhook tra.failed o sire.failed.
• Puedes abrir el checkin_url y registrarte como huésped de prueba. Usa datos ficticios.

6. Errores

Todas las respuestas de error tienen esta forma:

{ "error": "Mensaje legible", "code": "reservation_conflict", "details": { } }

Programa contra code, que es estable. error es un texto para humanos y puede cambiar.

7. Límites de peticiones

Cada respuesta incluye:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1727650060

Al superarlo recibes 429 con Retry-After (segundos).

8. Buenas prácticas

• Guarda nuestro reservation_id junto a tu reserva. No es obligatorio (todo funciona con tu external_id), pero ayuda cuando nos escribes por soporte.
• Procesa los webhooks de forma idempotente: deduplica por X-Digitra-Event-Id.
• No uses los webhooks como única fuente. Si tu receptor estuvo caído, consulta el estado con GET o reenvía los eventos desde el historial (Webhooks).
• Cancela en Digitra cada reserva que se cancele en tu PMS.
• Nunca pongas la llave en el navegador ni en una app móvil: las llamadas se hacen desde tu servidor.

9. Preguntas frecuentes sobre la API de SIRE y TRA

¿Migración Colombia tiene una API pública para reportar el SIRE?

Para alojamientos, el SIRE se reporta en el portal de Migración Colombia, huésped por huésped o con carga de un archivo plano; no hay una API pública documentada para hoteles y viviendas turísticas. La API de Digitra Rentals cubre ese hueco: tu PMS envía los datos del huésped y Digitra Rentals hace el reporte SIRE por ti.

¿Cómo se conecta un PMS con la TRA del MinCIT?

La TRA tiene una integración oficial para PMS que usa un token por RNT. El token se pide en pms.mincit.gov.co/token y llega al correo registrado en el RNT. Con la API de Digitra Rentals no programas esa integración: guardas el token en tu propiedad y Digitra Rentals envía la TRA el día de llegada del huésped, y las noches nuevas si se amplía la estadía.

¿A quién se reporta cada huésped?

Todo huésped va a la TRA. Los extranjeros, además, van al SIRE. Tú envías los mismos datos para todos y Digitra Rentals decide a dónde va cada uno; el estado de los dos reportes te llega en la consulta y por webhook.

¿Qué necesito para empezar?

• RNT activo y su token TRA.
• Si recibes extranjeros, tu código SIRE de Migración Colombia. Si aún no lo tienes, el asistente gratuito de digitra.rentals/sire te ayuda a pedirlo.
• La API habilitada en tu cuenta de Digitra Rentals. Tus llaves las creas en Configuración → API.

¿Puedo probar la integración sin reportar nada real?

Sí. Con una llave dgt_test_ trabajas sobre propiedades de prueba: TRA y SIRE se simulan y nada sale hacia el MinCIT ni hacia Migración Colombia (ver Ambiente de pruebas).