API docs by Redocly

PTM Sandbox API (1.0.0)

Download OpenAPI specification:Download

API del entorno sandbox de la Plataforma de Trazabilidad Minera (PTM) de Colombia. Este servicio es un simulador de la plataforma de trazabilidad de la ANM (Agencia Nacional de Minería): reproduce el comportamiento de las integraciones reales (registro de actores, transacciones de compraventa, reversiones, transformaciones y consultas de cupos) contra validaciones simuladas de RUCOM, RNEC y ANNA MINERÍA, sin efectos sobre los sistemas productivos.

Está pensado para que los integradores prueben sus flujos de extremo a extremo antes de conectarse al ambiente productivo. No procesa datos reales ni tiene validez legal.

Documenta únicamente los endpoints orientados al integrador. La maquinaria interna (provisión de datasets, hooks de Cognito, procesos automáticos, administración destructiva de usuarios) no forma parte de este contrato.

Gestión de usuarios y acceso

Autenticación de administradores y obtención del token dual OTTM + Comercializador.

Autenticación de administrador

Autentica usuarios administradores (admin_anm) vía Cognito. Soporta el flujo de login inicial (email + contraseña) y la respuesta al reto NEW_PASSWORD_REQUIRED para establecer una contraseña permanente. Endpoint público (sin headers de autenticación).

Request Body schema: application/json
email
required
string <email>

Email del usuario administrador.

password
string

Contraseña actual (login inicial).

session
string

Session token recibido en el reto (respuesta al reto).

new_password
string

Nueva contraseña a establecer (respuesta al reto).

Responses

Request samples

Content type
application/json
Example
{
  • "email": "admin@example.com",
  • "password": "MiPassword123!"
}

Response samples

Content type
application/json
Example
{
  • "access_token": "eyJhbGc...",
  • "token_type": "Bearer",
  • "expires_in": 3600
}

Autenticación dual OTTM + Comercializador

Autentica simultáneamente un OTTM y un Comercializador usando sus credenciales. Retorna un JWT HS256 único con ambos clientid en los claims, requerido por todos los endpoints de transacciones y transformaciones. El token es válido por 30 minutos.

Authorizations:
OcpApimKey
Request Body schema: application/json
required
object (ClientCredentials)
required
object (ClientCredentials)

Responses

Request samples

Content type
application/json
{
  • "opt": {
    },
  • "com": {
    }
}

Response samples

Content type
application/json
{
  • "accessToken": "eyJhbGc...",
  • "expiresIn": 1800,
  • "expiresOn": "2026-04-20T12:30:00Z"
}

Utilidad

Endpoints operativos y de salud del servicio.

Sonda de salud

Sonda de actividad (liveness) del servicio. No requiere autenticación.

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}

Registro de actores

Alta autoservicio de OTTM, comercializadores, mineros de subsistencia y títulos mineros.

Registro de OTTM

Registra un Operador Técnico de Trazabilidad Minera (OTTM). Genera automáticamente credenciales (clientid, client_secret, ocp_apim_subscriptionkey) y las envía por correo (SES) al email registrado.

Nota de autenticación: este endpoint fue abierto como autoservicio y actualmente se protege con Ocp-Apim-Subscription-Key, igual que el resto de endpoints de registro (ya no requiere el JWT RS256 de administrador).

Authorizations:
OcpApimKey
Request Body schema: application/json
document_type_id
required
integer

ID del tipo de documento.

document
required
string

Número de documento.

business_name
required
string

Razón social del OTTM.

email
required
string <email>

Email de contacto principal.

position_id
required
integer

ID de posición (debe ser OPT).

system_name
string

Sistema de referencia (default: RUCOM).

alternate_email
string
phone_number1
string
dane
string

Código DANE del municipio.

address_contact
string

Responses

Request samples

Content type
application/json
{
  • "document_type_id": 1,
  • "document": "900123456",
  • "business_name": "Minería SA",
  • "email": "contacto@mineria.com",
  • "position_id": 1,
  • "system_name": "RUCOM",
  • "alternate_email": "alt@mineria.com",
  • "phone_number1": "3001234567",
  • "dane": "11001",
  • "address_contact": "Calle 123, Bogotá"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "message": "OTTM registrado exitosamente.",
  • "mining_actor_id": "12345",
  • "business_name": "Minería SA",
  • "position_name": "Operador Técnico"
}

