Nexcar

Casos

Un caso representa un vehículo. Aquí defines el `case_id` que vas a usar para adjuntar documentos y consultar resultados.

Endpoints#

MétodoRutaDescripción
POST/v1/casesCrea un caso, opcionalmente con documentos iniciales
GET/v1/cases/{case_id}Consulta el caso y sus documentos con OCR
DELETE/v1/cases/{case_id}Da de baja el caso (baja lógica)
GET/v1/cases/{case_id}/namesNombres consolidados detectados en los documentos
GET/v1/cases/{case_id}/vinsVIN principal y VINs detectados por documento
GET/v1/cases/{case_id}/platesPlacas detectadas en el caso con datos de vigencia
GET/v1/cases/{case_id}/repuveDatos de inscripción REPUVE del vehículo
GET/v1/cases/{case_id}/pedimentoResultado más reciente de consulta de pedimento
POST/v1/cases/{case_id}/pedimentoLanza una nueva consulta de pedimento con datos del OCR
GET/v1/cases/{case_id}/rapiResultado más reciente de consulta RAPI (FGJCDMX actividad ilícita)
POST/v1/cases/{case_id}/rapiLanza una consulta RAPI para el VIN principal del caso
POST/v1/cases/{case_id}/taxesLanza consulta masiva de tenencias para todas las placas del caso
GET/v1/cases/{case_id}/invoicesFacturas asociadas con su estado de procesamiento
GET/v1/cases/{case_id}/metadataDatos de negocio asociados al caso
POST/v1/cases/{case_id}/metadataAgrega una entrada al historial de metadata
POST/v1/cases/{case_id}/processLanza el procesamiento masivo de los documentos
GET/v1/cases/{case_id}/statusEstado del último job de procesamiento

POST /v1/cases — Crear caso#

Crea un caso para un vehículo. Puedes adjuntar documentos en la misma llamada o subirlos después.

Cuerpo#

CampoTipoRequeridoDescripción
internal_idstringSíIdentificador del caso en tu sistema. No puede estar vacío.
statusstringSíEstado inicial del caso (p. ej. processing, nuevo).
vehicle_originstringNoNacional (default) o Importado.
initial_statusstringNoEstado inicial alternativo cuando se configuró un catálogo de estatus.
use_caseUUIDNoCaso de uso del expediente cuando aplique catálogo.
metadataobjectNoDatos de negocio adicionales (ver más abajo).
filesarrayNoDocumentos a cargar de inmediato.

Ejemplo con curl#

curl -X POST https://api.nexcar.mx/v1/cases \
  -H "x-api-key: tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "internal_id": "EXP-2026-0001",
    "status": "processing",
    "vehicle_origin": "Nacional",
    "metadata": {
      "numero_siniestro": "128890890",
      "tipo_afectado": "TERCERO",
      "nombre_afectado": "JUAN PÉREZ GARCÍA"
    },
    "files": [
      {
        "url": "https://tu-storage.example.com/factura.pdf",
        "mime_type": "application/pdf",
        "document_type": "factura"
      },
      {
        "url": "https://tu-storage.example.com/ine-titular.jpg",
        "mime_type": "image/jpeg",
        "document_type": "ine"
      }
    ]
  }'

Cuerpo del request#

{
  "internal_id": "EXP-2026-0001",
  "status": "processing",
  "vehicle_origin": "Nacional",
  "metadata": {
    "numero_siniestro": "128890890",
    "tipo_afectado": "TERCERO",
    "nombre_afectado": "JUAN PÉREZ GARCÍA"
  },
  "files": [
    {
      "url": "https://tu-storage.example.com/factura.pdf",
      "mime_type": "application/pdf",
      "document_type": "factura"
    },
    {
      "url": "https://tu-storage.example.com/ine-titular.jpg",
      "mime_type": "image/jpeg",
      "document_type": "ine"
    }
  ]
}

Respuestas#

201 Created — caso creado sin archivos:

{ "case_id": "7040fd87-5f49-4187-b2a3-b4a19670825c", "status": "completed" }

202 Accepted — caso creado con archivos en procesamiento:

{
  "case_id": "7040fd87-5f49-4187-b2a3-b4a19670825c",
  "job_id": "31b4ecf2-9a0b-4f98-8a91-2ab6e93f4f10",
  "total_files": 2,
  "status": "processing"
}

Errores comunes#

HTTPCódigoCausa
400VALIDATION_ERRORstatus ausente o internal_id vacío
400DUPLICATE_INTERNAL_IDYa existe un caso con ese internal_id y archivos cargados
422INVALID_STATUSstatus no está dentro del catálogo configurado

