{ "components": { "schemas": { "Balance": { "properties": { "available": { "description": "Total moins les réservations. Les crédits expirés ne peuvent pas financer un nouvel envoi.", "minimum": 0, "type": "integer" }, "reserved": { "description": "Crédits réservés pour les messages admis dont le résultat fournisseur reste à confirmer.", "minimum": 0, "type": "integer" }, "total": { "minimum": 0, "type": "integer" }, "valid_until": { "format": "date", "nullable": true, "type": "string" } }, "required": [ "available", "reserved", "total", "valid_until" ], "type": "object" }, "Batch": { "properties": { "counts": { "$ref": "#/components/schemas/StatusCounts" }, "created_at": { "format": "date-time", "type": "string" }, "credits_reserved": { "description": "Crédits en segments SMS réservés à l’admission du lot ; cette valeur ne représente pas le solde actuel.", "minimum": 1, "type": "integer" }, "id": { "format": "uuid", "type": "string" }, "recipient_count": { "minimum": 1, "type": "integer" }, "send_at": { "format": "date-time", "type": "string" } }, "required": [ "counts", "created_at", "credits_reserved", "id", "recipient_count", "send_at" ], "type": "object" }, "BatchCreateRequest": { "properties": { "recipients": { "items": { "maxLength": 13, "minLength": 13, "pattern": "^\\+2613[0-9]{8}$", "type": "string" }, "maxItems": 1000, "minItems": 1, "type": "array" }, "send_at": { "format": "date-time", "type": "string" }, "sender_name": { "maxLength": 11, "minLength": 1, "type": "string" }, "text": { "maxLength": 320, "minLength": 1, "type": "string" } }, "required": [ "recipients", "send_at", "text" ], "type": "object" }, "BatchMessages": { "properties": { "next_cursor": { "nullable": true, "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/Message" }, "type": "array" } }, "required": [ "next_cursor", "results" ], "type": "object" }, "ContactResponse": { "properties": { "address": { "nullable": true, "type": "string" }, "birthday": { "format": "date", "nullable": true, "type": "string" }, "company": { "maxLength": 100, "nullable": true, "type": "string" }, "first_name": { "maxLength": 100, "nullable": true, "type": "string" }, "home_email": { "nullable": true, "oneOf": [ { "format": "email", "maxLength": 254, "type": "string" }, { "maxLength": 0, "type": "string" } ] }, "id": { "readOnly": true, "type": "integer" }, "list_name": { "maxLength": 100, "type": "string" }, "office_email": { "nullable": true, "oneOf": [ { "format": "email", "maxLength": 254, "type": "string" }, { "maxLength": 0, "type": "string" } ] }, "phone_number": { "maxLength": 13, "minLength": 13, "pattern": "^\\+2613[0-9]{8}$", "type": "string" }, "position": { "maxLength": 100, "nullable": true, "type": "string" }, "source": { "maxLength": 50, "type": "string" }, "status": { "format": "int64", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "type": "integer" } }, "required": [ "id", "phone_number" ], "type": "object" }, "ContactWriteRequest": { "properties": { "address": { "nullable": true, "type": "string" }, "birthday": { "format": "date", "nullable": true, "type": "string" }, "company": { "maxLength": 100, "nullable": true, "type": "string" }, "first_name": { "maxLength": 100, "nullable": true, "type": "string" }, "home_email": { "nullable": true, "oneOf": [ { "format": "email", "maxLength": 254, "type": "string" }, { "maxLength": 0, "type": "string" } ] }, "list_name": { "maxLength": 100, "minLength": 1, "type": "string" }, "office_email": { "nullable": true, "oneOf": [ { "format": "email", "maxLength": 254, "type": "string" }, { "maxLength": 0, "type": "string" } ] }, "phone_number": { "maxLength": 13, "minLength": 13, "pattern": "^\\+2613[0-9]{8}$", "type": "string" }, "position": { "maxLength": 100, "nullable": true, "type": "string" }, "source": { "maxLength": 50, "minLength": 1, "type": "string" }, "status": { "format": "int64", "maximum": 9223372036854776000, "minimum": -9223372036854776000, "type": "integer" } }, "required": [ "phone_number" ], "type": "object" }, "Error": { "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail" }, "message_id": { "format": "uuid", "type": "string" } }, "required": [ "error" ], "type": "object" }, "ErrorDetail": { "properties": { "code": { "type": "string" }, "details": {}, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "Message": { "properties": { "delivery_time": { "format": "date-time", "nullable": true, "type": "string" }, "id": { "format": "uuid", "type": "string" }, "segments": { "maximum": 2, "minimum": 1, "type": "integer" }, "send_at": { "description": "Date de programmation initialement demandée, conservée après l’envoi. Null pour un message immédiat.", "format": "date-time", "nullable": true, "type": "string" }, "sender_name": { "description": "Nom d’expéditeur, ou chaîne vide après un effacement validé.", "type": "string" }, "status": { "allOf": [ { "$ref": "#/components/schemas/StatusEnum" } ], "description": "scheduled : en attente de la date d’envoi ; processing : soumission en cours ; accepted : acceptation du fournisseur confirmée ; delivered/undeliverable : accusé de livraison définitif ; blocked : expéditeur indisponible avant la soumission ; failed : refus confirmé ou échec avant la soumission ; unknown : résultat à vérifier.\n\n* `scheduled` - programmé\n* `processing` - en cours de traitement\n* `accepted` - accepté\n* `delivered` - livré\n* `undeliverable` - livraison impossible\n* `blocked` - bloqué\n* `failed` - échec\n* `unknown` - résultat inconnu" }, "to": { "description": "Mobile malgache destinataire au format E.164, ou chaîne vide après l’effacement validé des données d’un message dont le traitement est terminé.", "oneOf": [ { "maxLength": 13, "pattern": "^(?:\\+2613[0-9]{8})?$", "type": "string" }, { "maxLength": 0, "type": "string" } ] } }, "required": [ "delivery_time", "id", "segments", "send_at", "sender_name", "status", "to" ], "type": "object" }, "MessageCreateRequest": { "properties": { "send_at": { "format": "date-time", "type": "string" }, "sender_name": { "maxLength": 11, "minLength": 1, "type": "string" }, "text": { "maxLength": 320, "minLength": 1, "type": "string" }, "to": { "maxLength": 13, "minLength": 13, "pattern": "^\\+2613[0-9]{8}$", "type": "string" } }, "required": [ "text", "to" ], "type": "object" }, "StatusCounts": { "properties": { "accepted": { "minimum": 0, "type": "integer" }, "blocked": { "minimum": 0, "type": "integer" }, "delivered": { "minimum": 0, "type": "integer" }, "failed": { "minimum": 0, "type": "integer" }, "processing": { "minimum": 0, "type": "integer" }, "scheduled": { "minimum": 0, "type": "integer" }, "undeliverable": { "minimum": 0, "type": "integer" }, "unknown": { "minimum": 0, "type": "integer" } }, "required": [ "accepted", "blocked", "delivered", "failed", "processing", "scheduled", "undeliverable", "unknown" ], "type": "object" }, "StatusEnum": { "description": "* `scheduled` - programmé\n* `processing` - en cours de traitement\n* `accepted` - accepté\n* `delivered` - livré\n* `undeliverable` - livraison impossible\n* `blocked` - bloqué\n* `failed` - échec\n* `unknown` - résultat inconnu", "enum": [ "scheduled", "processing", "accepted", "delivered", "undeliverable", "blocked", "failed", "unknown" ], "type": "string" } }, "securitySchemes": { "OrganizationApiKey": { "bearerFormat": "bf_sms_.", "description": "Clé API organisationnelle créée dans BEFIANA Cloud. Les anciennes clés API et les JWT ne sont pas acceptés.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "API d’intégration SMS rattachée à une organisation. L’acceptation ne signifie pas la livraison.", "title": "API SMS by BEFIANA", "version": "2.0.2" }, "openapi": "3.0.3", "paths": { "/api/sms/v2/balance/": { "get": { "description": "Nécessite balance.read. Les crédits correspondent aux segments SMS. Le disponible est égal au total moins les réservations ; les crédits expirés ne peuvent pas financer un nouvel envoi.", "operationId": "getBalance", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" } }, "security": [ { "OrganizationApiKey": [] } ], "summary": "Consulter les crédits SMS", "tags": [ "Balance" ] } }, "/api/sms/v2/contacts/": { "post": { "description": "Nécessite contacts.manage. Crée ou met à jour le contact identifié par phone_number au format E.164 dans l’organisation de la clé. Les champs facultatifs absents restent inchangés. Renvoie 201 à la création et 200 à la mise à jour.", "operationId": "upsertContact", "requestBody": { "content": { "application/json": { "examples": { "Contact": { "value": { "first_name": "Alex", "phone_number": "+261321234567" } } }, "schema": { "$ref": "#/components/schemas/ContactWriteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } }, "description": "" }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } }, "description": "" }, "400": { "content": { "application/json": { "examples": { "InvalidRequest": { "summary": "Invalid request", "value": { "error": { "code": "validation_error", "message": "The request is invalid." } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" } }, "security": [ { "OrganizationApiKey": [] } ], "summary": "Créer ou mettre à jour un contact", "tags": [ "Contacts" ] } }, "/api/sms/v2/message-batches/": { "post": { "description": "Nécessite sms.schedule. Tous les destinataires distincts partagent le texte, l’expéditeur et send_at. Les messages et leurs réservations de crédits sont enregistrés ensemble. Les résultats d’envoi et de livraison restent individuels. La réponse est compacte ; consultez les messages du lot pour retrouver les destinataires.", "operationId": "createMessageBatch", "parameters": [ { "description": "Entre 1 et 128 caractères ASCII visibles. Portée durable : organisation et ressource. Les reprises conservent la réponse initiale, sauf après l’effacement validé des données d’un message dont le traitement est terminé (410 personal_data_erased) ; un contenu différent renvoie 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "pattern": "^[!-~]{1,128}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "ScheduledBatch": { "summary": "Scheduled batch", "value": { "recipients": [ "+261321234567", "+261331234567" ], "send_at": "2027-01-15T10:00:00+03:00", "text": "Appointment reminder" } } }, "schema": { "$ref": "#/components/schemas/BatchCreateRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } }, "description": "", "headers": { "Location": { "description": "URL relative de la ressource message ou lot acceptée.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "examples": { "InvalidRequest": { "summary": "Invalid request", "value": { "error": { "code": "validation_error", "message": "The request is invalid." } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" } }, "security": [ { "OrganizationApiKey": [] } ], "summary": "Programmer un lot atomique de messages", "tags": [ "Batches" ] } }, "/api/sms/v2/message-batches/{batch_id}/": { "get": { "description": "Nécessite delivery.read. Les compteurs reflètent les résultats actuels de chaque message ; accepted ne signifie pas delivered.", "operationId": "getMessageBatch", "parameters": [ { "in": "path", "name": "batch_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" } }, "security": [ { "OrganizationApiKey": [] } ], "summary": "Consulter la progression d’un lot", "tags": [ "Batches" ] } }, "/api/sms/v2/message-batches/{batch_id}/messages/": { "get": { "description": "Nécessite delivery.read. Renvoie au plus 100 messages dans l’ordre des destinataires fournis. Transmettez next_cursor sans modification pour consulter la page suivante ; null indique la dernière page.", "operationId": "listBatchMessages", "parameters": [ { "in": "path", "name": "batch_id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Curseur opaque retourné dans next_cursor.", "in": "query", "name": "cursor", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMessages" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" } }, "security": [ { "OrganizationApiKey": [] } ], "summary": "Lister les messages d’un lot", "tags": [ "Batches" ] } }, "/api/sms/v2/messages/": { "post": { "description": "Nécessite sms.send pour une soumission immédiate, ou sms.schedule lorsque send_at est présent. Les appels immédiats attendent l’acceptation du fournisseur (201) ; les programmations réservent les crédits de façon atomique (202). L’acceptation ne signifie pas la livraison. Seuls les mobiles malgaches et les textes de deux segments SMS au maximum sont pris en charge. Après l’effacement validé des données d’un message dont le traitement est terminé, le rejeu de sa requête d’origine renvoie 410 personal_data_erased ; ne le renvoyez jamais avec une nouvelle clé.", "operationId": "createMessage", "parameters": [ { "description": "Entre 1 et 128 caractères ASCII visibles. Portée durable : organisation et ressource. Les reprises conservent la réponse initiale, sauf après l’effacement validé des données d’un message dont le traitement est terminé (410 personal_data_erased) ; un contenu différent renvoie 409.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "pattern": "^[!-~]{1,128}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "ImmediateMessage": { "summary": "Immediate message", "value": { "text": "Hello from BEFIANA", "to": "+261321234567" } }, "ScheduledMessage": { "summary": "Scheduled message", "value": { "send_at": "2027-01-15T10:00:00+03:00", "text": "Appointment reminder", "to": "+261321234567" } } }, "schema": { "$ref": "#/components/schemas/MessageCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } }, "description": "", "headers": { "Location": { "description": "URL relative de la ressource message ou lot acceptée.", "schema": { "type": "string" } } } }, "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } }, "description": "", "headers": { "Location": { "description": "URL relative de la ressource message ou lot acceptée.", "schema": { "type": "string" } } } }, "400": { "content": { "application/json": { "examples": { "InvalidRequest": { "summary": "Invalid request", "value": { "error": { "code": "validation_error", "message": "The request is invalid." } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" } }, "security": [ { "OrganizationApiKey": [] } ], "summary": "Envoyer ou programmer un message", "tags": [ "Messages" ] } }, "/api/sms/v2/messages/{message_id}/": { "get": { "description": "Nécessite delivery.read. L’UUID public reste stable durant les tentatives de traitement. Une autre organisation reçoit 404. Un résultat inconnu ne doit pas déclencher de nouvel envoi automatique.", "operationId": "getMessage", "parameters": [ { "in": "path", "name": "message_id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "" } }, "security": [ { "OrganizationApiKey": [] } ], "summary": "Consulter le statut d’un message", "tags": [ "Messages" ] } } }, "servers": [ { "url": "https://api.befiana.cloud" } ] }