Entrada de ventav1.0.0
Contenido
  1. Introducción
  2. Autenticación
  3. Inicio rápido
  4. El envío
  5. Operaciones
  6. Reglas de negocio
  7. Errores
  8. De pruebas a producción

Entrada de venta de FIGITAL

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.

Una API REST que recibe y devuelve JSON. Hay dos entornos con la misma API; la clave dice a cuál hablas.

Staging fp_test_

https://api-pruebas.figital.pro

Para probar, con una clave fp_test_.

Producción fp_live_

https://api.figital.pro

Con una clave fp_live_, cuando tu envío ya entra limpio en staging.

El contrato formal es un OpenAPI 3.1.0: descárgalo en JSON para generar tu cliente o validar tus envíos. Esta página sale del mismo fichero que valida la entrada, así que nunca dicen cosas distintas.

Autenticación

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.

Cabecera
Authorization: Bearer fp_test_TU_CLAVE

FIGITAL emite las claves y empareja tus códigos de tienda. La de staging empieza por fp_test_ y la de producción por fp_live_; una no entra en el otro entorno. Sin una clave válida, la respuesta es 401:

Inicio rápido

  1. Guarda el envío de ejemplo

    Descarga envio.json en la carpeta desde la que vas a llamar: un día con dos tiendas, una que vendió y otra sin venta.

    Ver el envío de ejemplo
    Cuerpoenvio.json
    {
      "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": []
        }
      ]
    }
  2. Ensáyalo contra staging

    Con tu clave de prueba en lugar de TU_CLAVE. Ensayar valida igual que recibir, pero no guarda venta.

    Peticióncurl
    curl -sS -X POST 'https://api-pruebas.figital.pro/v1/ensayar' \
      -H 'Authorization: Bearer fp_test_TU_CLAVE' \
      -H 'Content-Type: application/json' \
      -d @envio.json
  3. Lee la respuesta

    Por tienda, cuántos tickets de venta, devoluciones y cancelaciones, y qué unidades e importe se guardarían. Si algo falla, llegan todos los errores a la vez.

    Respuesta200
    {
      "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
        }
      ]
    }

El envío

Un día de negocio de una o varias tiendas. Como mucho 5 MB; si no cabe, pártelo por tiendas. Es el cuerpo de recibir y de ensayar. Un campo que no esté en este árbol rechaza el envío (campo_desconocido).

  • diafechaobligatorio

    El día de negocio, AAAA-MM-DD. Ya cerrado, y no anterior al inicio de tu historia.

  • tiendas[]lista, al menos 1obligatorio

    Las tiendas que este envío sustituye en ese día. Cada una una sola vez.

    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ó.

    • tiendatextoobligatorio

      Tu código de tienda, como lo usa tu sistema (110). FIGITAL lo empareja con su tienda.

    • tickets[]listaobligatorio

      Todos los tickets de la tienda en el día. Vacía si no vendió.

      • cajatextoopcional

        Tu código de caja. Opcional; mándalo si dos cajas pueden repetir folio.

      • foliotextoobligatorio

        El folio del ticket. Único por tienda y caja en el día.

      • fecha_horatextoobligatorio

        Fecha y hora locales de la tienda, sin zona: 2026-11-15T13:42:05. Alimenta el reparto por hora.

      • tipoventa | devolucion | cancelacionobligatorio

        venta, devolucion o cancelacion. Da el signo: los números van siempre en positivo. La cancelación se guarda, pero no es venta.

      • folio_originaltextoopcional

        El folio del ticket de venta que se devuelve. Obligatorio en una devolución; no tiene que existir en FIGITAL.

      • vendedorobjetoobligatorio

        Quien vendió. El código es la llave; el nombre, la etiqueta: un nombre nuevo actualiza la etiqueta, nunca crea otro vendedor.

        • codigotextoobligatorio

          Código del vendedor en tu sistema.

        • nombretextoobligatorio

          Nombre del vendedor.

      • totalnúmero ≥ 0obligatorio

        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[]lista, al menos 1obligatorio

        Al menos uno.

        • articuloobjetoobligatorio

          El artículo. El código es la llave; el nombre, la etiqueta. No hace falta mandar un catálogo aparte.

          • codigotextoobligatorio

            Código del artículo en tu sistema (SKU, referencia).

          • nombretextoobligatorio

            Nombre del artículo.

        • cantidadnúmero > 0obligatorio

          Unidades, mayor que 0, también en una devolución.

        • importenúmero ≥ 0obligatorio

          Importe del renglón sin IVA, después del descuento. Como mucho 2 decimales.

        • descuentonúmero ≥ 0obligatorio

          Descuento del renglón sin IVA. 0 si no hubo. Como mucho 2 decimales.

