BRIDGE API - REST - Importación de grupo de documentos a facturar
© 2024 Napse. Todos los derechos reservados.
Este servicio permitirá crear desde fuentes externas, un grupo de documentos u ordenes en la tienda para luego ser retomadas por el punto de venta
- Se invoca de la siguiente manera: https://[direccion_ip]:[puerto]/billOrderGroup/create - Ejemplo: https://200.100.100.100:8090/billOrderGroup/create
- Se invoca via POST.
- Es un servicio de API tienda, NO estará disponible en API Central
Tener en cuenta:
- Primero se debe invocar al servicio de autenticación para obtener un token.
- Cuando se llama a cualquier servicio este token se envía como un parámetro más de la llamada en el header (x-access-token).
- Si al llamar al servicio el token expiró, se recibirá respuesta de token inválido y se deberá volver a pedir uno nuevo.
JSON ejemplo con cliente persona
"externalNumber": "SIS_79_0001",
"channelCode": "bridge",//opcional, defecto bridge
"currencyCode": "ARS", //opcional, defecto moneda base del sistema
"party": {
"code": "13308913",
"firstName": "Margarita",
"lastName": "Roddi",
"email": "[email protected]",
"typeCode": "Person",
"identificationType": 1,
"identifier": "13308913",
"partyRoleAssignments": [
{"partyRole":"1"}
],
"partyContactMethods": [
{
"name": "Facturacion",
"address": {
"firstLine": "Av. del Libertador 6000",
"countryCode": "ARG",
"cityCode": "CRR_0027",
"stateCode": "BSAS"
},
"emailAddress": "[email protected]",
"telephone": {
"telephoneNumber": "011 4744901"
},
"principalForDelivery": false,
"principalForBilling": true
},
{
"name": "Trabajo2",
"address": {
"firstLine": "Av. Directorio 5000",
"countryCode": "ARG",
"cityCode": "CRR_0027",
"stateCode": "BSAS"
},
"emailAddress": "[email protected]",
"telephone": {
"telephoneNumber": "011 4744901"
},
"principalForDelivery": true,
"principalForBilling": false,
"useForBilling": true
}
]
},
"documents": [
{
"externalDocumentNumber": "123456789",
"manualDiscountAmount": 20,
"notes": "", //opcional
"items": [
{
"itemCode": "PESABLE123",
"barcode" : "77998866",
"description": ,
"locationCode": "DEP1",
"magnitude": 1.455,
"unitPrice": 300,
"orderedQty": 1,
"packagePrice": false,
"otherUnitOfMeasureCode": ,
"priceModifier":
{
"amount": 5,
"reasonText": "Cupon de regalo"
}
,
"serie": "12345678",
"notes":""
},
{
"itemCode": "PARACETAMOL",
"description": "Paracetamol 600",
"locationCode": "DEP1",
"barcode": "555222333",
"units": 6,
"unitPrice": 100,
"orderedQty": 2,
"otherUnitOfMeasureCode": "BL",
"notes":"no requiere receta"
}
]
}
]
}
Descripción de los campos:
Importante: los campos que poseen este ícono 
, son valores tipificados que deben respetar los valores expuestos por BRIDGE en sus servicios (ver BRIDGE API - REST - Consulta de Maestros: https://share.linx.com.br/x/D5d8Cg)
NOTA: los campos de importes deben ser enviados hasta dos decimales
| Campo | Tipo | Descripción | Requerido | Ejemplos | Validación (código) | |
|---|---|---|---|---|---|---|
| externalNumber | String | Código del grupo de documentos | SI | "SIS_79_0001" Validaciones: al menos debe tener un caracter | 999: externalNumber debe tener al menos un 1 caracter (si no pasa la validación del tipo de dato) -------------- 994: Ya existe el código de grupo originante [Código]para el canal: [Código de Canal] | |
| channelCode | String | Código del canal de Origen | NO | "EXTERNALSYS" ver servicio channel/all (opcional. por defecto será "bridge") | 999: No se encontró el canal con código: [Código] |
| currencyCode | String | Código de la moneda | SI | "ARS" ver servicio currency/all (opcional, por defecto toma la moneda base del sistema) | 999: No se encontró la moneda con código: [Código] |
| notes | String | Comentarios sobre el grupo de documentos a facturar | NO | "Pedido de Margarita Roddi" opcional | ||
| party (cliente asociado a los documentos). Requerido | ||||||
| code | String | Código del cliente (BRIDGE genera el código con el tipo de documento concantenado con el nro de documento como una de las opciones) | NO (opcional. Si no viene informado se creará el código del cliente con el método que aplique Bridge para la creación de nuevos clientes en la tienda) | "13308913" | ||
| firstName | String | Nombre del Cliente | SI (solo si es typeCode = 'Person') | "Margarita", | 999: el nombre de la persona es requerido. | |
| lastName | String | Apellido del cliente | SI (solo si es typeCode = 'Person') | "Roddi", | 999: el apellido es requerido para clientes de tipo "Person" | |
| name | String | Razón social | SI (sólo si es typeCode = 'Organization') | IBM | ||
| String | Correo del cliente | SI | "marga@electroweb.com.ar" Se validará según se encuentre definido en la tienda (puede ser requerido para factura electrónica) | |||
| typeCode | String | Tipo de cliente (persona física o jurídica/empresa) | SI | Valores posibles:
| Error: “El campo party.typeCode debe coincidir con Person u Organization” | |
| identificationType | Number | Tipo de documento | SI | Valores posibles: 1: DNI ver servicio partyIdentificationType/all | 999: el tipo de identificación es requerido. |
| identifier | String | Número de documento o identificación NOTA: en el caso de CUIT o CUIL informar sin guiones (ej: 30505817423) | SI | "13308913", | 999: el número de identificación es requerido. | |
partyRoleAssignment (asignación de tipo de cliente)
| ||||||
partyRole | String | Código del tipo de cliente | NO | "partyRoleAssignment": [{ "partyRole": "EMPLE"} ], Puede ser una lista de tipo de clientes (debe ser uno de los códigos habilitados como Tipo de cliente en BRIDGE) | ||
partyContactMethods (direcciones del cliente). Requerido
| ||||||
| name | String | Nombre del método de contacto | SI | "Facturacion" Este dato debe ser único, en caso de encontrarse repetido dentro de la lista, se informará: "No puede realizar un pedido con dos métodos de contacto con el mismo nombre" | 1002: el nombre del método de contacto es requerido. | |
| address.firstLine | String | Calle y número | SI | "Av. del Libertador 6000" | 1003: la dirección es requerida. | |
| address.secondLine | String | Otra info | NO | "Piso 10" | ||
| adress.betweenStreets | String | Entre Calles | NO | |||
| address.cityCode | String | Ciudad | SI | MUN. Importante: código del listado de ciudades existentes, ver servicio city/all | 1004: la ciudad es requerida. |
| address.stateCode | String | Provincia | SI | "BSAS". Importante: código del listado de provincias existentes, ver servicio state/all | 1005: la provincia es requerida. |
| address.countryCode | String | Pais | SI | "ARG". Importante: código del listado de países existentes, ver servicio country/all | 1006: el país es requerido. |
| emailAddress | String | Email asociado a ese método de contacto | SI | Se puede poner el principal si no es diferente | 1007: el correo electrónico en el método de contacto, es requerido. | |
| telephone.countryCode | String | código de País | NO | 54 | 1008: el código de país del teléfono es requerido. | |
| telephone.areaCode | String | código de área | NO | 11 | 1009: el código de área del teléfono es requerido. | |
| telephone.telephoneNumber | String | número de teléfono | SI | 36637777 | 1010: el número de teléfono es requerido. | |
principalForDelivery | Boolean | NO | Opcional: true/false. En caso de enviar más de una dirección 'marcada' para delivery se va a tomar una sola. Idem para la dirección de facturación. | |||
| principalForBilling | Boolean | NO | Opcional: true/false. En caso de enviar más de una dirección 'marcada' para delivery se va a tomar una sola. Idem para la dirección de facturación. | |||
useForBilling | Boolean | Indicador de que debe utilizarse este método de contacto para facturación | NO | Opcional: true/false En caso de enviar este indicador = true se tomará esta dirección para facturar, sino toma la primera definida | ||
taxRegistrations (Datos fiscales, sólo requerido para un cliente del tipo "Organization". En el caso de Argentina se espera que se informen uno para la condición ante el IVA y de aplicar el de Ingresos Brutos, caso contrario no se podrá calcular percepciones) En el caso de otros países se debe encontrar configurado como Cliente impuestos - impuestos Ibb son requeridos = no (Configuración/sistema/tienda/clientes) cuando se integra con Bridge NOTA:
| ||||||
| aliqEffectiveDate | Date | Fecha de vigencia desde para la alícuota de IB de la jurisdicción informada (esto es lo que se considera como información de padrón del IB) Sino no informar | NO | 2020-07-01 08:51:00 Formato: yyyy-MM-dd HH:mm:ss | ||
| aliqExpirationDate | Date | Fecha de vigencia desde para la alícuota de IB de la jurisdicción informada (esto es lo que se considera como información de padrón del IB) Sino no informar | NO | 2020-07-31 08:51:00 Formato: yyyy-MM-dd HH:mm:ss | ||
| aliquot | Number | Alícuota de IB de la jurisdicción informada (esto es lo que se considera como información de padrón del IB) Sino no informar | NO | 4.00 | ||
| inscEffectiveDate | Date | Fecha de inicio de vigencia de la condición fiscal informada NOTA: considerar que BRIDGE valida la vigencia en la facturación | SI | 2020-07-01 08:51:00 Formato: yyyy-MM-dd HH:mm:ss | ||
| inscExpirationDate | Date | Fecha de fin de vigencia de la condición fiscal informada NOTA: considerar que BRIDGE valida la vigencia en la facturación | SI | 2030-07-01 08:51:00 Formato: yyyy-MM-dd HH:mm:ss | ||
| taxJurisdictionCode | String | Código de la jurisdicción | SI | ver servicio taxJurisdiction/all | ||
| taxTypeCode | String | Código del tipo de impuesto | SI | Valores posibles:
| ||
| taxCategoryCode | String | Código de la categoría impositiva (de IVA o de IB) | SI | ver servicio taxJurisdictionTaxType/all | ||
| name | String | Nombre de la razón social y tipo de impuesto (es descriptivo del registro) | SI | IBM - IVA | ||
| number | String | Número de la condición fiscal informada (CUIT o Nro de Ingresos Brutos para ARG, sin guiones) | SI | 30663205621 | ||
| documents (Grupo de documentos). Debe haber al menos un documento | ||||||
| externalDocumentNumber | String | Código del documento u orden dentro del listado | SI | "123456789" NOTA: debe ser único dentro del grupo de documentos | 994: El externalDocumentNumber no puede repetirse dentro del grupo | |
| manualDiscountAmount | Number | Importe de descuento del documento | NO | NOTA: el total de cada documento o pedido no puede ser menor a 0. Este total se calcula sumando todos los montos netos de cada artículo - el monto de descuento a nivel pedido. | ||
| notes | String | Comentarios o notas sobre el documento | NO | "Receta de OSDE" | ||
| externalSellerName | String | Nombre del vendedor o del usuario que genera la comanda en el sistema externo (no tendrá validación ya que no es un usuario Bridge) | NO | "Juan Perez" | a partir de v7.9.7 | |
| externalTerminal | String | Código de terminal del sistema externo que informa la comanda (no tendrá validación) | NO | "101" | a partir de v7.9.7 | |
| netAmount | number | Monto del pedido (no se harían validaciones, sino que seria lo informado por el sistema externo) | NO | 15000.00 | a partir de v7.9.7 | |
| documentsQty | integer | Cantidad de documentos enviado en el grupo (no tendrá validación) | NO | 3 | a partir de v7.9.7 | |
| documentAdditionalInfo [{"key": "", "value": "" }] | array | Datos de receta (afiliado, OS, etc) a nivel documento dentro de un pedido (no en la cabecera)
Lista de valores posibles:
| NO | documentAdditionalInfo [{"key": "NRO_AFILIADO", "value": "123456"}, {key": "OBRA_SOCIAL", "value": "OSDE"}, {key": "PLAN", "value": "310"}, {key": "NRO_AFILIADO", "value": "30212350310"} ] | a partir de v7.9.7 | |
| allowChange | boolean | Indicador si el documento/receta puede o no ser modificado (ej: no admite surtido parcial) | NO | default: true | a partir de v7.9.7 | |
items (Lista de artículos de cada documento) NOTAS:
| ||||||
| itemCode | String | SKU del producto | SI | "PESABLE123", ver servicio item/all o /item/[código] | 999: no se encontró el producto con código [Código del item] |
| barcode | String | Código de barras del artículo | NO | "77998866" NOTA: Es un dato opcional. Si viene informado se debe considerar que es el sku-barcode (debe existir esa relación) y debe encontrarse definido en BRIDGE como alias habilitado. | 999: El barcode [Código de barras] para el artículo [Código del item] no existe. | |
| description | String | Descripción o nombre del producto | NO (opcional) Si viene informado se toma ese valor, sino el del maestro | "Artículo pesable" NOTA: En el caso de que no venga informado y se informó un código de barras toma la descripción del código de barras, sino toma la descripción del item definido en el maestro de items. | ||
| locationCode | String | Código de depósito desde donde saldrá el stock | NO | "DEP1" ver servicio location/all | 999: el artículo no tiene depósito asociado Si no se informa el depósito, toma el asignado como default del ítem |
| orderedQty | Number | Cantidad | SI | 1 NOTA: en el caso de enviar items que requieran serie (serialNumberRequired) la cantidad debe ser igual a 1, no puede ser mayor ya que es una relación posterior al surtir/facturar de una unidad con su serie Del mismo modo si el item se vende por magnitud (peso, longitud, etc) | 999: la cantidad pedida es obligatoria. 999: El artículo no admite cantidad mayor a 1 por ser pesable | |
| units | Number Decimal | Unidades asociadas a la presentación (código de barras) Se multiplica "units" por "orderedQty" | NO | 2 Campo opcional. Por defecto toma el valor = 1. NOTAS:
| 999: La cantidad de unidades para el barcode [Código de barras] no coincide. | |
| magnitude | Number Decimal | Magnitud (cuando el artículo requiere magnitud, por ejemplo peso, largo, etc) | NO | 1.455 Campo opcional. NOTA: Sólo será considerado si el artículo enviado en el pedido se encuentra configurado con una unidad de medida definida con decimales (Ej.: gramos, metro, etc.)
| 999: El articulo requiere magnitud. 999: El artículo no admite cantidad mayor a 1 por ser pesable | |
| packagePrice | Boolean | Indicador si el precio enviado es por paquete o unitario | NO | Se asume false si no se envía
| ||
| unitPrice | Number | Precio unitario | SI | 300 | 999: el precio unitario es requerido. | |
| otherUnitOfMeasureCode | String | Código de unidad de medida equivalente | NO | "Bolsa" NOTA: Debe ser uno de los códigos de unidades de medida existente en BRIDGE y debe estar asociada al item | 999: El artículo no posee la unidad de medida: [Código de unidad de medida] asociada y habilitada. |
| serie | String | Nro de serie del artículo | NO | "12345678" NOTA: Si es enviado, tiene que ser un nro de serie existente para el item y contar con stock
| 999: Debe especificarse numero de serie para el artículo [Código del item] 999: No se encontró la serie [Código de serie] para el item [Código del item] | |
| notes | String | Nota o comentario adicional del artículo | NO | "Requiere datos adicionales" | ||
lotNumber | string | Nro de lote | NO | "A123" | a partir de v7.9.7 | |
trace | string | Nro de traza | NO | "123654" | ||
priceModifier : descuento otorgado al artículo (es único) NOTA: el monto de descuento no puede ser superior al monto total del artículo (Cantidad solicitada x precio unitario) Las variantes del cálculo del monto dependerá del artículo y sus características:
En todos estos escenarios se le restará el descuento. Ese monto neto por cada item debe ser mayor o igual a 0. | ||||||
| amount | Number | Monto de descuento | SI (si es informada la línea) | 5 | 999: si informa un descuento, debe informar el monto. | |
| reasonText | String | Razón del descuento | NO | Oferta del día | ||
Respuesta del servicio:
{
"ack": 0,
"message": "El grupo de facturación se ha ingresado con éxito.",
"internalNumber": "bridge000001000012"
}
- ack: es el código de respuesta, en caso de ser un error, mirar tabla a continuación.
- message: descripción del error en caso de existir.
- internalNumber: en caso de haberse creado con éxito, el número de lista de documentos asignado por Bridge.
El nro interno (internalNumber) que se informa en la respuesta será el que se asocie al grupo de documentos recibidos. Este se conformará con la cadena de caracteres "bridge"+ 12 dígitos:
- 6 para el código de tienda (completado con ceros a la izquierda)
- 6 para el nro secuencial (completado con ceros a la izquierda)
- Ejemplo:
- "internalNumber": "bridge000001000012"
- Código dela tienda: 1
- Nro secuencial para la tienda: 12
- "internalNumber": "bridge000001000012"
Validaciones sobre el stock
Configuraciones disponibles y validaciones
Configuración del sistema | Validaciones aplicadas | |
|---|---|---|
| 1 | Nombre de la propiedad:"Admite crear grupos de facturación sin stock", Descripción: "Admite crear grupos de facturación sin stock o no" |
Al recibir un grupo de documentos a facturar (billOrderGroup) se valida stock de los productos (solo aquellos que son stockItem y del tipo NORM)
Respuesta de error: "No hay suficiente stock para el item [Código del item]
|
| 2 | Nombre de la propiedad: "Reserva stock sin considerar flag de requiere reserva para itemType normal" Descripción: "Indica si reserva stock sin considerar flag de requiere reserva para itemType normal." | Si la config "Reserva stock sin considerar flag de requiere reserva para itemType normal"= SI, reserva para todo item del tipo NORM (sin considerar que tenga el indicador de "Requiere reserva activo") Si la config "Reserva stock sin considerar flag de requiere reserva para itemType normal"= NO, reserva sólo sobre aquellos que tengan el indicador de "Requiere reserva activo" |
Validación sobre items que requieren serie
- Si el item se encuentra definido como "Requiere serie"
- se valida que venga informado en el request junto con los datos del item
- si viene informado:
- Se valida que este definido en la lista de items/series (serializedUnit) y tiene que tener stock (cantidad actual menos la reservada mayor a 0)
- si no viene informado, se informará con un error y no se creará el grupo de documentos
Respuesta de error: "Debe especificarse número de serie para el artículo [Código del item]