FUEC por API

La API hace con el FUEC lo mismo que la pantalla, con las mismas reglas: revisión de documentos en el RUNT, sin terceros y dentro del contrato. Antes de integrarlo, lee la guía de FUEC.

Requisitos

• El plan de la organización debe incluir el FUEC (lo traen PyME, PyME Pro y Enterprise). Si no, todos los endpoints responden 403 con El plan de la organización no incluye el FUEC.
• La key necesita fuec.read para leer y fuec.write para registrar contratos, revisar, expedir y anular. Esos dos scopes solo aparecen al crear una key si el plan trae el FUEC.
• Para expedir, los datos de la empresa (habilitación y quien firma) deben estar completos en la pantalla. Si faltan, expedir responde 422 con errors.settings.

Endpoint	Scope	Qué hace
GET /fuec	fuec.read	FUEC expedidos. Filtros: state (active, upcoming, expired, voided), plate, contract
GET /fuec/{id}	fuec.read	Un FUEC, tal como se imprimió
GET /fuec/{id}/pdf	fuec.read	El PDF
POST /fuec/check	fuec.write	Revisión de documentos, sin guardar nada
POST /fuec	fuec.write	Expedir
POST /fuec/{id}/void	fuec.write	Anular
GET /fuec/contracts	fuec.read	Contratos
GET /fuec/contracts/{id}	fuec.read	Un contrato
POST /fuec/contracts	fuec.write	Registrar un contrato
PUT /fuec/contracts/{id}	fuec.write	Actualizar un contrato (se envía completo)
DELETE /fuec/contracts/{id}	fuec.write	Eliminar un contrato sin FUEC

Los id son uuid, no números consecutivos. Los listados se paginan como el resto de la API (Paginación): los elementos vienen en data.data.

El flujo

1. Registrar el contrato

curl -X POST https://api.notiauto.co/v1/fuec/contracts \
  -H "X-API-Key: $NOTIAUTO_KEY" -H "Content-Type: application/json" \
  -d '{
    "contractor_name": "Colegio Los Andes",
    "contractor_document_type": "N",
    "contractor_document": "800123456",
    "service_type": "students",
    "purpose": "Contrato para transporte de estudiantes",
    "origin_destination": "Bogotá perímetro urbano",
    "starts_on": "2026-11-01",
    "ends_on": "2026-12-15"
  }'

Sin number, toma el siguiente número de la organización. service_type es uno de students, employees, tourists, health o specific_group. La respuesta 201 trae el contrato con su id.

2. Revisar los documentos (opcional)

POST /fuec/check recibe lo mismo que expedir y responde la revisión sin guardar nada. Sirve para mostrarle al usuario qué impide expedir o qué avisos hay antes de intentarlo.

3. Expedir

curl -X POST https://api.notiauto.co/v1/fuec \
  -H "X-API-Key: $NOTIAUTO_KEY" -H "Content-Type: application/json" \
  -d '{
    "contract": "6f1c2b9e-4b0a-4e7c-9d2a-1f3e5a7b9c0d",
    "plate": "TLN810",
    "drivers": ["80218874"],
    "starts_on": "2026-11-03",
    "ends_on": "2026-11-30",
    "internal_number": "035"
  }'

Campo	Regla
contract	id de un contrato de la organización
plate	Un vehículo registrado en la flota. Se aceptan minúsculas, espacios y guiones
drivers	De 1 a 3 documentos de conductores registrados en la flota, en el orden del formato
starts_on	Desde hoy, dentro de la vigencia del contrato
ends_on	Hasta el fin del contrato como máximo
internal_number	Opcional. Se guarda en el vehículo para los siguientes
accept_warnings	Obligatorio en true si la revisión trae avisos

La respuesta 201 trae el FUEC: number (21 dígitos), state, verification_url (la página pública que abre el QR), pdf_url, el contrato, el vehículo y los conductores tal como se imprimieron, y channel: "api".

4. El PDF

GET /fuec/{id}/pdf devuelve el documento (application/pdf), igual al de la pantalla. Un FUEC anulado sale con la marca ANULADO.

5. Anular

curl -X POST https://api.notiauto.co/v1/fuec/{id}/void \
  -H "X-API-Key: $NOTIAUTO_KEY" -H "Content-Type: application/json" \
  -d '{"reason": "Cambio de vehículo por daño"}'

No se deshace y el número no se reusa. Anular un FUEC ya anulado responde 200 sin cambiar nada.

Cuando la revisión no deja expedir

Si algo impide expedir, o hay avisos sin accept_warnings: true, la respuesta es 422 con la forma de validación de siempre, más readiness con el detalle:

{
  "message": "Hay documentos que no permiten expedir este FUEC.",
  "errors": { "readiness": ["Hay documentos que no permiten expedir este FUEC."] },
  "readiness": {
    "blocked": true,
    "required_category": "C1",
    "suggested_ends_on": null,
    "checks": [
      {
        "subject": "vehicle", "subject_id": 1534, "label": "TLN810",
        "key": "soat", "status": "block", "code": "soat.expired",
        "params": { "date": "2026-11-01" }
      }
    ],
    "warnings": []
  }
}

• status: block impide expedir, warn exige accept_warnings, ok está al día.
• code dice qué pasó: soat.expired, rtm.expires_during, rcc.missing, operation_card.invalid, license.not_qualified, runt.pending… *.unknown (rcc.unknown, rce.unknown, operation_card.unknown) significa que ese dato aún no se ha consultado en el RUNT para ese vehículo: actualízalo desde su ficha en la plataforma.
• Con avisos, errors.accept_warnings y suggested_ends_on: el último día en que todo sigue vigente, por si prefieres recortar ends_on en vez de aceptar.

Los demás 422 son de validación normal (ver Errores), por ejemplo:

Campo	Cuándo
contract	El contrato no existe en la organización
plate	El vehículo no está registrado en la flota
drivers	Algún documento no es de un conductor de la flota
starts_on / ends_on	Antes de hoy o fuera del contrato
number	Al cambiar el número de un contrato que ya tiene FUEC

Eliminar un contrato con FUEC responde 409.

Webhooks

Dos eventos para los webhooks de la organización (se eligen al crearlos, en la sección API de la plataforma):

Evento	Cuándo
fuec.issued	Se expidió un FUEC, por la pantalla o por la API
fuec.voided	Se anuló un FUEC

data trae lo justo para ubicarlo; el detalle está en GET /fuec/{id}:

{
  "id": "0b8f2d3a-…",
  "number": "425015512202602550001",
  "plate": "TLN810",
  "contract_number": 255,
  "starts_on": "2026-11-03",
  "ends_on": "2026-11-30",
  "state": "active",
  "verification_url": "https://notiauto.co/verificar-fuec/K7QW2M9XRT",
  "voided_at": null,
  "void_reason": null
}

Cuando el FUEC pase al RUNT

Cuando el FUEC se expida en el RUNT (Decreto 1048 de 2026), NotiAuto dejará de expedirlo: POST /fuec y POST /fuec/check responderán 403 con La expedición del FUEC ya se hace en el RUNT. La lectura, el PDF y la verificación de los FUEC ya expedidos siguen funcionando.