Operaciones

Las tres van contra https://api-pruebas.figital.pro en staging y https://api.figital.pro en producción. Los ejemplos usan staging.

Recibir el día

POST/v1/recibir

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.

Cuerpo

Un envío, en JSON.

Respuestas

  • 200El día quedó guardado. Por tienda, lo que quedó.
  • 400El cuerpo no es JSON (json_invalido).
  • 401Sin clave, clave inválida o revocada.
  • 413El envío pasa de 5 MB (envio_demasiado_grande).
  • 422El envío tiene errores y no se guardó nada (envio_rechazado).

Campos de la respuesta 200

  • enviotexto o null

    Identificador del envío guardado. null en un ensayo.

  • ensayosí/no

    true si fue Ensayar el día: no se guardó venta (solo su anotación en la bitácora de envíos).

  • diafecha

    El día de negocio del envío.

  • tiendas[]lista

    Una por tienda del envío.

    Lo que quedó guardado de una tienda en el día, para cuadrar contra tu sistema.

    • tiendatexto

      Tu código de tienda.

    • ticketsentero

      Tickets de venta guardados: los que cuenta FIGITAL para la conversión.

    • devolucionesentero

      Devoluciones guardadas, aparte de los tickets.

    • cancelacionesentero

      Cancelaciones recibidas, aparte de los tickets: se cuentan y no son venta.

    • unidadesnúmero

      Unidades vendidas menos devueltas. Las canceladas no cuentan.

    • importenúmero

      Importe sin IVA vendido menos devuelto. Lo cancelado no cuenta.

Peticióncurl
curl -sS -X POST 'https://api-pruebas.figital.pro/v1/recibir' \
  -H 'Authorization: Bearer fp_test_TU_CLAVE' \
  -H 'Content-Type: application/json' \
  -d @envio.json
Respuesta200
{
  "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
    }
  ]
}

Ensayar el día

POST/v1/ensayar

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.

Cuerpo

Un envío, en JSON.

Respuestas

  • 200El envío entraría. Por tienda, lo que se guardaría (`ensayo: true`, sin `envio`).
  • 400El cuerpo no es JSON (json_invalido).
  • 401Sin clave, clave inválida o revocada.
  • 413El envío pasa de 5 MB (envio_demasiado_grande).
  • 422El envío tiene errores (envio_rechazado).

Campos de la respuesta 200

Los campos de la respuesta son los de Recibir el día.

Peticióncurl
curl -sS -X POST 'https://api-pruebas.figital.pro/v1/ensayar' \
  -H 'Authorization: Bearer fp_test_TU_CLAVE' \
  -H 'Content-Type: application/json' \
  -d @envio.json
Respuesta200
{
  "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
    }
  ]
}

Resumen

GET/v1/resumen

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.

Parámetros de la consulta

  • desdefechaobligatorio

    Primer día del rango, AAAA-MM-DD.

  • hastafechaobligatorio

    Último día del rango, incluido. Como mucho 31 días.

  • tiendatextoopcional

    Tu código de tienda. Sin él, todas las tiendas emparejadas.

Respuestas

  • 200Una fila por tienda emparejada y día del rango desde el inicio de tu historia y hasta ayer.
  • 401Sin clave, clave inválida o revocada.
  • 422Rango o tienda inválidos (rango_invalido, tienda_sin_emparejar).

Campos de la respuesta 200

  • desdefecha
  • hastafecha
  • dias[]lista

    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.

    • diafecha
    • tiendatexto

      Tu código de tienda.

    • estadorecibido | sin_venta | no_llego

      recibido; sin_venta (llegó con la lista vacía); no_llego (FIGITAL no lo tiene).

    • ticketsentero

      Como en la respuesta del envío.

    • devolucionesentero

      Como en la respuesta del envío.

    • cancelacionesentero

      Como en la respuesta del envío.

    • unidadesnúmero

      Como en la respuesta del envío.

    • importenúmero

      Como en la respuesta del envío.

    • recibido_enfecha y hora o null

      Cuándo llegó el envío que sustituyó ese día (UTC).

    • enviotexto o null

      El envío que lo dejó así.