Registro de Comercializador

Registra un Comercializador (CM) en el sistema PTM. Valida la existencia del actor en RUCOM (simulado) antes de persistir. Genera y envía las credenciales por correo (SES).

Authorizations:
OcpApimKey
Request Body schema: application/json
system_name
required
string
document_type_id
required
integer
position_type
required
string

Tipo de posición del actor.

required
object

Responses

Request samples

Content type
application/json
{
  • "system_name": "RUCOM",
  • "document_type_id": 1,
  • "position_type": "CM2",
  • "person": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "message": "Comercializador registrado exitosamente.",
  • "mining_actor_id": "67890",
  • "business_name": "Comercializadora XYZ",
  • "position_name": "Comercializador"
}

Registro de Minero de Subsistencia

Registra un Minero de Subsistencia (MS1/MS2/MS3). Valida la identidad en RNEC (simulado) antes de persistir e inicializa las cuotas anuales automáticamente. Los CUOMs no se generan en el registro: se crean al momento de la venta y se asignan al comprador.

Authorizations:
OcpApimKey
Request Body schema: application/json
document_type_id
required
integer

1=NIT, 2=CC, 3=CE, 4=PA.

document
required
string
business_name
required
string

Nombre completo o razón social.

email
required
string <email>
alternate_email
string
phone_number1
string
dane
string
address_contact
string

Responses

Request samples

Content type
application/json
{
  • "document_type_id": 2,
  • "document": "12345678",
  • "business_name": "Juan Pérez",
  • "email": "juan@example.com",
  • "alternate_email": "j.perez@gmail.com",
  • "phone_number1": "3201234567",
  • "dane": "68001",
  • "address_contact": "Vereda El Oro, Bucaramanga"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "message": "Minero de Subsistencia registrado exitosamente.",
  • "mining_actor_id": "11111",
  • "business_name": "Juan Pérez",
  • "position_name": "Minero de Subsistencia"
}

Registro de Título Minero

Registra un Título Minero en el sistema PTM. Valida la existencia del expediente en ANNA MINERÍA (simulado) antes de persistir y asocia el título al actor minero correspondiente.

Authorizations:
OcpApimKey
Request Body schema: application/json
document_type_id
required
integer

Tipo de documento del titular.

document
required
string

Documento del titular del título.

proceedings
required
string

Número de expediente del título minero.

mineral
required
string

Código del mineral (ej. AU, AG).

position_id
required
integer

ID de posición del titular.

Responses

Request samples

Content type
application/json
{
  • "document_type_id": 1,
  • "document": "900123456",
  • "proceedings": "IGA-123",
  • "mineral": "AU",
  • "position_id": 3
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "message": "Título Minero registrado exitosamente.",
  • "title_id": "55555"
}

Consultas

Consulta de credenciales de OTTM y de cupos de mineros de subsistencia.

Consultar credenciales de OTTM

Consulta las credenciales API de un OTTM registrado a partir de su número de documento.

Authorizations:
OcpApimKey
Request Body schema: application/json
person_id
required
string

Documento del OTTM.

Responses

Request samples

Content type
application/json
{
  • "person_id": "900123456"
}

Response samples

Content type
application/json
{
  • "ocp_apim_subscriptionkey": "abc123def456",
  • "person_id": "900123456",
  • "clientid": "CLIENT_ID_VALUE",
  • "client_secret": "SECRET_VALUE",
  • "version": 1,
  • "enabled": true
}

Consulta de cupos de Minero de Subsistencia

Consulta los cupos anuales disponibles de un Minero de Subsistencia por mineral y año. Retorna la cuota anual y el saldo disponible.

Authorizations:
OcpApimKey
Request Body schema: application/json
document_type_id
required
integer
document
required
string

Número de documento del minero.

mineral
required
string

Código del mineral.

year
integer

Año de consulta (default: año actual).

Responses

Request samples

Content type
application/json
{
  • "document_type_id": 2,
  • "document": "12345678",
  • "mineral": "AU",
  • "year": 2026
}

Response samples

Content type
application/json
{
  • "document_type": 2,
  • "document": "12345678",
  • "position_name": "Minero de Subsistencia",
  • "law": "Decreto 1073/2015",
  • "quota": [
    ]
}

Cuotas

Configuración de cuotas anuales de mineros de subsistencia (backoffice).

