Conceptos previos
Credencial, scopes, identificadores, idempotencia y errores. Lo mínimo que conviene saber antes de la primera llamada a la API de partners de SLAN.
La API de partners vive bajo https://api.slan.mx/v1/partner y es de servidor a servidor.
No está pensada para llamarse desde el navegador ni desde una aplicación móvil: tu credencial
tiene permisos sobre todos tus usuarios finales, y cualquiera que abra el código de una página
puede leerla.
Estas siete ideas aparecen en todos los endpoints. Vale la pena leerlas una vez antes de escribir código.
Credencial
Toda llamada lleva la cabecera x-api-key con un secreto que empieza por slan_.
La emite SLAN, se entrega por un canal seguro y se muestra una sola vez: no se puede recuperar, solo rotar. Vence a los 365 días. Lee Credenciales para el detalle.
Scopes
Cada endpoint exige el suyo — users:write, payment-links:read, etc. Si tu llave no lo
tiene, recibes 403 aunque la llave sea válida y esté vigente.
Los scopes salen de un catálogo cerrado. Pedir uno nuevo no es un cambio de configuración de nuestro lado: hay que añadirlo al catálogo, así que conviene pedir de entrada los que vas a necesitar.
Identificadores
Todo entra y sale por publicId, un ULID de 26 caracteres:
01JKX7MNDR0000000000000037Los enteros internos no salen nunca de la API. Son un detalle de implementación y podrían cambiar.
Para reconciliar contra tu propia base de datos usa externalRef al dar de alta un usuario:
lo guardas tú, lo guardamos nosotros, y te ahorra mantener una tabla de equivalencias.
Idempotencia
Los POST exigen la cabecera Idempotency-Key. Misma clave y mismo cuerpo devuelven la
respuesta original en lugar de crear un segundo recurso; misma clave con otro cuerpo
devuelve 422.
Es lo que hace seguro reintentar cuando se cae la red a mitad de una petición. Está explicado con casos en Idempotencia.
Recursos de otros partners
Un publicId que existe pero pertenece a otro partner responde 404, nunca 403.
No es un descuido: un 403 confirmaría que ese identificador existe. Con un 404 no se puede distinguir «no existe» de «no es tuyo», que es justo lo que queremos.
Errores
Todos los errores siguen RFC 9457 con el tipo de
contenido application/problem+json, y traen un campo code estable.
Programa contra code, nunca contra detail ni contra el texto del mensaje. La redacción
puede cambiar sin previo aviso; el code no. Lee Errores.
Paginación
Los listados paginan por cursor sobre publicId, no por número de página:
GET /v1/partner/users?limit=20&cursor=01JKX7MNDR0000000000000037La respuesta trae { items, nextCursor }. Cuando nextCursor viene en null, esa era la
última página. El máximo por página es 100. Lee Paginación.