Companies

Every route below requires the Connect manager session and a partner-connect-* plan.

List

GET /api/partner/organizations
Authorization: Bearer ACCESS_TOKEN

The response includes created companies and linked accounts, the latest seal and TTN status, hasLogo, invoicingSuspendedAt, taxIdLocked, taxIdLockReason, the active company count, the limit, the monthly quota, and link requests. The base64 logo is not in the list.

Read

GET /api/partner/organizations/{childOrgId}

Same profile as the list, plus logoBase64. taxIdLocked is true or false. taxIdLockReason is sandbox (mock identity), ttn_submitted (an invoice was already sent to TTN), or null when the tax ID can still change.

Create

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

{
  "name": "Client company SARL",
  "taxId": "1234567A",
  "managerEmail": "manager@client.tn",
  "phone": "71111222",
  "street": "Avenue Habib Bourguiba",
  "city": "Tunis",
  "postalCode": "1000",
  "ttnLogin": "ttn-login",
  "ttnPassword": "ttn-secret",
  "sealAlias": "seal-alias",
  "sealPin": "seal-pin"
}

Fatoora creates the child company, copies the Connect subscription, and grants invoicing (invoice:read, invoice:write, ttn:submit, seal:sign). If TTN or seal credentials are sent, the tests run immediately.

Name, manager email, phone, and address are required. logoBase64 is optional: a png, jpeg, gif, or webp data URL, about 500 KB. In the sandbox, the create response includes taxIdLocked: true and taxIdLockReason: "sandbox".

Update the profile

PATCH /api/partner/organizations/{childOrgId}

Optional fields, at least one: name, taxId, managerEmail, phone, street, city, postalCode, logoBase64. A missing field is left unchanged. logoBase64: null removes the logo.

Only for a company you created. A linked account returns 409 USE_DETACH_OTP. An archived company returns 409 CHILD_ARCHIVED.

When taxIdLocked is true, a different tax ID returns 409 TAX_ID_LOCKED with the same reason as GET. In the sandbox the tax ID does not change: the TTN login and SEAL alias are that tax ID. In production it locks after a TTN submission. Name, address, phone, email, and logo stay editable.

Pause

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

Pause rejects invoice creation, signature, and sending (409 INVOICING_SUSPENDED), including in the sandbox. The company still counts toward the quota, and reads stay open. Resume sets invoicingSuspendedAt back to null. Archive, below, is the deletion: it frees the quota.

Seal and TTN

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

Omitted fields are left unchanged. ttnPassword and sealPin are never returned in clear text.

Run a check again:

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

The latest result is stored on the company (ttnLastCredentialsOk, sealLastTestOk).

Archive

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

Only for a company you created. A linked fatoora.tn account is not archived this way: the owner stops the link from their account (USE_DETACH_OTP). See Linking.

Errors when creating

Code	HTTP	Meaning
TAX_ID_EXISTS	409	An existing fatoora.tn account. Do not create it again: link it. The response lists organizations.
ALREADY_LINKED	409	This company is already in your portfolio.
NOT_LINKABLE	409	The tax ID exists, but it cannot be created or linked. Read reason.
CONNECT_ORG_LIMIT	409	Company limit reached.
CONNECT_PLAN_REQUIRED	403	The account is not a Connect plan.
NOT_ALLOWED	403	Owner or manager role required.
TAX_ID_LOCKED	409	The tax ID can no longer change. reason: sandbox or ttn_submitted.
INVOICING_SUSPENDED	409	Company is paused. Resume it before invoicing.
CHILD_ARCHIVED	409	Archived company: profile updates and pause no longer apply.
LOGO_INVALID	400	The logo must be a PNG, JPEG, GIF, or WebP data URL.
LOGO_TOO_LARGE	400	Logo is too large (about 500 KB).

reason values for NOT_LINKABLE:

• own_child — already in your companies.
• managed_elsewhere — already managed by another Connect or a Cabinet.
• partner_or_cabinet — a Partner or Cabinet account, not a standard fatoora.tn company.