Aller au contenu principal

Sociétés

Toutes les routes ci-dessous exigent la session du gérant Connect et un plan partner-connect-*.

Lister​

GET /api/partner/organizations
Authorization: Bearer ACCESS_TOKEN

La réponse contient les sociétés créées et les comptes rattachés, le dernier statut du sceau et de TTN, hasLogo, invoicingSuspendedAt, taxIdLocked, taxIdLockReason, le nombre de sociétés actives, le plafond, le quota mensuel et les demandes de rattachement. Le logo en base64 n'est pas dans la liste.

Lire​

GET /api/partner/organizations/{childOrgId}

Même fiche que dans la liste, plus logoBase64. taxIdLocked vaut true ou false. taxIdLockReason vaut sandbox (identité du mock), ttn_submitted (une facture a déjà été déposée à TTN) ou null si le matricule est encore modifiable.

Créer​

POST /api/partner/organizations
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "name": "Société cliente SARL",
  "taxId": "1234567A",
  "managerEmail": "gerant@client.tn",
  "phone": "71111222",
  "street": "Avenue Habib Bourguiba",
  "city": "Tunis",
  "postalCode": "1000",
  "ttnLogin": "login-ttn",
  "ttnPassword": "secret-ttn",
  "sealAlias": "alias-sceau",
  "sealPin": "pin-sceau",
  "ttnEnv": "test"
}

Fatoora crée la société fille, reprend l'abonnement Connect et autorise la facturation (invoice:read, invoice:write, ttn:submit, seal:sign). Si le login TTN ou le sceau sont fournis, les tests partent tout de suite. En sandbox, ils partent toujours : le matricule et 111111 sont imposés à la création.

Nom, e-mail du gérant, téléphone et adresse sont obligatoires. logoBase64 est optionnel : data URL png, jpeg, gif ou webp, environ 500 Ko. En sandbox, la réponse de création porte taxIdLocked: true et taxIdLockReason: "sandbox".

Mettre à jour la fiche​

PATCH /api/partner/organizations/{childOrgId}

Champs optionnels, au moins un : name, taxId, managerEmail, phone, street, city, postalCode, logoBase64. Un champ absent n'est pas modifié. logoBase64: null retire le logo.

Réservé à une société créée. Un compte rattaché répond 409 USE_DETACH_OTP. Une société archivée répond 409 CHILD_ARCHIVED.

Si taxIdLocked est vrai, un autre matricule répond 409 TAX_ID_LOCKED avec le même reason que le GET. En sandbox le matricule ne change pas : le login TTN et l'alias SEAL sont ce matricule. En production, il se verrouille après un dépôt TTN. Nom, adresse, téléphone, e-mail et logo restent modifiables.

Pause​

POST /api/partner/organizations/{childOrgId}/pause
POST /api/partner/organizations/{childOrgId}/resume

La pause refuse la création, la signature et l'envoi de factures (409 INVOICING_SUSPENDED), y compris en sandbox. La société reste dans le quota et les lectures restent ouvertes. La reprise remet invoicingSuspendedAt à null. L'archive, plus bas, est la suppression : elle libère le quota.

Sceau et TTN​

PATCH /api/partner/organizations/{childOrgId}/credentials

Les champs absents ne sont pas effacés. ttnPassword et sealPin ne sont jamais renvoyés en clair.

ttnEnv vaut test ou prod. En production, test envoie le dépôt vers l’URL Elfatoora de test et prod vers l’URL de production. En sandbox, les deux valeurs sont enregistrées comme mock : le dépôt va toujours vers le mock, quel que soit le mode demandé. Sans ce champ, une valeur déjà enregistrée n’est pas écrasée. À la création sans ttnEnv, le défaut reste prod hors sandbox.

En sandbox, la création d’une société (pas un rattachement) ignore les identifiants envoyés et crée le compte mock suivant : login TTN = matricule fiscal, mot de passe TTN = 111111, alias SEAL = matricule fiscal, PIN = 111111. Le matricule est obligatoire et ne peut pas contenir /. Une mise à jour ultérieure écrit les identifiants tels quels, sans modifier le mock. Le test réussit seulement s’ils sont encore ce jeu ; toute autre valeur fait échouer TTN ou SEAL.

Relancer un contrôle :

POST /api/partner/organizations/{childOrgId}/test-ttn
POST /api/partner/organizations/{childOrgId}/test-seal

Le dernier résultat est enregistré sur la société (ttnLastCredentialsOk, sealLastTestOk).

Quand le test SEAL réussit, la réponse ajoute le premier certificat :

{
  "ttn": "pending",
  "seal": "ok",
  "certificate": {
    "serialNumber": "A1B2C3",
    "expiresAt": "2031-01-01T00:00:00Z",
    "commonName": "Société cliente SARL (1234567A)",
    "subject": "CN=Société cliente SARL (1234567A)"
  }
}

En échec, certificate est absent.

Archiver​

POST /api/partner/organizations/{childOrgId}/archive

Réservé à une société créée par le partenaire. Un compte fatoora.tn rattaché ne s'archive pas par cette route : le propriétaire arrête le rattachement depuis son compte (USE_DETACH_OTP). Voir Rattachement.

Erreurs à la création​

CodeHTTPSignification
TAX_ID_EXISTS409Compte fatoora.tn déjà existant. Ne le recréez pas : rattachez-le. La réponse liste organizations.
ALREADY_LINKED409Cette société est déjà dans votre portefeuille.
NOT_LINKABLE409Le matricule existe, mais il ne peut ni être créé ni rattaché. Lisez reason.
CONNECT_ORG_LIMIT409Plafond de sociétés atteint.
CONNECT_PLAN_REQUIRED403Le compte n'est pas une offre Connect.
NOT_ALLOWED403Réservé au propriétaire ou à un gestionnaire.
TAX_ID_LOCKED409Le matricule ne peut plus changer. reason : sandbox ou ttn_submitted.
INVOICING_SUSPENDED409Société en pause. Reprenez-la avant de facturer.
CHILD_ARCHIVED409Société archivée : la fiche et la pause ne s'appliquent plus.
LOGO_INVALID400Le logo doit être une data URL PNG, JPEG, GIF ou WebP.
LOGO_TOO_LARGE400Logo trop lourd (environ 500 Ko).

Valeurs de reason pour NOT_LINKABLE :

  • own_child — déjà dans vos sociétés.
  • managed_elsewhere — déjà géré par un autre Connect ou un Cabinet.
  • partner_or_cabinet — compte Partenaire ou Cabinet, pas une société fatoora.tn standard.