API : Ventas > Enviar Ventas a OBUMA via API

https://www.obuma.cl/ayuda/articulo/141/api--ventas--enviar-ventas-a-obuma-via-api

La API permite generar o enviar a OBUMA Ventas hechas en otros sistemas, para ser emitidas y enviadas al SII por OBUMA.

 

Ventas > Crear ventas :

 

  •  POST   /ventasIntegracionExternas.create.json 

Permite enviar un array con el contenido del documento a procesar.

Sirve tanto para facturas, guias, notas de debito y credito, boletas y notas de venta. 

 

CAMPO DESCRIPCION OBLIGATORIO OPCIONES
Datos generales del dcto      
venta_tipo_dcto

Indicar el codigo del tipo dcto.

Ej. 33 

Si   
venta_nro_dcto Irrelevante, lo asigna el sistema de forma automatica. Si  
venta_nro_dcto_fijo Indicar si se desea que OBUMA respete el folio enviado en venta_nro_dcto, util para sincronizar ventas procesados por otros sistemas. Opcional

0 = No (por defecto)

1 = Si

venta_fecha

Indicar la fecha del dcto emitido.

Si no se informa utiliza fecha actual.

 

dd-mm-yyyy 

yyyy-mm-dd

venta_fecha_vencimiento Indicar la fecha de vencimiento, si no indica se asigna la fecha del dcto.    dd-mm-yyyy 

yyyy-mm-dd

venta_canal Indicar el CODIGO del canal de venta. Opcional  
venta_sucursal Indicar el CODIGO de la lista precio. Opcional  
venta_bodega Indicar el CODIGO de la bodega. Opcional  
venta_lista_precio Indicar el CODIGO de la lista precio. Opcional  
venta_usuario Indicar el CODIGO del usuario. Opcional  
venta_vendedor Indicar el CODIGO del vendedor. Opcional  
venta_subtotal Indicar el subtotal afecto.    
venta_exento Indicar el monto exento de iva.    
venta_neto Indicar el monto neto.    
venta_iva Indicar el monto iva.    
venta_total Indicar el monto total del dcto.    
venta_total_pagado Indicar el monto pagado.    
venta_total_por_pagar Indicar el monto por pagar.     
       
Datos del cliente      
cliente_rut

Indicar el rut del cliente

 Si Formato chile con guión y digito verificador.
cliente_razon_social Indicar la razon social del cliente.  Si texto
cliente_comuna Indicar el ID de la comuna.  Si numerico
cliente_region Indicar el ID de la region.  Si numerico
cliente_giro Indicar el giro o glosa descriptiva del cliente.  Si texto
cliente_email Indicar el email del cliente.  Si texto
cliente_telefono Indicar el telefono del cliente.  Si texto
cliente_contacto Indicar el nombre del contacto principal.  Si texto
       
Datos del detalle de los items      
venta_detalle Es un array con los items del dcto    
 > codigo_comercial Indicar el código SKU del item    
 > producto_nombre Indicar el nombre del item    
 > mostrar_descripcion Indicar si se desea mostrar o incluir la descripción del item  

1=mostrar

0=no mostrar

 > producto_descripcion Indicar la descripcion    
 > cantidad Indicar la cantidad de items   numerico con decimales
 > producto_precio Indicar el precio unitario del producto   numerico con decimales
 > descuento Indicar el porcentaje descuento unitario   numerico con decimales
 > descuento_monto Indicar el monto del descuento    
 > subtotal Indicar el monto del subtotal    numerico entero
 > producto_exento Indica si el item es exento o no Opcional

0= afecto a iva

1 = exento

Si no envia campo toma por defecto valor 0.

 > unidad_medida  Indica la unidad de medida. Opcional  
       
Datos de las referencias   Opcional  
venta_referencias Es un array con las referencias del dcto    
 > tipo_dcto_ref Indicar el tipo dcto al que hace referencia segun tabla codigos dctos del SII    
 > folio_dcto_ref  Indicar el folio del dcto.    
 > fecha_dcto_ref  Indicar la fecha del dcto.    
 > codigo_ref 

Indicar el codigo de la referencia...

Para notas de credito y debito:

1: Anula dcto

2: Corrige datos receptor

3: Corrige montos

 

Condicional al tipo dcto   
 > razon_ref  Indicar breve descripcion Opcional  

 

Ejemplo array php : 