GET /v1/cases/{case_id}#

Devuelve el caso y todos sus documentos con su OCR (cuando esté disponible).

Ejemplo con curl#

curl https://api.nexcar.mx/v1/cases/7040fd87-5f49-4187-b2a3-b4a19670825c \
  -H "x-api-key: tu_api_key"

Respuesta#

{
  "case_id": "7040fd87-5f49-4187-b2a3-b4a19670825c",
  "internal_id": "EXP-2026-0001",
  "status": "nuevo",
  "vehicle_origin": "Nacional",
  "documents": [
    {
      "document_id": "abc123",
      "type": "factura",
      "mime_type": "application/pdf",
      "url": "https://...nexcar.mx/storage/.../factura.pdf",
      "parsed_data": { "vin": "3VWFE21C04M000001", "monto_total": 285000 }
    }
  ]
}

DELETE /v1/cases/{case_id}#

Marca el caso como inactivo. No borra archivos físicamente; deja de aparecer en consultas y reportes.

curl -X DELETE https://api.nexcar.mx/v1/cases/7040fd87-5f49-4187-b2a3-b4a19670825c \
  -H "x-api-key: tu_api_key"

POST /v1/cases/{case_id}/process#

Encola el procesamiento masivo (OCR + extracción) de los documentos del caso. Útil cuando subiste archivos sin tipo y quieres lanzar el flujo en batch.

curl -X POST https://api.nexcar.mx/v1/cases/7040fd87-5f49-4187-b2a3-b4a19670825c/process \
  -H "x-api-key: tu_api_key"

{ "job_id": "31b4ecf2-9a0b-4f98-8a91-2ab6e93f4f10", "status": "processing" }

Consulta el avance con GET /v1/cases/{case_id}/status.

GET /v1/cases/{case_id}/plates#

Devuelve las placas detectadas en los documentos del caso, enriquecidas con NIV, número de motor, nombre del propietario y — para placas emplaçadas en el Estado de México — los datos de vigencia (estatus, fechas de vigencia y placa anterior cuando aplique) consultados al portal oficial.

La lista se construye y persiste automáticamente como parte del pipeline de procesamiento del caso. Este endpoint es de solo lectura.

Ejemplo con curl#

curl https://api.nexcar.mx/v1/cases/7040fd87-5f49-4187-b2a3-b4a19670825c/plates \
  -H "x-api-key: tu_api_key"

Respuesta#

{
  "case_id": "7040fd87-5f49-4187-b2a3-b4a19670825c",
  "internal_id": "EXP-2026-0001",
  "plates": [
    {
      "plate": "MJM626C",
      "entity": "MEX",
      "document_type": "vehicle_certificate",
      "document_date": "01/09/2025",
      "file_id": "0126537c-8dad-402a-a559-0bbbcafd53a3",
      "ocr_id": "f2dd2062-d11d-480b-9c0b-1b6d03b6f1df",
      "niv": "JN1BE6DSXS9121418",
      "motor_number": "QR258585700Q",
      "owner_name": null,
      "plate_status": "Vigente",
      "plate_valid_from": "01/09/2025",
      "plate_valid_until": "01/09/2030",
      "previous_plate": null,
      "previous_plate_lookup_status": null
    }
  ]
}

Referencia de campos#

CampoTipoDescripción
platestringPlaca normalizada (mayúsculas, sin separadores)
entitystringCódigo de tres letras del estado (MEX, NLE, JAL, …)
document_typestringDocumento de origen: certificate_title, tax_payment, alta_vehicular, vehicle_certificate, vehicle_plate, lumo_checklist o repuve
document_datestringFecha asociada al documento de origen (DD/MM/YYYY cuando esté disponible)
nivstring | nullNúmero de identificación vehicular (17 caracteres cuando está disponible; parcial en otros casos)
motor_numberstring | nullNúmero de motor del documento de origen
owner_namestring | nullPropietario declarado en el documento de origen
plate_statusstring | nullEstatus actual de la placa según el portal: Vigente, Vencida o Inactiva
plate_valid_fromstring | nullInicio de vigencia de la placa actual (DD/MM/YYYY)
plate_valid_untilstring | nullFin de vigencia de la placa actual (DD/MM/YYYY)
previous_platestring | nullPlaca anterior, cuando existió una previa a la actual
previous_plate_lookup_statusstring | nullEstado de la consulta — ver tabla

Valores de previous_plate_lookup_status#

ValorSignificado
nullLa consulta no aplica (placa no emplaçada en MEX) o el portal confirmó que no hay placa anterior
"pending"Consulta en curso en background — vuelve a llamar en unos segundos
"found"El portal devolvió una placa anterior (poblada en previous_plate)
"error"La consulta falló tras los reintentos (portal caído, error de parseo, etc.)

