{
  "openapi": "3.1.1",
  "info": {
    "title": "mrnew · API des étiquettes",
    "version": "1.0.0",
    "description": "API locale pour gérer le carnet de destinataires et exporter des étiquettes Amazon ou Mondial Relay."
  },
  "servers": [
    {
      "url": "/",
      "description": "Instance mrnew qui sert ce document."
    }
  ],
  "paths": {
    "/api/v1/destinations": {
      "get": {
        "operationId": "listDestinations",
        "summary": "Lister les fiches du carnet",
        "parameters": [
          {
            "name": "mode",
            "in": "query",
            "description": "Restreint la liste aux destinations utilisables dans ce format.",
            "schema": { "$ref": "#/components/schemas/Mode" }
          }
        ],
        "responses": {
          "200": {
            "description": "Liste des fiches.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["items"],
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Destination" }
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      },
      "post": {
        "operationId": "addDestination",
        "summary": "Ajouter ou réutiliser une fiche du carnet",
        "description": "Réutilise une fiche ayant la même adresse imprimée normalisée, le même pays, la même agence et la même tournée. Le nom dans le carnet peut différer. La fiche existante conserve ses données.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/NewDestination" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Fiche existante réutilisée avec son identifiant et ses données.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Destination" } }
            }
          },
          "201": {
            "description": "Fiche créée.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Destination" } }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "422": { "$ref": "#/components/responses/InvalidInput" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/api/v1/destinations/suggest": {
      "post": {
        "operationId": "suggestDestinations",
        "summary": "Proposer des fiches du carnet pour un suivi",
        "description": "Pour Mondial Relay, un suivi enregistré ou une tournée unique dans le même HUB permet une sélection automatique. Pour Amazon, les fiches de Satolas et Longvic sont proposées.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SuggestionRequest" },
              "example": { "tracking": "85734727210101304362001442", "limit": 5 }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Fiches proposées, classées par correspondance.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Suggestions" } }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "422": { "$ref": "#/components/responses/InvalidInput" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/api/v1/destinations/discover": {
      "get": {
        "operationId": "discoverDestinations",
        "summary": "Chercher une adresse publique",
        "description": "Recherche par nom public ou lieu. Les résultats servent de brouillons et peuvent inclure des fiches déjà enregistrées au même site. La recherche ne modifie pas le carnet.",
        "parameters": [
          {
            "name": "q", "in": "query",
            "schema": { "type": "string", "minLength": 2, "maxLength": 100 },
            "description": "Nom d’entreprise, lieu ou SIRET. Fournir q ou postal_code."
          },
          {
            "name": "postal_code", "in": "query",
            "schema": { "type": "string", "pattern": "^[0-9]{5}$" },
            "description": "Code postal français facultatif."
          }
        ],
        "responses": {
          "200": {
            "description": "Adresses publiques, sources et avertissements éventuels.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveredDestinations" } }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "422": { "$ref": "#/components/responses/InvalidInput" },
          "502": {
            "description": "Toutes les sources configurées sont indisponibles.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },
    "/api/v1/labels": {
      "post": {
        "operationId": "generateLabel",
        "summary": "Générer une étiquette PNG",
        "description": "Un suivi de 10 chiffres utilise le format Amazon. Un suivi de 26 chiffres utilise le format Mondial Relay.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/LabelRequest" },
              "example": { "tracking": "8573472721", "destination": "satolas" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Fichier PNG.",
            "headers": {
              "X-Tracking-Number": {
                "description": "Numéro encodé dans le code-barres.",
                "schema": { "type": "string", "pattern": "^[0-9]{26}$" }
              },
              "Content-Disposition": { "$ref": "#/components/headers/FileDownload" }
            },
            "content": {
              "image/png": { "schema": { "contentMediaType": "image/png" } }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "404": { "$ref": "#/components/responses/DestinationNotFound" },
          "422": { "$ref": "#/components/responses/InvalidInput" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/api/v1/labels/batch": {
      "post": {
        "operationId": "generateLabelBatch",
        "summary": "Générer un lot d’étiquettes en ZIP",
        "description": "Toutes les lignes utilisent le même format et le même destinataire. Un nom et une adresse d’expéditeur différents sont générés pour chaque PNG.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/BatchRequest" },
              "example": {
                "tracking_numbers": ["8573472721", "8573473321"],
                "destination": "longvic"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Archive ZIP contenant les PNG dans l’ordre des suivis.",
            "headers": {
              "Content-Disposition": { "$ref": "#/components/headers/FileDownload" }
            },
            "content": {
              "application/zip": { "schema": { "contentMediaType": "application/zip" } }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "404": { "$ref": "#/components/responses/DestinationNotFound" },
          "422": { "$ref": "#/components/responses/InvalidInput" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/api/v1/openapi.json": {
      "get": {
        "operationId": "getOpenApi",
        "summary": "Lire le contrat OpenAPI",
        "responses": {
          "200": {
            "description": "Document OpenAPI de cette version.",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "FileDownload": {
        "description": "Nom conseillé pour le fichier téléchargé.",
        "schema": { "type": "string" }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "JSON, structure ou paramètre de requête invalide.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "DestinationNotFound": {
        "description": "Fiche de destination introuvable.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "InvalidInput": {
        "description": "Données incompatibles avec la génération ou l’enregistrement.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "InternalError": {
        "description": "Impossible de traiter la demande.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "schemas": {
      "Mode": {
        "type": "string",
        "enum": ["amazon", "mondial_relay"]
      },
      "Alias": {
        "type": "string",
        "enum": ["satolas", "longvic"]
      },
      "DestinationSelector": {
        "description": "Identifiant d’une fiche ou alias d’une destination Amazon. Amazon accepte uniquement les fiches de Satolas et Longvic.",
        "oneOf": [
          { "type": "integer", "minimum": 1 },
          { "$ref": "#/components/schemas/Alias" }
        ]
      },
      "SingleDestinationSelector": {
        "description": "Utiliser auto uniquement pour une correspondance unique. Une réponse 422 avec le code destination_choice_required demande de choisir une fiche dans les suggestions.",
        "oneOf": [
          { "$ref": "#/components/schemas/DestinationSelector" },
          { "type": "string", "const": "auto" }
        ]
      },
      "Destination": {
        "type": "object",
        "required": ["id", "name", "address", "modes"],
        "properties": {
          "id": { "type": "integer", "minimum": 1 },
          "name": { "type": "string", "description": "Nom de la fiche dans le carnet." },
          "slug": { "$ref": "#/components/schemas/Alias" },
          "address": { "type": "array", "items": { "type": "string" } },
          "agency_code": { "type": "string", "description": "Code agence enregistré, si renseigné." },
          "reference": { "type": "string", "description": "Tournée enregistrée, si renseignée." },
          "modes": { "type": "array", "items": { "$ref": "#/components/schemas/Mode" } }
        }
      },
      "NewDestination": {
        "type": "object",
        "required": ["name", "address", "agency_code", "reference"],
        "properties": {
          "name": { "type": "string", "minLength": 1, "description": "Nom de la fiche dans le carnet." },
          "address": {
            "type": "array",
            "minItems": 1,
            "maxItems": 3,
            "items": { "type": "string", "minLength": 1 },
            "description": "Lignes d’adresse imprimées dans l’ordre."
          },
          "agency_code": { "type": "string", "minLength": 1, "examples": ["AG 436"] },
          "reference": { "type": "string", "minLength": 1, "examples": ["T 144"] },
          "country": { "type": "string", "minLength": 2, "maxLength": 2, "default": "FR" }
        }
      },
      "TrackingNumber": {
        "type": "string",
        "pattern": "^\\s*(?:[0-9]\\s*){10}(?:(?:[0-9]\\s*){16})?$",
        "description": "10 chiffres pour Amazon ou 26 chiffres pour Mondial Relay. Les espaces sont ignorés. Envoyer une chaîne pour préserver les zéros initiaux.",
        "examples": ["8573472721", "85734727210101304362001442"]
      },
      "SuggestionRequest": {
        "type": "object",
        "required": ["tracking"],
        "properties": {
          "tracking": { "$ref": "#/components/schemas/TrackingNumber" },
          "limit": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5 }
        }
      },
      "Suggestions": {
        "type": "object",
        "required": ["mode", "hub", "reference", "items", "auto_select_id"],
        "properties": {
          "mode": { "$ref": "#/components/schemas/Mode" },
          "hub": { "type": ["string", "null"] },
          "reference": { "type": ["string", "null"] },
          "auto_select_id": {
            "type": ["integer", "null"],
            "description": "Fiche proposée automatiquement si la correspondance est unique."
          },
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/SuggestedDestination" } }
        }
      },
      "SuggestedDestination": {
        "allOf": [
          { "$ref": "#/components/schemas/Destination" },
          {
            "type": "object",
            "required": ["match"],
            "properties": {
              "match": { "type": "string", "enum": ["tracking", "agency_reference", "agency", "amazon_option"] }
            }
          }
        ]
      },
      "DiscoveredDestinations": {
        "type": "object",
        "required": ["items", "sources", "warnings"],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["name", "address", "country", "source", "source_url"],
              "properties": {
                "name": { "type": "string" },
                "address": { "type": "array", "items": { "type": "string" } },
                "country": { "type": "string" },
                "source": { "type": "string" },
                "source_url": { "type": "string", "format": "uri" },
                "siret": { "type": "string" },
                "existing_destinations": {
                  "type": "array",
                  "description": "Fiches du carnet dont la rue, le code postal et la ville correspondent au site après normalisation. Plusieurs destinataires ou tournées peuvent partager cette adresse.",
                  "items": { "$ref": "#/components/schemas/Destination" }
                }
              }
            }
          },
          "sources": { "type": "array", "items": { "type": "string" } },
          "warnings": { "type": "array", "items": { "type": "string" } }
        }
      },
      "Sender": {
        "type": "object",
        "required": ["name", "street", "city"],
        "properties": {
          "name": { "type": "string", "minLength": 1 },
          "street": { "type": "string", "minLength": 1 },
          "city": { "type": "string", "minLength": 1, "description": "Code postal et ville à imprimer." }
        }
      },
      "LabelRequest": {
        "type": "object",
        "required": ["tracking", "destination"],
        "properties": {
          "tracking": { "$ref": "#/components/schemas/TrackingNumber" },
          "destination": { "$ref": "#/components/schemas/SingleDestinationSelector" },
          "sender": { "$ref": "#/components/schemas/Sender" }
        }
      },
      "BatchRequest": {
        "type": "object",
        "required": ["tracking_numbers", "destination"],
        "properties": {
          "tracking_numbers": {
            "type": "array",
            "minItems": 1,
            "maxItems": 50,
            "uniqueItems": true,
            "items": { "$ref": "#/components/schemas/TrackingNumber" }
          },
          "destination": { "$ref": "#/components/schemas/DestinationSelector" },
          "sender_seed": {
            "type": "string",
            "description": "Réutiliser la même valeur pour retrouver les mêmes expéditeurs lors d’un nouvel export du même lot."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" },
              "details": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": ["line", "message"],
                  "properties": {
                    "line": { "type": "integer", "minimum": 1 },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
