Introducción
En esta plataforma encontrarás algunos servicios que se pueden usar directamente desde tu panel una vez que tengas tu cuenta:
- Correos transaccionales
- Optimización de imágenes
- Almacenamiento de archivos
- Generación de PDF
- Acortador de URL
Estos servicios también ofrecen una API REST para interactuar con ellos desde cualquier otro sistema que pueda realizar solicitudes HTTP.
Empezar
Activar servicios
Antes de utilizar la API de un servicio, es necesario que lo actives en su respectiva página.
Páginas de los servicios:- Correos transaccionales
- Optimización de imágenes
- Almacenamiento de archivos
- Generación de PDF
- Acortador de URL
Crear API keys
En cada página de servicio encontrarás un acordeón con la leyenda "API key", al hacer clic sobre él verás el botón "Crear API key".
Headers
A continuación se muestran las cabeceras necesarias para usar la API.
Authorization
/*...*/
// La API key sólo debe existir en el servidor.
Authorization: `Bearer ${API_KEY}`,
/*...*/Todas las solicitudes autenticadas deben realizarse desde tu servidor e incluir esta cabecera. Su valor se compone de la palabra "Bearer" seguida por tu API key y separada por un espacio. Nunca expongas la credencial en código enviado al navegador.
Content-Type
/*...*/
// Usa este tipo para cuerpos JSON.
'Content-Type': 'application/json'
/*...*/Cuando se requiera enviar datos en el body de la solicitud, esta cabecera será necesaria y deberá contener el valor "application/json".
Accept-Language
/*...*/
// Opcional: solicita mensajes de error en español.
'Accept-Language': 'es',
/*...*/Usar esta cabecera con el valor "es" hará que los mensajes de error en las respuestas de la API estén en español. Utilizar cualquier otro valor o no enviar ninguno hará que todos estos mensajes estén en inglés.
Metadatos de respuesta y soporte
withResponseMetadata está disponible en los seis SDKs: TESClient, IOSClient, FSSClient, PGSClient, USSClient y HESClient, tanto con los paquetes individuales como con @ircg/sdk. Su uso es opcional.
Capturar metadatos con el SDK
Las respuestas HTTP de la API incluyen X-IRCG-Request-ID en éxitos y errores, independientemente del diagnóstico de tiempos. Guarda este identificador al solicitar soporte. En cualquier SDK, usa withResponseMetadata como en el ejemplo siguiente: result conserva el retorno del método y responses contiene requestId, status y url por respuesta recibida. Cada llamada mantiene sus propios metadatos. Pasa el contexto a cada método de la operación. Si termina sin utilizar el contexto, se emite un aviso. Para callbacks intencionadamente locales, pasa { allowNoRequests: true } como segundo argumento de withResponseMetadata. Las simulaciones lo permiten automáticamente. Si una llamada lanza un error, error.responses conserva las respuestas parciales, incluso si un intento posterior falla sin respuesta. La firma y la descarga posterior tienen identificadores distintos. Si no se recibió una respuesta, responses queda vacío; si falta la cabecera, requestId es opcional. El ejemplo usa getAll, que devuelve los fallos en result.error; lee su identificador en result.error.details?.requestId. Las variantes Unsafe, como getAllUnsafe, lanzan los errores: captúralos para consultar error.requestId y error.responses. Las simulaciones locales no generan un identificador remoto.
// server.ts / server.js
import { IOSClient } from '@ircg/ios'
const apiKey = process.env.IRCG_IOS_API_KEY
if (!apiKey) throw new Error('Configura IRCG_IOS_API_KEY en el servidor')
const ios = new IOSClient({ apiKey, lang: 'es' })
// SDK
const { result, responses } = await ios.withResponseMetadata(context =>
ios.getAll({ fields: ['imageId'], amount: 10, page: 1, ascending: false }, context)
)
for (const { requestId, status, url } of responses) {
console.log({ requestId, status, url })
}
if (result.error) {
console.error(result.error.message, result.error.details?.requestId)
} else {
console.log(result.optimizedImages)
}
// REST
const query = new URLSearchParams({
fields: JSON.stringify(['imageId']),
amount: '10',
page: '1',
ascending: 'false'
})
const response = await fetch('https://ircg.dev/api/v1/images?' + query, {
headers: { Authorization: 'Bearer ' + apiKey, 'Accept-Language': 'es' }
})
const requestId = response.headers.get('X-IRCG-Request-ID')
console.log({ requestId, status: response.status, url: response.url })
if (!response.ok) {
const errorBody = await response.json().catch(() => null)
console.error(errorBody?.message ?? 'HTTP ' + response.status, requestId)
} else {
const body = await response.json()
console.log(body.optimizedImages)
}Con REST, lee X-IRCG-Request-ID en los encabezados de la respuesta. En cURL, --include muestra esos encabezados antes del cuerpo; busca allí esa cabecera.
Operaciones anidadas
Para agrupar operaciones anidadas, pasa { parentContext } como segundo argumento de withResponseMetadata en la operación hija, usando el contexto exterior. El padre conserva las capturas de la hija en orden de llegada, tanto en éxito como en error, incluso si capturas ese error dentro del callback. Espera a que terminen las hijas antes de devolver el resultado exterior. Sin ese vínculo explícito, las operaciones conservan sus propias capturas; compartir cliente o anidar callbacks no las vincula automáticamente.
Errores y concurrencia
error.responses es una copia de la lista observada cuando el scope rechaza, no una vista que se actualice con respuestas posteriores. Si un hermano sigue en vuelo al fallar Promise.all, su respuesta tardía no se añade a esa lista. Para incluir todas las respuestas, espera Promise.allSettled y lanza el error desde el padre después de que terminen todas las hijas. Otro scope que propague el error puede asignarle una nueva copia con lo observado al rechazar ese scope. El aviso de contexto sin uso no detecta una hija sin parentContext si el padre ya hizo una petición con su propio contexto; la ausencia de aviso no confirma que todas las hijas estén vinculadas.