La misma placa puede aparecer en varios elementos del arreglo cuando se detectó en más de un documento. Todos los elementos con la misma placa comparten plate_status, fechas de vigencia y campos previous_plate_* una vez que el lookup en background termina.

Errores comunes#

HTTPCausa
404Caso no encontrado, inactivo, o aún no se han calculado las placas para este caso

GET /v1/cases/{case_id}/repuve#

Retorna el job de REPUVE más reciente para el caso. Si el job terminó en error pero existe una respuesta válida de placas.info, el endpoint aplica auto-recuperación y devuelve los datos correctos.

Ejemplo con curl#

curl https://api.nexcar.mx/v1/cases/7040fd87-5f49-4187-b2a3-b4a19670825c/repuve \
  -H "x-api-key: tu_api_key"

Respuesta#

{
  "codigo": "ok",
  "info": {
    "niv": "3N6AD35A9LK875826",
    "placa": "Y83BGS",
    "marca": "NISSAN",
    "modelo": "NP300/NP300 FRONTIER/FRONTIER",
    "tipo": "CAB. Y CHASIS ESTACAS",
    "clase": "CAMIONETA",
    "anio_modelo": 2020,
    "entidad_emplacado": "CIUDAD DE MEXICO",
    "fecha_inscripcion": "22/09/20",
    "fecha_actualizacion": "12/10/24",
    "reporte_robo": [
      { "tipo_reporte": "FGJ", "estatus": "SIN REPORTE DE ROBO" },
      { "tipo_reporte": "OCRA", "estatus": "SIN REPORTE DE ROBO" }
    ],
    "robo_usa_can": { "tiene_robo": false },
    "aviso_judicial": { "tiene_aviso_judicial": false }
  },
  "job_id": "4a201139-7945-4ae7-8a17-dc8e048c7437",
  "job_status": "completed"
}

Referencia de campos#

CampoTipoDescripción
codigostringok — datos de REPUVE disponibles. error — todos los servicios fallaron. processing — job aún en curso.
infoobject | nullDatos de inscripción del vehículo en REPUVE. null cuando el vehículo no está inscrito o el job no ha completado.
info.nivstringNúmero de identificación vehicular (NIV/VIN)
info.placastring | nullPlaca registrada en REPUVE
info.marcastringMarca
info.modelostringModelo
info.anio_modelointegerAño modelo
info.entidad_emplacadostring | nullEstado de emplacamiento
info.fecha_inscripcionstring | nullFecha de inscripción en REPUVE
info.fecha_actualizacionstring | nullFecha de última actualización en REPUVE
info.reporte_roboarrayReportes de robo de las fuentes FGJ y OCRA
info.robo_usa_canobjectEstado de reporte de robo en USA/Canadá
info.aviso_judicialobjectEstado de aviso judicial
job_idUUIDIdentificador interno del job
job_statusstringcompleted, error, processing o pending

Errores comunes#

HTTPCausa
404Caso no encontrado, inactivo, o no se ha realizado ninguna consulta REPUVE para este caso

GET /v1/cases/{case_id}/pedimento#

Devuelve el resultado más reciente de consulta de pedimento para el caso. Los datos se leen de pedimento_responses (pipeline legacy) y processing_jobs (API v1), se deduplican por contenido y se ordenan por fecha.

Ejemplo con curl#

curl https://api.nexcar.mx/v1/cases/7040fd87-5f49-4187-b2a3-b4a19670825c/pedimento \
  -H "x-api-key: tu_api_key"

Respuesta#

{
  "case_id": "7040fd87-5f49-4187-b2a3-b4a19670825c",
  "job_id": "4a201139-7945-4ae7-8a17-dc8e048c7437",
  "status": "completed",
  "source": "processing_jobs",
  "result": {
    "success": true,
    "data": { "pedimento": "39317003384", "aduana": "MANZANILLO", "vin": "LUCGM6669J3104807" }
  }
}

Errores comunes#

HTTPCausa
404Caso no encontrado, inactivo, o no se ha realizado ninguna consulta de pedimento. Llama a POST /v1/cases/{id}/pedimento primero.

GET /v1/cases/{case_id}/taxes (sin ?plate)#

Devuelve todos los resultados de tenencias por placa del caso, agrupados por placa. Lee de processing_jobs en todas las fuentes (pipeline en background y consulta on-demand v1).

Cuando se proporciona ?plate el comportamiento original de consulta por placa individual se mantiene sin cambios.

Ejemplo con curl#