$data = array(
   
    'venta_tipo_dcto'     => 33, // el codigo del tipo documento segun normas del SII
    'venta_nro_dcto'     => "", // irrelevante, obuma maneja el folio
    'venta_fecha'         => "2017-04-06",
    'venta_fecha_vencimiento'       => "2017-04-06",

    'venta_canal'     => '', // codigo creado en obuma   
    'venta_sucursal'     => '', // codigo creado en obuma
    'venta_bodega'         => '', // codigo creado en obuma
    'venta_lista_precio'=> '', // codigo creado en obuma
    'venta_usuario'     => '', // codigo creado en obuma
    'venta_vendedor'     => '', // codigo creado en obuma

    'venta_subtotal'     => 100,
    'venta_exento'         => 0,
    'venta_neto'         => 100, 
    'venta_iva'         => 19,
    'venta_total'         => 119,
    'venta_total_pagado'     => 0,
    'venta_total_por_pagar' => 0,

    'cliente_rut'             => "99.999.999-9", 
    'cliente_razon_social'     => "Cliente de Prueba SpA",
    'cliente_direccion'     => "Alameda 1000",
    'cliente_comuna'         => 46,
    'cliente_region'         => 13,
    'cliente_giro'             => "Servicios",
    'cliente_email'         => "",
    'cliente_telefono'         => "00000",
    'cliente_contacto'         => "Don Juan Perez",

    'venta_detalle' => array (

       'codigo_comercial'        => "", // codigo sku
       'producto_nombre'        => "Servicio mantencion",
       'mostrar_descripcion'    => "",
       'producto_descripcion'    => "Mantencion detallada",
       'cantidad'                => 1,  
       'producto_precio'        => 100,
       'descuento'                => 0,
       'descuento_monto'        => 0,
       'subtotal'                => 100,
       'producto_exento'        => "", // si el producto es exento indicar 1
       'unidad_medida'            => ""

    ),

   'venta_referencias' =>  array(

       'tipo_dcto_ref' => '801', 
       'folio_dcto_ref' => '1',
       'fecha_dcto_ref' => '2018-01-10',
       'codigo_ref' => 'codigo segun sii',
       'razon_ref' => 'breve detalle',

   ),
   'venta_extra_datos' =>  array(

     'key' =>test',
     'value' =>123'
  
  ),

                  
);


$data =  array('docs' => $data); 


 

Ejemplo estructura json:

{
  "docs": [
{
  "venta_tipo_dcto": 56,
  "venta_nro_dcto": "",
  "venta_fecha": "2020-01-25",
  "venta_fecha_vencimiento": "2020-01-25",
  "venta_sucursal": "S-VGH-01",
  "venta_bodega": "B-VGH-01",
  "venta_lista_precio": "L-VGH-01",
  "venta_usuario": "",
  "venta_vendedor": "V-VGH-01",
  "venta_subtotal": "0",
  "venta_exento": "2363358",
  "venta_neto": "0",
  "venta_iva": "0",
  "venta_total": "2363358",
  "venta_total_pagado": 0,
  "venta_total_por_pagar": 0,
  "cliente_rut": "7.743.110-0",
  "cliente_razon_social": "KIPREOS INGENIEROS S.A",
  "cliente_direccion": "AMERICO VESPUCIO",
  "cliente_comuna": "21",
  "cliente_giro": "-",
  "cliente_email": "-",
  "cliente_telefono": "4431301",
  "venta_condicion_pago": "-",
  "venta_observacion": "-",
  "venta_detalle": [
    {
      "identificador": "53c3bce66e43be4f209556518c2fcb54",
      "producto_nombre": "Reversa Nota Credito",
      "mostrar_descripcion": "",
      "producto_descripcion": "",
      "cantidad": "1",
      "producto_precio": "2363358",
      "descuento": "0",
      "descuento_monto": "0",
      "subtotal": "2363358",
      "codigo_comercial": "",
      "producto_exento": "1",
      "unidad_medida": "",
      "imagen": "",
      "type": "",
      "id": "292"
    }
   ]
}
  ]
}

OJOOO: docs es un array de dctos... 

 

Ejemplo de uso:

$url='https://api.obuma.cl/v1.0/ventasIntegracionExternas.create.json';
$json = post_recurso($url, $data); // funcion mostrada en el articulo de Introduccion a la API

Para revisar el resultado del envio puedes usar : print_r($json);


El resultado va a devolver varias variables, como:

$json['result']['result']  esta variable debe indicar OK

$json['result']['result_detail'] esta variable indica el log de la operacion

// En la variable result_dte obuma te devuelve el folio del DTE asignado por OBUMA, mas la url del PDF y del XML
$resultado = $json['result']['result_dte'];

foreach($resultado as $r){
        echo '
'.$r['dte_folio'].' '.$r['dte_result'].' '.$r['dte_id_obuma'].' '.$r['dte_pdf'];

}

Ejemplo resultado con errores:

 
{"errors":[{"code":111,"message":"Invalid Parameters: Error en id cliente."}]}
Se debe a RUT erroneo.

{"errors":[{"code":112,"message":"Invalid Parameters: Error no hay CAF."}]}
Se debe a que no hay FOLIOS disponibles.
 

 

Otras opciones o variables :

 

Si quieres informar el monto pagado al momento de emitir el DTE, debes usar :
 
// registrar cobro 0=no 1=si
$venta_registrar_cobro = 1;

// forma pago
$venta_forma_pago = CODIGO FORMA PAGO EN OBUMA
$venta_fecha_pago = dd-mm-yyyy, yyyy-mm-dd, si no se indica usa fecha actual. 
 
// monto pagado
$venta_total_pagado = MONTO DEL PAGO
 
