Para desarrolladores

Construye sobre TraXmark: una única superficie REST, claves API con scopes explícitos, errores RFC 7807 y paginación por cursor.

Referencia OpenAPI 3.1.0

API v1 de TraXmark

Inteligencia de interacción por email en una única superficie REST. Lee y escribe contactos, mensajes, eventos, documentos, sobres y propuestas con el mismo formato de clave, la misma forma de error y el mismo contrato de paginación.

Autenticación: una clave API trax_…. Solo se almacena su hash Argon2id.
Los errores siguen RFC 7807 e incluyen una clave i18n y la cabecera x-correlation-id.
Paginación por cursor en cada lista, con un máximo de 100 elementos por página.
Anti-enumeración: un recurso que no existe y un recurso al que no puedes acceder responden ambos con 404.

Recursos

Seis recursos, cada uno con lectura y escritura mediante scopes equivalentes.

/api/v1/contactsSe lee con el scope contacts:read y se escribe con el scope contacts:write.

/api/v1/messagesSe lee con el scope messages:read y se escribe con el scope messages:write.

/api/v1/eventsSe lee con el scope events:read y se escribe con el scope events:write.

/api/v1/documentsSe lee con el scope documents:read y se escribe con el scope documents:write.

/api/v1/envelopesSe lee con el scope envelopes:read y se escribe con el scope envelopes:write.

/api/v1/proposalsSe lee con el scope proposals:read y se escribe con el scope proposals:write.

Scopes

Cada clave API se emite con un conjunto explícito de 16 scopes.

campaigns:read

campaigns:write

contacts:read

contacts:write

messages:read

messages:write

events:read

events:write

documents:read

documents:write

envelopes:read

envelopes:write

proposals:read

proposals:write

devices:read

devices:write

Una solicitud sin el scope requerido se rechaza con 403.

Puntos de conexión (19)

Todas las rutas viven bajo una única URL base y responden con la misma forma de error.

Método	Endpoint	Scope	Descripción
`GET`	`/api/v1/contacts`	`contacts:read`	Devuelve una página de `contacts` (paginación por cursor, máximo 100).
`POST`	`/api/v1/contacts`	`contacts:write`	Crea una entrada nueva de `contacts`.
`GET`	`/api/v1/contacts/{id}`	`contacts:read`	Obtiene un elemento de `contacts` por ID. Si no existe o no tienes acceso: 404.
`GET`	`/api/v1/messages`	`messages:read`	Devuelve una página de `messages` (paginación por cursor, máximo 100).
`POST`	`/api/v1/messages`	`messages:write`	Crea una entrada nueva de `messages`.
`GET`	`/api/v1/messages/{id}`	`messages:read`	Obtiene un elemento de `messages` por ID. Si no existe o no tienes acceso: 404.
`GET`	`/api/v1/events`	`events:read`	Devuelve una página de `events` (paginación por cursor, máximo 100).
`POST`	`/api/v1/events`	`events:write`	Crea una entrada nueva de `events`.
`GET`	`/api/v1/events/{id}`	`events:read`	Obtiene un elemento de `events` por ID. Si no existe o no tienes acceso: 404.
`GET`	`/api/v1/documents`	`documents:read`	Devuelve una página de `documents` (paginación por cursor, máximo 100).
`POST`	`/api/v1/documents`	`documents:write`	Crea una entrada nueva de `documents`.
`GET`	`/api/v1/documents/{id}`	`documents:read`	Obtiene un elemento de `documents` por ID. Si no existe o no tienes acceso: 404.
`GET`	`/api/v1/envelopes`	`envelopes:read`	Devuelve una página de `envelopes` (paginación por cursor, máximo 100).
`POST`	`/api/v1/envelopes`	`envelopes:write`	Crea una entrada nueva de `envelopes`.
`GET`	`/api/v1/envelopes/{id}`	`envelopes:read`	Obtiene un elemento de `envelopes` por ID. Si no existe o no tienes acceso: 404.
`GET`	`/api/v1/proposals`	`proposals:read`	Devuelve una página de `proposals` (paginación por cursor, máximo 100).
`POST`	`/api/v1/proposals`	`proposals:write`	Crea una entrada nueva de `proposals`.
`GET`	`/api/v1/proposals/{id}`	`proposals:read`	Obtiene un elemento de `proposals` por ID. Si no existe o no tienes acceso: 404.
`POST`	`/api/v1/campaigns/send`	`campaigns:write`	Inicia una campaña. Consume una unidad de `campaigns_per_month` más `messages_per_month` igual al número de destinatarios. Por encima del límite de mensajes, la API responde 403, salvo que el tenant tenga exceso contratado (`platform_config` → `overage.enabled`) y un cliente de Stripe; entonces se factura un bloque de 1000 mensajes, el límite crece y el envío sigue adelante.

Fragmentos de SDK

Puntos de partida para copiar y pegar contra la URL base pública.

Node.js

fetch nativo, cuerpo RFC 7807 en caso de fallo y cursor desde nextCursor.

const res = await fetch('https://api.traxmark.com/api/v1/contacts?limit=50', {
  headers: { Authorization: `Bearer ${process.env.TRAXMARK_API_KEY}` },
});
if (!res.ok) throw new Error(await res.text()); // RFC7807 JSON
const { items, nextCursor } = await res.json();

Python

requests con raise_for_status y decodificación JSON.

import requests
r = requests.get('https://api.traxmark.com/api/v1/contacts',
                 headers={'Authorization': f'Bearer {API_KEY}'}, params={'limit': 50})
r.raise_for_status(); data = r.json()

Sustituye la variable de entorno por una clave emitida en Ajustes → Claves API; empieza por trax_.