{
  "openapi": "3.1.0",
  "info": {
    "title": "Entrada de venta de FIGITAL",
    "version": "1.0.0",
    "description": "Una sola entrada para que el punto de venta de cualquier cliente mande su venta a FIGITAL: un envío por día de negocio, con sus tiendas y sus tickets. Todo o nada por envío; reenviar un día sustituye, por tienda, lo que había. Importes sin IVA y siempre en positivo: el tipo de ticket da el signo."
  },
  "servers": [
    {
      "url": "https://api-pruebas.figital.pro",
      "description": "Staging: para probar, con una clave «fp_test_»."
    },
    {
      "url": "https://api.figital.pro",
      "description": "Producción: con una clave «fp_live_», cuando tu envío ya entra limpio en staging."
    }
  ],
  "security": [
    {
      "clave": []
    }
  ],
  "x-limites": {
    "bytesPorEnvio": 5000000,
    "bytesPorEnvioTexto": "5 MB",
    "toleranciaDelTotal": 0.01,
    "decimalesDeImporte": 2,
    "diasPorResumen": 31
  },
  "x-prefijos-de-clave": {
    "staging": "fp_test_",
    "produccion": "fp_live_"
  },
  "x-errores": [
    {
      "codigo": "clave_ausente",
      "grupo": "clave",
      "http": 401,
      "titulo": "El envío no trae clave.",
      "esperado": "La cabecera «Authorization: Bearer <tu clave>».",
      "pista": "La clave de staging empieza por «fp_test_» y la de producción por «fp_live_». Si no tienes una, pídela a FIGITAL."
    },
    {
      "codigo": "clave_invalida",
      "grupo": "clave",
      "http": 401,
      "titulo": "La clave no es de ningún cliente.",
      "esperado": "Una clave vigente, emitida por FIGITAL para este entorno.",
      "pista": "Una clave de staging («fp_test_») no entra en producción, ni al revés. Revisa que la copiaste entera."
    },
    {
      "codigo": "clave_revocada",
      "grupo": "clave",
      "http": 401,
      "titulo": "La clave fue revocada.",
      "esperado": "Una clave vigente.",
      "pista": "Pide a FIGITAL una clave nueva; la revocada no vuelve a entrar."
    },
    {
      "codigo": "ruta_desconocida",
      "grupo": "formato",
      "http": 404,
      "titulo": "Esa ruta o ese método no existen.",
      "esperado": "POST /v1/recibir, POST /v1/ensayar o GET /v1/resumen.",
      "pista": "La versión va en la ruta: «/v1/…»."
    },
    {
      "codigo": "envio_demasiado_grande",
      "grupo": "limites",
      "http": 413,
      "titulo": "El envío pasa del tamaño máximo.",
      "esperado": "Un cuerpo de {limite} como mucho.",
      "pista": "Parte el día por tiendas y manda varios envíos: cada uno sustituye solo las tiendas que trae, así que partirlo no rompe nada."
    },
    {
      "codigo": "json_invalido",
      "grupo": "formato",
      "http": 400,
      "titulo": "El cuerpo no es JSON.",
      "esperado": "Un objeto JSON en UTF-8, con «Content-Type: application/json».",
      "pista": "Valida el cuerpo con cualquier lector de JSON antes de mandarlo."
    },
    {
      "codigo": "campo_requerido",
      "grupo": "formato",
      "http": 422,
      "titulo": "Falta un campo obligatorio.",
      "esperado": "El campo «{campo}».",
      "pista": "Los campos obligatorios de cada objeto están en la sección «El envío» de la página."
    },
    {
      "codigo": "campo_desconocido",
      "grupo": "formato",
      "http": 422,
      "titulo": "El envío trae un campo que el contrato no tiene.",
      "esperado": "Solo los campos del contrato.",
      "pista": "Revisa cómo está escrito: un campo mal escrito no se ignora, porque se perdería un dato sin que nadie lo note."
    },
    {
      "codigo": "tipo_de_dato_invalido",
      "grupo": "formato",
      "http": 422,
      "titulo": "El valor no es del tipo que pide el campo.",
      "esperado": "Un valor de tipo {tipo}.",
      "pista": "Los importes y las cantidades van como número JSON (sin comillas); los códigos y folios, como texto (con comillas)."
    },
    {
      "codigo": "texto_vacio",
      "grupo": "formato",
      "http": 422,
      "titulo": "Un texto obligatorio llegó vacío.",
      "esperado": "Un texto con al menos un carácter que no sea espacio.",
      "pista": "Si el dato no existe en tu sistema, pregunta a FIGITAL antes de inventarlo."
    },
    {
      "codigo": "dia_invalido",
      "grupo": "formato",
      "http": 422,
      "titulo": "La fecha no es una fecha válida.",
      "esperado": "Una fecha AAAA-MM-DD, como 2026-11-15.",
      "pista": "Es el día de negocio, sin hora ni zona."
    },
    {
      "codigo": "dia_en_el_futuro",
      "grupo": "datos",
      "http": 422,
      "titulo": "El día de negocio todavía no termina.",
      "esperado": "Un día anterior a hoy, en la hora de la tienda.",
      "pista": "Manda cada día cuando ya cerró: lo normal es mandar ayer, hoy temprano."
    },
    {
      "codigo": "dia_anterior_a_la_historia",
      "grupo": "datos",
      "http": 422,
      "titulo": "El día es anterior al inicio de tu historia.",
      "esperado": "Un día desde el {historia_desde}.",
      "pista": "FIGITAL declaró que tu historia empieza el {historia_desde}; los días anteriores no se guardan. Si necesitas más historia, pídelo."
    },
    {
      "codigo": "rango_invalido",
      "grupo": "limites",
      "http": 422,
      "titulo": "El rango del resumen no es válido.",
      "esperado": "«desde» menor o igual que «hasta», y como mucho {dias} días.",
      "pista": "Para un periodo largo, pide el resumen por tramos."
    },
    {
      "codigo": "envio_sin_tiendas",
      "grupo": "datos",
      "http": 422,
      "titulo": "El envío no trae ninguna tienda.",
      "esperado": "Al menos una tienda en «tiendas».",
      "pista": "Una tienda que no vendió va con su lista de tickets vacía; un envío sin tiendas no sustituye nada."
    },
    {
      "codigo": "tienda_sin_emparejar",
      "grupo": "datos",
      "http": 422,
      "titulo": "Ese código de tienda no está dado de alta.",
      "esperado": "Un código de tienda dado de alta para tu clave.",
      "pista": "Los dados de alta para tu clave son: {codigos}. Si es una tienda nueva, pide a FIGITAL que la empareje: la entrada nunca crea tiendas."
    },
    {
      "codigo": "tienda_repetida",
      "grupo": "datos",
      "http": 422,
      "titulo": "La misma tienda viene dos veces en el envío.",
      "esperado": "Cada tienda una sola vez, con todos sus tickets del día.",
      "pista": "Junta sus tickets en una sola entrada de «tiendas»."
    },
    {
      "codigo": "folio_repetido",
      "grupo": "datos",
      "http": 422,
      "titulo": "El folio se repite en la misma tienda y caja.",
      "esperado": "Un folio único por tienda y caja en el día.",
      "pista": "Si son dos tickets distintos, manda la caja de cada uno; si es el mismo, mándalo una vez."
    },
    {
      "codigo": "fecha_hora_invalida",
      "grupo": "formato",
      "http": 422,
      "titulo": "La fecha y hora del ticket no son válidas.",
      "esperado": "Fecha y hora locales de la tienda, AAAA-MM-DDThh:mm:ss, sin zona: 2026-11-15T13:42:05.",
      "pista": "Es la hora del reloj de la tienda; no la conviertas a UTC ni le pongas «Z»."
    },
    {
      "codigo": "fecha_hora_fuera_del_dia",
      "grupo": "datos",
      "http": 422,
      "titulo": "El ticket no es del día de negocio del envío.",
      "esperado": "Una fecha del {dia}, o del día siguiente si la tienda cierra después de medianoche.",
      "pista": "Manda cada ticket en el envío de su día de negocio."
    },
    {
      "codigo": "tipo_de_ticket_invalido",
      "grupo": "formato",
      "http": 422,
      "titulo": "El tipo de ticket no existe.",
      "esperado": "venta, devolucion o cancelacion.",
      "pista": "Sin acentos y en minúsculas. El tipo da el signo: los números van siempre en positivo."
    },
    {
      "codigo": "folio_original_requerido",
      "grupo": "datos",
      "http": 422,
      "titulo": "La devolución no dice qué ticket devuelve.",
      "esperado": "El folio del ticket de venta original en «folio_original».",
      "pista": "No tiene que ser un ticket que nos hayas mandado: puede ser anterior al inicio de tu historia."
    },
    {
      "codigo": "ticket_sin_renglones",
      "grupo": "datos",
      "http": 422,
      "titulo": "El ticket no trae renglones.",
      "esperado": "Al menos un renglón.",
      "pista": "Un día sin venta se manda como la tienda con la lista de tickets vacía, no como un ticket vacío."
    },
    {
      "codigo": "total_no_cuadra",
      "grupo": "datos",
      "http": 422,
      "titulo": "El total del ticket no cuadra con sus renglones.",
      "esperado": "La suma de los importes de sus renglones, {suma}, con tolerancia de {tolerancia}.",
      "pista": "Los dos van sin IVA y después del descuento. Si el total incluye IVA, quítaselo."
    },
    {
      "codigo": "numero_negativo",
      "grupo": "datos",
      "http": 422,
      "titulo": "Un importe, un descuento o un total llegó negativo.",
      "esperado": "Un número mayor o igual que 0.",
      "pista": "Todo va en positivo: el tipo de ticket (devolucion) da el signo, no el número."
    },
    {
      "codigo": "cantidad_no_positiva",
      "grupo": "datos",
      "http": 422,
      "titulo": "La cantidad del renglón no es mayor que cero.",
      "esperado": "Un número mayor que 0.",
      "pista": "En una devolución la cantidad también va en positivo. Un renglón sin unidades no se manda."
    },
    {
      "codigo": "demasiados_decimales",
      "grupo": "limites",
      "http": 422,
      "titulo": "El importe trae más decimales de los que tiene la moneda.",
      "esperado": "Como mucho {decimales} decimales.",
      "pista": "Redondea al centavo antes de mandarlo, y cuadra el total con los renglones ya redondeados."
    }
  ],
  "x-grupos-de-error": {
    "clave": "La clave",
    "formato": "El formato",
    "datos": "Los datos",
    "limites": "Los límites"
  },
  "paths": {
    "/v1/recibir": {
      "post": {
        "operationId": "recibirDia",
        "summary": "Recibir el día",
        "description": "Guarda el día de las tiendas que trae el envío. Sustituye completo lo que FIGITAL tenía de cada una de esas tiendas en ese día; las tiendas que no vienen no se tocan. Si hay un solo error, no guarda nada y devuelve todos los errores. Reintentar el mismo envío da el mismo resultado.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Envio"
              },
              "example": {
                "dia": "2026-11-15",
                "tiendas": [
                  {
                    "tienda": "110",
                    "tickets": [
                      {
                        "caja": "2",
                        "folio": "A-48211",
                        "fecha_hora": "2026-11-15T13:42:05",
                        "tipo": "venta",
                        "vendedor": {
                          "codigo": "V017",
                          "nombre": "Laura Méndez"
                        },
                        "total": 1637.93,
                        "renglones": [
                          {
                            "articulo": {
                              "codigo": "2790090-39",
                              "nombre": "Bota Chelsea negra 39"
                            },
                            "cantidad": 1,
                            "importe": 1293.1,
                            "descuento": 143.68
                          },
                          {
                            "articulo": {
                              "codigo": "5510021",
                              "nombre": "Calcetín deportivo"
                            },
                            "cantidad": 2,
                            "importe": 344.83,
                            "descuento": 0
                          }
                        ]
                      },
                      {
                        "folio": "A-48230",
                        "fecha_hora": "2026-11-15T17:05:51",
                        "tipo": "devolucion",
                        "folio_original": "A-47002",
                        "vendedor": {
                          "codigo": "V017",
                          "nombre": "Laura Méndez"
                        },
                        "total": 344.83,
                        "renglones": [
                          {
                            "articulo": {
                              "codigo": "5510021",
                              "nombre": "Calcetín deportivo"
                            },
                            "cantidad": 2,
                            "importe": 344.83,
                            "descuento": 0
                          }
                        ]
                      }
                    ]
                  },
                  {
                    "tienda": "112",
                    "tickets": []
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "El día quedó guardado. Por tienda, lo que quedó.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespuestaDelEnvio"
                },
                "example": {
                  "envio": "6f1d3c2a-9b0e-4c57-8a51-2f7e0d4b9c11",
                  "ensayo": false,
                  "dia": "2026-11-15",
                  "tiendas": [
                    {
                      "tienda": "110",
                      "tickets": 1,
                      "devoluciones": 1,
                      "cancelaciones": 0,
                      "unidades": 1,
                      "importe": 1293.1
                    },
                    {
                      "tienda": "112",
                      "tickets": 0,
                      "devoluciones": 0,
                      "cancelaciones": 0,
                      "unidades": 0,
                      "importe": 0
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "El cuerpo no es JSON (json_invalido).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "codigo": "envio_rechazado",
                  "mensaje": "El envío tiene 2 errores y no se guardó nada.",
                  "errores": [
                    {
                      "codigo": "total_no_cuadra",
                      "tienda": "110",
                      "ticket": "A-48211",
                      "renglon": null,
                      "campo": "tiendas[0].tickets[0].total",
                      "recibido": 1900,
                      "esperado": "La suma de los importes de sus renglones, 1637.93, con tolerancia de 0.01.",
                      "pista": "Los dos van sin IVA y después del descuento. Si el total incluye IVA, quítaselo."
                    },
                    {
                      "codigo": "numero_negativo",
                      "tienda": "110",
                      "ticket": "A-48230",
                      "renglon": 1,
                      "campo": "tiendas[0].tickets[1].renglones[0].importe",
                      "recibido": -344.83,
                      "esperado": "Un número mayor o igual que 0.",
                      "pista": "Todo va en positivo: el tipo de ticket (devolucion) da el signo, no el número."
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Sin clave, clave inválida o revocada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "codigo": "envio_rechazado",
                  "mensaje": "El envío tiene 2 errores y no se guardó nada.",
                  "errores": [
                    {
                      "codigo": "total_no_cuadra",
                      "tienda": "110",
                      "ticket": "A-48211",
                      "renglon": null,
                      "campo": "tiendas[0].tickets[0].total",
                      "recibido": 1900,
                      "esperado": "La suma de los importes de sus renglones, 1637.93, con tolerancia de 0.01.",
                      "pista": "Los dos van sin IVA y después del descuento. Si el total incluye IVA, quítaselo."
                    },
                    {
                      "codigo": "numero_negativo",
                      "tienda": "110",
                      "ticket": "A-48230",
                      "renglon": 1,
                      "campo": "tiendas[0].tickets[1].renglones[0].importe",
                      "recibido": -344.83,
                      "esperado": "Un número mayor o igual que 0.",
                      "pista": "Todo va en positivo: el tipo de ticket (devolucion) da el signo, no el número."
                    }
                  ]
                }
              }
            }
          },
          "413": {
            "description": "El envío pasa de 5 MB (envio_demasiado_grande).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "codigo": "envio_rechazado",
                  "mensaje": "El envío tiene 2 errores y no se guardó nada.",
                  "errores": [
                    {
                      "codigo": "total_no_cuadra",
                      "tienda": "110",
                      "ticket": "A-48211",
                      "renglon": null,
                      "campo": "tiendas[0].tickets[0].total",
                      "recibido": 1900,
                      "esperado": "La suma de los importes de sus renglones, 1637.93, con tolerancia de 0.01.",
                      "pista": "Los dos van sin IVA y después del descuento. Si el total incluye IVA, quítaselo."
                    },
                    {
                      "codigo": "numero_negativo",
                      "tienda": "110",
                      "ticket": "A-48230",
                      "renglon": 1,
                      "campo": "tiendas[0].tickets[1].renglones[0].importe",
                      "recibido": -344.83,
                      "esperado": "Un número mayor o igual que 0.",
                      "pista": "Todo va en positivo: el tipo de ticket (devolucion) da el signo, no el número."
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "El envío tiene errores y no se guardó nada (envio_rechazado).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "codigo": "envio_rechazado",
                  "mensaje": "El envío tiene 2 errores y no se guardó nada.",
                  "errores": [
                    {
                      "codigo": "total_no_cuadra",
                      "tienda": "110",
                      "ticket": "A-48211",
                      "renglon": null,
                      "campo": "tiendas[0].tickets[0].total",
                      "recibido": 1900,
                      "esperado": "La suma de los importes de sus renglones, 1637.93, con tolerancia de 0.01.",
                      "pista": "Los dos van sin IVA y después del descuento. Si el total incluye IVA, quítaselo."
                    },
                    {
                      "codigo": "numero_negativo",
                      "tienda": "110",
                      "ticket": "A-48230",
                      "renglon": 1,
                      "campo": "tiendas[0].tickets[1].renglones[0].importe",
                      "recibido": -344.83,
                      "esperado": "Un número mayor o igual que 0.",
                      "pista": "Todo va en positivo: el tipo de ticket (devolucion) da el signo, no el número."
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/ensayar": {
      "post": {
        "operationId": "ensayarDia",
        "summary": "Ensayar el día",
        "description": "El mismo cuerpo y la misma validación que «Recibir el día», pero no guarda venta: devuelve lo que se guardaría, o los errores. Para iterar tu integración sin ensuciar datos. Como todo envío, queda anotado en la bitácora de envíos que FIGITAL consulta para atender tus dudas.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Envio"
              },
              "example": {
                "dia": "2026-11-15",
                "tiendas": [
                  {
                    "tienda": "110",
                    "tickets": [
                      {
                        "caja": "2",
                        "folio": "A-48211",
                        "fecha_hora": "2026-11-15T13:42:05",
                        "tipo": "venta",
                        "vendedor": {
                          "codigo": "V017",
                          "nombre": "Laura Méndez"
                        },
                        "total": 1637.93,
                        "renglones": [
                          {
                            "articulo": {
                              "codigo": "2790090-39",
                              "nombre": "Bota Chelsea negra 39"
                            },
                            "cantidad": 1,
                            "importe": 1293.1,
                            "descuento": 143.68
                          },
                          {
                            "articulo": {
                              "codigo": "5510021",
                              "nombre": "Calcetín deportivo"
                            },
                            "cantidad": 2,
                            "importe": 344.83,
                            "descuento": 0
                          }
                        ]
                      },
                      {
                        "folio": "A-48230",
                        "fecha_hora": "2026-11-15T17:05:51",
                        "tipo": "devolucion",
                        "folio_original": "A-47002",
                        "vendedor": {
                          "codigo": "V017",
                          "nombre": "Laura Méndez"
                        },
                        "total": 344.83,
                        "renglones": [
                          {
                            "articulo": {
                              "codigo": "5510021",
                              "nombre": "Calcetín deportivo"
                            },
                            "cantidad": 2,
                            "importe": 344.83,
                            "descuento": 0
                          }
                        ]
                      }
                    ]
                  },
                  {
                    "tienda": "112",
                    "tickets": []
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "El envío entraría. Por tienda, lo que se guardaría (`ensayo: true`, sin `envio`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespuestaDelEnvio"
                },
                "example": {
                  "envio": null,
                  "ensayo": true,
                  "dia": "2026-11-15",
                  "tiendas": [
                    {
                      "tienda": "110",
                      "tickets": 1,
                      "devoluciones": 1,
                      "cancelaciones": 0,
                      "unidades": 1,
                      "importe": 1293.1
                    },
                    {
                      "tienda": "112",
                      "tickets": 0,
                      "devoluciones": 0,
                      "cancelaciones": 0,
                      "unidades": 0,
                      "importe": 0
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "El cuerpo no es JSON (json_invalido).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "codigo": "envio_rechazado",
                  "mensaje": "El envío tiene 2 errores y no se guardó nada.",
                  "errores": [
                    {
                      "codigo": "total_no_cuadra",
                      "tienda": "110",
                      "ticket": "A-48211",
                      "renglon": null,
                      "campo": "tiendas[0].tickets[0].total",
                      "recibido": 1900,
                      "esperado": "La suma de los importes de sus renglones, 1637.93, con tolerancia de 0.01.",
                      "pista": "Los dos van sin IVA y después del descuento. Si el total incluye IVA, quítaselo."
                    },
                    {
                      "codigo": "numero_negativo",
                      "tienda": "110",
                      "ticket": "A-48230",
                      "renglon": 1,
                      "campo": "tiendas[0].tickets[1].renglones[0].importe",
                      "recibido": -344.83,
                      "esperado": "Un número mayor o igual que 0.",
                      "pista": "Todo va en positivo: el tipo de ticket (devolucion) da el signo, no el número."
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Sin clave, clave inválida o revocada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "codigo": "envio_rechazado",
                  "mensaje": "El envío tiene 2 errores y no se guardó nada.",
                  "errores": [
                    {
                      "codigo": "total_no_cuadra",
                      "tienda": "110",
                      "ticket": "A-48211",
                      "renglon": null,
                      "campo": "tiendas[0].tickets[0].total",
                      "recibido": 1900,
                      "esperado": "La suma de los importes de sus renglones, 1637.93, con tolerancia de 0.01.",
                      "pista": "Los dos van sin IVA y después del descuento. Si el total incluye IVA, quítaselo."
                    },
                    {
                      "codigo": "numero_negativo",
                      "tienda": "110",
                      "ticket": "A-48230",
                      "renglon": 1,
                      "campo": "tiendas[0].tickets[1].renglones[0].importe",
                      "recibido": -344.83,
                      "esperado": "Un número mayor o igual que 0.",
                      "pista": "Todo va en positivo: el tipo de ticket (devolucion) da el signo, no el número."
                    }
                  ]
                }
              }
            }
          },
          "413": {
            "description": "El envío pasa de 5 MB (envio_demasiado_grande).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "codigo": "envio_rechazado",
                  "mensaje": "El envío tiene 2 errores y no se guardó nada.",
                  "errores": [
                    {
                      "codigo": "total_no_cuadra",
                      "tienda": "110",
                      "ticket": "A-48211",
                      "renglon": null,
                      "campo": "tiendas[0].tickets[0].total",
                      "recibido": 1900,
                      "esperado": "La suma de los importes de sus renglones, 1637.93, con tolerancia de 0.01.",
                      "pista": "Los dos van sin IVA y después del descuento. Si el total incluye IVA, quítaselo."
                    },
                    {
                      "codigo": "numero_negativo",
                      "tienda": "110",
                      "ticket": "A-48230",
                      "renglon": 1,
                      "campo": "tiendas[0].tickets[1].renglones[0].importe",
                      "recibido": -344.83,
                      "esperado": "Un número mayor o igual que 0.",
                      "pista": "Todo va en positivo: el tipo de ticket (devolucion) da el signo, no el número."
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "El envío tiene errores (envio_rechazado).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "codigo": "envio_rechazado",
                  "mensaje": "El envío tiene 2 errores y no se guardó nada.",
                  "errores": [
                    {
                      "codigo": "total_no_cuadra",
                      "tienda": "110",
                      "ticket": "A-48211",
                      "renglon": null,
                      "campo": "tiendas[0].tickets[0].total",
                      "recibido": 1900,
                      "esperado": "La suma de los importes de sus renglones, 1637.93, con tolerancia de 0.01.",
                      "pista": "Los dos van sin IVA y después del descuento. Si el total incluye IVA, quítaselo."
                    },
                    {
                      "codigo": "numero_negativo",
                      "tienda": "110",
                      "ticket": "A-48230",
                      "renglon": 1,
                      "campo": "tiendas[0].tickets[1].renglones[0].importe",
                      "recibido": -344.83,
                      "esperado": "Un número mayor o igual que 0.",
                      "pista": "Todo va en positivo: el tipo de ticket (devolucion) da el signo, no el número."
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/resumen": {
      "get": {
        "operationId": "resumen",
        "summary": "Resumen",
        "description": "Lo que FIGITAL tiene, por tienda y día de un rango: tickets, unidades e importe, con las mismas cuentas que la respuesta de «Recibir el día». Para conciliar con tu sistema.",
        "parameters": [
          {
            "name": "desde",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Primer día del rango, AAAA-MM-DD."
          },
          {
            "name": "hasta",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Último día del rango, incluido. Como mucho 31 días."
          },
          {
            "name": "tienda",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Tu código de tienda. Sin él, todas las tiendas emparejadas."
          }
        ],
        "responses": {
          "200": {
            "description": "Una fila por tienda emparejada y día del rango desde el inicio de tu historia y hasta ayer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resumen"
                },
                "example": {
                  "desde": "2026-11-14",
                  "hasta": "2026-11-15",
                  "dias": [
                    {
                      "dia": "2026-11-14",
                      "tienda": "110",
                      "estado": "recibido",
                      "tickets": 209,
                      "devoluciones": 2,
                      "cancelaciones": 0,
                      "unidades": 342,
                      "importe": 158904.31,
                      "recibido_en": "2026-11-15T06:10:12Z",
                      "envio": "2b8e4f60-1c3d-4a9e-b7f2-5d0c8e6a1f34"
                    },
                    {
                      "dia": "2026-11-15",
                      "tienda": "110",
                      "estado": "recibido",
                      "tickets": 1,
                      "devoluciones": 1,
                      "cancelaciones": 0,
                      "unidades": 1,
                      "importe": 1293.1,
                      "recibido_en": "2026-11-16T06:09:40Z",
                      "envio": "6f1d3c2a-9b0e-4c57-8a51-2f7e0d4b9c11"
                    },
                    {
                      "dia": "2026-11-14",
                      "tienda": "112",
                      "estado": "no_llego",
                      "tickets": 0,
                      "devoluciones": 0,
                      "cancelaciones": 0,
                      "unidades": 0,
                      "importe": 0,
                      "recibido_en": null,
                      "envio": null
                    },
                    {
                      "dia": "2026-11-15",
                      "tienda": "112",
                      "estado": "sin_venta",
                      "tickets": 0,
                      "devoluciones": 0,
                      "cancelaciones": 0,
                      "unidades": 0,
                      "importe": 0,
                      "recibido_en": "2026-11-16T06:09:40Z",
                      "envio": "6f1d3c2a-9b0e-4c57-8a51-2f7e0d4b9c11"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Sin clave, clave inválida o revocada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "codigo": "envio_rechazado",
                  "mensaje": "El envío tiene 2 errores y no se guardó nada.",
                  "errores": [
                    {
                      "codigo": "total_no_cuadra",
                      "tienda": "110",
                      "ticket": "A-48211",
                      "renglon": null,
                      "campo": "tiendas[0].tickets[0].total",
                      "recibido": 1900,
                      "esperado": "La suma de los importes de sus renglones, 1637.93, con tolerancia de 0.01.",
                      "pista": "Los dos van sin IVA y después del descuento. Si el total incluye IVA, quítaselo."
                    },
                    {
                      "codigo": "numero_negativo",
                      "tienda": "110",
                      "ticket": "A-48230",
                      "renglon": 1,
                      "campo": "tiendas[0].tickets[1].renglones[0].importe",
                      "recibido": -344.83,
                      "esperado": "Un número mayor o igual que 0.",
                      "pista": "Todo va en positivo: el tipo de ticket (devolucion) da el signo, no el número."
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Rango o tienda inválidos (rango_invalido, tienda_sin_emparejar).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "codigo": "envio_rechazado",
                  "mensaje": "El envío tiene 2 errores y no se guardó nada.",
                  "errores": [
                    {
                      "codigo": "total_no_cuadra",
                      "tienda": "110",
                      "ticket": "A-48211",
                      "renglon": null,
                      "campo": "tiendas[0].tickets[0].total",
                      "recibido": 1900,
                      "esperado": "La suma de los importes de sus renglones, 1637.93, con tolerancia de 0.01.",
                      "pista": "Los dos van sin IVA y después del descuento. Si el total incluye IVA, quítaselo."
                    },
                    {
                      "codigo": "numero_negativo",
                      "tienda": "110",
                      "ticket": "A-48230",
                      "renglon": 1,
                      "campo": "tiendas[0].tickets[1].renglones[0].importe",
                      "recibido": -344.83,
                      "esperado": "Un número mayor o igual que 0.",
                      "pista": "Todo va en positivo: el tipo de ticket (devolucion) da el signo, no el número."
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "clave": {
        "type": "http",
        "scheme": "bearer",
        "description": "La clave de tu organización, en «Authorization: Bearer <clave>». Decide de qué cliente es el envío: el cuerpo nunca lo dice. Staging y producción tienen claves distintas."
      }
    },
    "schemas": {
      "Envio": {
        "type": "object",
        "description": "Un día de negocio de una o varias tiendas. Como mucho 5 MB; si no cabe, pártelo por tiendas.",
        "required": [
          "dia",
          "tiendas"
        ],
        "additionalProperties": false,
        "properties": {
          "dia": {
            "type": "string",
            "format": "date",
            "description": "El día de negocio, AAAA-MM-DD. Ya cerrado, y no anterior al inicio de tu historia."
          },
          "tiendas": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/Tienda"
            },
            "description": "Las tiendas que este envío sustituye en ese día. Cada una una sola vez."
          }
        }
      },
      "Tienda": {
        "type": "object",
        "description": "Una tienda y todos sus tickets del día. Una lista vacía es un día sin venta, distinto de un día que no llegó.",
        "required": [
          "tienda",
          "tickets"
        ],
        "additionalProperties": false,
        "properties": {
          "tienda": {
            "type": "string",
            "minLength": 1,
            "description": "Tu código de tienda, como lo usa tu sistema («110»). FIGITAL lo empareja con su tienda."
          },
          "tickets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Ticket"
            },
            "description": "Todos los tickets de la tienda en el día. Vacía si no vendió."
          }
        }
      },
      "Ticket": {
        "type": "object",
        "required": [
          "folio",
          "fecha_hora",
          "tipo",
          "vendedor",
          "total",
          "renglones"
        ],
        "additionalProperties": false,
        "properties": {
          "caja": {
            "type": "string",
            "minLength": 1,
            "description": "Tu código de caja. Opcional; mándalo si dos cajas pueden repetir folio."
          },
          "folio": {
            "type": "string",
            "minLength": 1,
            "description": "El folio del ticket. Único por tienda y caja en el día."
          },
          "fecha_hora": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$",
            "description": "Fecha y hora locales de la tienda, sin zona: 2026-11-15T13:42:05. Alimenta el reparto por hora."
          },
          "tipo": {
            "type": "string",
            "enum": [
              "venta",
              "devolucion",
              "cancelacion"
            ],
            "description": "venta, devolucion o cancelacion. Da el signo: los números van siempre en positivo. La cancelación se guarda, pero no es venta."
          },
          "folio_original": {
            "type": "string",
            "minLength": 1,
            "description": "El folio del ticket de venta que se devuelve. Obligatorio en una devolución; no tiene que existir en FIGITAL."
          },
          "vendedor": {
            "$ref": "#/components/schemas/Vendedor"
          },
          "total": {
            "type": "number",
            "minimum": 0,
            "description": "Total del ticket sin IVA, después de descuentos. Cuadra con la suma de los importes de sus renglones a un centavo. Como mucho 2 decimales."
          },
          "renglones": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/Renglon"
            },
            "description": "Al menos uno."
          }
        }
      },
      "Vendedor": {
        "type": "object",
        "description": "Quien vendió. El código es la llave; el nombre, la etiqueta: un nombre nuevo actualiza la etiqueta, nunca crea otro vendedor.",
        "required": [
          "codigo",
          "nombre"
        ],
        "additionalProperties": false,
        "properties": {
          "codigo": {
            "type": "string",
            "minLength": 1,
            "description": "Código del vendedor en tu sistema."
          },
          "nombre": {
            "type": "string",
            "minLength": 1,
            "description": "Nombre del vendedor."
          }
        }
      },
      "Renglon": {
        "type": "object",
        "required": [
          "articulo",
          "cantidad",
          "importe",
          "descuento"
        ],
        "additionalProperties": false,
        "properties": {
          "articulo": {
            "$ref": "#/components/schemas/Articulo"
          },
          "cantidad": {
            "type": "number",
            "exclusiveMinimum": 0,
            "description": "Unidades, mayor que 0, también en una devolución."
          },
          "importe": {
            "type": "number",
            "minimum": 0,
            "description": "Importe del renglón sin IVA, después del descuento. Como mucho 2 decimales."
          },
          "descuento": {
            "type": "number",
            "minimum": 0,
            "description": "Descuento del renglón sin IVA. 0 si no hubo. Como mucho 2 decimales."
          }
        }
      },
      "Articulo": {
        "type": "object",
        "description": "El artículo. El código es la llave; el nombre, la etiqueta. No hace falta mandar un catálogo aparte.",
        "required": [
          "codigo",
          "nombre"
        ],
        "additionalProperties": false,
        "properties": {
          "codigo": {
            "type": "string",
            "minLength": 1,
            "description": "Código del artículo en tu sistema (SKU, referencia)."
          },
          "nombre": {
            "type": "string",
            "minLength": 1,
            "description": "Nombre del artículo."
          }
        }
      },
      "RespuestaDelEnvio": {
        "type": "object",
        "required": [
          "envio",
          "ensayo",
          "dia",
          "tiendas"
        ],
        "properties": {
          "envio": {
            "type": [
              "string",
              "null"
            ],
            "description": "Identificador del envío guardado. null en un ensayo."
          },
          "ensayo": {
            "type": "boolean",
            "description": "true si fue «Ensayar el día»: no se guardó venta (solo su anotación en la bitácora de envíos)."
          },
          "dia": {
            "type": "string",
            "format": "date",
            "description": "El día de negocio del envío."
          },
          "tiendas": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CuentaDeTienda"
            },
            "description": "Una por tienda del envío."
          }
        }
      },
      "CuentaDeTienda": {
        "type": "object",
        "description": "Lo que quedó guardado de una tienda en el día, para cuadrar contra tu sistema.",
        "required": [
          "tienda",
          "tickets",
          "devoluciones",
          "cancelaciones",
          "unidades",
          "importe"
        ],
        "properties": {
          "tienda": {
            "type": "string",
            "description": "Tu código de tienda."
          },
          "tickets": {
            "type": "integer",
            "description": "Tickets de venta guardados: los que cuenta FIGITAL para la conversión."
          },
          "devoluciones": {
            "type": "integer",
            "description": "Devoluciones guardadas, aparte de los tickets."
          },
          "cancelaciones": {
            "type": "integer",
            "description": "Cancelaciones recibidas, aparte de los tickets: se cuentan y no son venta."
          },
          "unidades": {
            "type": "number",
            "description": "Unidades vendidas menos devueltas. Las canceladas no cuentan."
          },
          "importe": {
            "type": "number",
            "description": "Importe sin IVA vendido menos devuelto. Lo cancelado no cuenta."
          }
        }
      },
      "Resumen": {
        "type": "object",
        "required": [
          "desde",
          "hasta",
          "dias"
        ],
        "properties": {
          "desde": {
            "type": "string",
            "format": "date"
          },
          "hasta": {
            "type": "string",
            "format": "date"
          },
          "dias": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiaDeTienda"
            },
            "description": "Una fila por tienda emparejada y día del rango desde el inicio de tu historia y hasta ayer, por tienda y luego por día. Un día guardado de una tienda que ya no está emparejada también sale."
          }
        }
      },
      "DiaDeTienda": {
        "type": "object",
        "required": [
          "dia",
          "tienda",
          "estado",
          "tickets",
          "devoluciones",
          "cancelaciones",
          "unidades",
          "importe",
          "recibido_en",
          "envio"
        ],
        "properties": {
          "dia": {
            "type": "string",
            "format": "date"
          },
          "tienda": {
            "type": "string",
            "description": "Tu código de tienda."
          },
          "estado": {
            "type": "string",
            "enum": [
              "recibido",
              "sin_venta",
              "no_llego"
            ],
            "description": "recibido; sin_venta (llegó con la lista vacía); no_llego (FIGITAL no lo tiene)."
          },
          "tickets": {
            "type": "integer",
            "description": "Como en la respuesta del envío."
          },
          "devoluciones": {
            "type": "integer",
            "description": "Como en la respuesta del envío."
          },
          "cancelaciones": {
            "type": "integer",
            "description": "Como en la respuesta del envío."
          },
          "unidades": {
            "type": "number",
            "description": "Como en la respuesta del envío."
          },
          "importe": {
            "type": "number",
            "description": "Como en la respuesta del envío."
          },
          "recibido_en": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Cuándo llegó el envío que sustituyó ese día (UTC)."
          },
          "envio": {
            "type": [
              "string",
              "null"
            ],
            "description": "El envío que lo dejó así."
          }
        }
      },
      "Error": {
        "type": "object",
        "description": "Un envío rechazado. Todo o nada: no se guardó nada, y vienen todos los errores, no solo el primero.",
        "required": [
          "codigo",
          "mensaje",
          "errores"
        ],
        "properties": {
          "codigo": {
            "type": "string",
            "description": "«envio_rechazado» si el cuerpo tiene errores; si no, el código del único error."
          },
          "mensaje": {
            "type": "string",
            "description": "Qué pasó, en una línea."
          },
          "errores": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ErrorDetalle"
            }
          }
        }
      },
      "ErrorDetalle": {
        "type": "object",
        "description": "Un error, dicho para corregirlo en una sola lectura.",
        "required": [
          "codigo",
          "tienda",
          "ticket",
          "renglon",
          "campo",
          "recibido",
          "esperado",
          "pista"
        ],
        "properties": {
          "codigo": {
            "type": "string",
            "enum": [
              "clave_ausente",
              "clave_invalida",
              "clave_revocada",
              "ruta_desconocida",
              "envio_demasiado_grande",
              "json_invalido",
              "campo_requerido",
              "campo_desconocido",
              "tipo_de_dato_invalido",
              "texto_vacio",
              "dia_invalido",
              "dia_en_el_futuro",
              "dia_anterior_a_la_historia",
              "rango_invalido",
              "envio_sin_tiendas",
              "tienda_sin_emparejar",
              "tienda_repetida",
              "folio_repetido",
              "fecha_hora_invalida",
              "fecha_hora_fuera_del_dia",
              "tipo_de_ticket_invalido",
              "folio_original_requerido",
              "ticket_sin_renglones",
              "total_no_cuadra",
              "numero_negativo",
              "cantidad_no_positiva",
              "demasiados_decimales"
            ],
            "description": "Uno de la tabla de errores."
          },
          "tienda": {
            "type": [
              "string",
              "null"
            ],
            "description": "Tu código de tienda, si el error está dentro de una."
          },
          "ticket": {
            "type": [
              "string",
              "null"
            ],
            "description": "El folio del ticket, si el error está dentro de uno."
          },
          "renglon": {
            "type": [
              "integer",
              "null"
            ],
            "description": "El número del renglón dentro del ticket, contando desde 1."
          },
          "campo": {
            "type": [
              "string",
              "null"
            ],
            "description": "Dónde está, como ruta: tiendas[0].tickets[3].renglones[1].importe."
          },
          "recibido": {
            "description": "El valor que llegó, tal cual (null si faltaba)."
          },
          "esperado": {
            "type": "string",
            "description": "Qué se esperaba."
          },
          "pista": {
            "type": "string",
            "description": "Cómo arreglarlo."
          }
        }
      }
    }
  }
}
