Referencia de la API pública
Documentación de la API pública de Fidelizador. Audiencia: desarrolladores externos que integran la plataforma (envío, consulta de estado, gestión de dominios/credenciales, webhooks).
Base URL y versionado
- Base URL producción: por definir con comercial.
- Base URL sandbox: ver Validar su integración en sandbox.
- Versión: va en el path (
/v1/..., sin prefijo/api) y es por endpoint. Cuando un endpoint necesita un cambio incompatible se publica en la versión siguiente y el resto se queda en la suya, así que pueden convivir/v2/mails/sendy/v1/mails. La versión vigente de cada endpoint está en su ficha:/v1no significa que la API entera vaya a migrar en bloque, y una integración no necesita migrar los endpoints que no cambiaron. Los endpoints autenticados por API key viven directamente bajo la versión, sin namespace adicional. - Formato: JSON (request y response). Headers
Content-Type: application/json. - Alcance del host: sirve la API pública (
/v1/..., autenticada por API key). La gestión de credenciales y la configuración del tenant se hacen desde el panel, no por este host.
Autenticación
Toda llamada a la API viaja con estos headers, todos obligatorios. key_id es la primera parte de su API key completa (FD.<key_id>.<token>); tenant-slug es el identificador corto de su instancia:
Authorization: Bearer FD.<key_id>.<token>
X-Instance-Slug: <tenant-slug>
| Mecanismo | Authorization | Cuándo usarlo |
|---|---|---|
| API key | Bearer FD.<key_id>.<token> | Recomendado para cliente programático |
| JWT de usuario | Bearer <jwt> | Para operaciones de gestión hechas por operadores humanos desde un frontend |
Antes de su primera llamada
Credenciales API
Crearla en el panel, elegir sus permisos y guardarla: se muestra una sola vez.
Validar en sandbox
Probar la credencial contra el ambiente de pruebas antes de ir a producción.
Endpoints principales
A continuación se muestran los endpoints disponibles de la API pública de Fidelizador.
| Familia | Endpoints |
|---|---|
/v1/mails | send · list · get · logs |
/v1/activities | sent · export · bounced · export · opens · export · clicks · export |
/v1/stats | overview |
/v1/domains/v1/senders | Ver Dominios y remitentes — gestión de dominios (DKIM, SPF) y remitentes. |
/v1/mail-templates | list · get — solo lectura |
/v1/mail-restrictions | list — solo lectura |
/v1/mail-unsubscribes | list · get |
/v1/mail-complaints | list · get |
/v1/fields/v1/forms/v1/consent-terms/v1/consent-purposes/v1/consent-events/v1/consent-rules | Ver Campos, formularios y consentimiento — catálogo de campos, formularios y consentimiento (Ley 21.719). |
/webhook | Tabla y modelo de datos ya definidos; no existe hoy un endpoint de gestión (CRUD) ni un worker de delivery — ambos están planeados. |
Contrato OpenAPI vigente: lo sirve la propia API, generado desde el código y disponible en todo ambiente, en https://$API_HOST/docs (referencia navegable) y https://$API_HOST/openapi.json (el spec, importable en Postman o Insomnia). GET https://$API_HOST/ devuelve un documento con esos enlaces y el de esta guía.
Ejemplos
Los ejemplos usan $API_HOST (el host de su API, ver Base URL), $API_KEY (FD.<key_id>.<token>) y $SLUG (el slug de su instancia). Todos los endpoints de este host se autentican con API key. El ejemplo curl completo de cada endpoint está en su ficha, linkeada desde la tabla de Endpoints principales.
Enviar un correo (POST /v1/mails/send, ver ficha completa):
curl -X POST "https://$API_HOST/v1/mails/send" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG" \
-H "Content-Type: application/json" \
-d '{
"sender_email": "contacto@correos.micomercio.cl",
"to": [{ "email": "destinatario@ejemplo.com", "name": "Destinatario" }],
"subject": "Bienvenido",
"html": "<p>Hola, gracias por registrarte.</p>"
}'
Identificadores
Entender los IDs que aparecen en las respuestas y logs:
| ID | Origen | Dónde aparece | Persistido |
|---|---|---|---|
request_id | Generado por API en cada HTTP request | Response header X-Request-Id, logs, mensaje de error | No |
msg_id | Devuelto al enviar un correo exitoso | Campo message_id en el body de la respuesta POST /v1/mails/send; como msg_id en GET /v1/mails y en logs de entrega | Sí |
mail_id | Uno por destinatario del envío | Reportes, payloads de webhook (cuando el delivery worker esté implementado) | Sí |
Webhooks
Estado actual: solo el modelo de datos existe hoy en la plataforma. No hay un endpoint HTTP (CRUD) para gestionar webhooks ni un worker de delivery — ambos están planeados. El cliente no puede registrar webhooks todavía.
Sandbox
Entorno de pruebas con dominios y prefijos que simulan comportamientos del mundo real. Detalle: Validar su integración en sandbox.
Límites
- Rate limits API/SMTP: ver Rate limits — el bandwidth shaping por instancia está activo hoy; el resto (requests/segundo por API key, por tenant, SMTP por credencial) está planeado.
- SLA formal (uptime, latencia, compensaciones): se define por contrato con comercial.
Filtros de texto
Los filtros de texto de los listados (domain, name, email, subject, recipient) tienen dos
modos de coincidencia. Cada ficha declara cuál usa su filtro:
| Modo | Qué hace | Dónde |
|---|---|---|
| Parcial | Coincide si el valor aparece en cualquier parte del campo, sin distinguir mayúsculas. | domain, name, email, subject, y recipient en los listados de supresión (restricciones, desuscripciones y quejas) |
| Exacta | Coincide solo con la dirección completa. | recipient en el listado de correos y en los de actividad; estos últimos aceptan además recipient_operator=starts_with, que lo cambia a prefijo |
El recipient de supresión es parcial a propósito: es lo que permite la higiene por dominio, como
?recipient=@acme.com para listar todo lo suprimido de ese dominio. El reverso hay que tenerlo
presente: ?recipient=ana@ejemplo.com también devuelve a mariana@ejemplo.com.mx, porque la
primera dirección está contenida en la segunda. Para decidir si una dirección puntual está
suprimida, comparar la dirección de cada resultado - no alcanza con que la respuesta traiga
registros.
Los caracteres % y _ se buscan literales. La API los escapa, así que no funcionan como
comodines: un ?name=50%25 (o sea 50%) devuelve las plantillas cuyo nombre contiene el texto
50%, y no las que tienen un 50 seguido de cualquier cosa. No hay búsqueda con comodines.
Una dirección con + debe ir percent-encodeada como %2B. En una query string el + se
decodifica como espacio, así que enviarlo tal cual busca usuario tag@ejemplo.com y la respuesta
es un 200 con lista vacía - falla en silencio, sin error que lo delate:
# correcto
curl "https://$API_HOST/v1/mail-unsubscribes?recipient=usuario%2Btag@ejemplo.com" \
-H "Authorization: Bearer $API_KEY" -H "X-Instance-Slug: $SLUG"
# incorrecto - el `+` llega como espacio y no matchea nada
curl "https://$API_HOST/v1/mail-unsubscribes?recipient=usuario+tag@ejemplo.com" ...
La regla general es percent-encodear todo valor de query string; el + es el caso que más sorprende
porque el resto de una dirección de email viaja sin cambios.
Formato de respuesta
En éxito, un recurso se devuelve bare (sus campos al top level, sin envoltura) y una colección usa { "data": [...], "pagination": {...} }. Los status codes siguen RFC 9110 (200 con representación, 201 + header Location al crear, 204 sin cuerpo) y las colecciones paginan con page/page_size. Esquema completo del envelope, paginación y headers (X-Request-Id, X-Trace-Id, Location): Paginación y formato de respuesta.
Errores comunes
Todas las APIs responden errores con el formato RFC 9457 application/problem+json. La referencia completa — esquema del envelope, code (discriminador estable), errors[] con code/pointer/params por campo, y lista de códigos — está en Respuestas de error.
Resumen de status codes:
| Código | Uso |
|---|---|
| 200 / 201 | Operación exitosa |
| 400 | Request mal formado |
| 401 | No autenticado |
| 403 | Autenticado pero sin permisos |
| 404 | Recurso no existe |
| 409 | Conflicto (p. ej. recurso ya existe) |
| 422 | Validación fallida — incluye errors[] con code/pointer por campo |
| 429 | Rate limit excedido (planeado) |
| 500 | Error interno — reportar con el trace_id del cuerpo de respuesta |
Referencias
- Contrato técnico autoritativo:
https://$API_HOST/docsyhttps://$API_HOST/openapi.json, servidos por la propia API. - SDK oficiales: por definir.
- Changelog de la API: planeado, no disponible todavía.
Este hub reformatea y contextualiza para audiencia externa, pero no es la fuente de verdad del contrato. Ante discrepancia, el contrato OpenAPI publicado por la API manda.