Pruebas de integración

Muchos de nuestros trámites requieren una interacción manual del equipo de Punto: revisar documentación, avanzar el trámite o resolver una incidencia. Para que puedas validar tu integración sin depender de nosotros, tienes disponibles en desarrollo unos endpoints de test que emulan esas acciones.

Objetivo

Esta guía define el proceso para validar tu integración con la API de Punto. Cubre, en orden:

1. Configurar tus webhooks antes de empezar las pruebas.
2. Emulación de acciones — los endpoints de test que sustituyen las acciones manuales del equipo de Punto (avanzar el estado de un trámite, añadir un documento, crear o resolver una incidencia).
3. Flujos a validar para cada tipo de trámite: matriculación, transferencia y notificación.

Como anexo, encontrarás también un listado de documentos de ejemplo por si no quieres usar tus propios PDFs.

Configuración de los webhooks

Para poder recibir los eventos de los trámites es necesario que configures tus webhooks antes de empezar las pruebas. Los webhooks se configuran de forma independiente por entorno.

Envíanos un email a developers@punto.ai indicándonos, para cada entorno:

• URL.
• Tipos de eventos que quieres recibir. Si no especificas nada, te enviamos todos.
• Opcionalmente, una cabecera HTTP para validar que los eventos son legítimos.

Más detalle en la guía de Webhooks.

Emulación de acciones

Muchas de las acciones sobre el trámite — cambiar el estado, añadir un documento generado, crear o resolver una incidencia— las realiza normalmente el equipo de Punto. Para que puedas probarlas sin depender de nosotros, en el entorno de desarrollo tienes disponibles los siguientes endpoints de test.

Cambiar el estado de un trámite

Cambia el estado de un trámite, del mismo modo que lo haría el equipo de Punto. Se recibe un evento procedure.status_changed con el nuevo estado. Los valores válidos son los mismos que los del listado de estados de un trámite.

PUT /v1/test/procedures/{id}/status

{
  "status": "IN_PROGRESS"
}

Añadir un documento generado a un trámite

Añade un documento de ejemplo al trámite indicando únicamente su tipo. El documento se añade a generatedDocuments y dispara un evento procedure.document.added. Documentos disponibles:

POST /v1/test/procedures/{id}/documents

{
  "type": "es_ivtm_payment_proof"
}

Crear una incidencia a nivel de trámite

Añade una incidencia a nivel de trámite, de nivel blocker o hold. El trámite pasa a BLOCKED y se reciben los eventos procedure.status_changed y procedure.incident.added. Algunos tipos disponibles:

Nivel blocker — el trámite está bloqueado por algo que el cliente puede desbloquear

Nivel hold — el trámite espera una respuesta de una entidad externa

POST /v1/test/procedures/{id}/incidents

{
  "type": "unpaid-ivtm-tax"
}

Crear una incidencia a nivel de documento

Añade una incidencia a nivel de documento. El trámite pasa a BLOCKED y se reciben los eventos procedure.status_changed y procedure.incident.added. Algunos tipos disponibles:

POST /v1/test/procedures/{id}/documents/{documentId}/incidents

{
  "type": "invalid-document"
}

Resolver cualquier tipo de incidencia

Marca como resuelta cualquier incidencia — de nivel hold o blocker — de un trámite o de un documento. El body de la petición va vacío. Se reciben los eventos procedure.status_changed (de vuelta a PENDING si no quedan más incidencias) y procedure.incident.solved.

POST /v1/test/procedures/{id}/incidents/{incidentId}/solve

{}

Pruebas de trámites DGT

A continuación recogemos los flujos que puede seguir un trámite en la operativa diaria. Te animamos a validarlos en el entorno de pruebas para comprobar que tu integración funciona correctamente y que recibes la información necesaria para mantener actualizado el estado del trámite por tu lado. No hace falta que ejecutes los tres: prueba uno o varios según los flujos con los que te vayas a encontrar. Los pasos marcados como (emulación) se ejecutan con los endpoints de test de la sección anterior.

Flujo 1 — Crea trámite pendiente de confirmar