Peticióncurl
curl -sS 'https://api-pruebas.figital.pro/v1/resumen?desde=2026-11-14&hasta=2026-11-15' \
  -H 'Authorization: Bearer fp_test_TU_CLAVE'
Respuesta200
{
  "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"
    }
  ]
}

Reglas de negocio

  • Sin IVA. Importes, descuentos y totales van sin IVA, con 2 decimales como mucho, en la moneda de tu organización.
  • Todo en positivo. Cantidades e importes siempre positivos: el tipo de ticket (venta, devolucion, cancelacion) da el signo.
  • El total cuadra. El total de cada ticket es la suma de los importes de sus renglones, con una tolerancia de 0.01.
  • Todo o nada. Un solo error rechaza el envío entero y no guarda nada; la respuesta trae todos los errores.
  • Reenviar sustituye. Un envío sustituye completo el día de cada tienda que trae; las tiendas que no trae no se tocan. El mismo envío dos veces da el mismo resultado.
  • Día sin venta no es día que no llegó. Una tienda que no vendió va con "tickets": [] y queda sin_venta; una que no mandas queda no_llego, y a FIGITAL le salta como alerta.
  • Inicio de tu historia. FIGITAL declara desde qué día guarda tu venta; un día anterior se rechaza (dia_anterior_a_la_historia). La historia se carga igual, un día por envío.
  • Tamaño. Como mucho 5 MB por envío. Un día que no cabe se parte por tiendas, en varios envíos.
  • Devoluciones. Son un ticket propio que nombra el folio del ticket original en folio_original, y restan el día en que se hicieron.
  • Cancelaciones. Se mandan con su tipo: se cuentan, pero no son venta.
  • Tus códigos. Tiendas, cajas, artículos y vendedores van con los códigos de tu sistema. La entrada nunca crea tiendas: una sin emparejar rechaza el envío (tienda_sin_emparejar).

Errores

Un envío rechazado. Todo o nada: no se guardó nada, y vienen todos los errores, no solo el primero. Cada error dice en qué tienda, qué ticket (su folio), qué renglón (contando desde 1), qué campo, qué valor se recibió, qué se esperaba y una pista.

Respuesta422
{
  "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."
    }
  ]
}

Los códigos que pueden salir. Lo marcado así, codigos, se rellena con tu dato en la respuesta.

La clave

CódigoHTTPQué pasóQué se esperabaPista
clave_ausente401El envío no trae clave.La cabecera Authorization: Bearer <tu clave>.La clave de staging empieza por fp_test_ y la de producción por fp_live_. Si no tienes una, pídela a FIGITAL.
clave_invalida401La clave no es de ningún cliente.Una clave vigente, emitida por FIGITAL para este entorno.Una clave de staging (fp_test_) no entra en producción, ni al revés. Revisa que la copiaste entera.
clave_revocada401La clave fue revocada.Una clave vigente.Pide a FIGITAL una clave nueva; la revocada no vuelve a entrar.

El formato

CódigoHTTPQué pasóQué se esperabaPista
ruta_desconocida404Esa ruta o ese método no existen.POST /v1/recibir, POST /v1/ensayar o GET /v1/resumen.La versión va en la ruta: /v1/….
json_invalido400El cuerpo no es JSON.Un objeto JSON en UTF-8, con Content-Type: application/json.Valida el cuerpo con cualquier lector de JSON antes de mandarlo.
campo_requerido422Falta un campo obligatorio.El campo campo.Los campos obligatorios de cada objeto están en la sección El envío de la página.
campo_desconocido422El envío trae un campo que el contrato no tiene.Solo los campos del contrato.Revisa cómo está escrito: un campo mal escrito no se ignora, porque se perdería un dato sin que nadie lo note.
tipo_de_dato_invalido422El valor no es del tipo que pide el campo.Un valor de tipo tipo.Los importes y las cantidades van como número JSON (sin comillas); los códigos y folios, como texto (con comillas).
texto_vacio422Un texto obligatorio llegó vacío.Un texto con al menos un carácter que no sea espacio.Si el dato no existe en tu sistema, pregunta a FIGITAL antes de inventarlo.
dia_invalido422La fecha no es una fecha válida.Una fecha AAAA-MM-DD, como 2026-11-15.Es el día de negocio, sin hora ni zona.
fecha_hora_invalida422La fecha y hora del ticket no son válidas.Fecha y hora locales de la tienda, AAAA-MM-DDThh:mm:ss, sin zona: 2026-11-15T13:42:05.Es la hora del reloj de la tienda; no la conviertas a UTC ni le pongas Z.
tipo_de_ticket_invalido422El tipo de ticket no existe.venta, devolucion o cancelacion.Sin acentos y en minúsculas. El tipo da el signo: los números van siempre en positivo.

