API de dungo (v1)

Cada llamada debe incluir tu API key en el header X-Api-Key:

X-Api-Key: dgk_7Fq2mZK9xR4tLbNc8vWe1A

La key identifica a tu cuenta: no necesitas enviar ningún otro identificador. Cada key solo ve y modifica los datos de la cuenta para la que fue creada.

Cómo obtener una API key

En la aplicación web de dungo, con un usuario SUPER: Ajustes → API → Crear API key. Ahí eliges el nombre, los permisos y la caducidad.

La key completa se muestra una sola vez, al crearla. Guárdala en un lugar seguro (un gestor de secretos o las variables de entorno de tu servidor). Si la pierdes, revócala y crea una nueva. Después de crearla, en el listado solo se ven sus primeros caracteres.

La API está pensada para llamarse desde tu servidor, nunca desde el navegador ni desde una app móvil: cualquiera que vea el código podría leer la key.

Caducidad y revocación

Al crear la key eliges si caduca en días, meses, años, o si no caduca. Una key expirada deja de autenticar por sí sola. Puedes revocar cualquier key desde la misma pantalla, y el corte es inmediato.

Cada key lleva la lista de permisos que le asignaste. read habilita las lecturas (GET) y write las escrituras (POST, PUT, DELETE) del recurso.

Si llamas a un endpoint sin el scope necesario, la respuesta es 403 con el código SCOPE_INSUFICIENTE. Da a cada integración solo los permisos que necesita.

Los listados aceptan page (base 0) y size (20 por omisión) y responden con esta forma:

{
  "data": [ ... ],
  "page": 0,
  "size": 20,
  "total": 137,
  "totalPages": 7
}

Todos los errores comparten el mismo cuerpo:

{
  "code": "NOT_FOUND",
  "message": "Recurso no encontrado",
  "details": "Contacto no encontrado: 0198f1c2-...",
  "timestamp": "2026-08-03T14:22:31.482"
}

Hasta 120 solicitudes por minuto por API key. Al superarlo recibes 429; reintenta después de unos segundos. Si necesitas un volumen mayor, escríbenos.

Listar tus contactos:

curl -H "X-Api-Key: $DUNGO_API_KEY" \
  "https://dungo.ai/api/v1/contactos?size=5"

Crear un contacto:

curl -X POST "https://dungo.ai/api/v1/contactos" \
  -H "X-Api-Key: $DUNGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nombre":"Ana","apellido":"Perez","telefono":"56912345678","email":"ana@ejemplo.cl"}'

Etiquetar ese contacto:

curl -X POST "https://dungo.ai/api/v1/contactos/$CONTACTO_ID/etiquetas/$ETIQUETA_ID" \
  -H "X-Api-Key: $DUNGO_API_KEY"

Mover un trato de etapa (el etapaId sale de GET /api/v1/tableros/{id}, que devuelve el tablero con sus etapas en orden):

curl -X PUT "https://dungo.ai/api/v1/tratos/$TRATO_ID/etapa" \
  -H "X-Api-Key: $DUNGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"etapaId":"0198f1c2-4a7b-7c3d-9e21-5f6a7b8c9d01"}'

Mover un trato a una etapa de tipo ganado o perdido es un movimiento más: se usa este mismo endpoint.

El caso más común: cuando tu sistema registra un lead, quieres encontrarlo en dungo por su teléfono y etiquetarlo; si no existe, crearlo y etiquetarlo igual.

Eso es una sola llamada: POST /api/v1/contactos/sincronizar. Necesitas una key con contactos:write y, para leer el catálogo de etiquetas la primera vez, etiquetas:read.

Una sola vez: obtén el etiquetaIdDun de la etiqueta que vas a aplicar con GET /api/v1/etiquetas y guárdalo en la configuración de tu integración.

Por cada lead:

curl -X POST "https://dungo.ai/api/v1/contactos/sincronizar" \
  -H "X-Api-Key: $DUNGO_API_KEY" -H "Content-Type: application/json" \
  -d '{
        "telefono": "+56 9 1234 5678",
        "nombre": "Ana",
        "apellido": "Perez",
        "email": "ana@ejemplo.cl",
        "empresa": "Ejemplo SpA",
        "etiquetaIds": ["0198f1c2-4a7b-7c3d-9e21-5f6a7b8c9d01"]
      }'

Respuesta:

{
  "contacto": { "contactoIdDun": "0198f...", "nombre": "Ana", "telefono": "+56 9 1234 5678", … },
  "creado": true,
  "datosActualizados": false,
  "etiquetasAgregadas": ["0198f1c2-4a7b-7c3d-9e21-5f6a7b8c9d01"],
  "etiquetasYaPresentes": []
}

Qué te garantiza:

• El formato del teléfono no importa. +56 9 1234 5678, 56912345678 y (56) 9 1234-5678 son el mismo contacto. Un teléfono identifica a un solo contacto dentro de tu cuenta.
• Es idempotente. Repetir la llamada con el mismo lead no duplica nada: creado pasa a false y las etiquetas que ya tenía vuelven en etiquetasYaPresentes, sin error.
• No hay duplicados por concurrencia. Todo ocurre en una transacción, así que dos ejecuciones simultáneas del mismo lead no pueden crear dos contactos. No necesitas serializar nada en tu lado.
• No se pisan los datos que ya están en dungo. Si el contacto existe, sus datos quedan como están; envía "actualizarDatos": true si prefieres que los tuyos manden.

El tipo de contacto

tipoContactoId acepta CLIENTE, PROSPECTO, PROVEEDOR, COLABORADOR, EX_CLIENTE o DEFAULT, y se aplica solo al crear: los contactos nuevos nacen con el tipo que envíes (o DEFAULT si lo omites) y los que ya existen conservan el suyo, aunque mandes otro.

Es a propósito: si un CLIENTE vuelve a pasar por tu formulario de leads, no queremos degradarlo a PROSPECTO ni disparar los algoritmos de ese cambio sin que nadie lo pida. actualizarDatos: true tampoco toca el tipo. Para cambiarlo deliberadamente está PUT /api/v1/contactos/{id}/tipo/{tipoContactoId}.

nombre solo es obligatorio cuando el contacto hay que crearlo. El código de respuesta es 201 si nació en esa llamada y 200 si ya existía.

Etiquetar dispara el trigger ETIQUETA_AGREGADA del motor de algoritmos: puedes colgar de esa etiqueta una automatización en dungo —por ejemplo, que un agente de IA salude al lead— sin escribir nada más en tu integración.

Buscar por teléfono sin crear nada

Si solo quieres consultar, telefonoExacto compara ignorando el formato:

curl -H "X-Api-Key: $DUNGO_API_KEY" \
  "https://dungo.ai/api/v1/contactos?telefonoExacto=56912345678"

(El parámetro telefono, en cambio, busca por coincidencia parcial: 1234 también devuelve 991234567.)

Alta, consulta y mantenimiento de contactos, y su etiquetado.

Lectura de tableros, sus etapas y los tratos que contienen.

Catalogo de etiquetas con las que se clasifica a los contactos.

Creacion, movimiento entre etapas, eliminacion e historial de tratos.