Si informas $venta_total_pagado debes tambien informar $venta_total_por_pagar
 
Solo se puede informar un unico PAGO por esta vía
 
 
Si quieres que obuma mantenga o respete los datos del cliente enviados en el json :
 
$cliente_actualizar_datos=1; 
 
Por defecto, cada vez que envias una solicitud, se verifica si el RUT enviado existe, si existe entonces se usan los datos almacenados en OBUMA sin importar los datos enviados en el json, si se desea utilizar los datos enviados entonces usar la variable $cliente_actualizar_datos con valor 1.

 

Si quieres que obuma envie el email con el DTE al cliente automaticamente :

$venta_enviar_email_cliente=1;

 

Si quieres que obuma contabilice el DTE emitido automaticamente (hacer voucher contable) :
 
$venta_registrar_contabilidad=1;

 

Si quieres rebajar stock al vender :

$venta_rebajar_stock=1;

$venta_bodega=CODIGO BODEGA EN OBUMA

El producto debe existir en obuma y estar marcado como inventariable.

 

Si quieres informar las referencias del documento :

$venta_referencias = array();

"venta_referencias": [
{
"tipo_dcto_ref" : "801",
"folio_dcto_ref" : "30",
"fecha_dcto_ref" : "10-11-2018",
"codigo_ref" : "codigo segun sii",
"razon_ref" : "breve detalle"
}
]

 

Las notas de credito utilizan los mismos campos que una factura, solo se diferencian por el codigo del tipo dcto y por la referencia.

La referencia debe indicar los datos del dcto al que se aplica la nota de crédito.

 

Si quieres informar extra datos de libre uso :

$venta_extra_datos = array();

"venta_extra_datos": [
{
"key" : "external_id",
"value" : "30"
},

{
"key" : "external_site",
"value" : "www.obuma.cl"
}
]

 

Si quieres emitir una guia despacho :

 

Las guias de despacho utilizan los mismos campos que una factura, solo se diferencian por el codigo del tipo dcto, por los indicadores del tipo despacho y traslado, y por la referencia.

 

 
$venta_tipo_dcto = 52
 
$venta_guia_tipo_traslado = 1
 
                1 > Operacion constituye venta
                2 > Ventas por efectuar
                3 > Consignaciones
                4 > Entrega Gratuita
                5 > Traslados internos
                6 > Otros traslados no venta
                7 > Guia de devolucion
 
$venta_guia_tipo_despacho = 1
 
                1 > Por cuenta CLIENTE
                2 > EMISOR a instalaciones cliente
                3 > EMISOR a OTRAS instalaciones cliente
 
 
Ejemplo de la referencia en una guia : Indicar el tipo, folio y fecha de la factura
'venta_referencias' =>  array(

       'tipo_dcto_ref' => '33', 
       'folio_dcto_ref' => '100',
       'fecha_dcto_ref' => '2018-01-10',
       'codigo_ref' => '',
       'razon_ref' => 'despacho',

   ),
 
 

Si quieres manipular tú tus folios :

$venta_nro_dcto = {TuFolio};

$venta_nro_dcto_fijo = 1; // Esto hace que OBUMA respete el folio informado por ti en el campo $venta_nro_dcto

 Bajo esta modalidad, la responsabilidad de administrar la asignacion de los folios es del usuario.

 

Para hacer que OBUMA valide los documentos antes de procesarlos y evitar duplicidad de folios o documentos, utilizar los siguientes parametros:

$venta_external_id_validar = 1
$venta_external_id = {$id} // Indicar el id unico en tu sistema, para que OBUMA valide su existencia, si ya existe, no procesa el dcto enviado.
 
 

 

 

 

Codigos TIPOS DOCUMENTOS :

4 : Nota de venta

33 : Factura electronica

34 : Factura electronica exenta

56 : Nota de debito electronica

61 : Nota de credito electronica

52 : Guia de despacho electronica

39 : Boleta electronica

41 : Boleta electronica exenta

 

 

 

 

Ventas > Consultas sobre DTE :

 

  •  POST   /ventasConsultaDte.listPdfXml.json 

Permite obtener el PDF y XML de un DTE.

--- Parametros :

tipoDte : el tipo dcto a consultar

folio : el folio del dcto a consultar

 

 

 

 

  •  POST   /ventasConsultaDte.estadoDTEenSII.json 

Permite consultar el estado de un DTE en el SII. 

--- Parametros :

tipoDte : el tipo dcto a consultar

folio : el folio del dcto a consultar

{
  "tipoDte":"33",
  "folio":"10520"
}

 

--- Resultado : 

dte_aceptado_sii : 1 = si, aceptado por el SII.

dte_aceptado_receptor :
0 = Sin respuesta
1 = Documento Aceptado por RECEPTOR
2 = Documento Rechazado por RECEPTOR
3 = Documento Anulado con Nota de Credito
4 = Documento con Pago Contado
5 = Documento Aceptado por OMISION
"result": {
"result": "0",
"result_detail": "10-4",
"result_dte": [
  {
"dte_aceptado_sii": "0"
}
],
}