Desarrolladores

Webhooks

Ponte en contacto con nosotros developers@punto.ai para registrar un webhook a una URL de tu dominio. Así podrás recibir en tiempo real los eventos que te interesan. Cada vez que ocurre algo relevante —un trámite cambia de estado, se genera un documento, aparece una incidencia— Punto envía una petición POST a la URL que decidas.

Cómo funciona

Cuando ocurre un evento, Punto realiza una petición POST a tu endpoint con un cuerpo JSON. El campo event identifica qué ha ocurrido y el campo data contiene los detalles del recurso afectado.

Todos los eventos comparten tres campos comunes: id (identificador del recurso), path (ruta para obtener el detalle completo) y timestamp (fecha y hora en ISO 8601). Cada tipo de evento añade campos específicos del recurso que permiten enrutar tu lógica sin necesidad de hacer una llamada adicional.

Tu endpoint debe responder con HTTP 200 en menos de 5 segundos. Si no, Punto reintentará el envío.

Crear un webhook

Para que podamos configurar un webhook deberás indicarnos:

URL: URL a la que quieres que enviemos los eventos
Eventos: Listado de eventos que quieres recibir (ver listado más abajo). Si no especificas una lista configuraremos todos los tipos de eventos.
Cabeceras (opcional): Cabecera HTTP que quieres que incluyamos en los eventos para validar que son legítimos.

Entornos: Desarrollo y producción

Los webhooks se configuran de forma independiente por entorno. Una suscripción creada en desarrollo no existe en producción y viceversa.

Entorno	URL base
Desarrollo	`https://api.dev.punto.ai`
Producción	`https://api.punto.ai`

Indícanos qué URLs usar en cada entorno por separado.

Recibir y procesar eventos

La URL configurada recibirá una petición POST con el siguiente formato:

JSON

{
  "event": "procedure.status_changed",
  "data": {
    "id": "pro_1234",
    "path": "/v1/procedures/pro_1234",
    "procedureType": "VEHICLE_REGISTRATION",
    "status": "IN_PROGRESS",
    "timestamp": "2025-08-12T10:30:00.000Z"
  }
}

Cuando necesites el detalle completo del recurso, usa el campo path del payload para hacer un GET:

Text

GET https://api.punto.ai{path}
// Sustituye {path} por el valor de data.path recibido en el evento

Eventos disponibles

Todos los eventos incluyen los siguientes campos:

event: Identifica el tipo de evento
data.id: ID de la entidad que ha generado el evento
data.path: API path para obtener más detalles sobre la entidad que ha generado el evento
data.timestamp: Timestamp del momento en el que ocurre el evento (ISO 8601)

Trámites

Evento	Cuándo se emite
`procedure.status_changed`	Un trámite ha cambiado de estado
`procedure.finished`	Un trámite ha llegado a un estado terminal (completado o fallido)

Los campos específicos de este tipo de eventos son:

data.procedureType: Tipo de trámite: VEHICLE_REGISTRATION | VEHICLE_TRANSFER | ...
data.status: Estado del trámite: DRAFT | PENDING | IN_PROGRESS | DONE | ... | DELIVERED_TO_CLIENT

Documentos de un trámite

Evento	Cuándo se emite
`procedure.document.added`	Se ha generado un nuevo documento en el trámite

Los campos específicos de este tipo de eventos son:

data.documentType: Tipo de documento: temp_technical_sheet | temp_veh_registration_cert | procedure_invoice | ...
data.downloadUrl: URL para descargar el documento (caduca pasado un tiempo)
data.procedureId: ID del trámite relacionado con el documento
data.procedureType: Tipo de trámite: VEHICLE_REGISTRATION | VEHICLE_TRANSFER | ...
data.procedurePath: API path para obtener más detalles sobre el trámite (p.e. /v1/procedures/{procedurId})

Incidencias de un trámite

Evento	Cuándo se emite
`procedure.incident.added`	Se ha registrado una incidencia en el trámite
`procedure.incident.solved`	Una incidencia ha sido marcada como resuelta
`procedure.incident.removed`	Una incidencia ha sido eliminada

Los campos específicos de este tipo de eventos son:

data.type: Tipo de incidente: expired-document | unreadable-document | ...
data.level:
- blocker: El trámite está bloqueado por algo que el usuario puede desbloquear
- hold: El trámite está esperando a una entidad externa (p.e. a una respuesta de la administración pública)
data.description: Descripción de la incidencia
data.subjectType: Tipo de entidad sobre la que se produce la incidencia: procedure | document | ...
data.subjectId: ID de la entidad sobre la que se produce la incidencia
data.subjectPath: API path para obtener más detalles de la entidad sobre la que se produce la incidencia
data.procedureId: ID del trámite relacionado con la incidencia
data.procedureType: VEHICLE_REGISTRATION | VEHICLE_TRANSFER | ...
data.procedurePath: API path para obtener más detalles sobre el trámite (p.e. /v1/procedures/{procedurId})

Firmas electrónicas

Evento	Cuándo se emite
`signature.status_changed`	El estado de una solicitud de firma ha cambiado

Los campos específicos de este tipo de eventos son:

data.status: Estado de la firma: DRAFT | SUBMITTED | SENT | PARTIALLY_SIGNED | ... | SIGNED
data.documents: Lista de documentos a firmar
- data.documents[].name: Nombre del documento
- data.documents[].type: Tipo de documento
- data.documents[].signedDocumentUrl: URL para descargar el documento firmado (es necesario usar API token)

Informes

Evento	Cuándo se emite
`report.completed`	Un informe ha finalizado correctamente
`report.status_changed`	El estado de un informe ha cambiado (incluye errores de procesamiento)

Los campos específicos de este tipo de eventos son:

data.status: Estado del informe: processing | completed | error
data.type: Tipo de informe: complete | reduced
data.vrm: Matrícula del vehículo del informe
data.transferabilityStatus: Resultado de transferibilidad del vehículo (ausente si el informe termina en error)
data.processable: Si el informe es procesable (ausente si el informe termina en error)

Siguientes pasos

Trámites — cómo crear y seguir trámites con la DGT
Referencia API — documentación completa de todos los endpoints