API v1 · REST · JSON

Documentation de l'API

Envoyez vos emails et vos SMS depuis votre propre application, votre boutique ou votre back-office. Une clé API suffit.

Démarrer

L'API Parino est une API REST : chaque requête est indépendante, le corps et la réponse sont au format JSON. Toutes les adresses commencent par :

Adresse de base

https://parino.tn/api/v1

Clients européens : https://parino.fr/api/v1. Les deux serveurs exposent les mêmes routes ; utilisez celui sur lequel votre compte a été créé.

Où trouver ma clé ? Connectez-vous à votre espace Parino, rubrique Clés API. Vous choisissez à la création ce que la clé a le droit de faire : envoyer des emails, des SMS, ou lire vos formulaires. La clé n'est affichée qu'une seule fois — conservez-la immédiatement.

Authentification

Chaque requête porte votre clé dans l'en-tête X-API-Key. Il n'y a ni jeton à rafraîchir, ni session à maintenir.

cURL

curl https://parino.tn/api/v1/usage \
  -H "X-API-Key: parino_live_votre_cle"

Ne mettez jamais votre clé dans du code exécuté par le navigateur. Elle serait lisible par n'importe quel visiteur, qui pourrait alors envoyer en votre nom et épuiser votre crédit. Appelez l'API depuis votre serveur.

Envoyer un email

POST/v1/emailsclé Email

Envoie un email transactionnel à un destinataire. Décompté de votre crédit email.

Champ	Type	Description
toEmail	string	Adresse du destinataire. Obligatoire.
toName	string	Nom affiché du destinataire.
subject	string	Objet de l'email. Obligatoire.
htmlContent	string	Corps en HTML.
textContent	string	Version texte, pour les clients mail qui refusent le HTML.
templateId	number	Identifiant d'un modèle de votre compte, au lieu du contenu.
params	object	Valeurs des variables du modèle.
tags	string[]	Étiquettes libres, utiles pour vos statistiques.
attachments	object[]	Pièces jointes : { "name": "facture.pdf", "content": "<base64>" }. 5 fichiers et 10 Mo au total ; PDF, Word, Excel, PowerPoint, CSV, TXT, ICS, JPG, PNG ou GIF.

cURL

curl -X POST https://parino.tn/api/v1/emails \
  -H "X-API-Key: parino_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "toEmail": "client@exemple.tn",
    "toName": "Sonia Ben Ali",
    "subject": "Votre commande est prête",
    "htmlContent": "<p>Bonjour Sonia, votre commande vous attend.</p>",
    "tags": ["commande"]
  }'

Réponse 200

{
  "id": 4821,
  "toEmail": "client@exemple.tn",
  "subject": "Votre commande est prête",
  "status": "SENT",
  "sentAt": "2026-08-14T09:12:44Z"
}

Envoyer un SMS

Réservé aux comptes entreprise validés : le SMS part de votre propre compte WinSMS, qui vous le facture. Connectez votre clé dans Paramètres › Compte entreprise.

POST/v1/smsclé SMS

Envoie un SMS depuis votre compte WinSMS.

Champ	Type	Description
recipient	string	Numéro au format international, ex. +21620123456. Obligatoire.
senderName	string	Facultatif : l'expéditeur enregistré chez WinSMS s'applique toujours.
content	string	Texte du message, 1000 caractères maximum. Obligatoire.

cURL

curl -X POST https://parino.tn/api/v1/sms \
  -H "X-API-Key: parino_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "+21620123456",
    "senderName": "MaSociete",
    "content": "Votre commande est prete. Merci !"
  }'

Attention aux accents. Un SMS sans accent contient 160 caractères ; dès qu'un accent ou un emoji apparaît, la limite tombe à 70 et le message est facturé en plusieurs SMS.

Codes de vérification par SMS

Vérifiez qu'un utilisateur possède bien son numéro : à l'inscription, à la connexion ou avant un changement de mot de passe. Parino génère le code, l'envoie et vous dit si la saisie est juste — votre application n'a jamais le code entre les mains. Le texte est imposé et l'expéditeur est toujours « Parino ».

POST/v1/verificationsclé SMS

Envoie un code à 6 chiffres, valable 10 minutes. Consomme un crédit SMS.

Champ	Type	Description
phone	string	Numéro au format international, ex. +21620123456. Obligatoire.
purpose	string	SIGNUP, LOGIN, PASSWORD_RESET, PHONE_CHANGE ou OTHER : choisit la phrase du SMS.
appName	string	Nom de votre application dans le SMS, 2 à 20 caractères. Par défaut : la société de votre compte.
locale	string	fr (par défaut) ou en.
domain	string	Domaine de votre site (30 caractères max) : Chrome et Safari proposent alors le code dans le formulaire.

cURL

curl -X POST https://parino.tn/api/v1/verifications \
  -H "X-API-Key: parino_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+21620123456",
    "purpose": "SIGNUP",
    "appName": "MonApp"
  }'

Réponse 201

{
  "id": "vrf_8kQ2mZtP4xWn7cR3hJ5bLd9e",
  "phone": "+336 •• •• •• 78",
  "purpose": "SIGNUP",
  "status": "PENDING",
  "expiresAt": "2026-09-25T10:10:00Z",
  "resendAvailableAt": "2026-09-25T10:00:30Z"
}

SMS reçu

482913 est votre code MonApp pour confirmer votre inscription. Valable 10 min. Ne le communiquez à personne.