Configurar cuotas anuales de un minero de subsistencia

Endpoint de backoffice (no forma parte del catálogo ANM). Actualiza las cuotas anuales de un Minero de Subsistencia para el año en curso. Solo aplica a actores de tipo minero de subsistencia y activos.

Si alguna cuota nueva es menor al consumo ya acumulado, responde 409 con requiere_confirmacion: true; envíe forzar_si_conflicto: true para aplicar el cambio de todas formas.

Formato de error: este endpoint de backoffice usa un formato de error distinto al estándar del catálogo (ver AdminError / QuotaConflict).

Authorizations:
OcpApimKey
path Parameters
actor_id
required
integer
Example: 11111

ID interno (entero) del actor minero de subsistencia.

Request Body schema: application/json
required
Array of objects

Cuotas anuales a establecer (array no vacío).

motivo
string

Motivo del ajuste (opcional, para auditoría).

forzar_si_conflicto
boolean
Default: false

Si es true, aplica la cuota aunque sea menor al consumo acumulado.

Responses

Request samples

Content type
application/json
{
  • "nuevas_cuotas": [
    ],
  • "motivo": "Ajuste anual autorizado por resolución",
  • "forzar_si_conflicto": false
}

Response samples

Content type
application/json
{
  • "actor_id": 11111,
  • "cuotas_actualizadas": [
    ],
  • "cuotas_anteriores": [
    ],
  • "timestamp": "2026-04-20T12:00:00+00:00"
}

Transacciones

Registro, confirmación, reversión y cierre de transacciones de compraventa de mineral.

Registrar transacción de compraventa

Registra una transacción de compraventa de mineral. Valida existencia y saldo de los CUOMs del vendedor (excepto Mineros de Subsistencia). Genera un código de aceptación de 9 caracteres enviado al vendedor por correo (SES), válido por 15 minutos.

Nota: el path receivetransanction conserva un typo intencional del spec original (sin la s en transaction).

Authorizations:
(OcpApimKeyHs256Bearer)
Request Body schema: application/json
required
object
required
object
operator_id
required
string

ID del operador PTM.

version
required
integer

Versión del esquema.

currency
required
string
barcode
required
string

Código de barras de la factura.

invoice_date
required
string

Fecha de factura (ISO 8601).

transaction_date
required
string

Fecha de transacción (ISO 8601).

operator_transaction_id
required
string

ID interno del operador.

city
required
string
net_price
required
number
gross_price
required
number
final_consumption
required
boolean
required
Array of objects

Detalle de minerales.

Responses

Request samples

Content type
application/json
{
  • "seller": {
    },
  • "buyer": {
    },
  • "operator_id": "OP001",
  • "version": 1,
  • "currency": "COP",
  • "barcode": "BAR123456",
  • "invoice_date": "2026-04-20",
  • "transaction_date": "2026-04-20",
  • "operator_transaction_id": "TXN-2026-001",
  • "city": "Bogotá",
  • "net_price": 50000000,
  • "gross_price": 55000000,
  • "final_consumption": false,
  • "ltransaction_detail": [
    ]
}

Response samples

Content type
application/json
{
  • "transaction_id": "TXN-UUID-001",
  • "trasaction_hash": "sha256:abc123...",
  • "seller": {
    },
  • "buyer": {
    }
}

Confirmación de venta por el vendedor

El vendedor confirma la transacción ingresando el código de aceptación de 9 caracteres recibido por correo (vigencia de 15 minutos, sin distinción de mayúsculas/minúsculas). Al confirmar, notifica a ambas partes vía SES.

Authorizations:
(OcpApimKeyHs256Bearer)
Request Body schema: application/json
transaction_id
required
string
validation_code
required
string

Código de 9 caracteres (no distingue mayúsculas/minúsculas).

Responses

Request samples

Content type
application/json
{
  • "transaction_id": "TXN-UUID-001",
  • "validation_code": "ABC123XYZ"
}

Response samples

Content type
application/json
{
  • "transaction_id": "TXN-UUID-001",
  • "status_name": "Aceptado",
  • "date": "2026-04-20T14:30:00Z",
  • "seller": {
    },
  • "buyer": {
    }
}

Iniciar reversión de transacción

