# API : search

1 opérations REST du groupe search.

Base : `/api/v1`. [Conventions](/documentation/api-conventions/) · [Toutes les ressources](/documentation/api-reference/)

- GET /search : Recherche globale (texte : contexte utilisateur ; identifiant externe : les deux realms)
## GET /search

```json
{
  "summary": "Recherche globale (texte : contexte utilisateur ; identifiant externe : les deux realms)",
  "description": "Les HUIT enregistrements (T-1430, ADR-176 D2 ; commandes depuis #427) : sociétés, contacts, devis, contrats, commandes, factures, requêtes, activités commerciales - mêmes règles que la recherche de l'UI web (5 par groupe, casse et accents repliés, corbeille et contacts anonymisés exclus), visibilité du principal appliquée groupe par groupe. Mode texte (`q`) : requête vide = les plus récents par catégorie ; réservé aux sessions utilisateur (§2bis), 403 pour une app connectée. Mode identifiant externe (`externalId`, `externalSource` facultatif, T-1197) : les objets qui portent cet identifiant exact, ouvert aux apps connectées dans leur périmètre et pour les objets de leurs scopes de lecture (un objet hors scope = liste vide) ; il ne couvre que les objets qu'`external_ref` porte (société, contact, devis, facture, contrat), `requests` et `activities` y répondent vide ; `q` et `externalId` ne se combinent pas (422). Les contrats et les commandes se lisent sous `quotes:read`, comme la ressource `/contracts` ; `orders` répond vide en mode identifiant externe (external_ref ne porte pas la commande). La facture et l'activité n'ont pas de page de fiche : leur `ref` porte la clé de loupe de leur liste.",
  "tags": [
    "mobile"
  ],
  "parameters": [
    {
      "name": "q",
      "in": "query",
      "required": false,
      "schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "description": "Texte recherché (vide = récents) - contexte utilisateur",
        "type": "string"
      }
    },
    {
      "name": "externalId",
      "in": "query",
      "required": false,
      "schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "description": "Objets qui portent cet identifiant externe (exact) - avec `externalSource` pour une source précise",
        "type": "string"
      }
    },
    {
      "name": "externalSource",
      "in": "query",
      "required": false,
      "schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "description": "Source de l'identifiant externe (`tacto`…)",
        "type": "string"
      }
    }
  ],
  "security": [
    {
      "oauth2": []
    },
    {
      "userSession": []
    }
  ],
  "responses": {
    "200": {
      "description": "Résultats par catégorie",
      "content": {
        "application/json": {
          "schema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
              "companies": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "company",
                        "contact",
                        "quote",
                        "contract",
                        "order",
                        "invoice",
                        "request",
                        "salesActivity",
                        "article"
                      ]
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                    },
                    "title": {
                      "type": "string"
                    },
                    "sub": {
                      "type": "string"
                    },
                    "ref": {
                      "description": "Clé de loupe des objets sans page de fiche (numéro de facture, titre d'activité) : de quoi ouvrir la liste correspondante sur la ligne visée",
                      "type": "string"
                    }
                  },
                  "required": [
                    "kind",
                    "id",
                    "title",
                    "sub"
                  ],
                  "additionalProperties": false
                },
                "description": "Résultats sociétés (5 au plus)"
              },
              "contacts": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "company",
                        "contact",
                        "quote",
                        "contract",
                        "order",
                        "invoice",
                        "request",
                        "salesActivity",
                        "article"
                      ]
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                    },
                    "title": {
                      "type": "string"
                    },
                    "sub": {
                      "type": "string"
                    },
                    "ref": {
                      "description": "Clé de loupe des objets sans page de fiche (numéro de facture, titre d'activité) : de quoi ouvrir la liste correspondante sur la ligne visée",
                      "type": "string"
                    }
                  },
                  "required": [
                    "kind",
                    "id",
                    "title",
                    "sub"
                  ],
                  "additionalProperties": false
                },
                "description": "Résultats contacts (5 au plus)"
              },
              "quotes": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "company",
                        "contact",
                        "quote",
                        "contract",
                        "order",
                        "invoice",
                        "request",
                        "salesActivity",
                        "article"
                      ]
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                    },
                    "title": {
                      "type": "string"
                    },
                    "sub": {
                      "type": "string"
                    },
                    "ref": {
                      "description": "Clé de loupe des objets sans page de fiche (numéro de facture, titre d'activité) : de quoi ouvrir la liste correspondante sur la ligne visée",
                      "type": "string"
                    }
                  },
                  "required": [
                    "kind",
                    "id",
                    "title",
                    "sub"
                  ],
                  "additionalProperties": false
                },
                "description": "Résultats devis (5 au plus)"
              },
              "contracts": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "company",
                        "contact",
                        "quote",
                        "contract",
                        "order",
                        "invoice",
                        "request",
                        "salesActivity",
                        "article"
                      ]
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                    },
                    "title": {
                      "type": "string"
                    },
                    "sub": {
                      "type": "string"
                    },
                    "ref": {
                      "description": "Clé de loupe des objets sans page de fiche (numéro de facture, titre d'activité) : de quoi ouvrir la liste correspondante sur la ligne visée",
                      "type": "string"
                    }
                  },
                  "required": [
                    "kind",
                    "id",
                    "title",
                    "sub"
                  ],
                  "additionalProperties": false
                },
                "description": "Résultats contrats (5 au plus)"
              },
              "orders": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "company",
                        "contact",
                        "quote",
                        "contract",
                        "order",
                        "invoice",
                        "request",
                        "salesActivity",
                        "article"
                      ]
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                    },
                    "title": {
                      "type": "string"
                    },
                    "sub": {
                      "type": "string"
                    },
                    "ref": {
                      "description": "Clé de loupe des objets sans page de fiche (numéro de facture, titre d'activité) : de quoi ouvrir la liste correspondante sur la ligne visée",
                      "type": "string"
                    }
                  },
                  "required": [
                    "kind",
                    "id",
                    "title",
                    "sub"
                  ],
                  "additionalProperties": false
                },
                "description": "Résultats commandes (5 au plus)"
              },
              "invoices": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "company",
                        "contact",
                        "quote",
                        "contract",
                        "order",
                        "invoice",
                        "request",
                        "salesActivity",
                        "article"
                      ]
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                    },
                    "title": {
                      "type": "string"
                    },
                    "sub": {
                      "type": "string"
                    },
                    "ref": {
                      "description": "Clé de loupe des objets sans page de fiche (numéro de facture, titre d'activité) : de quoi ouvrir la liste correspondante sur la ligne visée",
                      "type": "string"
                    }
                  },
                  "required": [
                    "kind",
                    "id",
                    "title",
                    "sub"
                  ],
                  "additionalProperties": false
                },
                "description": "Résultats factures (5 au plus)"
              },
              "requests": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "company",
                        "contact",
                        "quote",
                        "contract",
                        "order",
                        "invoice",
                        "request",
                        "salesActivity",
                        "article"
                      ]
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                    },
                    "title": {
                      "type": "string"
                    },
                    "sub": {
                      "type": "string"
                    },
                    "ref": {
                      "description": "Clé de loupe des objets sans page de fiche (numéro de facture, titre d'activité) : de quoi ouvrir la liste correspondante sur la ligne visée",
                      "type": "string"
                    }
                  },
                  "required": [
                    "kind",
                    "id",
                    "title",
                    "sub"
                  ],
                  "additionalProperties": false
                },
                "description": "Résultats requêtes (5 au plus)"
              },
              "activities": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "company",
                        "contact",
                        "quote",
                        "contract",
                        "order",
                        "invoice",
                        "request",
                        "salesActivity",
                        "article"
                      ]
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                    },
                    "title": {
                      "type": "string"
                    },
                    "sub": {
                      "type": "string"
                    },
                    "ref": {
                      "description": "Clé de loupe des objets sans page de fiche (numéro de facture, titre d'activité) : de quoi ouvrir la liste correspondante sur la ligne visée",
                      "type": "string"
                    }
                  },
                  "required": [
                    "kind",
                    "id",
                    "title",
                    "sub"
                  ],
                  "additionalProperties": false
                },
                "description": "Résultats activités commerciales (5 au plus)"
              },
              "articles": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "company",
                        "contact",
                        "quote",
                        "contract",
                        "order",
                        "invoice",
                        "request",
                        "salesActivity",
                        "article"
                      ]
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                    },
                    "title": {
                      "type": "string"
                    },
                    "sub": {
                      "type": "string"
                    },
                    "ref": {
                      "description": "Clé de loupe des objets sans page de fiche (numéro de facture, titre d'activité) : de quoi ouvrir la liste correspondante sur la ligne visée",
                      "type": "string"
                    }
                  },
                  "required": [
                    "kind",
                    "id",
                    "title",
                    "sub"
                  ],
                  "additionalProperties": false
                },
                "description": "Résultats articles publiés de la base de connaissances (#1061) (5 au plus)"
              }
            },
            "required": [
              "companies",
              "contacts",
              "quotes",
              "contracts",
              "orders",
              "invoices",
              "requests",
              "activities",
              "articles"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "default": {
      "description": "Erreur - enveloppe problem+json (RFC 9457)",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    }
  }
}
```