Documentación de la API

Dos endpoints REST en JSON para que tu ERP consulte la tramitabilidad de un vehículo y solicite su baja ante la DGT sin pasar por el panel. Ahora mismo la API se activa manualmente por tenant — si eres CAT cliente de BTVE Cloud y necesitas tu clave, escribe a contacto@btve.cloud.

Autenticación

Cada request lleva la cabecera x-api-key con la clave de tu CAT. Una clave inválida o de un tenant suspendido devuelve 401.

curl -X POST https://tu-dominio/api/btve/consulta-tramitabilidad \
  -H "x-api-key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "matricula": "1234ABC", "bastidor": "...", "doiTitular": "12345678Z" }'

`POST /api/btve/consulta-tramitabilidad`

Consulta si un vehículo es tramitable ante la DGT y crea el expediente (estado tramitable o no_tramitable). El bajaId devuelto se usa después para solicitar la baja.

Cuerpo de la petición

Campo	Tipo	Obligatorio	Notas
matricula	string	Sí	—
bastidor	string	Sí	Últimos 6 dígitos o VIN completo
doiTitular	string	Sí	NIF/CIF del titular
doiSolicitante	string	No	Obligatorio si el titular es persona jurídica
numeroCema	string	No	Vehículos agrícolas

Respuesta (200)

{
  "bajaId": "cmrlunsjw000ers7ynnmnz94i",
  "codigoError": "BTVE0000",
  "descripcionError": "",
  "tramitable": true
}

Errores

401 — falta x-api-key o la clave no es válida.
400 — faltan matricula, bastidor o doiTitular.

`POST /api/btve/solicitud-baja`

Envía la solicitud de baja definitiva a la DGT sobre un expediente que ya pasó por consulta-tramitabilidad y salió tramitable. El justificante firmado se archiva en el expediente (no se devuelve en base64 en la respuesta, para no exponerlo en logs o proxies) — descárgalo después desde el panel o pídelo a soporte.

Cuerpo de la petición

Campo	Tipo	Obligatorio	Notas
bajaId	string	Sí	`bajaId` de una consulta tramitable previa
matricula, bastidor, doiTitular	string	Sí	Deben coincidir con el expediente
tipoBaja	string	Sí	`OFICIO` · `SINIESTRO_TOTAL` · `TITULAR` · `TRATAMIENTO_RESIDUAL`
tipoOficio	string	No	`AYUNTAMIENTO` · `OTRA_AUTORIDAD`
provincia, municipio	string	No	—
autoridad	string	No	`JUZGADO` · `OTRA_AUTORIDAD` · `POLICIA`
certDestruccion, certMedioambiental	"S" \| "N"	No	—
remitente	objeto	Sí	`{ nombre, apellidos?, nif }`
interesados	array	Sí	Al menos un `{ nombre, apellidos?, nif }`

Ejemplo

curl -X POST https://tu-dominio/api/btve/solicitud-baja \
  -H "x-api-key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bajaId": "cmrlunsjw000ers7ynnmnz94i",
    "matricula": "1234ABC",
    "bastidor": "...",
    "doiTitular": "12345678Z",
    "tipoBaja": "TITULAR",
    "remitente": { "nombre": "Juan", "apellidos": "Pérez", "nif": "12345678Z" },
    "interesados": [{ "nombre": "Juan", "apellidos": "Pérez", "nif": "12345678Z" }]
  }'

Respuesta (200)

{
  "bajaId": "cmrlunsjw000ers7ynnmnz94i",
  "codigoError": "BTVE0000",
  "descripcionError": "",
  "numeroRegistro": "...",
  "tramitable": true
}

Errores

401 — falta x-api-key o la clave no es válida.
400 — solicitud inválida: falta bajaId, algún campo obligatorio, un tipoBaja no reconocido, o algún interesado sin nombre/NIF.

Auditoría

Toda llamada a estos dos endpoints queda registrada en el log de auditoría con hash-chaining del CAT correspondiente, igual que las acciones hechas desde el panel — no hay ninguna vía que quede sin trazar.