Inicia la reversión de una transacción confirmada. Genera un código de reversión de 9 caracteres enviado al vendedor, válido por 15 minutos. Los CUOMs vuelven a estado disponible solo al confirmar la reversión.

Authorizations:
(OcpApimKeyHs256Bearer)
Request Body schema: application/json
transaction_id
required
string
reason
string

Motivo de la reversión.

Responses

Request samples

Content type
application/json
{
  • "transaction_id": "TXN-UUID-001",
  • "reason": "Error en cantidad declarada"
}

Response samples

Content type
application/json
{
  • "transaction_id": "TXN-UUID-001"
}

Confirmar reversión

El vendedor confirma la reversión ingresando el código recibido por correo. Al validar, se restauran los saldos de CUOMs y se notifica a todas las partes.

Nota: el path validatereversetrans es el nombre real de la ruta.

Authorizations:
(OcpApimKeyHs256Bearer)
Request Body schema: application/json
transaction_id
required
string
validation_code
required
string

Código de reversión de 9 caracteres.

Responses

Request samples

Content type
application/json
{
  • "transaction_id": "TXN-UUID-001",
  • "validation_code": "REV456ABC"
}

Response samples

Content type
application/json
{
  • "marketer_user_id": "900123456",
  • "transaction_id": "TXN-UUID-001",
  • "valitation_code": "REV456ABC",
  • "status": "Reversado"
}

Cierre de cadena (exportación)

Cierra la cadena de trazabilidad mineral marcando los CUOMs como exportados. Operación irreversible: los saldos quedan en 0. Notifica a todos los actores de la cadena de suministro.

Authorizations:
(OcpApimKeyHs256Bearer)
Request Body schema: application/json
transaction_date
required
string

Fecha de cierre (ISO 8601).

buyer_id
string

ID del comprador final/exportador.

required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "transaction_date": "2026-04-20",
  • "buyer_id": "EXPORTADOR-001",
  • "ltransaction_detail": [
    ]
}

Response samples

Content type
application/json
{
  • "transaction_id": "CLOSE-UUID-001",
  • "trasaction_hash": "sha256:xyz789...",
  • "seller": {
    },
  • "buyer": {
    }
}

Transformaciones

Registro, reversión y cierre de procesos de transformación (beneficio) de mineral.

Registro de transformación

Inicia un proceso de transformación mineral. Bloquea los CUOMs de entrada seleccionados hasta que la transformación sea cerrada o revertida. Valida que el actor transformador esté registrado en RUCOM (simulado).

Nota: el path ottm_tranformationregister conserva un typo intencional (tranformation, sin la s).

Authorizations:
(OcpApimKeyHs256Bearer)
Request Body schema: application/json
required
object (ActorRef)
required
object (ActorRef)
required
Array of objects (ProductionRegisterItem)

CUOMs a transformar.

Responses

Request samples

Content type
application/json
{
  • "mining_actor": {
    },
  • "transformation_actor": {
    },
  • "lproduction_register": [
    ]
}

Response samples

Content type
application/json
{
  • "transformation_id": "TRANS-UUID-001",
  • "mining_actor": {
    },
  • "date": "2026-04-20T15:00:00Z",
  • "transformation_creation_date": "2026-04-20T15:00:00Z"
}

Reversión de transformación

Revierte una transformación en curso. Solo puede ejecutarla el actor que la inició. Restaura los CUOMs bloqueados a estado disponible.

Authorizations:
(OcpApimKeyHs256Bearer)
Request Body schema: application/json
transformation_id
required
string

Responses

Request samples

Content type
application/json
{
  • "transformation_id": "TRANS-UUID-001"
}

Response samples

Content type
application/json
{
  • "transformation_id": "TRANS-UUID-001",
  • "status": "reversado",
  • "date": "2026-04-20T16:00:00Z"
}

Cierre de transformación

Finaliza una transformación convirtiendo el mineral en producto industrial derivado. Operación irreversible: los CUOMs de entrada quedan en saldo 0 y salen del sistema de trazabilidad.

Nota: el path Closuretransformation conserva la C mayúscula intencional.

Authorizations:
(OcpApimKeyHs256Bearer)
Request Body schema: application/json
required
Array of objects

Lista de actores y CUOMs a cerrar.

Responses

Request samples

Content type
application/json
{
  • "lmineral_transformation": [
    ]
}

Response samples

Content type
application/json
{
  • "transformations": [
    ]
}