curl https://api.nexcar.mx/v1/cases/7040fd87-5f49-4187-b2a3-b4a19670825c/taxes \
  -H "x-api-key: tu_api_key"

Respuesta#

{
  "case_id": "7040fd87-5f49-4187-b2a3-b4a19670825c",
  "plates_count": 2,
  "taxes": [
    {
      "plate": "MES452A",
      "job_id": "abc123",
      "status": "completed",
      "source": "api_v1_cases_taxes_bulk",
      "result": { "codigo": "ok", "info": [...] },
      "created_at": "2026-06-05T10:00:00+00:00"
    }
  ]
}

POST /v1/cases/{case_id}/taxes#

Lanza una consulta masiva de tenencias para todas las placas únicas del caso (placas principales + placas anteriores), usando los datos de GET /v1/cases/:id/plates internamente (sin HTTP). Se crea un registro en processing_jobs por cada placa con su propio job_id, external_payload y external_response. El workflow corre en Temporal (cola invoice-background-queue).

Ejemplo con curl#

curl -X POST https://api.nexcar.mx/v1/cases/7040fd87-5f49-4187-b2a3-b4a19670825c/taxes \
  -H "x-api-key: tu_api_key"

Respuesta 202 Accepted#

{
  "job_id": "31b4ecf2-9a0b-4f98-8a91-2ab6e93f4f10",
  "plates": ["MES452A", "NDJ3622"],
  "status": "pending"
}

Consulta GET /v1/cases/{case_id}/taxes (sin ?plate) para ver los resultados por placa a medida que se completan.

Errores comunes#

HTTPCausa
400No se encontraron placas para este caso. Llama a POST /v1/cases/{id}/plates primero.
404Caso no encontrado o inactivo

POST /v1/cases/{case_id}/pedimento#

Inicia una nueva consulta de pedimento usando los datos extraídos del OCR del documento principal del caso (la factura vinculada al VIN principal). Se ejecuta de forma asíncrona en Temporal. Devuelve un job_id inmediatamente; consulta GET /v1/cases/{id}/pedimento para obtener el resultado.

Los parámetros requeridos (aduana, ano_vehiculo) se leen del OCR automáticamente. Si no están disponibles en el documento, el endpoint devuelve un 400 indicando los campos que faltan.

Ejemplo con curl#

curl -X POST https://api.nexcar.mx/v1/cases/7040fd87-5f49-4187-b2a3-b4a19670825c/pedimento \
  -H "x-api-key: tu_api_key"

Respuesta 202 Accepted#

{ "job_id": "4a201139-7945-4ae7-8a17-dc8e048c7437", "status": "pending" }

Errores comunes#

HTTPCausa
400No se encontró VIN principal, o faltan campos OCR requeridos (aduana, ano_vehiculo)
404Caso no encontrado o inactivo

GET /v1/cases/{case_id}/rapi#

Devuelve el resultado más reciente de consulta RAPI (FGJCDMX — actividad ilícita vehicular) para el caso. Lee de rapi_responses (pipeline legacy) y processing_jobs (API v1), deduplicados por contenido y ordenados por fecha.

Ejemplo con curl#

curl https://api.nexcar.mx/v1/cases/7040fd87-5f49-4187-b2a3-b4a19670825c/rapi \
  -H "x-api-key: tu_api_key"

Respuesta#

{
  "case_id": "7040fd87-5f49-4187-b2a3-b4a19670825c",
  "job_id": "4a201139-7945-4ae7-8a17-dc8e048c7437",
  "status": "completed",
  "source": "processing_jobs",
  "result": { ... }
}

Errores comunes#

HTTPCausa
404Caso no encontrado, inactivo, o no se ha realizado ninguna consulta RAPI. Llama a POST /v1/cases/{id}/rapi primero.

POST /v1/cases/{case_id}/rapi#

Lanza una consulta RAPI para el VIN principal del caso (obtenido de GET /v1/cases/:id/vins). Se ejecuta de forma asíncrona en Temporal (invoice-background-queue). Devuelve un job_id inmediatamente.

Ejemplo con curl#

curl -X POST https://api.nexcar.mx/v1/cases/7040fd87-5f49-4187-b2a3-b4a19670825c/rapi \
  -H "x-api-key: tu_api_key"

Respuesta 202 Accepted#

{ "job_id": "4a201139-7945-4ae7-8a17-dc8e048c7437", "vin": "3N6AD35A9LK875826", "status": "pending" }

Errores comunes#

HTTPCausa
400No se encontró VIN principal. Procesa los documentos con POST /v1/cases/{id}/process primero.
404Caso no encontrado o inactivo
AnteriorAutenticación
SiguienteDocumentos