POST/v1/verifications/{id}/checkclé SMS

Vérifie la saisie de l'utilisateur. Un code juste ne sert qu'une fois ; au cinquième code faux, il est bloqué.

Champ	Type	Description
code	string	Le code saisi par l’utilisateur. Obligatoire.

cURL

curl -X POST https://parino.tn/api/v1/verifications/vrf_8kQ2mZtP4xWn7cR3hJ5bLd9e/check \
  -H "X-API-Key: parino_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{ "code": "482913" }'

Réponse 200

{ "valid": true,  "id": "vrf_…", "status": "VERIFIED", "attemptsRemaining": 0 }
{ "valid": false, "id": "vrf_…", "status": "PENDING",  "attemptsRemaining": 3 }

Seul valid: true autorise l'utilisateur. Les autres statuts : EXPIRED (dix minutes écoulées), BLOCKED (cinq codes faux), CANCELED (un code plus récent a été envoyé), VERIFIED (déjà utilisé). Sans l'identifiant, envoyez { "phone", "code" } à POST /v1/verifications/check : le dernier code envoyé à ce numéro est vérifié.

Limites anti-abus. Un code toutes les 30 secondes et cinq par heure au même numéro ; au-delà, la réponse est 429 avec l'en-tête Retry-After. Un SMS refusé par l'opérateur répond 502 et n'est pas débité. Suivez l'état d'un code avec GET /v1/verifications/{id}.

Créer ou mettre à jour un contact

POST/v1/contacts

Enregistre un contact. L'opération est idempotente : réenvoyer la même adresse met le contact à jour au lieu d'en créer un second.

Champ	Type	Description
email	string	Adresse du contact. Obligatoire, sert de clé.
firstName / lastName	string	Prénom et nom.
phone	string	Numéro de téléphone.
company	string	Société.
country / city	string	Pays et ville.
birthDate	date	Date de naissance, format AAAA-MM-JJ.
source	string	Origine du contact, ex. « Site web ». Utile pour vos statistiques.
listIds	number[]	Listes auxquelles rattacher le contact.

JavaScript (Node.js)

const res = await fetch('https://parino.tn/api/v1/contacts', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.PARINO_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'client@exemple.tn',
    firstName: 'Sonia',
    source: 'Site web',
    listIds: [3],
  }),
});
const contact = await res.json();

Lister vos listes de contacts

GET/v1/lists

Renvoie vos listes avec leur identifiant, à utiliser dans listIds.

Réponse 200

[
  { "id": 3, "name": "Newsletter", "contactsCount": 1248 },
  { "id": 7, "name": "Clients 2026", "contactsCount": 312 }
]

Connaître votre crédit restant

GET/v1/usage

Renvoie votre forfait et le crédit restant sur chaque canal.

Réponse 200

{
  "plan": "BUSINESS",
  "email": { "used": 4813, "limit": 15000, "remaining": 10187, "unlimited": false },
  "sms":   { "used": 180,  "limit": 500,   "remaining": 320,   "unlimited": false },
  "periodStart": "2026-08-01T00:00:00Z",
  "periodEnd":   "2026-09-01T00:00:00Z"
}

Forfaits illimités. limit et remaining valent alors -1, et unlimited passe à true. Testez unlimited avant d'afficher le nombre, sous peine d'annoncer « -1 email restant » à vos utilisateurs.

Suivre vos quotas sans requête supplémentaire

Chaque envoi renvoie votre solde dans les en-têtes de la réponse. Vous n'avez donc pas besoin d'appeler /v1/usage après chaque message : le solde tient déjà compte de l'envoi qui vient d'être effectué.

En-têtes de réponse

X-Parino-Email-Remaining: 10186
X-Parino-Email-Limit: 15000

X-Parino-Sms-Remaining: 319
X-Parino-Sms-Limit: 500

Surveillez ces valeurs pour prévenir vos équipes avant l'épuisement du crédit. Une fois le quota atteint, les envois sont refusés avec un code 402 jusqu'au mois suivant ou au changement de forfait.

Codes d'erreur

Une erreur renvoie toujours le même format, avec un message lisible et, pour les erreurs de validation, le détail champ par champ.

Réponse d'erreur

{
  "status": 400,
  "error": "Validation Failed",
  "message": "Données invalides",
  "path": "/api/v1/emails",
  "timestamp": "2026-08-14T09:12:44Z",
  "details": ["subject: ne doit pas être vide"]
}

Code	Signification	Que faire
400	Requête invalide	Lisez details : il indique le champ fautif.
401	Clé absente ou invalide	Vérifiez l'en-tête X-API-Key.
403	Portée insuffisante	La clé n’autorise pas cette opération. Créez-en une avec la bonne portée.
402	Crédit épuisé	Attendez le mois suivant ou changez de forfait.
404	Ressource introuvable	Vérifiez l'identifiant transmis.
429	Trop de demandes	Codes de vérification trop rapprochés : attendez la durée indiquée par Retry-After.
502	Service d’envoi indisponible	Incident temporaire : réessayez dans quelques instants.

Rejouer un envoi après une erreur 502 ? Le message a pu partir malgré l'erreur. Sur un email de confirmation, un doublon est sans gravité ; sur un code à usage unique, vérifiez d'abord avec /v1/usage si le crédit a été décompté.

Prêt à connecter votre application ?

Créez votre compte, générez une clé et envoyez votre premier message en quelques minutes.

Créer un compte Poser une question