Integración - Crear comprobantes electrónicos (01, 03, 07 y 08)

Proyecto API

📘 API – Emisión de Comprobantes Electrónicos

Versión: 1.0
Base URL:https://tuservidor.com
Recurso principal:/api/comprobantes/crear
Método:POST
Tipo de autenticación:Bearer Token o auth='user' (según la configuración de Odoo)
Formato de envío:application/json o text/yaml
Formato de respuesta:JSON

Autenticación y Seguridad

  • Autenticación requerida: Sí (auth='user')
  • Método de autenticación: Los usuarios deben autenticarse a través del endpoint /web/session/authenticate para obtener una sesión válida.

Pasos para Autenticarse

  1. Autenticarse en Odoo:

    • Realiza una solicitud POST al endpoint /web/session/authenticate con las credenciales del usuario.
    • Obtendrás una cookie de sesión (session_id).

  2. Usar la Sesión en las Solicitudes:

    • Incluye el session_id en las cookies de la solicitud.

Endpoint: /api/comprobantes/crear

  • Método HTTP: POST
  • Tipo de contenido: application/json
  • Autenticación: Requerida (auth='user')
  • Descripción: Permite dar de alta a un cliente en el sistema Odoo.

Parámetros principales

  • tipo_doc: Tipo de documento a emitir.
    Valores permitidos: FAC (Factura) o BOL (Boleta).

  • serie: Serie del comprobante (por ejemplo F001 o B001).

  • cliente_tipo_de_documento: Tipo de documento del cliente.
    Ejemplo: 6 para RUC, 1 para DNI o 0 para sin documento.

  • cliente_numero_de_documento: Número de RUC o DNI del cliente.

  • cliente_denominacion: Razón social o nombre del cliente.

  • cliente_direccion, cliente_departamento, cliente_provincia, cliente_distrito:
    Datos de ubicación del cliente.

  • cliente_email / cliente_celular: Datos de contacto opcionales.

  • fecha_de_emision: Fecha de emisión del comprobante en formato DD/MM/YYYY.

  • tipo_operacion_comprobante:
    Define el tipo de operación:
    0101 = Venta interna,
    0200 = Exportación (bienes y servicios).

  • validar_comprobante:
    "1", el comprobante se valida automáticamente.
    "0", se crea en estado borrador.

  • items:
    Lista de productos o servicios incluidos en el comprobante.
    Cada item debe contener:

    • producto: Código o nombre del producto.

    • descripcion: Descripción del producto o servicio.

    • cantidad: Cantidad vendida.

    • precio_unitario: Precio unitario (sin o con IGV según tipo_igv).

    • tipo_impuesto: Tipo de afectación IGV (1=Gravado, 2=Exonerado, 4=Inafecto).

    • tipo_igv: 0 si el precio no incluye IGV, 1 si lo incluye.

    • porcentaje_igv: Generalmente 18.

Ejemplo de Solicitud

Paso 1: Autenticarse

Solicitud:

http

POST /web/session/authenticate HTTP/1.1
Content-Type: application/json

{
    "jsonrpc": "2.0",
    "method": "call",
    "params": {
        "db": "nombre_de_la_base_de_datos",
        "login": "usuario@example.com",
        "password": "tu_contraseña"
    },
    "id": 1
}

Respuesta:

json

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "uid": 2,
        "user_context": {...},
        "company_id": 1,
        "partner_id": 3,
        "session_id": "session_id_obtenido"
    }
}

Paso 2: Invocar el Endpoint /cliente_alta

Solicitud:

http

POST /cliente_alta HTTP/1.1
Content-Type: application/json
Cookie: session_id=session_id_obtenido
json
 {
  "tipo_doc": "FAC",
  "serie": "F001",
  "cliente_tipo_de_documento": "6",
  "cliente_numero_de_documento": "20987654321",
  "cliente_denominacion": "EMPRESA DEMO S.A.C.",
  "cliente_direccion": "AV. ABC 123, LIMA",
  "cliente_departamento": "LIMA",
  "cliente_provincia": "LIMA",
  "cliente_distrito": "SAN MARTÍN DE PORRES",
  "cliente_pais": "Perú",
  "cliente_email": "ventas@demo.com",
  "cliente_celular": "999888777",
  "fecha_de_emision": "28/10/2025",
  "tipo_operacion_comprobante": "1",
  "validar_comprobante": "1",
  "items": [
    {
      "producto": "SERV001",
      "descripcion": "SERVICIO DE CONSULTORÍA",
      "cantidad": 1,
      "precio_unitario": 118.00,
      "tipo_impuesto": "1",
      "tipo_igv": "1",
      "porcentaje_igv": "18"
    }
  ]
}

 

Respuestas

Éxito (200 OK)

El cliente ha sido dado de alta correctamente.

Ejemplo de respuesta:

json

{
  "status": 200,
  "message": "Comprobante F001-123 creado y validado correctamente.",
  "response": {
    "data": {
      "tipo_doc": "FAC",
      "serie": "F001",
      "numero": "123",
      "base_imponible": 100.00,
      "igv": 18.00,
      "total": 118.00,
      "url_pdf": "url"
    }
  }
}

Error de validación (400 Bad Request)

Faltan campos requeridos o hay errores en los datos proporcionados.

Ejemplo de respuesta:

json

{
  "status": 400,
  "message": "Falta el campo obligatorio 'cliente_numero_de_documento'.",
  "response": {
    "data": null
  }
}


Códigos de respuesta

  • 200:El comprobante fue creado correctamente.

  • 400: Error de validación. Falta un campo o el formato es incorrecto.

  • 404: Recurso no encontrado (cliente, diario o producto).

  • 409: El comprobante ya se encuentra registrado.

  • 500: Error interno del servidor o validación fallida en Odoo.

Proceso Detallado de Autenticación

1. Autenticarse en Odoo

Solicitud de Autenticación:

http

POST /web/session/authenticate HTTP/1.1
Content-Type: application/json

{
    "jsonrpc": "2.0",
    "method": "call",
    "params": {
        "db": "nombre_de_la_base_de_datos",
        "login": "usuario@example.com",
        "password": "tu_contraseña"
    },
    "id": 1
}

Respuesta Exitosa:

json

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "uid": 2,
        "user_context": {...},
        "company_id": 1,
        "partner_id": 3,
        "session_id": "session_id_obtenido"

    }
}

2. Realizar Solicitudes a los Endpoints Protegidos

Incluye el session_id en las cookies.

Consideraciones de Seguridad

  • Sesiones: Las sesiones tienen una duración limitada. Si la sesión expira, debes volver a autenticarse.
  • Almacenamiento Seguro: Asegúrate de almacenar de forma segura el session_id en tu aplicación cliente.
  • Comunicación Segura: Utiliza siempre HTTPS para las comunicaciones con el servidor Odoo para proteger los datos en tránsito.