{ "info": { "name": "Fatoora Connect", "description": "Créer ou rattacher une société, puis mettre à jour le sceau et TTN. La facturation, la signature et la soumission TTN sont dans la collection partenaire.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "variable": [ { "key": "base_url", "value": "https://business.fatoora.tn", "type": "string" }, { "key": "client_id", "value": "ak_partner_YOUR_CLIENT_ID", "type": "string" }, { "key": "client_secret", "value": "YOUR_SECRET_ID_HERE", "type": "string" }, { "key": "partner_app_id", "value": "partn_YOUR_PARTNER_APP_ID", "type": "string" }, { "key": "partner_email", "value": "partner@exemple.tn", "type": "string" }, { "key": "partner_password", "value": "YOUR_PASSWORD", "type": "string" }, { "key": "access_token", "value": "", "type": "string" }, { "key": "child_org_id", "value": "", "type": "string" }, { "key": "source_organization_id", "value": "EXISTING_FATOORA_ORG_UUID", "type": "string" }, { "key": "link_request_id", "value": "", "type": "string" }, { "key": "company_name", "value": "Société cliente SARL", "type": "string" }, { "key": "seller_tax_id", "value": "1234567A", "type": "string" }, { "key": "seller_name", "value": "Société cliente SARL", "type": "string" }, { "key": "seller_street", "value": "Avenue Habib Bourguiba", "type": "string" }, { "key": "seller_city", "value": "Tunis", "type": "string" }, { "key": "seller_postal_code", "value": "1000", "type": "string" }, { "key": "ttn_login", "value": "login-ttn", "type": "string" }, { "key": "ttn_password", "value": "secret-ttn", "type": "string" }, { "key": "seal_alias", "value": "alias-sceau", "type": "string" }, { "key": "seal_pin", "value": "pin-sceau", "type": "string" } ], "item": [ { "name": "1. Session du partenaire", "item": [ { "name": "Connexion", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const json = pm.response.json();", "if (json.accessToken) {", " pm.collectionVariables.set('access_token', json.accessToken);", " console.log('access_token sauvegardé');", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"email\": \"{{partner_email}}\",\n \"password\": \"{{partner_password}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/auth/login", "host": [ "{{base_url}}" ], "path": [ "api", "auth", "login" ] }, "description": "Jeton de session du gérant Connect. Il sert à créer une société, rattacher un compte et mettre à jour TTN / sceau." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{base_url}}/api/auth/login", "host": [ "{{base_url}}/api/auth/login" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"accessToken\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.session\",\n \"user\": {\n \"email\": \"partner@exemple.tn\"\n }\n}" }, { "name": "401 Unauthorized", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{base_url}}/api/auth/login", "host": [ "{{base_url}}/api/auth/login" ] } }, "status": "Unauthorized", "code": 401, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": \"Invalid credentials\"\n}" } ] } ] }, { "name": "2. Sociétés", "item": [ { "name": "Lister les sociétés", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{base_url}}/api/partner/organizations", "host": [ "{{base_url}}" ], "path": [ "api", "partner", "organizations" ] }, "description": "Sociétés créées et comptes fatoora.tn rattachés, avec le dernier statut SEAL / TTN, hasLogo, invoicingSuspendedAt, taxIdLocked et taxIdLockReason." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/partner/organizations", "host": [ "{{base_url}}/api/partner/organizations" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"organizations\": [\n {\n \"id\": \"child-org-uuid\",\n \"name\": \"Société cliente SARL\",\n \"taxId\": \"1234567A\",\n \"status\": \"active\",\n \"linkedOrganizationId\": null,\n \"linkedOrganizationName\": null,\n \"ttnLogin\": \"login-ttn\",\n \"sealAlias\": \"alias-sceau\",\n \"ttnLastCredentialsOk\": true,\n \"sealLastTestOk\": true,\n \"hasLogo\": false,\n \"invoicingSuspendedAt\": null,\n \"taxIdLocked\": true,\n \"taxIdLockReason\": \"sandbox\"\n }\n ],\n \"requests\": [],\n \"activeCount\": 1,\n \"maxOrgs\": 10,\n \"monthlyDocsUsed\": 0,\n \"monthlyDocLimit\": 500\n}" } ] }, { "name": "Créer une société", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const json = pm.response.json();", "const id = json.organization && json.organization.id;", "if (id) {", " pm.collectionVariables.set('child_org_id', id);", " console.log('child_org_id sauvegardé', id);", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"{{company_name}}\",\n \"taxId\": \"{{seller_tax_id}}\",\n \"managerEmail\": \"gerant@client.tn\",\n \"phone\": \"71111222\",\n \"street\": \"{{seller_street}}\",\n \"city\": \"{{seller_city}}\",\n \"postalCode\": \"{{seller_postal_code}}\",\n \"ttnLogin\": \"{{ttn_login}}\",\n \"ttnPassword\": \"{{ttn_password}}\",\n \"sealAlias\": \"{{seal_alias}}\",\n \"sealPin\": \"{{seal_pin}}\",\n \"logoBase64\": null\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/partner/organizations", "host": [ "{{base_url}}" ], "path": [ "api", "partner", "organizations" ] }, "description": "Crée la société enfant, copie l'abonnement et pose l'autorisation invoice:read, invoice:write, ttn:submit, seal:sign. logoBase64 est optionnel (data URL image, environ 500 Ko). En sandbox le matricule est verrouillé." }, "response": [ { "name": "201 Created", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{base_url}}/api/partner/organizations", "host": [ "{{base_url}}/api/partner/organizations" ] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"organization\": {\n \"id\": \"child-org-uuid\",\n \"name\": \"Société cliente SARL\",\n \"taxId\": \"1234567A\",\n \"status\": \"active\"\n },\n \"tests\": {\n \"ttn\": \"ok\",\n \"seal\": \"ok\"\n },\n \"activeCount\": 1,\n \"maxOrgs\": 10\n}" }, { "name": "409 TAX_ID_EXISTS", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{base_url}}/api/partner/organizations", "host": [ "{{base_url}}/api/partner/organizations" ] } }, "status": "Conflict", "code": 409, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": \"This tax ID already belongs to a fatoora.tn account. Attach that company instead of creating a new one.\",\n \"code\": \"TAX_ID_EXISTS\",\n \"action\": \"exists\",\n \"organizations\": [\n {\n \"id\": \"existing-org-uuid\",\n \"name\": \"Compte fatoora.tn\"\n }\n ]\n}" }, { "name": "409 NOT_LINKABLE", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{base_url}}/api/partner/organizations", "host": [ "{{base_url}}/api/partner/organizations" ] } }, "status": "Conflict", "code": 409, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": \"This tax ID belongs to a Partner or Cabinet account, not a standard fatoora.tn company. It cannot be created or attached.\",\n \"code\": \"NOT_LINKABLE\",\n \"reason\": \"partner_or_cabinet\",\n \"classified\": {\n \"action\": \"not_linkable\",\n \"reason\": \"partner_or_cabinet\"\n }\n}" } ] }, { "name": "Mettre à jour sceau et TTN", "request": { "method": "PATCH", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"ttnLogin\": \"{{ttn_login}}\",\n \"ttnPassword\": \"{{ttn_password}}\",\n \"sealAlias\": \"{{seal_alias}}\",\n \"sealPin\": \"{{seal_pin}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/partner/organizations/{{child_org_id}}/credentials", "host": [ "{{base_url}}" ], "path": [ "api", "partner", "organizations", "{{child_org_id}}", "credentials" ] }, "description": "Met à jour les identifiants TTN et le sceau de la société enfant. Les champs absents ne sont pas effacés." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "PATCH", "header": [], "url": { "raw": "{{base_url}}/api/partner/organizations/{{child_org_id}}/credentials", "host": [ "{{base_url}}/api/partner/organizations/{{child_org_id}}/credentials" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"success\": true\n}" } ] }, { "name": "Tester TTN", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{base_url}}/api/partner/organizations/{{child_org_id}}/test-ttn", "host": [ "{{base_url}}" ], "path": [ "api", "partner", "organizations", "{{child_org_id}}", "test-ttn" ] }, "description": "Relance le test des identifiants TTN et enregistre le dernier statut." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{base_url}}/api/partner/organizations/{{child_org_id}}/test-ttn", "host": [ "{{base_url}}/api/partner/organizations/{{child_org_id}}/test-ttn" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"ttn\": \"ok\",\n \"seal\": \"pending\"\n}" } ] }, { "name": "Tester le sceau", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{base_url}}/api/partner/organizations/{{child_org_id}}/test-seal", "host": [ "{{base_url}}" ], "path": [ "api", "partner", "organizations", "{{child_org_id}}", "test-seal" ] }, "description": "Relance le test du sceau et enregistre le dernier statut." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{base_url}}/api/partner/organizations/{{child_org_id}}/test-seal", "host": [ "{{base_url}}/api/partner/organizations/{{child_org_id}}/test-seal" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"ttn\": \"ok\",\n \"seal\": \"ok\"\n}" } ] }, { "name": "Lire une société", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{base_url}}/api/partner/organizations/{{child_org_id}}", "host": ["{{base_url}}"], "path": ["api", "partner", "organizations", "{{child_org_id}}"] }, "description": "Fiche complète, y compris logoBase64. taxIdLocked et taxIdLockReason (sandbox, ttn_submitted ou null) indiquent si le matricule peut encore changer." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/partner/organizations/{{child_org_id}}", "host": ["{{base_url}}/api/partner/organizations/{{child_org_id}}"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [{ "key": "Content-Type", "value": "application/json" }], "cookie": [], "body": "{\n \"id\": \"child-org-uuid\",\n \"name\": \"Société cliente SARL\",\n \"taxId\": \"1234567A\",\n \"hasLogo\": false,\n \"logoBase64\": null,\n \"invoicingSuspendedAt\": null,\n \"taxIdLocked\": true,\n \"taxIdLockReason\": \"sandbox\"\n}" } ] }, { "name": "Mettre à jour la fiche", "request": { "method": "PATCH", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"street\": \"{{seller_street}}\",\n \"city\": \"{{seller_city}}\",\n \"postalCode\": \"{{seller_postal_code}}\",\n \"phone\": \"71111222\",\n \"managerEmail\": \"gerant@client.tn\",\n \"logoBase64\": null\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/partner/organizations/{{child_org_id}}", "host": ["{{base_url}}"], "path": ["api", "partner", "organizations", "{{child_org_id}}"] }, "description": "Met à jour nom, adresse, téléphone, e-mail, logo et, hors verrou, le matricule. Au moins un champ. logoBase64 null retire le logo. Société créée seulement. En sandbox un autre matricule répond 409 TAX_ID_LOCKED reason sandbox." }, "response": [ { "name": "409 TAX_ID_LOCKED", "originalRequest": { "method": "PATCH", "header": [], "url": { "raw": "{{base_url}}/api/partner/organizations/{{child_org_id}}", "host": ["{{base_url}}/api/partner/organizations/{{child_org_id}}"] } }, "status": "Conflict", "code": 409, "_postman_previewlanguage": "json", "header": [{ "key": "Content-Type", "value": "application/json" }], "cookie": [], "body": "{\n \"error\": \"The tax ID is the sandbox TTN identity and cannot be changed\",\n \"code\": \"TAX_ID_LOCKED\",\n \"reason\": \"sandbox\"\n}" } ] }, { "name": "Mettre en pause", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{base_url}}/api/partner/organizations/{{child_org_id}}/pause", "host": ["{{base_url}}"], "path": ["api", "partner", "organizations", "{{child_org_id}}", "pause"] }, "description": "Suspend la création, la signature et l'envoi de factures, y compris en sandbox. La société reste dans le quota." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{base_url}}/api/partner/organizations/{{child_org_id}}/pause", "host": ["{{base_url}}/api/partner/organizations/{{child_org_id}}/pause"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [{ "key": "Content-Type", "value": "application/json" }], "cookie": [], "body": "{\n \"id\": \"child-org-uuid\",\n \"status\": \"active\",\n \"invoicingSuspendedAt\": \"2026-09-30T12:00:00.000Z\"\n}" } ] }, { "name": "Reprendre la facturation", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{base_url}}/api/partner/organizations/{{child_org_id}}/resume", "host": ["{{base_url}}"], "path": ["api", "partner", "organizations", "{{child_org_id}}", "resume"] }, "description": "Lève la pause. L'archive reste la suppression." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{base_url}}/api/partner/organizations/{{child_org_id}}/resume", "host": ["{{base_url}}/api/partner/organizations/{{child_org_id}}/resume"] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [{ "key": "Content-Type", "value": "application/json" }], "cookie": [], "body": "{\n \"id\": \"child-org-uuid\",\n \"status\": \"active\",\n \"invoicingSuspendedAt\": null\n}" } ] }, { "name": "Archiver une société créée", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{base_url}}/api/partner/organizations/{{child_org_id}}/archive", "host": [ "{{base_url}}" ], "path": [ "api", "partner", "organizations", "{{child_org_id}}", "archive" ] }, "description": "Archive une société créée par le partenaire. Un compte fatoora.tn rattaché s'arrête depuis le compte du propriétaire." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{base_url}}/api/partner/organizations/{{child_org_id}}/archive", "host": [ "{{base_url}}/api/partner/organizations/{{child_org_id}}/archive" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"id\": \"child-org-uuid\",\n \"status\": \"archived\"\n}" }, { "name": "409 USE_DETACH_OTP", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{base_url}}/api/partner/organizations/{{child_org_id}}/archive", "host": [ "{{base_url}}/api/partner/organizations/{{child_org_id}}/archive" ] } }, "status": "Conflict", "code": 409, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": \"The owner stops a linked company from their fatoora.tn account\",\n \"code\": \"USE_DETACH_OTP\"\n}" } ] } ] }, { "name": "3. Rattachement fatoora.tn", "item": [ { "name": "Demander le rattachement", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const json = pm.response.json();", "if (json.id) {", " pm.collectionVariables.set('link_request_id', json.id);", " console.log('link_request_id sauvegardé', json.id);", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"sourceOrganizationId\": \"{{source_organization_id}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/api/partner/link-requests", "host": [ "{{base_url}}" ], "path": [ "api", "partner", "link-requests" ] }, "description": "Ouvre une demande vers un compte fatoora.tn déjà existant. Le propriétaire l'accepte ou la refuse dans son compte. Le partenaire ne confirme pas le rattachement." }, "response": [ { "name": "201 Created", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{base_url}}/api/partner/link-requests", "host": [ "{{base_url}}/api/partner/link-requests" ] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"id\": \"link-request-uuid\",\n \"sourceOrganizationId\": \"existing-org-uuid\",\n \"status\": \"pending\"\n}" } ] }, { "name": "Lister les demandes", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{base_url}}/api/partner/link-requests?status=pending", "host": [ "{{base_url}}" ], "path": [ "api", "partner", "link-requests" ], "query": [ { "key": "status", "value": "pending", "description": "pending (en cours), expired, cancelled, rejected, approved, revoked. Omettre pour tout lister." } ] }, "description": "Liste les demandes du partenaire. status=pending regroupe les demandes en cours (pending et otp_sent). Une demande sans réponse expire après 7 jours. Le propriétaire accepte ou refuse depuis son compte fatoora.tn." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/partner/link-requests?status=pending", "host": [ "{{base_url}}/api/partner/link-requests?status=pending" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"requests\": [\n {\n \"id\": \"link-request-uuid\",\n \"sourceOrganizationId\": \"existing-org-uuid\",\n \"sourceOrganizationName\": \"Société cliente\",\n \"sourceTaxId\": \"1234567A\",\n \"status\": \"pending\"\n }\n ]\n}" } ] }, { "name": "Annuler une demande en cours", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{base_url}}/api/partner/link-requests/{{link_request_id}}/cancel", "host": [ "{{base_url}}" ], "path": [ "api", "partner", "link-requests", "{{link_request_id}}", "cancel" ] }, "description": "Annule une demande encore en cours. Une demande expirée, refusée ou déjà acceptée ne peut pas être annulée." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{base_url}}/api/partner/link-requests/{{link_request_id}}/cancel", "host": [ "{{base_url}}/api/partner/link-requests/{{link_request_id}}/cancel" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"cancelled\"\n}" }, { "name": "400 REQUEST_EXPIRED", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{base_url}}/api/partner/link-requests/{{link_request_id}}/cancel", "host": [ "{{base_url}}/api/partner/link-requests/{{link_request_id}}/cancel" ] } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": \"This request has expired\",\n \"code\": \"REQUEST_EXPIRED\"\n}" } ] } ] } ] }