Editor de diagramas de secuencia Mermaid
Un diagrama de secuencia muestra quién habla con quién y en qué orden. Sirve cuando lo interesante es el intercambio de mensajes entre varias partes — una autenticación, un pago, una integración entre servicios. Si solo hay un actor y lo que importa son las bifurcaciones, un diagrama de flujo dice lo mismo con menos ruido.
Un pago con tarjeta y autenticación reforzada
El valor de este diagrama está en los bloques `alt`: dejan ver que el 3-D Secure no siempre ocurre y que hay dos finales distintos. Fíjate también en que la pasarela habla con el banco sin que la tienda se entere; eso es exactamente lo que un diagrama de secuencia hace visible y un diagrama de flujo esconde.
sequenceDiagram
autonumber
participant C as Cliente
participant T as Tienda
participant P as Pasarela
participant B as Banco emisor
C->>T: Confirmar el pedido
T->>P: Solicitar autorización
P->>B: Enviar la operación
B-->>P: Requiere autenticación
alt El banco pide 3-D Secure
P-->>C: Redirigir al banco
C->>B: Introducir el código
B-->>P: Autenticación correcta
else El banco no la pide
B-->>P: Autorizada directamente
end
P-->>T: Autorización concedida
T-->>C: Pedido confirmado
T->>T: Registrar la ventaEjemplos resueltos
1. Dos participantes y un mensaje
`->>` es una flecha con punta rellena, para una llamada. `-->>` es punteada, para la respuesta. Esa pareja cubre la mayoría de los diagramas.
sequenceDiagram
Cliente->>API: Crear el pedido
API-->>Cliente: 201 Created2. Alias para nombres largos
`participant X as Nombre largo` da un identificador corto para escribir y un nombre legible para leer. Declarar los participantes al principio también fija su orden en el dibujo, que si no se decide por el orden de aparición.
sequenceDiagram
participant N as Navegador
participant A as API de pedidos
participant I as Servicio de inventario
N->>A: POST /pedidos
A->>I: Reservar unidades
I-->>A: Reserva confirmada
A-->>N: 201 Created3. Activaciones y llamadas a uno mismo
`activate` y `deactivate` dibujan la barra que indica que un participante está trabajando. El sufijo `+` y `-` en la flecha hace lo mismo escribiendo menos. Una flecha de un participante a sí mismo representa trabajo interno.
sequenceDiagram
participant A as API
participant D as Base de datos
Cliente->>+A: GET /factura/42
A->>+D: SELECT factura
D-->>-A: Fila encontrada
A->>A: Calcular el IVA
A-->>-Cliente: 200 OK4. Alternativas, opcionales y bucles
`alt`/`else` son caminos excluyentes, `opt` es un bloque que puede no ocurrir y `loop` una repetición. Los tres se cierran con `end`, y olvidarlo es el error más habitual del tipo.
sequenceDiagram
participant C as Cliente
participant A as API
participant M as Servicio de correo
C->>A: Solicitar el alta
alt Correo ya registrado
A-->>C: 409 Conflict
else Correo libre
A-->>C: 201 Created
A->>M: Enviar verificación
loop Hasta 3 reintentos
M->>M: Reintentar si falla el envío
end
end
opt El cliente acepta el boletín
A->>M: Dar de alta en la lista
end5. Notas y agrupaciones en paralelo
`par` muestra ramas que ocurren a la vez, algo que un diagrama de flujo insinúa pero no afirma. Las notas son el sitio correcto para el detalle que no cabe en una etiqueta de mensaje.
sequenceDiagram
participant A as API de pedidos
participant F as Facturación
participant L as Logística
Note over A: El pedido ya está pagado
par Avisar a facturación
A->>F: Emitir la factura
F-->>A: Factura 2026/0431
and Avisar a logística
A->>L: Preparar el envío
L-->>A: Albarán generado
end
Note over F,L: Ambas siguen su propio ritmoReferencia de sintaxis del diagrama de secuencia
Las flechas son lo que hay que memorizar, y son propias de este tipo: el `-->` de un diagrama de flujo aquí significa otra cosa, y el `->>` de aquí es un error en un diagrama de clases.
| Sintaxis | Significado |
|---|---|
| sequenceDiagram | Abre el diagrama. Distingue mayúsculas: `sequencediagram` no vale. |
| participant A | Declara un participante y fija su posición. |
| participant A as Nombre | Identificador corto con nombre legible. |
| actor A | Igual que participant, pero dibuja una figura humana. |
| A->>B: texto | Mensaje con punta rellena — una llamada. |
| A-->>B: texto | Línea punteada — una respuesta. |
| A-)B: texto | Punta abierta — un mensaje asíncrono. |
| A->>A: texto | Un participante se llama a sí mismo. |
| activate A / deactivate A | Marca el periodo en que A está trabajando. |
| A->>+B: / B-->>-A: | Lo mismo en forma abreviada, sobre la propia flecha. |
| alt cond ... else ... end | Caminos excluyentes. |
| opt cond ... end | Bloque que puede no ocurrir. |
| loop texto ... end | Repetición. |
| par ... and ... end | Ramas simultáneas. |
| Note over A,B: texto | Nota sobre uno o varios participantes. También `Note left of` y `Note right of`. |
| autonumber | Numera los mensajes automáticamente. |
Seis errores que rompen un diagrama de secuencia
Reproducidos con Mermaid 11.12.2. El más común con diferencia es el primero, y su mensaje de error es de los que peor señalan dónde está el problema.
Lo que ves
Parse error señalado en la última línea del diagrama
Por qué
Un bloque abierto y nunca cerrado. `alt`, `opt`, `loop` y `par` necesitan su `end`. Mermaid informa del fallo en el punto en que se le acaba la entrada, así que el número de línea apunta al final del fichero y no al bloque que falta cerrar. Con dos bloques anidados esto se vuelve genuinamente difícil de ver.
Solución
Cuenta los bloques que abres y los `end` que escribes. Si el error señala la última línea, casi siempre es esto.
sequenceDiagram
Cliente->>API: Petición
alt Todo correcto
API-->>Cliente: 200 OKsequenceDiagram
Cliente->>API: Petición
alt Todo correcto
API-->>Cliente: 200 OK
endLo que ves
No diagram type detected matching given configuration
Por qué
La palabra clave está mal escrita en mayúsculas y minúsculas. `sequenceDiagram` funciona; `sequencediagram` y `SequenceDiagram` no. Mermaid distingue mayúsculas en todas sus palabras clave.
Solución
D mayúscula, el resto en minúscula.
sequencediagram
Cliente->>API: HolasequenceDiagram
Cliente->>API: HolaLo que ves
Se dibuja, pero el mensaje sale sin texto
Por qué
Falta el texto después de los dos puntos. Comprobado: Mermaid no lo rechaza — dibuja el mensaje con una etiqueta vacía, y la flecha se queda sin explicación. Lo que sí se cae es omitir los dos puntos por completo: `Cliente->>API` a secas da `Expecting 'TXT', got 'NEWLINE'`. Es decir, los dos puntos son obligatorios y el texto no lo es, justo al revés de lo que uno supondría.
Solución
Escribe algo después de los dos puntos, aunque sea una palabra. Una flecha sin etiqueta casi nunca es lo que querías.
sequenceDiagram
Cliente->>API:
API-->>Cliente: 200sequenceDiagram
Cliente->>API: Crear el pedido
API-->>Cliente: 200Lo que ves
Parse error después de un `alt` con condición larga
Por qué
Un salto de línea dentro de la condición del bloque. La condición de `alt`, `opt` o `loop` tiene que caber en una sola línea; al partirla, la segunda mitad se interpreta como un mensaje y no encaja en ningún sitio.
Solución
Deja la condición en una línea. Si es demasiado larga, acórtala y pon el detalle en una nota.
sequenceDiagram
alt El cliente tiene saldo
suficiente en la cuenta
A-->>B: OK
endsequenceDiagram
alt El cliente tiene saldo suficiente
A-->>B: OK
end
Note over A,B: Saldo comprobado contra el límite diarioLo que ves
Se dibuja, pero aparece un participante que no habías declarado
Por qué
Una errata en el nombre de un participante. Mermaid crea el participante la primera vez que lo ve, así que `Pasarela` y `Pasarala` son dos columnas distintas y no avisa de nada. En español pasa sobre todo con las tildes: `API` y `APÍ`, o `Facturación` escrito una vez sin tilde, generan una columna extra.
Solución
Declara los participantes con `participant` al principio. No evita la errata, pero deja a la vista cuáles son los válidos y hace que la columna sobrante salte al ojo.
sequenceDiagram
Cliente->>Facturación: Emitir factura
Facturacion-->>Cliente: Factura emitidasequenceDiagram
participant C as Cliente
participant F as Facturación
C->>F: Emitir factura
F-->>C: Factura emitidaLo que ves
Se dibuja, pero el orden de las columnas no es el que querías
Por qué
No has declarado los participantes. Sin declaraciones, el orden lo fija la primera aparición de cada nombre, así que un mensaje añadido al principio del diagrama puede recolocar todas las columnas y cruzar las flechas. El diagrama sigue siendo correcto, pero se lee mucho peor.
Solución
Declara todos los participantes en la cabecera, en el orden en que quieres verlos.
sequenceDiagram
Banco-->>Pasarela: Autorizada
Cliente->>Tienda: Confirmar pedido
Tienda->>Pasarela: AutorizarsequenceDiagram
participant Cliente
participant Tienda
participant Pasarela
participant Banco
Cliente->>Tienda: Confirmar pedido
Tienda->>Pasarela: Autorizar
Pasarela->>Banco: Enviar operación
Banco-->>Pasarela: AutorizadaNotas sobre el dibujado
Medido sobre el Mermaid 11.12.2 que usa este sitio. El diagrama de secuencia se comporta distinto al resto en dos aspectos concretos.
El ancho lo marcan los participantes, no los mensajes
Medido: dos participantes dan un viewBox de 450 píxeles de ancho y seis dan 1250, unos 200 píxeles por columna añadida, sea cual sea el texto de los mensajes. Los mensajes solo suman altura, unos 46 píxeles cada uno. Con un matiz que conviene conocer: si una etiqueta de mensaje es más larga que el ancho mínimo de columna, sí ensancha el diagrama — la misma pareja de participantes pasó de 450 a 603 píxeles solo por alargar el texto de un mensaje. En español, donde las etiquetas son largas por defecto, esto se nota antes que en inglés.
Es el único tipo con el origen del viewBox en negativo
Los diagramas de secuencia salen con un viewBox que empieza en `-50 -10` en lugar de `0 0`. No es un fallo: Mermaid reserva ese margen para las cajas de los participantes. Solo importa si procesas el SVG con tus propias herramientas, porque cualquier cálculo que dé por hecho que el origen es cero recortará la primera columna.
La exportación a PNG es exacta, aquí sí
A diferencia de los diagramas de flujo, de clases, de estados y ER, el de secuencia dibuja sus etiquetas como texto SVG plano y no dentro de un `<foreignObject>`. Eso permite rasterizarlo directamente: el PNG exportado coincide con la pantalla sin ningún redibujado intermedio y sin desplazamientos tipográficos.
Un participante declarado y nunca usado se dibuja igual
Un `participant` que no envía ni recibe ningún mensaje aparece en el diagrama con su columna vacía. Puede ser útil a propósito, para mostrar a alguien que existe y no interviene en este flujo, pero también es lo que queda cuando se borra el último mensaje de un participante y se olvida borrar su declaración.
El tema cambia el color, nunca la geometría
El mismo diagrama con el tema claro y con el oscuro da un viewBox idéntico, así que las columnas no se desplazan ni los bloques cambian de tamaño al cambiar de tema.
Cuándo conviene otro diagrama
Si solo hay un participante, no hay secuencia que mostrar. Un diagrama con una única columna y flechas hacia sí mismo es un diagrama de flujo escrito de forma incómoda.
Si lo que quieres describir son los estados por los que pasa una cosa y no la conversación entre varias, usa un diagrama de estados. Se nota enseguida: si acabas escribiendo el mismo mensaje una y otra vez con condiciones distintas, lo que tienes es una máquina de estados.
Y si el intercambio tiene más de una docena de mensajes, pártelo. Un diagrama de secuencia de sesenta mensajes es técnicamente correcto y humanamente inútil; suele leerse mucho mejor como tres diagramas, uno por fase, con una nota que los enlace.
Otros tipos de diagrama
Escrito por Dominik Malsch · Última actualización: