API de administración para distribuidores (7.0)

Download OpenAPI specification:Download

INTRODUCCION

No es una API pública: está limitada a distribución. Solo la pueden usar los distribuidores corporativos (empresas con su CIF) que se hayan validado antes. Para validarse, pídala a soporte: comprobamos los datos de la empresa y, si todo está bien, se la activamos. Mientras no esté activada en su cuenta, cualquier llamada contesta -2. Cómo pedirla, en Activación y seguridad.

Con esta API un distribuidor gestiona desde su propio programa a sus usuarios (las cuentas que cuelgan de la suya), lo mismo que hace a mano en Usuarios Distribución:



- Dar de alta usuarios nuevos. Cada uno recibe un correo de bienvenida con la marca del distribuidor, desde su dominio de correo, con un enlace para elegir su contraseña.
- Cambiar sus datos: nombre, empresa, identificador fiscal (NIF/CIF), país y teléfono.
- Darles y quitarles créditos.
- Validar sus remitentes: un número de teléfono (con un código que recibe ese número) o un dominio de correo (con unos registros en su DNS).
- Consultar la lista de sus usuarios, sus remitentes y sus dominios de correo.
- Enviar en nombre de sus usuarios con sus propias claves, con el permiso de cada uno (ver Enviar en nombre de sus usuarios).
- Confirmar el correo de sus usuarios y dejarles puestos, al darlos de alta, los datos de certificación y contratación.
- Ceder a sus usuarios sus propios remitentes (alias de SMS y números) para los envíos que hace en su nombre.



Solo actúa sobre los usuarios del distribuidor que hace la llamada: con el identificador de un usuario de otra cuenta, la respuesta es -5.

ACTIVACION Y SEGURIDAD


1. Solo empresas. Está disponible únicamente para distribuidores corporativos: la cuenta tiene que ser de una empresa, con su razón social y su CIF en Sus datos. No se activa a particulares.
2. Hay que validarse antes de usarla. La API no está abierta para ninguna cuenta hasta que soporte la activa. Pídala desde Soporte indicando las direcciones IP públicas desde las que llamará su servidor (una o varias, o una red pequeña). Soporte comprueba los datos de la empresa y, si están bien, la activa para esas direcciones. Desde cualquier otra dirección, o mientras no esté activada, la respuesta es -2, aunque el usuario y la clave sean buenos.
3. Solo el titular de la cuenta, con el usuario y el API Token de la cuenta principal. Un usuario autorizado (subcuenta) o la clave de una conexión con una herramienta de automatización no pueden usarla.
4. Siempre por HTTPS y en POST. Una petición GET se rechaza: los datos de sus clientes no viajan nunca en la dirección.
5. Todo queda registrado: cada llamada, buena o rechazada, con la dirección IP desde la que llegó.

AUTENTICACION

Igual que el resto de nuestras APIs: autenticación Basic con su usuario API y su API Token, que encontrará en su panel en Sus datos → Configurar → Seguridad.



Debe incluir en cada petición la cabecera Authorization: Basic Base64StringAPI, donde Base64StringAPI es la cadena UsuarioAPI:APIToken codificada en Base64. Casi todas las librerías lo hacen solas si les da el usuario y la clave.

ENVIAR EN NOMBRE DE SUS USUARIOS

Puede enviar y consultar en nombre de uno de sus usuarios con sus propias credenciales, sin conocer las de ese usuario: llame a las funciones de envío y consulta de siempre (las de nuestras demás APIs) con su usuario API y su API Token, y añada el parámetro ENNOMBREDE con el número del usuario (o la cabecera X-En-Nombre-De).



- La petición se atiende como si la hiciera el usuario: se cobra de su saldo, con sus remitentes, su lista de bajas y sus límites, y queda entre sus envíos. Si el envío lo paga usted, pásele antes los créditos con DistribuidorCreditos.
- Hace falta el permiso del usuario. Los usuarios que crea por esta API lo traen de serie (el correo de bienvenida se lo explica). A los demás se lo puede pedir con DistribuidorUsuarios (ACCION=PEDIR_PERMISO): le llega un correo con su marca y lo da con un botón. El usuario puede darlo o quitarlo cuando quiera en su panel (Configuración > Seguridad), donde ve también lo que usted ha hecho en su nombre. Sin permiso, la respuesta es -2.
- Valen las mismas reglas que en esta API: solo el titular, desde sus direcciones IP autorizadas y solo con sus usuarios (con otro, -5). Si el usuario está de baja o bloqueado, -2.
- Puede enviar con un remitente suyo (su alias o su número) si se lo ha cedido con DistribuidorRemitentesCedidos. Solo vale en estas peticiones: el usuario no puede usarlo por su cuenta.
- Se admite en las funciones de envío (SMS, SMS certificado, RCS, WhatsApp, correo, correo certificado, voz, omnicanal, códigos OTP, contratos y verificación de identidad), en sus cancelaciones y cambios de fecha, en los informes y resultados, en las plantillas y en la consulta de saldo. No en esta API de distribuidores ni en las integraciones.
- Sin ENNOMBREDE, todo funciona como siempre: la petición es suya.

LIMITES

LímiteCuánto
Usuarios en su cuentaUno por cada 10 € que haya comprado (por ejemplo, con 300 € comprados puede tener 30 usuarios). Cuentan todos sus usuarios, los creados en el panel y los creados por la API. La lista de usuarios le dice cuántos tiene y cuántos puede tener.
Altas al día20 usuarios nuevos en 24 horas.
Códigos para validar números50 en 24 horas. Y como mucho 3 códigos en una hora a un mismo número.
Peticiones60 por minuto, sumando todas las funciones.
Correos a sus usuarios (confirmar su correo o pedirles permiso)Cuentan dentro de los 50 códigos del día. Como mucho 3 en una hora a un mismo correo y, para pedir permiso, 2 veces al día a un mismo usuario.
Peticiones en nombre de sus usuarios600 por minuto.


Si necesita más, pídalo a soporte: estos límites se pueden ampliar cuenta a cuenta.

QUE SE COBRA


- El correo de bienvenida de cada usuario nuevo se cobra en créditos a su cuenta, como cualquier correo. Sin créditos para ese correo no se crea el usuario.
- El código para validar un número se cobra a su cuenta como un SMS (o como una llamada, si el número es un fijo).
- Pasar créditos a un usuario no cuesta nada: salen de su saldo y entran en el suyo.
- Los correos a sus usuarios para confirmar su correo o pedirles permiso se cobran a su cuenta como un correo.
- Lo que envía en nombre de un usuario se cobra al usuario, de su saldo, como si lo enviara él.

FORMATO DE LA RESPUESTA

Por defecto, en JSON. Con el parámetro RESP puede pedirla en TXT o XML.



Puede enviar los parámetros como formulario o como un cuerpo JSON (Content-Type: application/json). Los nombres de los parámetros no distinguen mayúsculas.



Toda respuesta trae Res. Si es negativo, Error explica el motivo, en español:

ResQué quiere decir
1Hecho.
-1Usuario API o API Token incorrectos.
-2No autorizado: su cuenta no está validada para esta API (no se la hemos activado), la petición llega desde una IP que no está en su lista, no es el titular o la cuenta está de baja. En una petición en nombre de un usuario, también: ese usuario no le ha dado permiso, está de baja o bloqueado, o la función no lo admite.
-3Falta un parámetro o no vale. Error dice cuál.
-4Demasiadas peticiones, o hay otra operación igual en curso. Espere unos segundos y repita.
-5Ese usuario no existe o no es suyo.
-6Ha llegado al límite de usuarios de su cuenta o al de altas del día.
-7No tiene un dominio de correo validado para escribir a sus usuarios (el correo de bienvenida, el de confirmar su correo o el de pedirles permiso), o no tiene créditos para enviarlo.
-8Usted no tiene créditos suficientes.
-9El usuario no tiene tantos créditos para quitarle, o tiene demasiado saldo en negativo (lo revisa soporte).
-10Ese correo ya tiene una cuenta.
-11El identificador fiscal no se puede poner: la Agencia Tributaria no lo hace corresponder con la empresa o el nombre, o se ha cambiado demasiadas veces.
-12No se ha podido enviar el correo de bienvenida, así que el usuario no se ha creado. Inténtelo más tarde.
-13Código de validación (de un número o de un correo) incorrecto, caducado o sin pedir.
-14Límite de códigos o de correos: por número o correo y hora, o del día.
-15El número no es válido, es de un país no admitido o no se puede quitar.
-16Ese dominio no se puede usar: es de otra cuenta, el usuario ya tiene su dominio o no se ha solicitado antes.
-17Ese remitente no se puede ceder o retirar: no es suyo ahora mismo o no estaba cedido así.
-20Error interno. Soporte ya está avisado; inténtelo de nuevo más tarde.

Lista de usuarios

/DistribuidorUsuarios

Sin IDUSUARIO, devuelve la lista de sus usuarios, de 100 en 100 (PAGINA para las siguientes), y su límite: cuántos usuarios tiene y cuántos puede tener. Puede buscar uno por su correo (EMAIL) o por su identificador fiscal (CIF), escritos enteros.

Con IDUSUARIO, devuelve ese usuario con los remitentes que puede usar ahora mismo y sus dominios de correo (los validados y los que están en proceso). También dice si su correo está confirmado (CorreoVerificado), si le ha dado permiso para enviar en su nombre (EnvioEnNombre) y sus datos de certificación y contratación (DatosCertificacion, o null si no tiene).

Acciones sobre ese usuario, con ACCION. Las que le escriben lo hacen desde un dominio de correo suyo, validado, con su marca, y se cobran a su cuenta como un correo:
- ENVIAR_CODIGO_CORREO: le manda un correo para confirmar que es suyo, con un botón (lo confirma él, sin entrar en el panel) y un código de 6 cifras que vale 10 minutos, por si se lo dicta a usted. Si ya está confirmado, no se manda nada.
- VALIDAR_CORREO con CODIGO: comprueba ese código. Hay tres intentos; después, hay que pedir otro.
- PEDIR_PERMISO: le pide permiso para enviar en su nombre (ver Enviar en nombre de sus usuarios). Lo da él con un botón. Si ya lo ha dado, no se manda nada.

Con el correo confirmado le corresponden solos los alias de la CNMC de su dominio. El correo también queda confirmado cuando el usuario elige su contraseña con el enlace del correo de bienvenida.

Authorizations:
basicAuth
query Parameters
Idusuario
integer
Example: Idusuario=97801

Número de uno de sus usuarios. Opcional: sin él, la lista.

Email
string
Example: Email=cliente@ejemplo.es

Busca el usuario con este correo, escrito entero. No distingue mayúsculas.

Cif
string
Example: Cif=B12345674

Busca los usuarios con este identificador fiscal, escrito entero. Da igual si lleva guiones o espacios.

Pagina
integer
Example: Pagina=1

Página de la lista, de 100 usuarios cada una. Por defecto, la 1.

Accion
string
Example: Accion=ENVIAR_CODIGO_CORREO

Opcional, con IDUSUARIO. Sin ella, la lista o el usuario.
ENVIAR_CODIGO_CORREO - Le manda un correo para confirmar su correo, con un botón y un código
VALIDAR_CORREO - Comprueba el CODIGO que le ha llegado
PEDIR_PERMISO - Le pide permiso para enviar en su nombre

Codigo
string
Example: Codigo=482913

Con ACCION=VALIDAR_CORREO: el código de 6 cifras que le ha llegado al usuario.

Resp
string
Example: Resp=JSON

Formato de la respuesta.
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Request Body schema:

Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.

Idusuario
integer
Email
string
Cif
string
Pagina
integer
Accion
string
Codigo
string
Resp
string

Responses

Response Schema: application/json
Res
required
integer <int32>

Resultado. Los códigos están en la introducción.

Total
integer

En la lista: cuántos usuarios cumplen la búsqueda.

Pagina
integer

En la lista: la página devuelta.

PorPagina
integer

En la lista: usuarios por página.

Usuarios
Array of arrays

En la lista: sus usuarios. De cada uno: IdUsuario, Nombre, Apellidos, Empresa, CIF, Email, Pais (prefijo telefónico), Telefono, FechaAlta, Creditos y Baja (1 si está de baja).

Limite
object

En la lista: Maximo, cuántos usuarios puede tener; Actuales, cuántos tiene; EurosPorUsuario, cuántos euros comprados da derecho a un usuario.

Usuario
object

Con IDUSUARIO: ese usuario, con los mismos datos que en la lista.

Remitentes
object

Con IDUSUARIO: los remitentes que puede usar ahora mismo. AliasSMS y AliasRCS, los nombres (alias) inscritos en el Registro de Alias de la CNMC que le corresponden; Numericos, sus números validados; RemitenteDefecto, el que se usa cuando un envío no indica remitente.

DominiosEmail
object

Con IDUSUARIO: sus dominios de correo. Validados (con Estado y Premium) y EnProceso (con Estado y Paso).

CorreoVerificado
integer

Con IDUSUARIO: 1 si el usuario ha confirmado que su correo es suyo.

EnvioEnNombre
integer

1 si le ha dado permiso para enviar en su nombre.

DatosCertificacion
object

Con IDUSUARIO: sus datos de certificación y contratación (Logo es 1 si tiene logo), o null si no tiene.

Verificado
integer

En ENVIAR_CODIGO_CORREO y VALIDAR_CORREO: 1 si el correo ya está confirmado.

Correo
string

En las acciones: el correo del usuario al que se ha escrito o que se ha confirmado.

Coste
number

En las acciones que escriben al usuario: créditos cobrados a su cuenta por el correo.

CaducaMinutos
integer

En ENVIAR_CODIGO_CORREO: minutos que vale el código.

Restan
integer

En VALIDAR_CORREO, con un código incorrecto: intentos que quedan.

Mensaje
string

En las acciones: qué se ha hecho.

Error
string

El motivo, cuando Res es negativo.

Request samples

Content type
Example
{
  • "Pagina": 1
}

Response samples

Content type
application/json
Example
{
  • "Res": 1,
  • "Total": 2,
  • "Pagina": 1,
  • "PorPagina": 100,
  • "Usuarios": [
    ],
  • "Limite": {
    }
}

Crear un usuario

/DistribuidorCrearUsuario

Da de alta un usuario de su cuenta. El usuario entra en el panel con su correo y recibe enseguida un correo de bienvenida con un enlace para elegir su contraseña (vale 7 días y sirve una vez). Nadie más conoce su contraseña, tampoco usted.

El correo sale desde un dominio de correo suyo, validado en su cuenta (Estándar o Premium), con el nombre de su empresa. Si tiene varios, elija cuál con DOMINIOEMAIL. Sin dominio validado no se puede crear usuarios por la API (-7): puede darlo de alta en su panel, en Configuración > Email.

El usuario se crea entero o no se crea: si el correo de bienvenida no se puede enviar, no queda ninguna cuenta a medias (-12) y puede repetir la llamada.

Identificador fiscal. Si es español, se comprueba con la Agencia Tributaria: el de una empresa (CIF) tiene que corresponder a la razón social que ponga en EMPRESA; el de una persona (NIF o NIE), a su nombre y apellidos. Si no corresponde, no se crea el usuario (-11). Es opcional: puede crearlo sin él y ponerlo después.

Hay un máximo de usuarios según lo que haya comprado y un máximo de altas al día: están en Límites. No se admiten correos de usar y tirar.

Permiso para enviar en su nombre. Los usuarios creados por la API le dan permiso de serie para enviar en su nombre (EnvioEnNombre); el correo de bienvenida se lo explica y le dice cómo quitarlo. Ese correo lleva también un enlace para que confirme su correo sin entrar en el panel.

Datos de certificación y contratación. Son los que salen en los certificados y los contratos que envíe el usuario, y se crean con el alta: la empresa y el identificador fiscal son los de la cuenta (el CIF, ya comprobado con la Agencia Tributaria); el teléfono y el correo de contacto, los que indique en CERT_TELEFONO y CERT_EMAIL (si no, los de la cuenta), y el logo, si lo indica en CERT_LOGO. Después los cambia el propio usuario en su panel: por la API solo se pueden poner si no tiene ninguno (ver DistribuidorModificarUsuario).

Authorizations:
basicAuth
query Parameters
Email
required
string
Example: Email=ana@talleresperez.es

Correo del usuario. Es con lo que entrará en el panel y adonde llega el correo de bienvenida. Obligatorio. No puede tener ya una cuenta.

Nombre
string
Example: Nombre=Ana

Nombre. El nombre o los apellidos tienen que venir (al menos dos letras).

Apellidos
string
Example: Apellidos=Pérez Gil

Apellidos.

Empresa
string
Example: Empresa=Talleres Pérez SL

Razón social de la empresa. Si pone un CIF español, tiene que ser la que figura en la Agencia Tributaria.

Cif
string
Example: Cif=B12345674

Identificador fiscal: NIF, NIE o CIF español, o el VAT de otro país de la UE. Fuera de España (otro PAIS), el identificador de ese país. Opcional.

Pais
string
Example: Pais=34

Prefijo telefónico del país del usuario, sin el signo +. Por defecto, 34 (España).

Telefono
string
Example: Telefono=600111222

Teléfono de contacto, de 6 a 15 cifras. Opcional. No lo convierte en remitente: para eso, DistribuidorRemitenteMovil.

Dominioemail
string
Example: Dominioemail=midistribuidora.es

Dominio de correo suyo, validado en su cuenta, desde el que sale el correo de bienvenida. Opcional: si no lo indica, uno de los que tenga validados.

Remitentedefecto
string
Example: Remitentedefecto=TALLERPEREZ

Solo para los distribuidores que responden ellos mismos de los alias de sus clientes ante la CNMC (si no es su caso, se ignora). Remitente por defecto del usuario: un alias de hasta 11 letras o números, o un número de teléfono.

Cert_telefono
string
Example: Cert_telefono=+34 911234567

Teléfono de contacto que sale en sus certificados y contratos, de 6 a 15 cifras. Opcional: si no, el de la cuenta.

Cert_email
string
Example: Cert_email=administracion@talleresperez.es

Correo de contacto que sale en sus certificados y contratos. Opcional: si no, el de la cuenta.

Cert_logo
string
Example: Cert_logo=https://www.talleresperez.es/logo.png

Dirección https de su logo para los certificados y contratos: una imagen PNG o JPG de hasta 300 KB y 2000 × 2000 píxeles. Se descarga y se guarda; si no se puede, el usuario se crea igual y Aviso lo dice. Opcional.

Resp
string
Example: Resp=JSON

Formato de la respuesta.
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Request Body schema:

Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.

Email
required
string
Nombre
string
Apellidos
string
Empresa
string
Cif
string
Pais
string
Telefono
string
Dominioemail
string
Remitentedefecto
string
Cert_telefono
string
Cert_email
string
Cert_logo
string
Resp
string

Responses

Response Schema: application/json
Res
required
integer <int32>

Resultado. Los códigos están en la introducción.

IdUsuario
integer

Número del usuario creado. Es el que se usa en las demás funciones.

Usuario
object

Los datos del usuario tal como han quedado (el nombre con mayúsculas iniciales, el correo en minúsculas, el CIF sin guiones).

CorreoBienvenida
string

Dominio desde el que ha salido el correo de bienvenida.

Maximo
integer

Cuántos usuarios puede tener.

Actuales
integer

Cuántos tiene ahora.

EnvioEnNombre
integer

1: puede enviar en nombre de este usuario (ver Enviar en nombre de sus usuarios).

DatosCertificacion
object

Sus datos de certificación y contratación tal como han quedado (Logo es 1 si tiene logo).

Aviso
string

Si algo de los datos de certificación no se ha podido poner (el logo, por ejemplo): qué ha pasado. El usuario está creado.

Error
string

El motivo, cuando Res es negativo.

Request samples

Content type
Example
{
  • "Email": "ana@talleresperez.es",
  • "Nombre": "Ana",
  • "Apellidos": "Pérez Gil",
  • "Empresa": "Talleres Pérez SL",
  • "CIF": "B12345674",
  • "Telefono": "600111222"
}

Response samples

Content type
application/json
Example
{
  • "Res": 1,
  • "IdUsuario": 97801,
  • "Usuario": {
    },
  • "CorreoBienvenida": "midistribuidora.es",
  • "Maximo": 30,
  • "Actuales": 3,
  • "EnvioEnNombre": 1,
  • "DatosCertificacion": {
    }
}

Cambiar los datos de un usuario

/DistribuidorModificarUsuario

Cambia los datos de uno de sus usuarios. Envíe solo lo que cambia; lo que no envíe se queda como está. Para dejar un dato vacío, envíelo vacío.

Todo o nada. Si el identificador fiscal no se puede poner, no se guarda ningún cambio de esa llamada.

Identificador fiscal. Uno español se comprueba con la Agencia Tributaria contra la empresa o el nombre de esa misma llamada: si cambian a la vez la razón social y el CIF, envíe los dos juntos. Hay un tope de cambios de identificador fiscal por usuario (dos cada 30 días y cinco intentos al día). Al cambiarlo, el usuario deja de poder usar los alias de la CNMC que dependían del anterior: lo explica Aviso y le llega a usted un correo con el detalle.

El correo del usuario no se cambia por la API: es con lo que entra en el panel y por donde recupera su contraseña. Lo cambia el propio usuario en Sus datos.

Datos de certificación y contratación (CERT_TELEFONO, CERT_EMAIL, CERT_LOGO): solo se ponen si el usuario no tiene ninguno (le faltan la empresa o el identificador fiscal). La empresa y el identificador fiscal son los de su cuenta, con los cambios de esa misma llamada; si ya tenía algo (su logo, por ejemplo), se respeta y solo se rellena lo que falta. Si ya tiene datos, la respuesta es -3: los cambia el propio usuario en su panel. Si en la misma llamada cambian también datos de la cuenta, esos se guardan igual y Aviso dice por qué no los de certificación.

Authorizations:
basicAuth
query Parameters
Idusuario
required
integer
Example: Idusuario=97801

Número de uno de sus usuarios. Obligatorio.

Nombre
string
Example: Nombre=Ana

Nombre nuevo.

Apellidos
string
Example: Apellidos=Pérez Gil

Apellidos nuevos.

Empresa
string
Example: Empresa=Talleres Pérez e Hijos SL

Razón social nueva.

Cif
string
Example: Cif=B12345674

Identificador fiscal nuevo. Si es el mismo escrito de otra forma (con guiones, en minúsculas), solo se guarda bien escrito.

Pais
string
Example: Pais=34

Prefijo telefónico del país, sin el signo +.

Telefono
string
Example: Telefono=611222333

Teléfono de contacto, de 6 a 15 cifras.

Remitentedefecto
string
Example: Remitentedefecto=TALLERPEREZ

Solo para los distribuidores que responden ellos mismos de los alias de sus clientes ante la CNMC (si no es su caso, se ignora). Alias de hasta 11 letras o números, o un número de teléfono.

Cert_telefono
string
Example: Cert_telefono=+34 911234567

Solo si no tiene datos de certificación: teléfono de contacto de sus certificados y contratos. Si no, el de la cuenta.

Cert_email
string
Example: Cert_email=administracion@talleresperez.es

Solo si no tiene datos de certificación: correo de contacto de sus certificados y contratos. Si no, el de la cuenta.

Cert_logo
string
Example: Cert_logo=https://www.talleresperez.es/logo.png

Solo si no tiene datos de certificación ni logo: dirección https de su logo, PNG o JPG de hasta 300 KB y 2000 × 2000 píxeles.

Email
string
Example: Email=

No se admite: si lo envía, la respuesta es -3 y no se cambia nada.

Resp
string
Example: Resp=JSON

Formato de la respuesta.
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Request Body schema:

Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.

Idusuario
required
integer
Nombre
string
Apellidos
string
Empresa
string
Cif
string
Pais
string
Telefono
string
Remitentedefecto
string
Cert_telefono
string
Cert_email
string
Cert_logo
string
Email
string
Resp
string

Responses

Response Schema: application/json
Res
required
integer <int32>

Resultado. Los códigos están en la introducción.

Usuario
object

Los datos del usuario tal como han quedado.

Aviso
string

Si al cambiar el identificador fiscal han cambiado los alias que puede usar el usuario, o si los datos de certificación no se han podido poner del todo: qué ha pasado.

DatosCertificacion
object

Con CERT_*: sus datos de certificación y contratación tal como han quedado (Logo es 1 si tiene logo).

Error
string

El motivo, cuando Res es negativo.

Request samples

Content type
Example
{
  • "IdUsuario": 97801,
  • "Empresa": "Talleres Pérez e Hijos SL",
  • "CIF": "B12345674"
}

Response samples

Content type
application/json
Example
{
  • "Res": 1,
  • "Usuario": {
    }
}

Dar o quitar créditos

/DistribuidorCreditos

Pasa créditos de su cuenta a uno de sus usuarios (DAR) o se los devuelve de ese usuario a usted (QUITAR).

- Nunca más de los que hay. Si usted no tiene los que quiere dar, o el usuario no tiene los que le quiere quitar, no se mueve nada: no se reparte lo que haya. La respuesta lo dice (-8 o -9) y trae el saldo que hay.
- Solo con sus usuarios. Con el de otra cuenta, -5.
- A un usuario con más de 100 créditos en negativo no se le pueden dar: lo revisa soporte, que ya queda avisado.
- Dos llamadas a la vez no pueden gastar dos veces el mismo saldo.

Reintentos sin duplicados. Si su programa no recibe la respuesta (un corte, un tiempo de espera agotado), no sabe si los créditos se movieron. Envíe con cada operación una REFERENCIA suya (por ejemplo, el número del pedido): si repite la llamada con la misma, no se mueve nada otra vez y la respuesta es la de la primera, con "Repetida":1. Si la primera no llegó a hacerse (respuesta negativa), la referencia queda libre y puede repetirla.

Authorizations:
basicAuth
query Parameters
Idusuario
required
integer
Example: Idusuario=97801

Número de uno de sus usuarios. Obligatorio.

Operacion
required
string
Example: Operacion=DAR

Obligatorio.
DAR - De su cuenta al usuario
QUITAR - Del usuario a su cuenta

Creditos
required
string
Example: Creditos=150

Cuántos créditos. Mayor que 0, con dos decimales como mucho (punto o coma): 150, 12.50. Obligatorio.

Referencia
string
Example: Referencia=PEDIDO-2026-0412

Un identificador suyo de esta operación, para que un reintento no la repita. Opcional pero recomendado. Hasta 64 letras y números; también valen . _ - :. Distingue mayúsculas.

Resp
string
Example: Resp=JSON

Formato de la respuesta.
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Request Body schema:

Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.

Idusuario
required
integer
Operacion
required
string
Creditos
required
string
Referencia
string
Resp
string

Responses

Response Schema: application/json
Res
required
integer <int32>

Resultado. Los códigos están en la introducción.

Operacion
string

La operación hecha.

Creditos
number

Los créditos movidos.

CreditosDistribuidor
number

Su saldo después de la operación (o el que tiene, si no ha podido dar).

CreditosUsuario
number

El saldo del usuario después de la operación (o el que tiene, si no se le ha podido quitar).

IdUsuario
integer

El usuario.

Referencia
string

La referencia que envió.

Repetida
integer

Llega, con valor 1, cuando esa referencia ya se había hecho: no se ha movido nada y la respuesta es la de entonces.

Error
string

El motivo, cuando Res es negativo.

Request samples

Content type
{
  • "IdUsuario": 97801,
  • "Operacion": "DAR",
  • "Creditos": "150",
  • "Referencia": "PEDIDO-2026-0412"
}

Response samples

Content type
application/json
Example
{
  • "Res": 1,
  • "Operacion": "DAR",
  • "Creditos": 150,
  • "CreditosDistribuidor": 850,
  • "CreditosUsuario": 150,
  • "IdUsuario": 97801,
  • "Referencia": "PEDIDO-2026-0412"
}

Validar números de teléfono

/DistribuidorRemitenteMovil

Valida un número de teléfono como remitente de uno de sus usuarios, o se lo quita. Un número solo se valida con prueba de que es suyo: recibe un código y hay que devolverlo.

Cómo se valida un número:
1. ACCION=ENVIAR_CODIGO con el número. Le llega un código de 6 cifras por SMS (si es un fijo español, por una llamada que se lo dicta; las llamadas, de 9:00 a 22:00). Se cobra a su cuenta.
2. Su cliente le dice el código.
3. ACCION=VALIDAR con el mismo número y el CODIGO. Desde ese momento el usuario puede enviar con ese número.

El código caduca a los 10 minutos y admite 3 intentos; después hay que pedir otro. Vale solo para ese usuario y ese número.

ACCION=LISTAR devuelve los remitentes que el usuario puede usar ahora mismo, y ACCION=BORRAR le quita un número. Los números contratados con la plataforma (de voz o para recibir respuestas) no se quitan aquí: dejan de ser remitentes al darlos de baja.

Por la API se validan números de España (34), Portugal (351), Andorra (376), Francia (33), Italia (39), Alemania (49), Reino Unido (44), Suiza (41), Bélgica (32), Países Bajos (31), Irlanda (353) y Austria (43). Para otro país, escríbanos desde Soporte.

Los nombres de remitente (alias, como TALLERPEREZ) no se validan aquí: dependen del Registro de Alias de la CNMC. Para que sus usuarios usen los suyos en lo que usted envía en su nombre, DistribuidorRemitentesCedidos.

Authorizations:
basicAuth
query Parameters
Idusuario
required
integer
Example: Idusuario=97801

Número de uno de sus usuarios. Obligatorio.

Accion
required
string
Example: Accion=ENVIAR_CODIGO

Obligatorio.
LISTAR - Los remitentes que puede usar ahora mismo
ENVIAR_CODIGO - Manda el código al número
VALIDAR - Comprueba el código y da de alta el número
BORRAR - Le quita el número

Prefijo
string
Example: Prefijo=34

Prefijo del país del número, sin el signo +. Por defecto, 34.

Numero
string
Example: Numero=600111222

El número, sin el prefijo (si lo lleva delante, también vale). Obligatorio salvo en LISTAR.

Codigo
string
Example: Codigo=482913

En VALIDAR: el código de 6 cifras que ha recibido el número.

Extension
string
Example: Extension=214

En ENVIAR_CODIGO a un fijo con centralita: la extensión a la que pasar la llamada.

Resp
string
Example: Resp=JSON

Formato de la respuesta.
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Request Body schema:

Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.

Idusuario
required
integer
Accion
required
string
Prefijo
string
Numero
string
Codigo
string
Extension
string
Resp
string

Responses

Response Schema: application/json
Res
required
integer <int32>

Resultado. Los códigos están en la introducción.

Numero
string

El número completo, con el prefijo.

Canal
string

En ENVIAR_CODIGO: SMS o VOZ (llamada).

Coste
number

En ENVIAR_CODIGO: créditos que ha costado.

CaducaMinutos
integer

En ENVIAR_CODIGO: minutos que vale el código.

YaValidado
integer

En ENVIAR_CODIGO: 1 si el número ya era remitente del usuario (no se manda nada ni se cobra).

Nuevo
integer

En VALIDAR: 1 si el número se ha dado de alta ahora; 0 si ya lo estaba.

Restan
integer

En VALIDAR con un código incorrecto: intentos que quedan.

EraDefecto
integer

En BORRAR: 1 si era su remitente por defecto (deja de serlo).

AliasSMS
Array of arrays

En LISTAR: alias para SMS.

AliasRCS
Array of arrays

En LISTAR: alias para RCS.

Numericos
Array of arrays

En LISTAR: números validados.

RemitenteDefecto
string

En LISTAR: el remitente por defecto.

Mensaje
string

Qué ha pasado, para enseñarlo si quiere.

Error
string

El motivo, cuando Res es negativo.

Request samples

Content type
Example
{
  • "IdUsuario": 97801,
  • "Accion": "ENVIAR_CODIGO",
  • "Prefijo": "34",
  • "Numero": "600111222"
}

Response samples

Content type
application/json
Example
{
  • "Res": 1,
  • "Canal": "SMS",
  • "Numero": "34600111222",
  • "Coste": 1,
  • "CaducaMinutos": 10,
  • "Mensaje": "Le hemos enviado el código por SMS."
}

Validar dominios de correo

/DistribuidorRemitenteEmail

Valida el dominio de correo de uno de sus usuarios (por ejemplo talleresperez.es) para que pueda enviar correos desde él. Solo se valida con prueba de que el dominio es suyo: unos registros en el DNS del dominio que pone quien lo administra.

Paso a paso:
1. ACCION=SOLICITAR con el dominio. La respuesta trae en Registros un registro TXT para demostrar que el dominio es suyo.
2. Se pone ese registro en el DNS del dominio, tal cual, y se llama a ACCION=COMPROBAR.
3. Cuando el TXT está bien, la respuesta trae los registros de firma de los correos (DKIM, tres CNAME), el de rebotes (un CNAME en mail.) y los recomendados de SPF y DMARC. Se ponen en el DNS y se vuelve a llamar a COMPROBAR.
4. Con todo bien puesto, la verificación tarda entre 5 y 30 minutos: mientras, COMPROBAR contesta PENDIENTE_VERIFICACION. Cuando contesta ACTIVO, el usuario ya puede enviar desde su dominio.

Llame a COMPROBAR las veces que haga falta: cada vez dice en qué paso está (Estado), qué registros hay que poner y, si falta alguno, cuál (Errores). Los cambios de DNS pueden tardar en verse, a veces horas. Copie siempre el nombre y el valor de cada registro de la respuesta.

Cada usuario puede tener un dominio de este tipo (Estándar). Un dominio validado en otra cuenta no se puede pedir. Los dominios Premium se dan de alta con soporte.

Authorizations:
basicAuth
query Parameters
Idusuario
required
integer
Example: Idusuario=97801

Número de uno de sus usuarios. Obligatorio.

Accion
required
string
Example: Accion=SOLICITAR

Obligatorio.
LISTAR - Sus dominios validados y en proceso
SOLICITAR - Empieza la validación de un dominio
COMPROBAR - Mira el DNS y avanza todo lo que se pueda

Dominio
string
Example: Dominio=talleresperez.es

El dominio, sin www ni https://. Hasta 35 caracteres. Obligatorio salvo en LISTAR.

Resp
string
Example: Resp=JSON

Formato de la respuesta.
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Request Body schema:

Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.

Idusuario
required
integer
Accion
required
string
Dominio
string
Resp
string

Responses

Response Schema: application/json
Res
required
integer <int32>