Los datos

CódigoHTTPQué pasóQué se esperabaPista
dia_en_el_futuro422El día de negocio todavía no termina.Un día anterior a hoy, en la hora de la tienda.Manda cada día cuando ya cerró: lo normal es mandar ayer, hoy temprano.
dia_anterior_a_la_historia422El día es anterior al inicio de tu historia.Un día desde el historia_desde.FIGITAL declaró que tu historia empieza el historia_desde; los días anteriores no se guardan. Si necesitas más historia, pídelo.
envio_sin_tiendas422El envío no trae ninguna tienda.Al menos una tienda en tiendas.Una tienda que no vendió va con su lista de tickets vacía; un envío sin tiendas no sustituye nada.
tienda_sin_emparejar422Ese código de tienda no está dado de alta.Un código de tienda dado de alta para tu clave.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.
tienda_repetida422La misma tienda viene dos veces en el envío.Cada tienda una sola vez, con todos sus tickets del día.Junta sus tickets en una sola entrada de tiendas.
folio_repetido422El folio se repite en la misma tienda y caja.Un folio único por tienda y caja en el día.Si son dos tickets distintos, manda la caja de cada uno; si es el mismo, mándalo una vez.
fecha_hora_fuera_del_dia422El ticket no es del día de negocio del envío.Una fecha del dia, o del día siguiente si la tienda cierra después de medianoche.Manda cada ticket en el envío de su día de negocio.
folio_original_requerido422La devolución no dice qué ticket devuelve.El folio del ticket de venta original en folio_original.No tiene que ser un ticket que nos hayas mandado: puede ser anterior al inicio de tu historia.
ticket_sin_renglones422El ticket no trae renglones.Al menos un renglón.Un día sin venta se manda como la tienda con la lista de tickets vacía, no como un ticket vacío.
total_no_cuadra422El total del ticket no cuadra con sus renglones.La suma de los importes de sus renglones, suma, con tolerancia de 0.01.Los dos van sin IVA y después del descuento. Si el total incluye IVA, quítaselo.
numero_negativo422Un importe, un descuento o un total llegó negativo.Un número mayor o igual que 0.Todo va en positivo: el tipo de ticket (devolucion) da el signo, no el número.
cantidad_no_positiva422La cantidad del renglón no es mayor que cero.Un número mayor que 0.En una devolución la cantidad también va en positivo. Un renglón sin unidades no se manda.

Los límites

CódigoHTTPQué pasóQué se esperabaPista
envio_demasiado_grande413El envío pasa del tamaño máximo.Un cuerpo de 5 MB como mucho.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.
rango_invalido422El rango del resumen no es válido.desde menor o igual que hasta, y como mucho 31 días.Para un periodo largo, pide el resumen por tramos.
demasiados_decimales422El importe trae más decimales de los que tiene la moneda.Como mucho 2 decimales.Redondea al centavo antes de mandarlo, y cuadra el total con los renglones ya redondeados.

De pruebas a producción

Todo esto, contra staging y con tu clave de prueba.

  1. Ensayar

    Arma el envío de un día real y mándalo a /v1/ensayar. No guarda venta (solo queda anotado en la bitácora de envíos, la que FIGITAL mira si nos escribes): corrige los errores y repite hasta que conteste 200. Compara por tienda los tickets, devoluciones, cancelaciones, unidades e importe contra tu sistema.

  2. Mandar

    El mismo cuerpo a /v1/recibir. Guarda el envio de la respuesta: es el identificador para cualquier duda. Lo normal es mandar cada mañana el día anterior de todas tus tiendas.

  3. Reenviar

    Quita un ticket o corrige un renglón y vuelve a mandar el día: el resumen tiene que mostrar el día nuevo, no la suma de los dos. Manda una tienda con la lista vacía y verás su día como sin_venta.

  4. Conciliar

    Pide /v1/resumen para un rango (hasta 31 días) y compáralo con tu sistema. Un día en no_llego es uno que FIGITAL no tiene: mándalo. Uno que no cuadra se arregla reenviándolo.

Pasar a producción

Cuando tu envío entra limpio en staging, FIGITAL te da una clave fp_live_. Cambia la URL base a https://api.figital.pro y la clave; el resto no cambia.