# Migrar desde Z-API

> Cómo reemplazar Z-API por Messajo y conservar tu número.

Esta página muestra qué cambia al salir de Z-API y cómo cada operación suya se convierte en una llamada de Messajo. Las tablas generales de cualquier proveedor (Cloud API, 360dialog, Twilio y APIs no oficiales) están en [Migrar desde otro proveedor](/es/operate/migrate/); aquí solo van los puntos de Z-API.

## Qué cambia en el modelo

Z-API vincula un teléfono, como WhatsApp Web. Messajo usa la API oficial de Meta. En la práctica:

| En Z-API | En Messajo |
|---|---|
| Leer el código QR | Alta oficial de Meta (Embedded Signup), desde el panel |
| Instancia | Conexión (`conn_…`) |
| Mensaje libre a cualquier hora | Mensaje libre solo dentro de las 24 h del último mensaje de la persona; fuera de eso, una [plantilla aprobada](/es/guides/templates/) |
| Contacto que nunca te escribió | Exige opt-in: la persona debe haber aceptado recibir mensajes |
| Sin cobro por mensaje de Meta | Meta cobra por mensaje de plantilla, directamente a ti. Consulta [Costos de Meta](/es/guides/costs/) |
| Número vinculado | Número oficial, con calidad y límites medidos por Meta |

## Conservar el número

Para no perder la atención desde el celular, conecta en **coexistencia**: la app de WhatsApp Business sigue funcionando y Messajo importa los contactos y hasta 6 meses de historial, una sola vez, al conectar.

- Exige la app WhatsApp Business 2.24.17 o más nueva, con confirmación por código QR en la app.
- El caudal queda fijo en 20 mensajes por segundo.
- Los grupos no se sincronizan en coexistencia. Si dependes de grupos, consulta [Grupos](/es/guides/groups/): requieren el modo solo API.
- Para más volumen o un número nuevo, usa el modo **solo API**.

El paso a paso está en [Conectar WhatsApp](/es/connect/whatsapp/); si algo se traba, consulta [Problemas en la coexistencia](/es/troubleshooting/coexistence/).

## Autenticación

Z-API identifica la instancia por su ID y su token, que aparecen en el panel de Z-API. En Messajo toda llamada lleva `Authorization: Bearer <clave>`:

- **clave de organización** (`mj_…`): se envía con `connection_id` en el cuerpo;
- **clave de conexión** (`mjc_…`): vale solo para una conexión y no necesita `connection_id`. Es lo más parecido a "un token por instancia".

Consulta [Tipos de clave](/es/api/authentication/#tipos-de-clave).

## Operaciones lado a lado

Las rutas de Z-API no están aquí: consúltalas en la [documentación de Z-API](https://developer.z-api.io/). La columna izquierda nombra la operación.

| Operación en Z-API | En Messajo |
|---|---|
| Enviar texto | `POST /v1/messages` con `type: "text"`. Consulta [Enviar texto](/es/send/text/) |
| Enviar imagen | `type: "image"`. Consulta [Enviar imagen](/es/send/image/) |
| Enviar video | `type: "video"`. Consulta [Enviar video](/es/send/video/) |
| Enviar audio | `type: "audio"`. Consulta [Enviar audio](/es/send/audio/) |
| Enviar documento | `type: "document"`. Consulta [Enviar documento](/es/send/document/) |
| Enviar sticker | `type: "sticker"`. Consulta [Enviar sticker](/es/send/sticker/) |
| Enviar ubicación | `type: "location"`. Consulta [Enviar y pedir ubicación](/es/send/location/) |
| Enviar contacto | `type: "contacts"`. Consulta [Enviar contacto](/es/send/contacts/) |
| Enviar botones | `type: "interactive"`, botones de respuesta. Consulta [Enviar botones](/es/send/buttons/) |
| Enviar lista de opciones | `type: "interactive"`, lista. Consulta [Enviar lista](/es/send/list/) |
| Reaccionar a un mensaje | `type: "reaction"`. Consulta [Enviar reacción](/es/send/reaction/) |
| Responder citando un mensaje | `reply_to` en el cuerpo del envío |
| Marcar como leído | `POST /v1/messages/{id}/read`. Consulta [Marcar como leído](/es/send/mark-as-read/) |
| Enviar un archivo por URL | `link` (URL pública) o `media_id`, obtenido con `POST /v1/media` (multipart) |

El envío de texto de Z-API usa los campos `phone` y `message` ([Enviar texto simple](https://developer.z-api.io/message/send-text)). En Messajo pasan a ser `to` y `text.body`.

### Formato del destinatario

Messajo acepta el teléfono con prefijo de país, solo dígitos (por ejemplo `5511999999999`), o un contacto `ctc_…`. Los sufijos como `@c.us` no existen; cualquier carácter que no sea dígito se descarta.

## Webhooks

| En Z-API | En Messajo |
|---|---|
| Retorno de mensaje recibido | Evento `message.received` |
| Retorno de estado del mensaje (enviado, entregado, leído) | Evento `message.status` |
| Retorno de estado de la instancia | Eventos `connection.*` |
| Retorno del código QR | Sin equivalente: la conexión se hace desde el panel |

Registras un [destino de eventos](/es/webhooks/events/) y Messajo firma cada entrega con `Messajo-Signature` (HMAC-SHA256). Verifica la firma en tu servidor, como en [Verificar la firma](/es/webhooks/verify-signature/). En coexistencia, los mensajes enviados desde la app del celular llegan como `message.echo`.

## Qué no tiene equivalente o funciona distinto

- **Enviar a cualquier persona a cualquier hora.** En Messajo rige la ventana de 24 h y, fuera de ella, solo plantilla aprobada. Consulta [Límites](/es/api/limits/#ventanas).
- **Grupos.** No se sincronizan en coexistencia; para usar grupos, el modo es solo API. Consulta [Grupos](/es/guides/groups/).

## Checklist de cambio

- [ ] Conexión creada (coexistencia o solo API) y **Activa** en el panel.
- [ ] Plantillas creadas y aprobadas para los mensajes que envías fuera de la ventana.
- [ ] Destinos de eventos creados, con la firma verificada en tu servidor.
- [ ] Una clave de API por integración, con solo los permisos y conexiones necesarios.
- [ ] Prueba de punta a punta con un número tuyo: enviar, recibir, estados y plantilla.
- [ ] Integración cambiada al nuevo `Authorization` y formato de cuerpo, con destinatarios sin sufijos.
- [ ] Instancia de Z-API apagada **solo después** de que la conexión oficial esté activa y probada, y el dispositivo vinculado por código QR desvinculado de ella.
