Autenticación

Base URL, header de autenticación y cómo hacer tu primera request contra la API de Dardo

Todo lo que necesitás para hacer la primera request y saber que la credencial funciona.

Base URL

https://api.dardo.ai

Todos los recursos cuelgan de /api/v2/. Una URL completa se ve así:

https://api.dardo.ai/api/v2/profile

Elemento	Valor
Base URL	`https://api.dardo.ai`
Prefijo de todos los paths	`/api/v2/`
Versión de la API	`2.0.0`
Protocolo	HTTPS
`Content-Type` en requests con body	`application/json`

La API está disponible únicamente en el plan Business. Los planes Start y Grow no la incluyen. Si tu cuenta está en un plan inferior, el dashboard funciona normal pero los endpoints no te van a responder.

El header de autenticación

La API usa una clave estática en un header. No hay OAuth, no hay flujo de tokens, no hay Authorization: Bearer.

X-API-Key: <tu-clave>

Tu primera request

GET /api/v2/profile es el endpoint más liviano para verificar que la clave anda: es de solo lectura y devuelve los datos de la cuenta a la que pertenece la credencial.

curl -i https://api.dardo.ai/api/v2/profile \
  -H "X-API-Key: TU_CLAVE"

Respuesta esperada (200):

{
  "responseId": "0d4d1c1e-3f5a-4f0e-9b2a-2f5a7c9e1b44",
  "createdAt": "2026-09-07T16:37:46+00:00",
  "code": 200,
  "data": {
    "companyId": 1234,
    "name": "Mi Comercio",
    "userName": "Ana",
    "userSurname": "Pérez",
    "email": "ana@micomercio.com",
    "country": "AR",
    "timezone": "America/Argentina/Buenos_Aires",
    "currency": "ARS",
    "dateFormat": "d/m/Y"
  }
}

Ese envelope {responseId, createdAt, code, data} es el mismo en toda la API. Está explicado en Errores y códigos de respuesta.

Los ejemplos de código de la referencia se generan automáticamente desde el spec y no traen el header de autenticación. Es un detalle del generador, no del endpoint: si copiás un curl de cualquier página de la referencia tal cual, te va a devolver 401.

A todo pedido agregale -H "X-API-Key: TU_CLAVE" — salvo a los tres de Punto de venta, que usan otra credencial.

Si la autenticación falla

Comportamiento real de https://api.dardo.ai:

Situación	Status	Body
Sin header `X-API-Key`	`401`	`{"message":"Full authentication is required to access this resource."}`
Clave inexistente o revocada	`401`	`{"message":"API key is invalid"}`

Toda respuesta trae un header X-Request-ID. Logueálo siempre, incluso en las respuestas exitosas: es el dato que te vamos a pedir si abrís un ticket.

X-Request-ID: 706b3b4d9168037384a0aa93ddae6f94

Dónde se obtiene la clave

La clave se copia desde el panel, en Configuración → pestaña Integraciones. Está ahí con un botón para copiarla, junto al número de integraciones que incluye tu plan. El recorrido completo de esa pantalla está en Conectar servicios.

Esa clave es una contraseña. Da acceso programático a tu cuenta: a tus clientes, a sus saldos y a la posibilidad de acreditar transacciones. Guardala como secret del lado del servidor. Nunca en el frontend, nunca en un repositorio, nunca en un chat, un ticket o una captura.

Rotación

No hay documentado un vencimiento automático de la clave, y tampoco podemos afirmar que no lo tenga: no existe endpoint de renovación ni ningún campo de expiración en la API. En la práctica, la clave funciona hasta que se revoca.

Si necesitás rotarla —porque se filtró, porque se fue alguien del equipo, o simplemente por política— escribinos a soporte@dardo.ai y coordinamos el reemplazo antes de invalidar la vieja, para que la integración no se corte.

Si usás webhooks, la rotación te toca. La firma X-Signature de cada entrega se calcula con HMAC-SHA256 usando la clave de la cuenta que registró la suscripción, y cuando una cuenta tiene más de una clave se firma con la más vieja. Agregar o revocar claves puede mover la firma a otra clave y romper la verificación del lado receptor. Revisá tu verificación después de cualquier cambio.

Alcance de la clave

Esto importa si tu integración va a tocar sub-cuentas.

Lo que se puede afirmar mirando la API:

GET /api/v2/profile devuelve un companyId, y es su único campo obligatorio. La clave resuelve siempre a una cuenta concreta: no es una credencial global ni anónima.
GET /api/v2/companies lista las sub-cuentas, y cada una expone su propio campo apiKey. Es decir: existen claves a nivel cuenta y claves a nivel sub-cuenta, y una credencial de nivel superior puede leer las de abajo.
Hay dos superficies de perfil separadas: /api/v2/profile (la cuenta propia) y /api/v2/profile/agency.

Nivel de clave	Qué opera
Sub-cuenta	Los datos de esa cuenta: tarjetas, clientes, plantillas, operaciones, push
Cuenta principal	Lo anterior más la administración de sub-cuentas (`/api/v2/companies`, `/api/v2/profile/agency`)

La API no expone un sistema de permisos por clave. Todas las operaciones comparten el mismo esquema de autenticación, sin scopes ni claves de solo lectura. La separación de arriba viene del modelo de datos, no de un control configurable. Si necesitás acotar qué puede hacer una integración, la vía práctica hoy es usar una clave de sub-cuenta y no una de la cuenta principal.

Punto de venta usa otra credencial

Las tres operaciones del grupo Punto de venta no usan X-API-Key. Anulan explícitamente el esquema global y exigen otro header:

X-App-Token: <token-de-la-app>

Operación	Header requerido
`POST /api/v2/marketplace/resolve-credentials`	`X-App-Token`
`POST /api/v2/marketplace/accrue`	`X-App-Token`
`POST /api/v2/marketplace/reverse`	`X-App-Token`

Son dos credenciales distintas y no son intercambiables: tu clave de API no sirve para estos tres endpoints, y un App Token no sirve para el resto de la API.

Cómo se emite el App Token no está documentado. Si tu integración necesita estos endpoints —típicamente, un sistema de cobro externo acreditando y revirtiendo operaciones— escribinos a soporte@dardo.ai contando qué sistema vas a conectar y lo resolvemos con vos.

Checklist antes de integrar

La cuenta está en plan Business.
La clave está copiada desde Configuración → Integraciones.
La clave vive como secret del lado del servidor, nunca en el cliente.
GET /api/v2/profile devuelve 200 con el companyId esperado.
Tu cliente HTTP agrega X-API-Key a todos los pedidos.
Tu cliente HTTP loguea el X-Request-ID de cada respuesta.