1. Crea un trámite no confirmado con los datos mínimos — POST /v1/procedures/registration (o el endpoint equivalente de transferencia/notificación) con "confirmed": false.
2. Modifica el trámite añadiendo o cambiando algunos datos — PATCH /v1/procedures/registration/{id}.
3. Confirma el trámite — POST /v1/procedures/{id}/confirm. Se recibe procedure.status_changed → PENDING.
4. Valida que el trámite está confirmado — GET /v1/procedures/{id}.
5. Añade un documento de tipo generado (emulación). Se recibe procedure.document.added; el documento es descargable a través de event.data.downloadUrl.
6. Avanza el trámite hasta un estado final (emulación). Se reciben, en orden, procedure.status_changed → IN_PROGRESS y procedure.status_changed → DONE.

Flujo 2 — Crea un trámite confirmado

1. Crea un trámite ya confirmado, con todos los datos necesarios — POST /v1/procedures/registration (o equivalente). Se recibe procedure.status_changed → PENDING.
2. Valida que el trámite está confirmado — GET /v1/procedures/{id}.
3. Añade un documento de tipo generado (emulación). Se recibe procedure.document.added, descargable vía event.data.downloadUrl.
4. Avanza el trámite hasta un estado final (emulación). Se reciben, en orden, procedure.status_changed → IN_PROGRESS y procedure.status_changed → DONE.

Flujo 3 — Resuelve incidencias

Ejecuta este flujo con uno cualquiera de los tipos de trámite.

1. Crea un trámite confirmado, con todos los datos necesarios — POST /v1/procedures/registration (o equivalente). Se recibe procedure.status_changed → PENDING.
2. Añade una incidencia a nivel de trámite (emulación). Se reciben procedure.status_changed → BLOCKED y procedure.incident.added.
3. Resuelve la incidencia vía API — POST /v1/procedures/{id}/incidents/{incidentId}/solve. Se reciben procedure.status_changed → PENDING y procedure.incident.solved.
4. Añade una incidencia a nivel de documento (emulación). Se reciben procedure.status_changed → BLOCKED y procedure.incident.added.
5. Resuelve la incidencia vía API con el mismo endpoint. Se reciben procedure.status_changed → PENDING y procedure.incident.solved.
6. Avanza el trámite hasta un estado final (emulación). Se reciben, en orden, procedure.status_changed → IN_PROGRESS y procedure.status_changed → DONE.

Pruebas de informes DGT

Los informes DGT tienen dos tipos —reducido y completo— y se crean con POST /v1/reports/reduced y POST /v1/reports/complete. El informe se genera de forma asíncrona: la creación responde con status: "processing" y el resultado llega vía el webhook report.completed o consultando GET /v1/reports/{id}.

Para que puedas validar los distintos desenlaces —vehículo no transferible, con avisos, no registrado en la DGT, error técnico— sin depender de la DGT, en el entorno de desarrollo tienes reservadas unas matrículas sentinel. Al crear un informe con una de ellas, se devuelve el desenlace asociado en lugar del resultado real. Cualquier otra matrícula válida devuelve un informe correcto (transferabilityStatus: transferable).

Las matrículas sentinel son distintas para cada tipo de informe.

Informe reducido

Con cualquier otra matrícula válida el informe reducido se resuelve como status: completed y transferabilityStatus: transferable (vehículo transferible).

POST /v1/reports/reduced

{
  "vrm": "0000BBB"
}

Cuando el estado del informe reducido es completed se emiten los webhook events report.completed y report.status_changed. Cuando el estado del informe reducido es error sólo se emite el webhook event report.status_changed

Informe completo

Con cualquier otra matrícula válida el informe completo se resuelve como status: completed y transferabilityStatus: transferable (vehículo transferible).

POST /v1/reports/complete

{
  "vrm": "9999FFF"
}

El informe completo nunca devuelve transferable_with_alerts: las incidencias no bloqueantes se listan en chargesAndLiens, no en el veredicto. Para diferenciar un error transitorio de uno permanente, revisa failureReason — service_unavailable es reintentable, null no lo es.

Documentos de ejemplo

Si no quieres usar tus propios PDFs para las pruebas, puedes usar estos documentos de ejemplo.

Documentos de entrada

Matriculación

Transferencia y notificación

Documentos generados

Matriculación

Transferencia y notificación

Siguientes pasos

Una vez hayas validado el proceso, o mientras lo estés validando, podemos organizar una sesión conjunta entre nuestros equipos de ingeniería para revisar la integración y comprobar juntos qué se recibe en cada lado. Escríbenos a developers@punto.ai para coordinarla.