Resultado. Los códigos están en la introducción. Un dominio que aún no está listo no es un error: Res es 1 y Estado dice qué falta.

Dominio
string

El dominio.

Estado
string

En qué paso está:

PENDIENTE_PROPIEDADFalta el registro TXT que demuestra que el dominio es suyo.
PENDIENTE_DNSFaltan los registros de firma (DKIM) o de rebotes.
PENDIENTE_VERIFICACIONLos registros están bien; falta que termine la verificación (de 5 a 30 minutos).
ACTIVOValidado: ya puede enviar desde él.
Registros
Array of arrays

Los registros que hay que poner en el DNS del dominio. De cada uno: Tipo (TXT o CNAME), Nombre, Valor y Para (para qué sirve). Cópielos tal cual.

Errores
Array of arrays

En COMPROBAR, si falta algún registro o no está bien: cuáles.

Validados
Array of arrays

En LISTAR: sus dominios validados.

EnProceso
Array of arrays

En LISTAR: los que están en proceso.

Mensaje
string

Qué hacer ahora, para enseñarlo si quiere.

Error
string

El motivo, cuando Res es negativo.

Request samples

Content type
{
  • "IdUsuario": 97801,
  • "Accion": "SOLICITAR",
  • "Dominio": "talleresperez.es"
}

Response samples

Content type
application/json
Example
{
  • "Res": 1,
  • "Dominio": "talleresperez.es",
  • "Estado": "PENDIENTE_PROPIEDAD",
  • "Registros": [
    ],
  • "Mensaje": "Pon estos registros en el DNS del dominio y llama a ACCION=COMPROBAR. Los cambios de DNS pueden tardar en verse."
}

Ceder sus remitentes

/DistribuidorRemitentesCedidos

Cede a sus usuarios remitentes que usted puede usar: sus alias del Registro de Alias de la CNMC y sus números validados. Así, cuando envía en nombre de un usuario (ver Enviar en nombre de sus usuarios), el envío puede salir con su propio remitente, aunque el usuario no tenga ninguno.

- Solo vale en lo que envía usted en su nombre, con ENNOMBREDE: quien envía es usted. El usuario no puede usarlo desde su panel ni con sus propias claves: para él es un remitente no validado.
- Indíquelo en el REMITENTE de cada envío. Si lo escribe con otras mayúsculas, sale con la forma registrada.
- Puede cederlo a un usuario (IDUSUARIO) o a todos los suyos (sin IDUSUARIO).
- Solo puede ceder lo que puede usar en ese momento, y se vuelve a comprobar en cada envío: si un alias deja de ser suyo en la CNMC, deja de valer para sus usuarios al momento.
- Alias de SMS y números. El RCS no: sale siempre con el agente RCS de cada cuenta.

ACCION=LISTAR devuelve lo que puede ceder y lo que tiene cedido (con IDUSUARIO, lo de ese usuario, incluido lo cedido a todos).

Authorizations:
basicAuth
query Parameters
Accion
string
Example: Accion=CEDER

Por defecto, LISTAR.
LISTAR - Lo que puede ceder y lo que tiene cedido
CEDER - Cede un remitente suyo
RETIRAR - Deja de cederlo

Remitente
string
Example: Remitente=MIDISTRIB

En CEDER y RETIRAR: el alias o el número (con o sin el prefijo).

Tipo
string
Example: Tipo=SMS

En CEDER y RETIRAR.
SMS - Un alias de SMS
NUM - Un número

Idusuario
integer
Example: Idusuario=97801

El usuario al que se lo cede o se lo retira. Sin él (o con 0), todos sus usuarios. En LISTAR, para ver lo de un usuario.

Resp
string
Example: Resp=JSON

Formato de la respuesta.
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Request Body schema:

Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.

Accion
string
Remitente
string
Tipo
string
Idusuario
integer
Resp
string

Responses

Response Schema: application/json
Res
required
integer <int32>

Resultado. Los códigos están en la introducción.

Cedibles
object

En LISTAR: lo que puede ceder ahora mismo. SMS, sus alias; NUM, sus números.

Cedidos
Array of arrays

En LISTAR: lo que tiene cedido. De cada uno: Remitente, Tipo, IdUsuario (0 = a todos sus usuarios) y Fecha.

Remitente
string

En CEDER: el remitente cedido, en su forma registrada.

Tipo
string

En CEDER: SMS o NUM.

IdUsuario
integer

En CEDER: a quién (0 = a todos sus usuarios).

Retirado
integer

En RETIRAR: 1 si se ha retirado.

Mensaje
string

Qué se ha hecho.

Error
string

El motivo, cuando Res es negativo.

Request samples

Content type
Example
{
  • "Accion": "CEDER",
  • "Remitente": "MIDISTRIB",
  • "Tipo": "SMS",
  • "IdUsuario": 97801
}

Response samples

Content type
application/json
Example
{
  • "Res": 1,
  • "Remitente": "MIDISTRIB",
  • "Tipo": "SMS",
  • "IdUsuario": 97801,
  • "Mensaje": "Cedido. Solo vale en los envíos que hagas en nombre de ese usuario por la API."
}